Ahma HTTP Bridge for MCP

关键词

沙箱隔离流式传输JSON-RPC会话管理子进程通信

使用说明（Markdown 格式）

  • 项目简介

    • Ahma HTTP Bridge 是一个实现 MCP Streamable HTTP 传输的服务器端组件。它通过对每个客户端会话创建独立的 MCP 子进程来实现严格的沙箱隔离，管理握手流程、根目录协商、工具调用、以及对外暴露的 JSON-RPC 接口。桥接支持 STDIO 模式与 HTTP/ SSE 模式，确保 LLM 客户端能够安全地获取上下文、执行工具、并获取提示模板。

  • 主要功能点

    • 会话隔离与沙箱绑定：为每个客户端会话启动独立 MCP 子进程，沙箱范围在初次处理 roots/list 时绑定，后续不可更改。
    • 传输模式：提供 STDIO 与基于 HTTP 的 SSE/POST 双向传输，满足不同客户端的集成需求。
    • 握手流程：实现 initialize → SSE 连接 → initialized 通知 → roots/list 请求并返回，最终完成沙箱配置。
    • 资源与工具管理：桥接通过 MCP 子进程实现工具调用与资源访问的分离，确保上下文安全。
    • 错误与超时处理：对握手、请求超时、以及沙箱配置失败等情形提供明确的 JSON-RPC 错误信息与 HTTP 状态码。
    • 安全性与日志：默认开启 Kernel 级沙箱、日志输出可开启/关闭颜色，支持日志分层输出。

  • 安装步骤

    • 使用 cargo 构建：在仓库根目录执行 cargo build --release
    • 运行桥接服务器：使用 cargo run -p ahma_http_bridge -- --mode http --tools-dir .ahma --sandbox-scope /path/to/workspace（可选的其他参数如 --server-command、--handshake-timeout-secs 等按需配置）
    • MCP 子进程依赖：桥接会在运行时自动启动 ahma_mcp 子进程（默认命令名为 ahma-mcp，若有自定义请通过 --server-command 指定）

  • 服务器配置（json）示例注释 配置说明（请勿直接复制到代码中）的 JSON 表述，用于 MCP 客户端了解如何启动与连接 MCP 服务器（该 JSON 不属于代码，供配置示例参考）： { "servers": { "AhmaHTTPBridge": { "type": "http", "command": "ahma-http-bridge", "args": [ "--mode", "http", "--sandbox-scope", "/path/to/workspace", "--tools-dir", ".ahma", "--handshake-timeout-secs", "45" ], "description": "HTTP 桥接 MCP 服务器，提供握手、roots/list、以及工具调用的能力" } // MCP 客户端不需要此处代码实现，只需了解 bridge 的启动参数与工作方式 } }

    参数要点说明

    • server name：AhmaHTTPBridge，Bridge 提供的对外服务器标识名。
    • command：ahma-http-bridge 的可执行路径（默认在本地 cargo 构建产物中）。
    • args：启动桥接服务器时的参数，例如 mode=http、sandbox-scope、tools-dir 等。
    • 备注：MCP 客户端需要知道桥接服务器的启动方式与连接端点，桥接会在运行时创建独立 MCP 子进程来处理具体的 MCP 会话。

  • 基本使用方法

    1. 启动桥接服务器（HTTP 模式，默认本地端口 3000，需配置工作区根目录以绑定沙箱范围）：准备工作区和工具配置后运行桥接，客户端通过 http://127.0.0.1:3000/mcp 进行 JSON-RPC 交互。握手完成后，桥接将建立与 MCP 子进程的通信并开始执行请求。
    2. 客户端握手流程：通过 initialize 发起会话，打开 SSE 流并发送 initialized 通知，桥接会请求根目录列表（roots/list），客户端返回根目录以锁定沙箱范围。
    3. 资源与工具调用：握手完成且沙箱锁定后，客户端可通过 tools/call、tools/list 等接口调用工具，桥接将请求转发给相应的 MCP 子进程并将输出回传给客户端。
    4. 会话管理与清理：使用 HTTP DELETE /mcp 且带有 Mcp-Session-Id 头来终止会话，桥接将关闭对应子进程并回收资源。
    5. 安全与兼容性：桥接默认开启沙箱边界，支持多种传输模式，若目标平台无法完整开启内核沙箱，脚本会提供降级选项以确保测试可用。

  • 关键词 沙箱隔离, 流式传输, JSON-RPC, 会话管理, 子进程通信

  • 分类ID 6

服务器信息

访问项目