tin-canMCP

ブローカーを備えた階層型カタログとして構成された大規模MCPサーバー（20以上のツール）を構築するための規定テンプレートです。

tin-canMCPサーバーは、カタログのサイズに関係なく、AIクライアントに対して正確に7つのツールのみを公開します。カタログ自体には数百のツールを含めることができますが、ブローカーが可視性を制御するため、AIは常にタスクに関連する限定されたサブセットのみを認識します。

このテンプレートを使用すべき場合

tin-canMCPは、多数のツール（CLIバイナリ、APIエンドポイント、AppleScriptコマンド、SDKメソッド）をラップするMCPを作成する場合に使用してください。ブローカーパターンにより、AIが認識するツール数をキャッシュに適した上限内に維持できます。

グループ化が不要で3〜10個のツールしか必要ない場合は、tin-canMCPを使用しないでください。単純なFastMCPサーバーの方が適しています。

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

すべてのサーバーが公開する7つのツール

ドメインツールには catalog_run_tool を通じてのみアクセスできます。完全なワークフローについては HOW-TO-USE.md を参照してください。

クイックスタート

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

この時点でサーバーが読み込まれ、7つのブローカーツールが公開されます。catalog-runtime/registry/tools.json 内の TODO マーカーと、catalog-runtime/tools/ 配下のツールごとのマニフェストを埋めるまで、catalog_run_tool は実行を拒否します。

次へ: HOW-TO-USE.md を読んでください。ツールマニフェストの作成、グループ化戦略、階層の割り当てについて解説しています。

リポジトリ構成

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

設定

環境変数（.env またはシェル経由）:

• VAR_CATALOG_RUNTIME_DIR — カタログランタイムへのパス（デフォルト: リポジトリローカルの catalog-runtime/）

• VAR_SERVER_NAME — クライアントに表示されるMCPサーバー名（デフォルト: tin-canMCP）

• VAR_COMMAND_TIMEOUT_SECONDS — ツールごとのタイムアウト（デフォルト: 20）

• VAR_MAX_OUTPUT_CHARS — stdout/stderrの切り捨てしきい値（デフォルト: 12000）

• MCP_TRANSPORT — stdio、sse、または web（デフォルト: stdio）

やってはいけないこと

• app/tools/ 内のドメインツールに @mcp.tool() デコレータを追加しないでください。それはブローカーの目的を損ないます。代わりにカタログエントリを追加してください。

• max_tools_per_activation を15以上に設定しないでください。可視領域を制限することがこの設計の目的です。

• すべてのツールを canonical に入れないでください。ニッチなツールを後回しにするために advanced や internal 階層を使用してください。

• validate_registry.py をスキップしないでください。相互参照のバグは静かに発生します。

謝辞

このテンプレートは、josharsh 氏によるMCPブローカーパターンの取り組みに触発されました。

ライセンス

MIT。LICENSE を参照してください。