mcp-builderlisted

# MCP 服务器构建 系统化设计、实现、测试和部署 Model Context Protocol 服务器的方法论。 ## 1. 协议核心概念 MCP 定义三种原语： - **Tools（工具）**：AI 助手主动调用的函数，有副作用。如搜索、创建、删除操作。 - **Resources（资源）**：AI 助手只读访问的数据源，用 URI 标识。如 `users://{id}/profile`。 - **Prompts（提示词模板）**：预定义交互模板，引导用户触发工作流。 **选择原则：** 执行操作 → Tool | 读取数据 → Resource | 引导交互 → Prompt ## 2. 项目结构规范 ### TypeScript ``` my-mcp-server/ ├── src/ │ ├── index.ts # 入口，注册 tools/resources │ ├── tools/ # 按功能拆分 │ ├── resources/ │ └── lib/ # 客户端封装、校验逻辑 ├── tests/ ├── package.json └── tsconfig.json ``` 关键依赖：`@modelcontextprotocol/sdk` + `zod` ### Python ``` my-mcp-server/ ├── src/my_mcp_server/ │ ├── server.py │ ├── tools/ │ └── lib/ ├── tests/ └── pyproject.toml ``` 关键依赖：`mcp` + `pydantic` ## 3. Tool 设计原则 ### 命名 - `snake_case` 格式，动词开头：`search_users`、`create_issue`、`delete_file` - 名称自解释，AI 助手靠名称选工具，模糊命名导致误调用 ### 参数 - 每个参数有类型约束和 `.describe()` 描述 - 可选参数给默认值，减少 AI 决策负担 - 用枚举代替布尔开关 ```typescript server.tool("search_issues", { query: z.string().describe("搜索关键词"), status: z.enum(["open", "closed", "all"]).default("open").describe("状态筛选"), limit: z.number().min(1).max(100).default(20).describe("返回上限"), }, async ({ query, status, limit }) => { /* ... */ }); ``` ### 描述 说明**用途 + 返回内容 + 限制**，这是 AI 选择工具的关键依据： ```typescript server.tool("search_users", "根据姓名或邮箱搜索用户。返回 ID、姓名、邮箱列表。模糊匹配，最多 50 条。", schema, handler); ``` ### 输出 - 结构化数据 → JSON，人类可读内容 → Markdown - 始终用 `content: [{ type: "text", text: "..." }]` 格式返回 ## 4. 输入验证