初始化
This commit is contained in:
144
.cursor/skills/mcp-builder/SKILL.md
Normal file
144
.cursor/skills/mcp-builder/SKILL.md
Normal file
@@ -0,0 +1,144 @@
|
||||
---
|
||||
name: mcp-builder
|
||||
version: 1.1.0
|
||||
description: "构建 MCP Server，让 LLM 通过 Tool 与外部服务交互。当需要创建 MCP 工具或封装 API 为 MCP 时使用。推荐 TypeScript + MCP SDK。"
|
||||
---
|
||||
|
||||
# MCP Server 开发指南
|
||||
|
||||
## 触发条件
|
||||
|
||||
用户需要构建自定义 MCP Server 以封装 API 或服务为 LLM 可调用的 Tool。
|
||||
|
||||
## 执行流程
|
||||
|
||||
### Phase 1：研究与规划
|
||||
|
||||
#### 1.1 理解目标 API
|
||||
|
||||
- 梳理目标服务的 API 端点、认证方式、数据模型
|
||||
- 使用 WebFetch 或 WebSearch 获取 API 文档
|
||||
- 列出需要封装的端点，按优先级排序（最常用操作优先）
|
||||
|
||||
#### 1.2 学习 MCP 协议
|
||||
|
||||
**加载 MCP 规范**：
|
||||
- 起始页：`https://modelcontextprotocol.io/sitemap.xml`
|
||||
- 获取特定页面时添加 `.md` 后缀获取 Markdown 格式
|
||||
|
||||
**加载 MCP SDK 文档**：
|
||||
- WebFetch: `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
|
||||
- SDK 名称虽含 "typescript"，但完全支持纯 TypeScript 项目
|
||||
|
||||
#### 1.3 设计 Tool
|
||||
|
||||
| 设计原则 | 说明 |
|
||||
|---|---|
|
||||
| 命名清晰 | 使用 `prefix_action_target` 格式，如 `github_create_issue` |
|
||||
| 描述精准 | 简洁说明功能 + 参数含义 + 返回值结构 |
|
||||
| 错误可操作 | 错误信息应引导 LLM 找到解决方案 |
|
||||
| 结果聚焦 | 返回精准、相关的数据，支持分页/过滤 |
|
||||
| API 覆盖优先 | 不确定时优先提供全面的 API 覆盖，而非少量高层 Workflow Tool |
|
||||
|
||||
---
|
||||
|
||||
### Phase 2：实现
|
||||
|
||||
**推荐技术栈**：
|
||||
- **语言**：TypeScript（MCP SDK 原生支持，无需编译，直接运行）
|
||||
- **传输**：远程服务用 Streamable HTTP（无状态 JSON），本地用 stdio
|
||||
|
||||
#### 2.1 项目结构
|
||||
|
||||
```
|
||||
mcp-server-{{name}}/
|
||||
├── src/
|
||||
│ ├── index.ts # Server entry + tool registration
|
||||
│ ├── client.ts # API client with auth
|
||||
│ └── tools/ # One file per tool group
|
||||
│ ├── resources.ts
|
||||
│ └── actions.ts
|
||||
├── package.json
|
||||
└── README.md
|
||||
```
|
||||
|
||||
#### 2.2 基础设施
|
||||
|
||||
实现共享工具：
|
||||
- API Client（认证、请求头、Base URL）
|
||||
- 错误处理 Helper（统一格式，包含 actionable 信息）
|
||||
- 响应格式化（JSON 结构化 + 文本摘要）
|
||||
- 分页支持
|
||||
|
||||
#### 2.3 Tool 实现
|
||||
|
||||
每个 Tool 需要：
|
||||
|
||||
**输入 Schema**（Zod）：
|
||||
- Zod 在纯 TypeScript 中同样可用，提供运行时参数校验
|
||||
- 包含约束和清晰的字段描述
|
||||
- 在 description 中添加示例值
|
||||
|
||||
**输出 Schema**（推荐定义）：
|
||||
- 使用 `outputSchema` + `structuredContent` 返回结构化数据
|
||||
|
||||
**Tool 注解**：
|
||||
- `readOnlyHint`: 是否只读
|
||||
- `destructiveHint`: 是否有破坏性
|
||||
- `idempotentHint`: 是否幂等
|
||||
|
||||
---
|
||||
|
||||
### Phase 3：审查与测试
|
||||
|
||||
#### 3.1 代码质量检查
|
||||
- 无重复代码（DRY）
|
||||
- 一致的错误处理
|
||||
- 关键函数和参数有 JSDoc 注释
|
||||
- 清晰的 Tool 描述
|
||||
|
||||
#### 3.2 测试
|
||||
|
||||
```bash
|
||||
# 直接运行验证语法
|
||||
node src/index.ts
|
||||
|
||||
# 使用 MCP Inspector 交互式测试
|
||||
npx @modelcontextprotocol/inspector
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 4：集成到项目
|
||||
|
||||
将构建好的 MCP Server 注册到 `.cursor/mcp.json`：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"{{name}}": {
|
||||
"command": "node",
|
||||
"args": ["path/to/mcp-server-{{name}}/src/index.ts"],
|
||||
"env": {
|
||||
"API_KEY": "{{env_var}}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 验证
|
||||
|
||||
1. [ ] `node src/index.ts` 启动无错误
|
||||
2. [ ] MCP Inspector 可以列出所有 Tool
|
||||
3. [ ] 每个 Tool 的输入 Schema 有 Zod 校验
|
||||
4. [ ] 每个 Tool 的 description 清晰、包含参数说明
|
||||
5. [ ] 错误信息包含具体的修复建议（actionable）
|
||||
6. [ ] 需要分页的 Tool 支持 `cursor`/`limit` 参数
|
||||
7. [ ] 环境变量用于凭证/密钥，不硬编码
|
||||
8. [ ] `.cursor/mcp.json` 注册正确
|
||||
|
||||
## Tier 3 参考资料（按需读取）
|
||||
|
||||
- `references/mcp_best_practices.md` — MCP 最佳实践指南
|
||||
- `references/node_mcp_server.md` — TypeScript/Node.js 实现详细指南
|
||||
Reference in New Issue
Block a user