跳到主要内容
协议修订: 2025-11-25
模型上下文协议 (MCP) 提供了一种标准化的方式，使服务器能够为提示 (Prompts) 和资源模板 (Resource Templates) 的参数提供自动补全建议。当用户正在为特定的提示（通过名称标识）或资源模板（通过 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 个项目
  • 可选的可用匹配总数
  • 指示是否存在更多结果的布尔值

​
消息流

​
数据类型

​
CompleteRequest

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

​
CompleteResult

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

​
错误处理

服务器应该为常见的失败情况返回标准的 JSON-RPC 错误
  • 方法未找到：-32601 (不支持该能力)
  • 无效的提示名称：-32602 (无效参数)
  • 缺少必需参数：-32602 (无效参数)
  • 内部错误：-32603 (内部错误)

​
实现注意事项

  1. 服务器**应该**
    • 按相关性排序返回建议
    • 在适当时实现模糊匹配
    • 限制补全请求的速率
    • 验证所有输入
  2. 客户端**应该**
    • 对密集的补全请求进行防抖处理 (Debounce)
    • 在适当时缓存补全结果
    • 优雅地处理缺失或部分结果

​
安全性

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