自动补全
协议版本: 2025-11-25
模型上下文协议(MCP)为服务器提供了一种标准化的方式,为提示和资源模板的参数提供自动补全建议。当用户为特定提示(按名称标识)或资源模板(按URI标识)填写参数值时,服务器可以提供上下文相关的建议。
用户交互模型
MCP中的自动补全旨在支持类似于IDE代码补全的交互式用户体验。
例如,应用程序可以在用户输入时在下拉菜单或弹出窗口中显示补全建议,并能够过滤和选择可用选项。
但是,实现可以通过任何适合其需求的界面模式来公开自动补全——协议本身不强制任何特定的用户交互模型。
功能
支持补全的服务器必须声明completions功能:
{
"capabilities": {
"completions": {}
}
}协议消息
请求补全
要获取补全建议,客户端发送completion/complete请求,通过引用类型指定正在补全的内容:
请求:
{
"jsonrpc": "2.0",
"id": 1,
"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 | {"type": "ref/resource", "uri": "file:///{path}"} |
补全结果
服务器返回按相关性排序的补全值数组,包含:
- 每个响应最多100个项目
- 可用匹配的可选总数
- 表示是否存在额外结果的布尔值
消息流
sequenceDiagram
participant Client
participant Server
Note over Client: 用户输入参数
Client->>Server: completion/complete
Server-->>Client: 补全建议
Note over Client: 用户继续输入
Client->>Server: completion/complete
Server-->>Client: 精炼的建议
数据类型
CompleteRequest
ref:PromptReference或ResourceReferenceargument: 包含以下内容的对象:name: 参数名称value: 当前值
context: 包含以下内容的对象:arguments: 已解析参数名称到其值的映射。
CompleteResult
completion: 包含以下内容的对象:values: 建议数组(最多100个)total: 可选的匹配总数hasMore: 额外结果标志
错误处理
服务器应该为常见故障情况返回标准JSON-RPC错误:
- 方法未找到:
-32601(不支持功能) - 无效的提示名称:
-32602(无效参数) - 缺少必需参数:
-32602(无效参数) - 内部错误:
-32603(内部错误)
实现注意事项
服务器应该:
- 返回按相关性排序的建议
- 在适当的地方实现模糊匹配
- 限制补全请求的速率
- 验证所有输入
客户端应该:
- 对快速补全请求进行去抖动
- 在适当的地方缓存补全结果
- 优雅地处理缺失或部分结果
安全
实现必须:
- 验证所有补全输入
- 实施适当的速率限制
- 控制对敏感建议的访问
- 防止基于补全的信息泄露