mcp-prov

#mcp-prov

기존 n8n(메트로텔 프로비저닝 인스턴스)의 MCP 서버를 감싸는 Python 기반 로컬 MCP 프록시입니다. 백엔드를 건드리지 않고 캐시, 로깅, 복합 진단 도구, 자체 Bearer 인증을 추가합니다.

Docker Hub 이미지: metrotel/mcp-prov

• 🌐 stdio(Claude Code / 임베디드 클라이언트) 또는 HTTP(Claude Desktop 등) 지원

• 🔐 업스트림 토큰 격리: 클라이언트에게 절대 노출되지 않음

• ⚡ 멱등성 읽기 작업을 위한 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 같은 클라이언트는 시끄러운 재시도를 시작합니다. 또한 업스트림 토큰이 평문으로 구성 JSON에 존재했습니다.

이 프록시는:

• long-poll 제거: 각 도구 호출은 업스트림에 자체 HTTP 요청을 열고 완료 시 닫습니다.

• 업스트림 토큰 격리(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에 암호화된 시크릿 + 볼륨 사용: 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에 ts, tool, args, cached, duration_ms, error가 포함된 JSON 라인으로 기록됩니다. 자동 회전 5MB × 3.

보안

SECURITY.md 참조. 요약:

• HTTP 모드에서 Bearer 필수(Starlette 미들웨어).

• 업스트림 토큰은 프록시 밖으로 나가지 않습니다.

• 자격 증명이 있는 env 파일은 chmod 600으로, git 외부에 둡니다.

• .env는 .gitignore에 포함.

라이선스

MIT — LICENSE 참조.