Python MCP Server Kit

Una plantilla inicial solo para backend, para servidores del Model Context Protocol seguros, tipados y comprobables. Está dirigida al protocolo MCP 2026-07-28 a través del SDK oficial de Python v2 y utiliza Streamable HTTP sin estado para el despliegue.

Características

• Herramientas tipadas con salida Pydantic estructurada

• Ejemplos de calculadora genérica y catálogo determinista

• Herramientas, recursos y prompts de MCP

• Frontera de token Bearer y alcances por herramienta

• Límites de tamaño de solicitud, host y tasa en proceso

• IDs de correlación y registros de solicitudes estructurados

• Sondas públicas de salud y preparación

• Pruebas unitarias y de integración HTTP

• Imagen Docker de producción sin ejecutar como root

• CI para lint, formato, tipado, pruebas, compilación de imagen, secretos y flujos de trabajo

Related MCP server: MCP TypeScript SDK

Arquitectura

HTTP request
  -> SecurityMiddleware (host, size, auth, rate limit, request ID)
  -> MCP Streamable HTTP transport
  -> typed tool/resource/prompt
  -> scope check
  -> deterministic domain function

El registro del protocolo vive en src/mcp_server_kit/server.py; la lógica de dominio reutilizable se mantiene en módulos separados. TokenStore es intencionadamente un límite de despliegue reemplazable, no un servidor de autorización completo.

Inicio rápido

Se requiere Python 3.11+.

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
Copy-Item .env.example .env
.\scripts\dev.ps1

El endpoint de MCP es http://127.0.0.1:8000/mcp. Las sondas de salud están disponibles en /health y /ready. Los tokens de demostración solo locales son:

• demo-reader — catalog:read

• demo-operator — catalog:read, calculator:use

Ejecute MCP Inspector con npx -y @modelcontextprotocol/inspector y establezca una cabecera Authorization: Bearer demo-operator. Hay una forma de cliente sin credenciales disponible en examples/client.json; inyecte MCP_CLIENT_TOKEN localmente.

Comandos

.\scripts\dev.ps1    # development server with reload
.\scripts\check.ps1  # lint, format check, mypy, and tests
docker compose up --build

Configuración

Nunca haga commit de .env. Consulte seguridad y despliegue antes de un despliegue expuesto a internet y adición de herramientas al ampliar el registro.

Notas de despliegue

Establezca MCP_ENVIRONMENT=production, MCP_AUTH_MODE=bearer, un valor de MCP_BEARER_TOKENS gestionado como secreto y la lista exacta de hosts públicos permitidos. Termine TLS en un proxy inverso de confianza. Reemplace el almacén de tokens inicial por su verificador de servidor de recursos OAuth 2.1 cuando se requiera delegación de usuarios o gestión del ciclo de vida de los tokens.

Licencia

MIT