关键词

多代理编排AI 协作资源与工作流管理模型协同JSON-RPC 服务

使用说明

项目简介

Madrox 是一个基于 MCP（Model Context Protocol）的服务器端实现，旨在让若干 AI 模型（如 Claude、Codex 等）以可扩展的层次结构协同工作。服务器具备以下核心能力：

  • 资源（Resources）托管与数据访问
  • 工具（Tools）注册与执行，LLM 可以通过工具调用外部能力
  • Prompt 模板（Prompts）的定义、渲染与定制
  • 通过 JSON-RPC 与客户端通信，支持不同传输协议（HTTP/SSE、STDIO）
  • 会话管理、能力声明、以及跨会话状态持久化
  • 安全隔离、并发任务、任务分派、以及复杂的多模型网络编排

主要功能点

  • MCP 协议实现与 JSON-RPC 请求处理：服务器端对 MCP 请求（如 spawn、send、terminate、get status 等）进行解析、执行并返回 JSON-RPC 格式的响应。
  • 多模型协同网络：支持 Claude 家族模型和 Codex 等，能够在同一网络中混合使用不同模型以获得更优解。
  • 层级化的代理架构与双向通信：父代理与子代理之间实现 bidirectional 通信与协同工作流。
  • 资源与工作区隔离：每个实例拥有独立工作区，避免资源冲突。
  • 传输协议支持：HTTP/SSE（适用于 Claude Code 客户端）与 STDIO（适用于 Codex CLI 客户端）。
  • 监控、资源限制与健康检查：对令牌、成本、超时等进行控制，定期健康检查并可对异常实例进行清理。
  • 模板与模板化工作流：提供用于快速组建任务的模板与工作流模板，便于快速上手和扩展。
  • 开放式配置与插件化能力：支持 per-instance 的 MCP 配置、Playwright 等工具的集成，以及自定义工具与配置。

安装与运行步骤

  • 克隆并进入仓库
    • git clone <仓库地址>
    • 进入仓库目录
  • 安装运行依赖与工具（根据仓库提供的说明）
  • 启动服务器
    • 通过 HTTP/SSE 传输（Claude Code 客户端）： MADROX_TRANSPORT=http 或直接： python run_orchestrator.py 或使用 uv 直接启动（示例：uv run python run_orchestrator.py）
    • 通过 STDIO 传输（Codex CLI 客户端）： MADROX_TRANSPORT=stdio python run_orchestrator.py
  • MCP 客户端连接配置（Madrox 作为 MCP 服务器，对应 Claude Desktop/Claude Code 的设置）
    • 通过 HTTP 传输连接 Madrox： url: http://localhost:8001/mcp transport: http
    • 通过 STDIO 传输连接 Madrox： 使用服务器的 STDIO 传输，Madrox 将通过 STDIO 提供 MCP 功能
  • 客户端示例（无需直接拷贝代码，按如下描述进行配置）
    • HTTP 连接示例（Claude Code 客户端） 配置项应包含 madrox 对应的 url 与 transport 字段
    • STDIO 连接示例 配置 madrox 的启动命令及工作目录、必要的环境变量（如 ANTHROPIC_API_KEY 等）
  • 验证
    • 使用 MCP 客户端发起基本请求，例如创建一个简单的前端/后端代理，观察返回的内容是否包含 content、ids、以及正确的错误信息
    • 使用 /health、/tools、/instances 等 REST/HTTP 端点进行状态检查（若后端实现了 REST 端点）

服务器配置（MCP 客户端连接 Madrox 的示例配置，基于仓库实现的传输模式）

  • HTTP 传输（适用于 Claude Code/Claude Desktop） JSON 配置示例（仅描述字段，不提供可执行代码）： { "server_name": "madrox", "transport": "http", "url": "http://localhost:8001/mcp", "notes": "Madrox 将作为 MCP 服务器对接 Claude Code，HTTP 传输用于 JSON-RPC 通信" }

  • STDIO 传输（适用于 Codex CLI，直接通过 STDIO 与服务器交互） JSON 配置示例（仅描述字段，不提供可执行代码）： { "server_name": "madrox", "transport": "stdio", "command": "uv", "args": ["run", "python", "run_orchestrator.py"], "cwd": "/path/to/madrox", "env": { "ANTHROPIC_API_KEY": "your-api-key" }, "notes": "STDIO 传输用于 Codex CLI 客户端，Madrox 会以 STDIO 方式提供 MCP 功能" }

  • 备注

    • 客户端配置的核心目标是指明 MCP 服务器的启动方式或连接方式，Madrox 提供两种传输模式：HTTP/SSE（远程通信）和 STDIO（本地沟通）
    • 服务器也可通过环境变量控制传输模式与连接参数，例如 MADROX_TRANSPORT、ANTHROPIC_API_KEY 等

基本使用方法

  • 启动后，使用 Claude Code/Claude Desktop 将 Madrox 作为 MCP 服务器注册配置，之后就可以通过 MCP 工具调用 spawn、send、terminate 等操作，进行多代理的协作任务
  • 可以按需求注册和执行工具（Tools），以及定义/使用 Prompt 模板，与 LLM 进行灵活的对话与任务分解
  • 通过查看 /health、/tools、/instances 等接口查看服务器健康状况、已注册工具及实例信息
  • 使用模板快速部署特定工作流，如软件开发、研究分析等跨模型协作场景

信息

分类

AI与计算

访问项目