MCP、API、Skill 到底啥关系

1
// 传统 REST API 调用
2
POST /api/weather/current
3
Content-Type: application/json
4
Authorization: Bearer xxx
5

6
{
7
    "city": "重庆",
8
    "units": "celsius"
9
}
10

11
// 返回
12
{
13
    "code": 200,
14
    "data": {
15
        "temperature": 28,
16
        "humidity": 75,
17
        "wind": "3级"
18
    }
19
}

1
{
2
    "tools": [
3
        {
4
            "type": "function",
5
            "function": {
6
                "name": "get_weather",
7
                "description": "获取指定城市的当前天气",
8
                "parameters": {
9
                    "type": "object",
10
                    "properties": {
11
                        "city": { "type": "string", "description": "城市名称" },
12
                        "units": { "type": "string", "enum": ["celsius", "fahrenheit"] }
13
                    }
14
                }
15
            }
16
        }
17
    ]
18
}

1
// 1. 请求（Request）：客户端 → 服务器
2
{
3
    "jsonrpc": "2.0",
4
    "id": 1,
5
    "method": "tools/call",
6
    "params": {
7
        "name": "read_file",
8
        "arguments": {
9
            "path": "/workspace/config.json"
10
        }
11
    }
12
}
13

14
// 2. 成功响应（Success Response）：服务器 → 客户端
15
{
16
    "jsonrpc": "2.0",
17
    "id": 1,
18
    "result": {
19
        "content": [
20
            {
21
                "type": "text",
22
                "text": "{\"server\": {\"port\": 8080}}"
23
            }
24
        ]
25
    }
26
}
27

28
// 3. 错误响应（Error Response）：服务器 → 客户端
29
{
30
    "jsonrpc": "2.0",
31
    "id": 1,
32
    "error": {
33
        "code": -32000,
34
        "message": "File not found",
35
        "data": {
36
            "path": "/workspace/config.json"
37
        }
38
    }
39
}
40

41
// 4. 通知（Notification）：无 ID，不需要响应
42
{
43
    "jsonrpc": "2.0",
44
    "method": "notifications/initialized"
45
}

1
客户端                              MCP 服务器
2
  │                                      │
3
  │  ── 1. 建立连接（stdio/SSE）─────► │
4
  │                                     │
5
  │  ◄── 2. server.info ─────────────── │
6
  │       (名称、版本、能力声明)          │
7
  │                                     │
8
  │  ── 3. initialize ────────────────► │
9
  │       (客户端信息、协议版本)          │
10
  │                                     │
11
  │  ◄── 4. initialized ──────────────  │
12
  │       (确认初始化完成)               │
13
  │                                     │
14
  │  ── 5. tools/list ────────────────► │
15
  │  ◄── [tool1, tool2, ...] ─────────  │
16
  │                                     │
17
  │  ── 6. tools/call(name="read")───►  │
18
  │  ◄── {content: "..."} ────────────  │
19
  │                                     │
20
  │  ── 7. tools/call(name="write")──►  │
21
  │  ◄── {content: "ok"} ─────────────  │
22
  │                                     │
23
  │  ── 8. 关闭连接 ──────────────────► │

1
// opencode → MCP 服务器
2
{
3
    "jsonrpc": "2.0",
4
    "id": 1,
5
    "method": "tools/call",
6
    "params": {
7
        "name": "read_directory",
8
        "arguments": { "path": "/Users/tanzicai/CX" }
9
    }
10
}
11

12
// MCP 服务器 → opencode
13
{
14
    "jsonrpc": "2.0",
15
    "id": 1,
16
    "result": {
17
        "content": [
18
            {
19
                "type": "text",
20
                "text": "[\"README.md\", \"package.json\", \"src/\", ...]"
21
            }
22
        ]
23
    }
24
}

1
# 资源导向的 URL 设计
2
GET    /api/users           # 列出用户
3
POST   /api/users           # 创建用户
4
GET    /api/users/{id}      # 获取单个用户
5
PUT    /api/users/{id}      # 全量更新用户
6
PATCH  /api/users/{id}      # 部分更新用户
7
DELETE /api/users/{id}      # 删除用户
8

9
# 状态码规范
10
200 OK                      # GET/PUT/PATCH 成功
11
201 Created                 # POST 成功创建
12
204 No Content              # DELETE 成功
13
400 Bad Request             # 参数错误
14
401 Unauthorized            # 未认证
15
403 Forbidden               # 无权限
16
404 Not Found               # 资源不存在
17
500 Internal Server Error   # 服务器内部错误

