mcp-builder

1# MCP 服务器构建
2 
3系统化设计、实现、测试和部署 Model Context Protocol 服务器的方法论。
4 
5## 1. 协议核心概念
6 
7MCP 定义三种原语：
8 
9- **Tools（工具）**：AI 助手主动调用的函数，有副作用。如搜索、创建、删除操作。
10- **Resources（资源）**：AI 助手只读访问的数据源，用 URI 标识。如 `users://{id}/profile`。
11- **Prompts（提示词模板）**：预定义交互模板，引导用户触发工作流。
12 
13**选择原则：** 执行操作 → Tool | 读取数据 → Resource | 引导交互 → Prompt
14 
15## 2. 项目结构规范
16 
17### TypeScript
18```
19my-mcp-server/
20├── src/
21│   ├── index.ts          # 入口，注册 tools/resources
22│   ├── tools/             # 按功能拆分
23│   ├── resources/
24│   └── lib/               # 客户端封装、校验逻辑
25├── tests/
26├── package.json
27└── tsconfig.json
28```
29 
30关键依赖：`@modelcontextprotocol/sdk` + `zod`
31 
32### Python
33```
34my-mcp-server/
35├── src/my_mcp_server/
36│   ├── server.py
37│   ├── tools/
38│   └── lib/
39├── tests/
40└── pyproject.toml
41```
42 
43关键依赖：`mcp` + `pydantic`
44 
45## 3. Tool 设计原则
46 
47### 命名
48- `snake_case` 格式，动词开头：`search_users`、`create_issue`、`delete_file`
49- 名称自解释，AI 助手靠名称选工具，模糊命名导致误调用
50 
51### 参数
52- 每个参数有类型约束和 `.describe()` 描述
53- 可选参数给默认值，减少 AI 决策负担
54- 用枚举代替布尔开关
55 
56```typescript
57server.tool("search_issues", {
58  query: z.string().describe("搜索关键词"),
59  status: z.enum(["open", "closed", "all"]).default("open").describe("状态筛选"),
60  limit: z.number().min(1).max(100).default(20).describe("返回上限"),
61}, async ({ query, status, limit }) => { /* ... */ });
62```
63 
64### 描述
65说明**用途 + 返回内容 + 限制**，这是 AI 选择工具的关键依据：
66 
67```typescript
68server.tool("search_users",
69  "根据姓名或邮箱搜索用户。返回 ID、姓名、邮箱列表。模糊匹配，最多 50 条。",
70  schema, handler);
71```
72 
73### 输出
74- 结构化数据 → JSON，人类可读内容 → Markdown
75- 始终用 `content: [{ type: "text", text: "..." }]` 格式返回
76…