Skip to main content

RobotEditMCP

MCP server for Robot configuration management - AI Agent tools for Robot draft/online/template configs.

Overview

RobotEditMCP provides AI Agents with tools to manage Robot configurations through a Model Context Protocol (MCP) server. It enables operations on draft, online (production), and template configurations with support for complex relationships and batch operations.

Features

  • Draft Configuration Management: Create, read, update, delete draft configs
  • Online Configuration Management: Manage production environment configs
  • Template Management: Save, load, and apply configuration templates
  • Conversations Management: Create chat sessions and exchange messages
  • Batch Operations: Create interconnected configurations with internal references
  • Action Triggering: Execute configuration actions (sync and async)
  • Metadata Discovery: Explore scenes, factories, and schemas
  • Progressive Disclosure: Tools designed for AI-driven exploration

Installation

Prerequisites

  • Python 3.10 or higher
  • pip or poetry for package management

Install from source

# Clone the repository
git clone <repository-url>
cd RobotEditMCP

# Install in development mode
pip install -e .

# Or with poetry
poetry install

Configuration

RobotEditMCP requires environment variables for authentication and API access:

Required Environment Variables

Create a .env file in your project root:

# Required - API authentication and endpoint
ROBOT_ADMIN_TOKEN=your_admin_token_here
ROBOT_BASE_URL=https://api.robot.com

# Required - Kubernetes network routing headers
TF_NAMESPACE=staging-tenant
TF_ROBOT_ID=friday

# Optional
ROBOT_LOG_LEVEL=INFO
API_TIMEOUT=30
MAX_CONNECTIONS=10

Environment Variables Reference

Variable Required Description Default
ROBOT_ADMIN_TOKEN Yes Admin API token for authentication (sent in adminToken cookie) -
ROBOT_BASE_URL Yes RobotServer base URL -
TF_NAMESPACE Yes Kubernetes namespace for Pod routing (sent in tfNamespace cookie) -
TF_ROBOT_ID Yes Robot instance identifier for K8s service discovery (sent in tfRobotId cookie) -
ROBOT_LOG_LEVEL No Log level (INFO/ERROR/DEBUG) INFO
API_TIMEOUT No API request timeout in seconds 30
MAX_CONNECTIONS No Maximum HTTP connections 10

Kubernetes Architecture Notes

TF_NAMESPACE and TF_ROBOT_ID are essential cookies used in the Kubernetes network layer:

  • tfNamespace: Identifies the K8s namespace where the Robot pods are deployed
  • tfRobotId: Identifies the specific Robot instance for service discovery and routing

These cookies enable proper network routing in multi-tenant K8s environments, allowing requests to reach the correct Robot pod. They are set on the HTTP client instance and sent with every HTTP request, processed by the Kubernetes network infrastructure (e.g., Ingress, Service Mesh, or custom controllers).

Usage

Running the MCP Server

# Using the installed command
roboteditmcp

# Or directly with Python
python -m roboteditmcp.main

MCP Client Configuration

Add to your Claude Desktop config or MCP client configuration:

{
  "mcpServers": {
    "robotedit": {
      "command": "roboteditmcp",
      "env": {
        "ROBOT_ADMIN_TOKEN": "your_token_here",
        "ROBOT_BASE_URL": "https://api.robot.com",
        "TF_NAMESPACE": "staging-tenant",
        "TF_ROBOT_ID": "friday"
      }
    }
  }
}

Available Tools

Draft Configuration (9 tools)

  1. list_drafts - List draft configurations with optional filters
  2. get_draft - Get detailed information about a single draft
  3. create_draft - Create a new draft configuration
  4. update_draft - Update a draft (supports partial updates)
  5. delete_draft - Delete a draft configuration
  6. batch_create_drafts - Batch create with internal references
  7. release_draft - Release all drafts to production
  8. trigger_draft_action - Trigger an action on a draft

Online Configuration (4 tools)

  1. list_online_configs - List production environment configs
  2. get_online_config - Get online configuration details
  3. get_online_action_detail - Get action details (Online only)
  4. trigger_online_action - Trigger an action (supports async)

Template Management (5 tools)

  1. list_templates - List available templates (paginated)
  2. get_template - Get template details
  3. apply_template - Create draft from template
  4. save_as_template - Save draft as template
  5. delete_template - Delete a template

Conversations Management (3 tools)

  1. conversations_create - Create a new chat conversation
  2. conversations_send_message - Send a message to a conversation
  3. conversations_get_messages - Get messages and events from a conversation

Metadata Tools (2 tools)

  1. list_scenes - List all scene types
  2. list_factories - List factories for a scene

Usage Examples

Exploring the Configuration System

# 1. List available scenes
scenes = list_scenes()
# Returns: ["ROBOT", "LLM", "CHAIN", ...]

# 2. List factories for a scene
factories = list_factories(scene="ROBOT", type="draft")
# Returns: {factory_names: ["RobotBrainDraftSetting", ...]}

Creating a Configuration

# Create a new draft
draft = create_draft(
    scene="ROBOT",
    name="RobotBrainDraftSetting",
    setting_name="My Robot Config",
    config={"model": "gpt-4", "temperature": 0.7}
)