1
## API 文档的传统写法（给人看）
2

3
### 获取天气
4
接口地址：GET /api/weather
5
参数：
6
  - city：城市名称
7
  - units：单位（celsius/fahrenheit）
8
返回示例：
9
  { "temperature": 28, "humidity": 75 }
10

11
## API 文档的 AI 友好写法
12

13
### get_weather
14
用途：获取指定城市的天气预报数据
15
适用场景：用户在询问天气、需要决定出行安排时调用
16
参数：
17
  - city：必填，城市中文名称如"重庆"、"北京"
18
  - units：可选，默认 celsius
19
行为约束：不要同时查询多个城市，一次只查一个
20
返回字段说明：
21
  - temperature：当前温度，整数
22
  - humidity：湿度百分比
23
  - wind：风力等级描述
24
错误处理：如果城市不存在，返回 404，此时应告知用户城市名可能错误

1
# Skill 的结构化描述
2
name: proposal-writer              # 技能名称
3
description: 编写高校信息化建设方案   # 技能描述
4
version: 1.0.0
5

6
# 核心指令（告诉 AI 如何思考）
7
instructions:
8
  - 你是一个拥有10年经验的高校信息化顾问
9
  - 写方案前先理解客户需求，列出大纲
10
  - 每个方案必须包含：项目背景、建设目标、技术架构、实施计划、预算
11
  - 用正式书面语，专业术语需加括号备注英文
12
  - 避免过度技术化，突出业务价值
13

14
# 引用的 MCP 工具
15
mcp_tools:
16
  - filesystem:    # 读取方案模板和参考资料
17
  - web:           # 搜索相关政策和标准
18

19
# 参考文件
20
references:
21
  - path: /templates/proposal-template.docx
22
  - path: /guidelines/writing-style.md

1
# proposal-writer
2

3
你是一个资深的高校信息化建设顾问。
4
你的任务是帮助用户编写高质量的建设方案、可行性报告和投标文件。
5

6
## 工作流程
7

8
1. 需求分析
9
   - 先理解用户的学校类型、预算规模、核心需求
10
   - 列出方案大纲，请用户确认
11

12
2. 方案编写
13
   - 参考 /references/ 中的模板格式
14
   - 每个章节包含：核心观点 → 详细展开 → 案例支撑
15
   - 使用 MCP 文件系统工具读取已有的方案作为参考
16

17
3. 审核
18
   - 自检清单：
19
     [ ] 是否有明确的建设目标
20
     [ ] 技术架构是否合理
21
     [ ] 预算是否具体
22
     [ ] 实施计划是否可行
23

24
4. 输出
25
   - 生成 Markdown 版本供用户在 Obsidian 中编辑
26
   - 如有需要，使用 generate-docx.py 生成 Word 版本
27

28
## 写作规范
29

30
- 使用正式书面语，不使用口语化表达
31
- 英文专业术语保留并加括号备注中文
32
- 每个段落不超过 5 句话
33
- 不使用"首先其次最后"等模板化过渡词

1
                    ┌──────────────────────┐
2
                    │       Skill          │
3
                    │  （任务能力封装）      │
4
                    │  如何完成特定工作     │
5
                    └──────────┬───────────┘
6
                               │ 使用
7
                    ┌──────────▼───────────┐
8
                    │       MCP            │
9
                    │  （工具访问协议）      │
10
                    │  如何调用外部工具     │
11
                    └──────────┬───────────┘
12
                               │ 调用
13
                    ┌──────────▼───────────┐
14
                    │       API            │
15
                    │  （系统通信接口）      │
16
                    │  系统间如何通信       │
17
                    └──────────────────────┘

1
用户："帮我写一篇关于 MCP 的技术博客"
2

3
1. Skill 层加载
4
   └── opencode 加载 doc-generator 技能
5
       ├── 写作规范：技术文章结构
6
       ├── 风格指南：清晰、有代码示例
7
       └── 工作流：大纲 → 初稿 → 审校
8

9
2. MCP 层调用
10
   ├── filesystem：读取已有的博客文章作为参考
11
   ├── git：创建新分支、提交文件
12
   └── web：搜索相关资料
13

14
3. API 层通信
15
   ├── Anthropic API：调用 Claude 模型
16
   ├── GitHub API：通过 MCP 的 git 工具调用
17
   └── 文件系统 API：通过 MCP 的 filesystem 调用