tin-canMCP

Рекомендуемый шаблон для создания крупных MCP-серверов (более 20 инструментов), организованных в виде многоуровневого каталога с брокером.

Каждый сервер tin-canMCP предоставляет ровно 7 инструментов AI-клиенту, независимо от размера каталога. Сам каталог может содержать сотни инструментов; брокер ограничивает видимость, чтобы AI видел только ограниченный, релевантный для задачи подмножество в любой момент времени.

Когда использовать этот шаблон

Используйте tin-canMCP, когда ваш MCP будет объединять множество инструментов (бинарные файлы CLI, API-эндпоинты, команды AppleScript, методы SDK). Паттерн брокера удерживает количество видимых для AI инструментов в пределах, удобных для кэширования.

НЕ используйте tin-canMCP, если вам нужно всего 3–10 инструментов без группировки. Обычный сервер 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_run_tool будет отказываться запускать что-либо, пока вы не заполните маркеры TODO в catalog-runtime/registry/tools.json и манифесты для каждого инструмента в catalog-runtime/tools/.

Далее: прочитайте 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)

Чего НЕ следует делать

• Не добавляйте декораторы @mcp.tool() для ваших доменных инструментов в app/tools/. Это нарушает работу брокера. Вместо этого добавляйте записи в каталог.

• Не увеличивайте max_tools_per_activation выше ~15. Весь смысл заключается в ограниченной видимой поверхности.

• Не помещайте все инструменты в canonical. Используйте уровни advanced и internal для отложенного доступа к узкоспециализированным инструментам.

• Не пропускайте validate_registry.py. Ошибки перекрестных ссылок не выводятся в лог.

Благодарности

Этот шаблон был вдохновлен работой josharsh над паттернами MCP-брокеров.

Лицензия

MIT. См. LICENSE.