Mithril Proxy

米特拉代理

          * . * . *
      .  ___________  .
    *  /      *      \  *
   .  / ╔═══════════╗ \  .
   * /  ║ ╔═══════╗ ║  \ *
   .|   ║ ║       ║ ║   |.
   *|   ║ ║MITHRIL║ ║   |*
   .|   ║ ║       ║ ║   |.
   * \  ║ ╚═══════╝ ║  / *
   .  \ ╚═══════════╝ /  .
    *  \      *      /  *
        \     *     /
         \    *    /
          \   *   /
           \  *  /
            \ * /
             \ /
              V

“轻而比回火钢硬”

一个最小的Python MCP代理服务器。位于MCP客户端（Claude Desktop、Cursor等）和远程或本地MCP服务器之间，通过URL路径前缀路由请求，并转发承载令牌不变。

快速开始

# Install dependencies
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Add at least one destination
cat > config/destinations.yml <<'EOF'
destinations:
  my-server:
    type: streamable_http
    url: https://mcp.example.com/mcp
EOF

# Run
PYTHONPATH=src uvicorn mithril_proxy.main:app --host 0.0.0.0 --port 3000

客户端连接到 http://localhost:3000/my-server/mcp.

特性

• 流式HTTP代理 --转发MCP流式HTTP传输（POST/GET/DELETE /mcp)到偏远的上游；透明地传输SSE响应
• SSE代理 --对旧上游的传统MCP over SSE支持；重写 endpoint 事件，以便客户端通过代理发回消息
• stdio桥 --生成本地子流程（例如。 npx MCP服务器），在所有会话中共享；将stdin/stdout桥接到MCP流式HTTP传输，并在退出时自动重启
• 传递身份验证 --转发到上游的承载令牌保持不变；没有代理级凭据存储
• 审核日志记录 --完整的JSON-RPC请求/响应体， rpc_id，以及 mcp_method 在每条记录线上；32KB截断；切换至 AUDIT_LOG_BODIES=false
• 结构化JSON日志 --每个请求一行，写入可配置文件
• 健康检查 — GET /health → {"status": "ok"}

部署

看 设置.md 有关完整的Raspberry Pi/systemd安装说明。

运行测试

pip install pytest pytest-asyncio httpx
PYTHONPATH=src pytest tests/ -v

项目结构

src/mithril_proxy/
  main.py     FastAPI app + lifespan + route registration
  proxy.py    SSE proxy + Streamable HTTP forwarding + session management
  bridge.py   stdio-to-Streamable-HTTP bridge + per-destination subprocess lifecycle
  config.py   YAML config loader + validation
  secrets.py  Per-destination env vars from secrets.yml
  logger.py   JSON log formatter + writer (audit logging)
  utils.py    Shared request helpers (source_ip)
config/
  destinations.yml
  secrets.yml        (gitignored)
systemd/
  mithril-proxy.service
tests/
install.sh
SETUP.md