mcp-prov

Локальный MCP-прокси на Python, который оборачивает существующий MCP-сервер в n8n (экземпляр обеспечения Metrotel). Добавляет кэш, логирование, составной инструмент диагностики и собственную Bearer-аутентификацию, не затрагивая бэкенд.

Образ в Docker Hub: metrotel/mcp-prov

• 🌐 Говорит на stdio (Claude Code / встроенные клиенты) или HTTP (Claude Desktop и другие)

• 🔐 Изолирует upstream-токен: никогда не выходит к клиенту

• ⚡ Кэш в памяти 60 с для идемпотентных чтений (конфигурация через переменную окружения)

• 📝 JSON-lines лог каждого вызова инструмента (tool, args, cached, duration_ms, error)

• 🛠 Открывает 32 upstream-инструмента + составной инструмент diagnostico_completo

• ♻️ Переинициализирует сессию, если upstream её закрывает (известная ошибка n8n MCP)

• 🚀 Развёртывание: Docker / Docker Swarm / Kubernetes / systemd user unit / автономный Python

• 💾 Том /data для постоянных логов (и будущего кэша)

Зачем это нужно

MCP-сервер, встроенный в поток n8n Metrotel, закрывает long-poll SSE после периода бездействия, и такие клиенты, как mcp-remote, начинают шумные повторные попытки. Кроме того, upstream-токен хранился в открытом виде в JSON-конфигах.

Этот прокси:

• Устраняет long-poll: каждый вызов инструмента открывает собственный HTTP-запрос к upstream и закрывает его по завершении.

• Изолирует upstream-токен (X-Prov-MCP-Key): он живёт только в env-файле прокси, а не в конфигах Claude Desktop / Claude Code.

• Добавляет кэш для повторяющихся чтений (например, один и тот же contexto_servicio несколько раз за несколько минут).

• Добавляет составной инструмент, который объединяет несколько upstream-инструментов и возвращает сводку — избавляет модель от необходимости оркестрировать 3 вызова, когда можно запросить один.

Related MCP server: @qelos/better-mcp

Требования

• Python 3.10+

• uv (рекомендуется, или pip)

• Сетевой доступ к upstream 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 + том: см. swarm/README.md.

Развёртывание как systemd user unit

Шаблон в 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 (community): ~/.config/Claude/claude_desktop_config.json

Полный пример см. в examples/claude_desktop_config.example.json.

Переменные окружения

Доступные инструменты

Все инструменты upstream переэкспонируются как есть (на момент написания — 32), плюс один составной:

• diagnostico_completo(service_number) — вызывает contexto_servicio → Topologia → (если подпродукт ISI) ISI_Check_IP и возвращает сгруппированную сводку. Полезен как «точка входа» для быстрой диагностики услуги по её номеру.

Подробности об upstream-инструментах см. в коллекции 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 МБ × 3.

Безопасность

См. SECURITY.md. Вкратце:

• Bearer обязателен в HTTP-режиме (промежуточное ПО Starlette).

• Upstream-токен никогда не покидает прокси.

• Env-файл с учётными данными имеет chmod 600 и не входит в git.

• .env в .gitignore.

Лицензия

MIT — см. LICENSE.