tin-canMCP

브로커를 포함한 계층형 카탈로그로 구성된 대규모 MCP 서버(20개 이상의 도구)를 구축하기 위한 규범적 템플릿입니다.

모든 tin-canMCP 서버는 카탈로그 크기에 관계없이 AI 클라이언트에 정확히 7개의 도구만 노출합니다. 카탈로그 자체에는 수백 개의 도구가 포함될 수 있지만, 브로커가 가시성을 제어하므로 AI는 언제나 작업과 관련된 제한된 하위 집합만 볼 수 있습니다.

이 템플릿을 사용해야 할 때

MCP가 많은 도구(CLI 바이너리, API 엔드포인트, AppleScript 명령, SDK 메서드)를 래핑해야 할 때 tin-canMCP를 사용하세요. 브로커 패턴은 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를 참조하세요.