完成

协议版本：2025-03-26

模型上下文协议 (MCP) 提供了一种标准化的方式，让服务器为提示和资源 URI 提供参数自动完成建议。这实现了类似 IDE 的丰富体验，用户在输入参数值时接收上下文建议。

用户交互模型

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

引用类型

该协议支持两种类型的完成引用：

完成结果

服务器返回按相关性排序的完成值数组，包括：

• 每个响应最多 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 或 ResourceReference
• argument：包含以下内容的对象：
  • name：参数名称
  • value：当前值

CompleteResult

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

错误处理

服务器应该为常见失败情况返回标准 JSON-RPC 错误：

• 未找到方法：-32601（不支持功能）
• 无效的提示名称：-32602（无效参数）
• 缺少必需参数：-32602（无效参数）
• 内部错误：-32603（内部错误）

实现考虑

1. 服务器应该：

   • 返回按相关性排序的建议
   • 在适当的地方实施模糊匹配
   • 限制完成请求的速率
   • 验证所有输入

2. 客户端应该：

   • 对快速完成请求进行防抖
   • 在适当的地方缓存完成结果
   • 优雅地处理缺失或部分结果

安全

实现必须：

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