MCP 代理编排系统

这是一个使用模型上下文协议 (MCP) 的基于状态的代理编排系统的 Python 实现。

什么是 MCP？

模型上下文协议 (MCP) 允许应用程序以标准化的方式为 LLM 提供上下文，从而将提供上下文的关注点与实际的 LLM 交互分离。 使用 MCP，您可以构建服务器来公开：

• 资源 (Resources)：为 LLM 提供信息的数据源
• 工具 (Tools)：允许 LLM 执行操作的函数
• 提示词 (Prompts)：用于 LLM 交互的可重用模板

安装

前提条件

• Python 3.10 或更高版本
• MCP Python SDK 1.2.0 或更高版本

设置您的环境

使用 uv (推荐)

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 为我们的项目创建一个新目录
uv init mcp-agents-orchestra
cd mcp-agents-orchestra

# 创建虚拟环境并激活它
uv venv
source .venv/bin/activate  # 在 Unix/macOS 上
.venv\Scripts\activate     # 在 Windows 上

# 安装依赖
uv add "mcp[cli]" httpx

使用 pip

# 为我们的项目创建一个新目录
mkdir mcp-agents-orchestra
cd mcp-agents-orchestra

# 创建一个虚拟环境
python -m venv venv
source venv/bin/activate  # 在 Unix/macOS 上
venv\Scripts\activate     # 在 Windows 上

# 安装依赖
pip install "mcp[cli]" httpx

克隆或下载项目文件

将项目文件放置在您的目录中：

• orchestrator.py - 实现状态机的主 MCP 服务器
• orchestrator_client.py - 演示编排流程的客户端
• requirements.txt - 项目的依赖项
• .gitignore - Git 忽略文件

项目结构

• orchestrator.py - 实现状态机的主 MCP 服务器
• orchestrator_client.py - 演示编排流程的客户端
• requirements.txt - 项目的依赖项

运行编排系统

1. 直接启动编排服务器进行测试：

python orchestrator.py

2. 在单独的终端中，运行客户端以查看编排的实际效果：

python orchestrator_client.py

与 Claude for Desktop 集成

1. 安装 Claude for Desktop

确保您已安装 Claude for Desktop。 您可以从 Anthropic 的网站 下载最新版本。

2. 配置 Claude for Desktop

1. 打开您的 Claude for Desktop 配置文件：

   macOS/Linux:

   # 创建或编辑配置文件
   code ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

   Windows:

   # 路径可能因您的 Windows 版本而异
   code %APPDATA%\Claude\claude_desktop_config.json
   

2. 添加编排服务器配置：

   {
       "mcpServers": {
           "agent-orchestrator": {
               "command": "python",
               "args": [
                   "/ABSOLUTE/PATH/TO/YOUR/PROJECT/orchestrator.py"
               ]
           }
       }
   }
   

   将路径替换为您 orchestrator.py 文件的绝对路径。

3. 保存配置文件并重新启动 Claude for Desktop。

3. 在 Claude 中使用编排器

配置完成后，您可以：

1. 打开 Claude for Desktop
2. 单击侧边栏中的 MCP 服务器图标
3. 从可用服务器列表中选择“agent-orchestrator”
4. 开始与编排系统交互

Claude 将能够：

• 在不同的代理状态之间转换
• 从知识库存储和检索信息
• 跨状态转换维护对话上下文
• 访问特定于状态的提示词

代理状态

编排系统实现了一个状态机，具有以下状态：

• IDLE: 等待指令
• PLANNING: 为任务创建结构化计划
• RESEARCHING: 收集任务所需的信息
• EXECUTING: 执行计划的操作
• REVIEWING: 评估结果并确定后续步骤
• ERROR: 处理错误或意外情况

自定义系统

添加新状态

1. 将状态添加到 orchestrator.py 中的 AgentState 枚举
2. 为新状态创建一个提示词函数
3. 更新 _get_available_transitions() 中的转换逻辑
4. 在资源访问函数中为新状态添加处理程序

创建自定义工具

通过创建使用 @mcp.tool() 装饰的函数来添加新工具：

@mcp.tool()
def my_custom_tool(arg1: str, arg2: int, ctx: Context) -> str:
    """Description of what this tool does
    
    Args:
        arg1: Description of arg1
        arg2: Description of arg2
    """
    # Implementation here
    return "Result"

开发和测试

使用 MCP CLI

MCP CLI 提供了用于开发和测试的工具：

# 如果您尚未安装 MCP CLI，请安装它
pip install "mcp[cli]"

# 使用 MCP Inspector 测试您的服务器
mcp dev orchestrator.py

# 在 Claude Desktop 中安装
mcp install orchestrator.py

使用 Python 进行手动测试

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async with stdio_client(StdioServerParameters(command="python", args=["orchestrator.py"])) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        # Test state transitions
        await session.call_tool("transition_state", arguments={"new_state": "PLANNING"})

资源

• MCP Python SDK 文档
• 模型上下文协议规范

许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。