鸭梨公共文档

主题

补全 ​

协议版本: 2025-06-18

Model Context Protocol (MCP) 为服务器提供了一种标准化的方式，用于为提示和资源 URI 提供参数自动补全建议。这使得用户在输入参数值时能够获得丰富的、类似 IDE 的体验，接收到上下文相关的建议。

1. 用户交互模型 ​

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

例如，应用程序可能会在用户输入时显示下拉菜单或弹出菜单中的补全建议，用户可以过滤和选择可用的选项。

然而，实现方式可以自由地通过任何适合其需求的界面模式来展示补全功能——协议本身并不强制要求任何特定的用户交互模型。

2. 能力声明 ​

支持补全功能的服务器必须声明 completions 能力：

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

3. 协议消息 ​

3.1 请求补全 ​

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

请求：

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

响应：

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

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

请求：

json
{
  "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
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "completion": {
      "values": ["flask"],
      "total": 1,
      "hasMore": false
    }
  }
}

3.2 引用类型 ​

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

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

3.3 补全结果 ​

服务器返回按相关性排序的补全值数组，具有以下特性：

  • 每个响应最多 100 个项目
  • 可选的可用匹配总数
  • 指示是否存在额外结果的布尔值

4. 消息流程 ​

5. 数据类型 ​

5.1 CompleteRequest ​

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

5.2 CompleteResult ​

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

6. 错误处理 ​

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

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

7. 实现注意事项 ​

7.1 服务器应该 ​

  • 返回按相关性排序的建议
  • 在适当的情况下实现模糊匹配
  • 对补全请求进行速率限制
  • 验证所有输入

7.2 客户端应该 ​

  • 对快速的补全请求进行防抖处理
  • 在适当的情况下缓存补全结果
  • 优雅地处理缺失或部分结果

8. 安全性 ​

实现必须：

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