一个用于构建大型 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
工具 | 用途 |
| 显示当前的激活状态和路由提示 |
| 列出目录中的所有组 |
| 按名称/描述搜索完整目录（无需激活） |
| 开启组/层级，使其工具变为可运行状态 |
| 将激活范围扩大到下一层级（规范 → 高级 → 内部） |
| 显示当前可运行的工具 |
| 通过名称和参数执行活动工具 |
领域工具只能通过 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 和 catalog-runtime/tools/ 下的各工具清单中填入 TODO 标记之前，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 或 shell）：
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。
This server cannot be deployed
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Search, vet & assemble MCP servers from your agent: verified tools, risk labels, and trust scores.
Patterns for designing and reviewing AI skills, agents, and multi-agent workflows. Find guidance on context economy, delegation, verification, and tool design; inspect claims, worked examples, maturity labels, and source references. Five read-only tools let agents discover relevant patterns, compare concise cards, read specific sections, and explore relationships. Hosted Streamable HTTP at https://agentic-atlas.dev/mcp/ — no installation, account, or API key required. Browse the atlas at https://agentic-atlas.dev/.
