自动补全

协议版本: 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或ResourceReference
  • argument: 包含以下内容的对象:
    • name: 参数名称
    • value: 当前值
  • context: 包含以下内容的对象:
    • arguments: 已解析参数名称到其值的映射。

CompleteResult

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

错误处理

服务器应该为常见故障情况返回标准JSON-RPC错误:

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

实现注意事项

  1. 服务器应该:

    • 返回按相关性排序的建议
    • 在适当的地方实现模糊匹配
    • 限制补全请求的速率
    • 验证所有输入
  2. 客户端应该:

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

安全

实现必须:

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