tin-canMCP

Una plantilla prescriptiva para crear servidores MCP grandes (más de 20 herramientas) organizados como un catálogo escalonado con un intermediario (broker).

Cada servidor tin-canMCP expone exactamente 7 herramientas al cliente de IA, independientemente del tamaño del catálogo. El catálogo en sí puede contener cientos de herramientas; el intermediario limita la visibilidad para que la IA solo vea un subconjunto acotado y relevante para la tarea en cualquier momento.

Cuándo usar esta plantilla

Utilice tin-canMCP cuando su MCP vaya a envolver muchas herramientas (binarios CLI, puntos finales de API, comandos de AppleScript, métodos de SDK). El patrón de intermediario mantiene el número de herramientas visibles para la IA por debajo de un límite amigable para la caché.

NO utilice tin-canMCP si solo necesita de 3 a 10 herramientas sin agrupación. Un servidor FastMCP simple es más sencillo.

Related MCP server: production-grade-mcp-agentic-system

Las 7 herramientas que expone cada servidor

Las herramientas de dominio solo se alcanzan a través de catalog_run_tool. Consulte HOW-TO-USE.md para conocer el flujo de trabajo completo.

Inicio rápido

pip install -r requirements.txt
cp .env.example .env

# Scaffold a catalog for your domain
python scripts/scaffold_catalog.py \
  --name mydomain \
  --source cli \
  --tools list,get,create,delete \
  --out catalog-runtime \
  --force

# Validate the registry is structurally sound
python scripts/validate_registry.py catalog-runtime

# Run the server
python main.py --transport=stdio

En este punto, el servidor se carga, expone las 7 herramientas del intermediario, y catalog_run_tool se negará a ejecutar nada hasta que complete los marcadores TODO en catalog-runtime/registry/tools.json y los manifiestos por herramienta en catalog-runtime/tools/.

Siguiente: lea HOW-TO-USE.md; le guiará a través de la creación de manifiestos de herramientas, estrategias de agrupación y asignación de niveles.

Diseño del repositorio

.
├── app/
│   ├── catalog_runtime/     # Broker, loader, executor (DO NOT modify)
│   ├── tools/               # Registers the 7 broker MCP tools (DO NOT modify)
│   ├── prompts/             # Optional MCP prompts
│   ├── config.py            # Env-backed settings
│   └── server.py            # FastMCP server
├── catalog-runtime/
│   ├── registry/            # YOUR 7 registry JSON files — edit these
│   ├── tools/               # YOUR per-tool manifests — edit these
│   └── schema/              # JSON Schemas for registry files (reference)
├── scripts/
│   ├── scaffold_catalog.py  # Generate a registry skeleton
│   └── validate_registry.py # Check invariants (run in CI)
├── ai-prompts/              # Master prompt + per-source hints for AI implementation
├── docs/
│   └── catalog-runtime-template.md  # Full schema contract reference
├── main.py
└── HOW-TO-USE.md            # Prescriptive authoring workflow

Configuración

Variables de entorno (a través de .env o shell):

• VAR_CATALOG_RUNTIME_DIR — ruta a su tiempo de ejecución de catálogo (predeterminado: catalog-runtime/ local del repositorio)

• VAR_SERVER_NAME — nombre del servidor MCP mostrado a los clientes (predeterminado: tin-canMCP)

• VAR_COMMAND_TIMEOUT_SECONDS — tiempo de espera por herramienta (predeterminado: 20)

• VAR_MAX_OUTPUT_CHARS — umbral de truncamiento para stdout/stderr (predeterminado: 12000)

• MCP_TRANSPORT — stdio, sse o web (predeterminado: stdio)

Qué NO hacer

• No añada decoradores @mcp.tool() para sus herramientas de dominio en app/tools/. Eso anula el propósito del intermediario. Añada entradas al catálogo en su lugar.

• No aumente max_tools_per_activation por encima de ~15. El objetivo principal es una superficie visible acotada.

• No ponga todas las herramientas en canonical. Utilice los niveles advanced e internal para diferir las herramientas de nicho.

• No omita validate_registry.py. Los errores de referencia cruzada son silenciosos.

Agradecimientos

Esta plantilla se inspiró en el trabajo de josharsh sobre patrones de intermediarios MCP.

Licencia

MIT. Consulte LICENSE.