mcp-prov

本地 Python MCP 代理，用于包装 n8n 中现有的 MCP 服务器（Metrotel 的 provisioning 实例）。在不触碰后端的情况下，添加缓存、日志、组合诊断工具和自有的 Bearer 认证。

Docker Hub 镜像：metrotel/mcp-prov

• 🌐 支持 stdio（Claude Code / 嵌入式客户端）或 HTTP（Claude Desktop 等）

• 🔐 隔离上游 token：永远不会暴露给客户端

• ⚡ 针对幂等读取的 60 秒内存缓存（可通过环境变量配置）

• 📝 每次工具调用的 JSON-lines 日志（tool、args、cached、duration_ms、error）

• 🛠 暴露上游 32 个工具 + 一个组合工具 diagnostico_completo

• ♻️ 如果上游关闭会话，则重新初始化会话（n8n MCP 的已知问题）

• 🚀 部署方式：Docker / Docker Swarm / Kubernetes / systemd 用户单元 / 独立 Python

• 💾 /data 卷用于持久化日志（以及未来的缓存）

为什么存在

Metrotel 的 n8n 流程中嵌入的 MCP 服务器会在空闲一段时间后关闭 long-poll SSE，而像 mcp-remote 这样的客户端会开始发出嘈杂的重试。此外，上游 token 之前以明文形式存在于配置 JSON 中。

此代理：

• 消除 long-poll：每次工具调用都会向上游发起自己的 HTTP 请求，并在完成后关闭。

• 隔离上游 token（X-Prov-MCP-Key）：仅存在于代理的 env 文件中，不会出现在 Claude Desktop / Claude Code 配置中。

• 添加缓存，用于重复的读取（例如，在几分钟内多次请求相同的 contexto_servicio）。

• 添加一个组合工具，它链式调用多个上游工具并返回摘要——避免模型在只需一次调用时编排 3 次调用。

Related MCP server: @qelos/better-mcp

要求

• Python 3.10+

• uv（推荐，或 pip）

• 能够通过网络访问上游 MCP 服务器，并具有有效的 X-Prov-MCP-Key 头

快速开始

Docker（推荐，无需本地构建）

docker run -d --name prov-mcp -p 8767:8767 \
  -e PROV_MCP_KEY='pmcc_...' \
  -e PROV_MCP_AUTH_TOKEN='pmcp_...' \
  -v prov-data:/data \
  --restart unless-stopped \
  metrotel/mcp-prov:0.2.2

或使用仓库中的 docker-compose.yml：

git clone https://github.com/datacenter-metrotel/mcp-prov.git
cd mcp-prov
cp .env.example .env && chmod 600 .env    # editá .env
docker compose up -d

日志持久化在 prov-data 卷中（挂载到 /data/logs）：

docker exec prov-mcp tail -f /data/logs/calls.log

原生 HTTP 模式（无需 Docker）

git clone https://github.com/datacenter-metrotel/mcp-prov.git
cd mcp-prov

cp .env.example .env
chmod 600 .env
# editá .env con los valores reales

# Arrancar en foreground
uvx --from . prov-mcp-proxy
# server escuchando en http://0.0.0.0:8767/mcp

验证：

KEY=$(grep '^PROV_MCP_AUTH_TOKEN=' .env | cut -d= -f2)
curl -sS -L -X POST http://127.0.0.1:8767/mcp \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}'

stdio 模式（适用于 Claude Code / Cursor 或其他启动进程的客户端）

export PROV_MCP_KEY='pmcc_...'
export PROV_MCP_TRANSPORT=stdio
uvx --from . prov-mcp-proxy

在 .mcp.json 中（Claude Code）：

{
  "mcpServers": {
    "prov": {
      "command": "uvx",
      "args": ["--from", "/ruta/al/repo", "prov-mcp-proxy"],
      "env": { "PROV_MCP_KEY": "${PROV_MCP_KEY}" }
    }
  }
}

在 Kubernetes / Docker Swarm 上部署

• Kubernetes 使用 envFrom.secretRef + PersistentVolumeClaim： 参见 k8s/README.md。

• Docker Swarm 使用 raft 中加密的 secrets + 卷：参见 swarm/README.md。

部署为 systemd 用户单元

模板位于 systemd/prov-mcp-proxy.service.example：

mkdir -p ~/.config/systemd/user ~/.config/prov-mcp-proxy
cp systemd/prov-mcp-proxy.service.example ~/.config/systemd/user/prov-mcp-proxy.service
cp .env.example ~/.config/prov-mcp-proxy/env
chmod 600 ~/.config/prov-mcp-proxy/env
# editá ~/.config/prov-mcp-proxy/env con los valores reales

systemctl --user daemon-reload
systemctl --user enable --now prov-mcp-proxy.service
systemctl --user status prov-mcp-proxy.service

要在不登录的情况下在重启后保持运行： sudo loginctl enable-linger $USER。

从 Claude Desktop 使用

编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "prov": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "http://<HOST_IP>:8767/mcp",
        "--allow-http",
        "--transport", "http-only",
        "--header", "Authorization:Bearer <PROV_MCP_AUTH_TOKEN>"
      ]
    }
  }
}

配置路径：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

• Windows：%APPDATA%\Claude\claude_desktop_config.json

• Linux（社区）：~/.config/Claude/claude_desktop_config.json

完整示例见 examples/claude_desktop_config.example.json。

环境变量

暴露的工具

上游的所有工具都原样重新暴露（撰写本文时有 32 个），外加一个组合工具：

• diagnostico_completo(service_number) — 调用 contexto_servicio → Topologia →（如果子产品是 ISI）ISI_Check_IP，并返回分组摘要。适合作为“入口点”，根据服务号码快速诊断服务。

上游工具的详细信息请参见 postman/ 中的 Postman 集合。

缓存

从不缓存的工具（主动效果或易变数据）：

• Ping_tool

• ATA_Test_1、ATA_Test_2、ATA_Test_3

• Gestion_ACS

• Obtener_backup_equipo

其余工具进入缓存，TTL 可配置（默认 60 秒）。键包括工具名称 + 规范化参数的 SHA1 哈希。

日志

每次工具调用都会记录到 ~/.cache/prov_mcp_proxy/calls.log，作为一行 JSON，包含 ts、tool、args、cached、duration_ms、error。自动轮换 5 MB × 3。

安全性

参见 SECURITY.md。摘要：

• HTTP 模式下强制 Bearer（Starlette 中间件）。

• 上游 token 永远不会离开代理。

• 包含凭据的 env 文件使用 chmod 600，且不在 git 中。

• .env 在 .gitignore 中。

许可证

MIT — 参见 LICENSE。