> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.developerdoc.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 补全

<div id="enable-section-numbers" />

Model Context Protocol (MCP) 为服务器向提示和资源模板的参数提供自动补全建议提供了标准化方式。
当用户为特定提示（按名称标识）或资源模板（按 URI 标识）填写参数值时，服务器可以提供上下文相关建议。

## 用户交互模型

MCP 中的补全旨在支持类似 IDE 代码补全的交互式用户体验。

例如，应用可以在用户输入时通过下拉框或弹出菜单显示补全建议，并支持从可用选项中筛选和选择。

不过，实现可以自由地通过任何适合自身需求的界面模式公开补全；
协议本身并不强制规定任何特定的用户交互模型。

## 能力

支持补全的服务器 **MUST** 声明 `completions` 能力：

```json theme={null}
{
  "capabilities": {
    "completions": {}
  }
}
```

## 协议消息

### 请求补全

为了获取补全建议，客户端会发送 `completion/complete` 请求，并通过引用类型指定要补全的对象：

**请求：**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "completion/complete",
  "params": {
    "ref": {
      "type": "ref/prompt",
      "name": "code_review"
    },
    "argument": {
      "name": "language",
      "value": "py"
    }
  }
}
```

**响应：**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "completion": {
      "values": ["python", "pytorch", "pyside"],
      "total": 10,
      "hasMore": true
    }
  }
}
```

对于包含多个参数的提示或 URI 模板，客户端应在 `context.arguments` 对象中包含先前的补全结果，为后续请求提供上下文。

**请求：**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "completion/complete",
  "params": {
    "ref": {
      "type": "ref/prompt",
      "name": "code_review"
    },
    "argument": {
      "name": "framework",
      "value": "fla"
    },
    "context": {
      "arguments": {
        "language": "python"
      }
    }
  }
}
```

**响应：**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "completion": {
      "values": ["flask"],
      "total": 1,
      "hasMore": false
    }
  }
}
```

### 引用类型

协议支持两种补全引用类型：

| 类型             | 描述       | 示例                                                  |
| -------------- | -------- | --------------------------------------------------- |
| `ref/prompt`   | 按名称引用提示  | `{"type": "ref/prompt", "name": "code_review"}`     |
| `ref/resource` | 引用资源 URI | `{"type": "ref/resource", "uri": "file:///{path}"}` |

### 补全结果

服务器返回按相关性排序的补全值数组，其中包含：

* 每个响应最多 100 项
* 可用匹配项总数（可选）
* 表示是否存在更多结果的布尔值

## 消息流

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Server

    Note over Client: User types argument
    Client->>Server: completion/complete
    Server-->>Client: Completion suggestions

    Note over Client: User continues typing
    Client->>Server: completion/complete
    Server-->>Client: Refined suggestions
```

## 数据类型

### CompleteRequest

* `ref`：`PromptReference` 或 `ResourceReference`
* `argument`：包含以下内容的对象：
  * `name`：参数名称
  * `value`：当前值
* `context`：包含以下内容的对象：
  * `arguments`：已解析参数名称到其值的映射。

### CompleteResult

* `completion`：包含以下内容的对象：
  * `values`：建议数组（最多 100 项）
  * `total`：匹配项总数（可选）
  * `hasMore`：更多结果标志

## 错误处理

服务器 **SHOULD** 针对常见失败情况返回标准 JSON-RPC 错误：

* 方法未找到：`-32601`（Capability not supported）
* 无效提示名称：`-32602`（Invalid params）
* 缺少必需参数：`-32602`（Invalid params）
* 内部错误：`-32603`（Internal error）

## 实现注意事项

1. 服务器 **SHOULD**:
   * 返回按相关性排序的建议
   * 在适当位置实现模糊匹配
   * 对补全请求进行速率限制
   * 验证所有输入

2. 客户端 **SHOULD**:
   * 对快速连续的补全请求进行防抖
   * 在适当位置缓存补全结果
   * 妥善处理缺失或部分结果

## 安全

实现 **MUST**:

* 验证所有补全输入
* 实现适当的速率限制
* 控制对敏感建议的访问
* 防止基于补全的信息泄露