Argus MCP Gateway

关键词

模型上下文协议JSON-RPC 网关Telegram 机器人网关会话管理任务调度

使用说明（简要，便于快速上手）

  • 项目简介

    • Argus 是一个自托管的助手网关，内置 MCP 服务器实现，能够通过 JSON-RPC 统一向 LLM 客户端提供资源、工具、以及提示模板等上下文能力，并支持会话管理和多种传输方式（HTTP、WebSocket、StdIO 等）。

  • 主要功能点

    • MCP 服务器核心
      • 支持初始化对话、读取服务器能力、列出工具、调用工具等标准 MCP 操作，使用 JSON-RPC 2.0 语义进行请求/响应。
      • 会话级别的认证/授权，基于派生令牌实现多会话隔离。
    • 工具与能力
      • 工具列表包括节点查询、发送消息、Cron 管理、Node 调用等，LLM 客户端可通过工具接口执行外部功能。
    • 资源与上下文
      • 提供提示模板与项目上下文的读取与渲染，结合 Workpace/Agents/Cron 的状态，向 LLM 提供一致的上下文信息。
    • 会话与状态管理
      • 会话创建、绑定、跨 Agent 的会话解析、系统事件队列、Cron 的执行与写回等机制，确保长期对话的上下文连续性。
    • 安全与拓展
      • 通过 ARGUS_MCP_TOKEN/ARGUS_TOKEN 的派生令牌实现 session 级别授权，兼容多传输协议；集成 Telegram、Node、以及可选的 Codex/OpenAI 代理。

  • 安装与运行步骤

    • 需求：Docker + Docker Compose（如 README 所述）
    • 步骤概览
      • 设置环境变量：ARGUS_MCP_TOKEN（派生会话令牌的 master 秘钥）和其他网关配置（如 ARGUS_HOME_HOST_PATH、ARGUS_WORKSPACE_HOST_PATH）。
      • 启动网关及相关运行时组件：
        • 通过 docker compose 启动 Argus 网关（及 Telegram 机器人等可选组件）。
      • 验证 MCP 服务
        • 以 MCP 客户端向 /mcp 端点发送 JSON-RPC 请求，首次使用需初始化会话，服务端会返回会话 ID 以及所支持的协议版本。
    • 运行后端与 MCP 客户端通信要点
      • 请求头需要包含：
        • MCP-Session-Id：会话 ID（从服务器初始化返回的 header 获取并在后续请求中携带）
        • Authorization：Derived token（派生自 MASTER 秘钥，用于认证并确定会话范围）
      • 请求体采用 JSON-RPC 2.0 结构，必要时支持批量请求。
    • 常见问题
      • 未配置 ARGUS_MCP_TOKEN 或未正确派生会话令牌时，请求将返回 401/403，需在服务器端配置正确的 master 秘钥并完成初始化流程。
      • 若使用 Docker 提供的运行时，请确保 ARGUS_HOME_HOST_PATH 与 ARGUS_WORKSPACE_HOST_PATH 指向正确的宿主机路径，以确保工作区和工作空间的持久化。

  • 服务器配置（MCP 客户端启动所需信息，JSON 格式） 说明：MCP 客户端需要的启动配置用于连接 Argus 的 MCP 服务器。配置包含服务器名称、启动命令以及参数。具体参数请按下方示例理解并替换为实际运行时环境的路径与参数。示例仅作格式参考，实际客户端实现可能略有差异。 { "serverName": "Argus MCP Gateway", "command": "/path/to/mcp-client-runtime", "args": [ "--server", "http://<host>:<port>/mcp", "--token", "<derived-token>", // OAuth 风格的派生会话令牌，由 master 秘钥和会话 ID 派生得到 "--session", "<session-id>" // MCP 会话标识，用于作用域化访问 ], "notes": "请在 MCP 客户端启动时提供上述服务器地址与派生令牌，连接后会话将基于 sessionId 实现隔离访问。实际 runtime 的可执行路径请根据部署环境替换。" }

  • 基本使用方法

    • 第一步：初始化会话
      • 使用 MCP 客户端向 /mcp 发送 initialize 请求，获取会话 ID、协议版本及服务能力，并在响应头中获得 MCP-Session-Id。
    • 第二步：后续请求
      • 在每次请求时在 HTTP 头中携带 Authorization: Bearer <派生令牌> 以及 MCP-Session-Id: <会话ID>，并在请求体中使用正确的 JSON-RPC 结构。
    • 第三步：工具调用
      • 通过 tools/list 获取可用工具，通过 tools/call 调用具体工具完成任务，例如查询节点、发送消息、管理 Cron、调用节点等。
    • 第四步：整合到 LLM 流程
      • 将 MCP 的响应结构整合进 LLM 的上下文注入，利用 Argus 提供的资源、提示模板、以及 Cron/Heartbeat 机制实现持续性、可控的对话能力。

  • 运行与联调的小贴士

    • MCP 会话是基于独立的 session 级别授权，确保不同的 Agent/会话间数据隔离。
    • 如需扩展，请关注 /mcp 的 batch 请求处理逻辑，支持一次性多条 JSON-RPC 消息。
    • 参考代码中对工具返回内容的构造与结构化输出，便于下游 LLM 客户端进行解析与渲染。

  • 备注

    • 该实现的 MCP 服务端具备完整的初始化、工具列表与调用、以及会话管理能力，且包含对称的 HTTP/WebSocket 支持接口，具备在生产环境中作为后端上下文服务的可运行性与扩展性。

服务器信息

访问项目