tin-canMCP

Eine präskriptive Vorlage für den Aufbau großer MCP-Server (20+ Tools), organisiert als gestufter Katalog mit einem Broker.

Jeder tin-canMCP-Server stellt dem KI-Client genau 7 Tools zur Verfügung, unabhängig von der Kataloggröße. Der Katalog selbst kann Hunderte von Tools enthalten; der Broker steuert die Sichtbarkeit, sodass die KI zu jedem Zeitpunkt nur eine begrenzte, aufgabenrelevante Teilmenge sieht.

Wann diese Vorlage zu verwenden ist

Verwenden Sie tin-canMCP, wenn Ihr MCP viele Tools (CLI-Binärdateien, API-Endpunkte, AppleScript-Befehle, SDK-Methoden) kapseln soll. Das Broker-Muster hält die Anzahl der für die KI sichtbaren Tools unter einer cache-freundlichen Obergrenze.

Verwenden Sie tin-canMCP NICHT, wenn Sie nur 3–10 Tools ohne Gruppierung benötigen. Ein einfacher FastMCP-Server ist hierfür besser geeignet.

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

Die 7 Tools, die jeder Server bereitstellt

Domänen-Tools sind nur über catalog_run_tool erreichbar. Siehe HOW-TO-USE.md für den vollständigen Arbeitsablauf.

Schnellstart

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

An diesem Punkt lädt der Server, stellt die 7 Broker-Tools bereit, und catalog_run_tool wird die Ausführung verweigern, bis Sie die TODO-Markierungen in catalog-runtime/registry/tools.json und die Tool-spezifischen Manifeste unter catalog-runtime/tools/ ausgefüllt haben.

Weiter: Lesen Sie HOW-TO-USE.md – es führt Sie durch das Erstellen von Tool-Manifesten, Gruppierungsstrategien und die Zuweisung von Ebenen.

Repository-Struktur

.
├── 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

Konfiguration

Umgebungsvariablen (über .env oder Shell):

• VAR_CATALOG_RUNTIME_DIR — Pfad zu Ihrer Katalog-Laufzeitumgebung (Standard: repo-lokal catalog-runtime/)

• VAR_SERVER_NAME — MCP-Servername, der den Clients angezeigt wird (Standard: tin-canMCP)

• VAR_COMMAND_TIMEOUT_SECONDS — Timeout pro Tool (Standard: 20)

• VAR_MAX_OUTPUT_CHARS — Kürzungsschwelle für stdout/stderr (Standard: 12000)

• MCP_TRANSPORT — stdio, sse oder web (Standard: stdio)

Was Sie NICHT tun sollten

• Fügen Sie keine @mcp.tool()-Dekoratoren für Ihre Domänen-Tools in app/tools/ hinzu. Das untergräbt den Broker. Fügen Sie stattdessen Katalogeinträge hinzu.

• Erhöhen Sie max_tools_per_activation nicht über ca. 15. Der ganze Sinn besteht in einer begrenzten sichtbaren Oberfläche.

• Platzieren Sie nicht jedes Tool in canonical. Verwenden Sie die Ebenen advanced und internal, um Nischen-Tools zurückzustellen.

• Überspringen Sie nicht validate_registry.py. Fehler bei Querverweisen bleiben sonst unbemerkt.

Danksagungen

Diese Vorlage wurde von der Arbeit von josharsh an MCP-Broker-Mustern inspiriert.

Lizenz

MIT. Siehe LICENSE.