ARCH MCP 服务器

使用说明（Markdown 格式）

• 项目简介

  • ARCH 仪表盘与 Agent Runtime 的核心组件之一，提供一个可扩展的 MCP 服务器，用于在 LLM 客户端与后端 Agent 之间中介和协作。服务器负责注册和管理工具、控制访问、渲染和提供 Prompts/模板，以及在需要时提供 GitHub 集成的能力。

• 主要功能点

  • MCP 服务器核心协议支持：通过 SSE/HTTP 提供 MCP 服务，支持客户端查询工具、执行工具、获取上下文等。
  • 工具/catalog 管理：定义 Worker、Archie-only 和系统工具，以及可选的 GitHub 工具集合，按角色权限动态分发。
  • 访问控制与权限流：区分 Archie 与 Worker 的工具集，系统工具对所有代理可访问；集成运行时允许列表与权限请求工作流（handle_permission_request）。
  • GitHub 集成（可选）：在配置中启用后，提供创建/列出 Issue、Close Issue、Update Issue、Create Milestone 等工具。
  • 多代理协调：支持 Archie 与工作代理并发工作，工具调用可通过 MCP 服务器分发到对应的代理会话。
  • 服务器与会话生命周期：MCP 服务器实例可按代理逐个创建、挂载到对应会话并路由工具调用和消息流。
  • 安全与自治：设计中包含自定义许可、运行时工具限制、以及对会话上下文（如 BRIEF、Open PR、会话历史）的支持。
  • 流式输出与事件：通过 Stream/SSE 逐步输出事件，便于前端 UI（如 Textual Dashboard）或客户端实时解析。
  • 配置驱动：结合 StateStore/Worktree/SessionManager 等组件，提供完整的端到端工作流支持。

• 安装与运行要点

  • 该仓库的 MCP 服务器作为 ARCH 生态的一部分存在，通常与 Arch orchestrator 一同启动。测试用例使用 MCPServer 在内存状态或临时状态目录下启动，示范了以 uvicorn 作为后台服务的运行方式。
  • 运行前应确保依赖项满足，如 Python 环境、mcp 1.26+（包含 sseclient/ClientSession）、Git、Docker 与 gh CLI（如启用 GitHub 功能时）。

• 服务器配置示例（JSON 配置，供 MCP 客户端使用）

  • 服务器端配置用于 MCP 客户端与服务端间的对接，通常包含服务器名称、启动命令及参数等。以下信息仅为描述性文本，实际客户端无需修改服务器端代码：
  • server name: arch
  • command: 启动服务器的命令（示例性描述，实际在代码中通过运行环境启动）
  • args: 启动参数（如端口、配置路径、是否启用沙箱、并发配置等）
  • 说明：MCP 客户端需要的配置通常由 generate_mcp_config 等工具输出，用于指向服务器的 URL 和连接方式（如 SSE 的 URL、端点路径等）。

• 基本使用方法

  • 启动与连接：启动 ARCH 的 MCP 服务端，与客户端建立 SSE 连接，获取工具列表并执行工具调用。
  • 工具执行：通过 MCP 的工具调度，在 Archie/Worker 之间分发工作、发送消息、更新状态、保存进度等。
  • 运行时权限：当需要临时权限时，系统会通过权限请求对话进行处理，支持“仅这次”、“始终允许”或拒绝等选项。
  • GitHub 集成使用：在配置启用 GitHub 时，Archie 可以访问与操作 GitHub 相关的工具，如创建 Issue、拉取 Milestone 等。

• 进一步使用的关键信息

  • MCPServer 提供的工具集合按角色分组，Archie 拥有更广泛的工具集，Worker 仅暴露通用工作工具。
  • 服务器设计包含对 GitHub、容器化代理、以及 BRIEF.md 的协作性操作，为复杂的 AI 协作工作流提供上下文服务。
  • 流式输出与事件驱动为前端 UI（如仪表盘）或客户端实现提供实时反馈能力。