# MCP协议联调

## 规则（Rules）

# MCP协议联调规范

## 适用对象和范围

本规范适用于所有MCP协议联调对接的场景。

---

## 1. 以协议文档为准

**规则**：联调必须以MCP协议文档或Server源码中的工具定义为准。

**违反后果**：脱离文档联调导致工具调用参数不匹配。

---

## 2. inputSchema校验规范

**规则**：禁止在未确认inputSchema的情况下调用工具，必须严格遵循参数定义。

**违反后果**：参数不匹配导致工具调用失败。

---

## 3. content结构规范

**规则**：禁止忽略MCP返回的content结构，MCP统一使用content数组包裹返回数据。

**违反后果**：忽略content结构导致数据解析错误。

## 方法（Methods）

# MCP协议联调方法

## 前置条件

- [ ] 已有MCP Server实现或协议设计文档
- [ ] MCP Server已注册了工具、资源或提示

---

## 流程概览

```
阅读协议文档 → 检查Server实现 → 检查客户端调用 → 编写数据转换协议 → 逐项验证 → 修复问题
```

---

## 详细步骤

### 步骤1：阅读MCP协议文档

分析协议文档或Server源码，提取工具定义和参数Schema。

### 步骤2：检查MCP Server实现

检查工具注册、资源注册和服务初始化是否正确。

### 步骤3：检查客户端调用

检查客户端MCP调用代码是否与Server定义一致。

## 技巧（Tips）

# MCP协议联调技巧

## 1. 直接从Server源码提取工具定义

**适用场景**：协议文档不存在时。

**具体做法**：读取MCP Server源码中的工具注册代码，直接提取工具名称、描述和inputSchema。

## 2. 使用统一的错误格式

**适用场景**：MCP返回的错误格式与客户端期望不一致时。

**具体做法**：编写 `normalizeMcpError` 函数统一错误格式。

## 3. 常见问题速查

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| 工具调用无响应 | Server未正确处理call_tool | 检查Server的请求处理函数 |
| 参数校验失败 | inputSchema定义不完整 | 补充required数组和字段类型 |
| 返回数据为空 | content结构解析错误 | 检查content数组中的type字段 |