补全 - Model Context Protocol 中文文档

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

用户交互模型

MCP 中的补全被设计为支持类似 IDE 代码补全的交互式用户体验。例如，应用可以在用户输入时，在下拉列表或弹出菜单中显示补全建议，并允许用户筛选和选择可用选项。不过，实现可以自由地通过任何适合自身需求的界面模式公开补全；协议本身并不强制规定任何特定的用户交互模型。

能力

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

{
  "capabilities": {
    "completions": {}
  }
}

协议消息

请求补全

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "resultType": "complete",
  "method": "completion/complete",
  "params": {
    "ref": {
      "type": "ref/prompt",
      "name": "code_review"
    },
    "argument": {
      "name": "language",
      "value": "py"
    }
  }
}

响应：

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

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

{
  "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"
      }
    }
  }
}

响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "completion": {
      "values": ["flask"],
      "total": 1,
      "hasMore": false
    }
  }
}

引用类型

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

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

补全结果

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

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

消息流

数据类型

CompleteRequest

ref：一个 PromptReference 或 ResourceTemplateReference。对于 ResourceTemplateReference，uri 是 URI 或 URI 模板。
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）

实现注意事项

服务器 SHOULD：
- 按相关性排序返回建议
- 在适当情况下实现模糊匹配
- 对补全请求进行速率限制
- 验证所有输入
客户端 SHOULD：
- 对快速连续的补全请求进行防抖
- 在适当情况下缓存补全结果
- 优雅处理缺失或部分结果

安全

实现 MUST：

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

基础协议

客户端能力

服务器能力

补全

用户交互模型

能力

协议消息

请求补全

引用类型

补全结果

消息流

数据类型

CompleteRequest

CompleteResult

错误处理

实现注意事项

安全

​用户交互模型

​能力

​协议消息

​请求补全

​引用类型

​补全结果

​消息流

​数据类型

​CompleteRequest

​CompleteResult

​错误处理

​实现注意事项

​安全

用户交互模型

能力

协议消息

请求补全

引用类型

补全结果

消息流

数据类型

CompleteRequest

CompleteResult

错误处理

实现注意事项

安全