Batch Creating with References

# Create multiple interconnected configs
result = batch_create_drafts(drafts=[
    {
        "temp_id": -1,
        "draft": {
            "scene": "LLM",
            "name": "LLMProviderDraftSetting",
            "setting_name": "My GPT",
            "config": {"model": "gpt-4"}
        }
    },
    {
        "temp_id": -2,
        "draft": {
            "scene": "ROBOT",
            "name": "RobotBrainDraftSetting",
            "setting_name": "My Robot",
            "config": {
                "llm_provider": {"setting_id": -1, "category": "Draft"}
            }
        }
    }
])

Updating and Releasing

# Update configuration (partial)
update_draft(
    setting_id=123,
    setting_name="My Robot Config (Updated)",
    config={"temperature": 0.8}  # Only update temperature
)

# Release all drafts to production
release_draft()

Managing Conversations

# Create a new conversation
conversation = conversations_create(title="Customer Support Chat")
# Returns: {conversationId: 7, title: "Customer Support Chat", ...}

# Send a message to the conversation
conversations_send_message(
    conversation_id=7,
    content="Hello, I need help with my account"
)

# Get messages and events (AI responses are generated asynchronously)
messages = conversations_get_messages(conversation_id=7, count=-10)
# Returns: {cursor: "...", messages: [...], events: [...]}

# Poll for AI response (may need multiple calls if AI is still generating)
response = conversations_get_messages(conversation_id=7)

Architecture

src/roboteditmcp/
├── __init__.py           # Package initialization
├── config.py             # Configuration management
├── client.py             # HTTP API client
├── server.py             # MCP server implementation
├── main.py               # CLI entry point
├── logging_config.py     # Logging setup
├── models/
│   └── __init__.py       # Data models
└── tools/
    ├── __init__.py       # Tools registry
    ├── draft.py          # Draft configuration tools
    ├── online.py         # Online configuration tools
    ├── template.py       # Template management tools
    ├── conversations.py  # Conversations management tools
    └── metadata.py       # Metadata tools

Authentication

RobotEditMCP uses the admin_key header for authentication (consistent with frontend implementation):

headers = {
    "admin_key": ROBOT_ADMIN_TOKEN,
    "Content-Type": "application/json"
}

Error Handling

All API responses follow the TFSResponse format:

{
  "code": 200,
  "message": "success",
  "data": {...}
}

Errors are raised with detailed messages for debugging.

Development

Running Tests

# Run tests (if available)
pytest tests/

# Or with poetry
poetry run pytest

Code Structure

  • client.py: Low-level HTTP client with all API endpoints
  • tools/*.py: MCP tool definitions and handlers
  • server.py: MCP server orchestration
  • config.py: Configuration and validation

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

License

[Specify your license here]

Support

For issues and questions:

  • API Documentation: /Users/huruize/PycharmProjects/TFRobotServer/tfrobotserver/api/v1/robot_factory/
  • Example Configurations: /Users/huruize/PycharmProjects/RobotEditMCP/机器人配置json.txt

Version History

  • 0.1.4 (2025): Add conversations management

    • Create and manage chat conversations
    • Send messages and retrieve responses
    • Support for pagination in message history
  • 0.1.3 (2025): Type conversion improvements

    • Added setting_id type conversion for string inputs
    • Enhanced error handling
  • 0.1.0 (2025): Initial release

    • Draft, Online, Template configuration management
    • Batch operations with references
    • Action triggering (sync/async)
    • Metadata discovery tools

Metadata

Release files for roboteditmcp 0.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for roboteditmcp 0.2.2
File Size Uploaded Provenance Actions
roboteditmcp-0.2.2.tar.gz 169.1 kB With provenance Details for roboteditmcp-0.2.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for roboteditmcp 0.2.2
File Interpreter ABI Platform Actions
roboteditmcp-0.2.2-py3-none-any.whl Python 3 none any Details for roboteditmcp-0.2.2-py3-none-any.whl

Total release size: 202.8 kB

Release files / roboteditmcp-0.2.2.tar.gz

Download URL roboteditmcp-0.2.2.tar.gz
Size 169.1 kB
Tags Source
SHA-256 checksum
How to use checksums
5d045b9e1cc60fad99e33ec9d1430232a3b7c3d05212e8e1c4a1fcd2e1424f48
BLAKE2b-256 checksum
How to use checksums
2a6196aac0cdb7b0c4ebb4ae593a0df15edad334ab68454077809c25779b3c77
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 18, 2026.

Transparency log

Release files / roboteditmcp-0.2.2-py3-none-any.whl

Download URL roboteditmcp-0.2.2-py3-none-any.whl
Size 33.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
686e4e7e75553d4b160c05dacdc51dd862ca595390e691af72633ae6d57d6d7b
BLAKE2b-256 checksum
How to use checksums
532e4aca566885e012dd0f4ca8040ca469bc07ba5d76471083f4f904b8d84bc6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 18, 2026.

Transparency log

Security for roboteditmcp 0.2.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for roboteditmcp-0.2.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page