补全

Model Context Protocol (MCP) 提供了一种标准化的方式，让服务端能够为提示模板和资源模板的参数提供自动补全建议。当用户为特定提示模板（通过名称标识）或资源模板（通过 URI 标识）填写参数值时，服务端可以提供上下文相关的建议。

NOTE

为简洁起见，本页的请求示例省略了 _meta 请求元数据（io.modelcontextprotocol/protocolVersion、io.modelcontextprotocol/clientInfo 和 io.modelcontextprotocol/clientCapabilities）。每个请求 MUST（必须）包含必需的 _meta 字段；参见 _meta。

用户交互模型

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

例如，应用程序可以在用户输入时以下拉菜单或弹出菜单的形式显示补全建议，并支持对可用选项进行筛选和选择。

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

能力

支持补全的服务端 MUST（必须）声明 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": {
    "resultType": "complete",
    "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": {
    "resultType": "complete",
    "completion": {
      "values": ["flask"],
      "total": 1,
      "hasMore": false
    }
  }
}

引用类型

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

Type	Description	Example
ref/prompt	References a prompt by name	{"type": "ref/prompt", "name": "code_review"}
ref/resource	References a resource URI or URI template	{"type": "ref/resource", "uri": "file:///{path}"}

补全结果

服务端返回按相关性排序的补全值数组，其中包含：

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

消息流程

sequenceDiagram
    participant Client
    participant Server

    Note over Client: User types argument
    Client->>Server: completion/complete
    Server-->>Client: Completion suggestions

    Note over Client: User continues typing
    Client->>Server: completion/complete
    Server-->>Client: Refined suggestions

数据类型

CompleteRequest

• ref：一个 PromptReference 或 ResourceTemplateReference。对于 ResourceTemplateReference，uri 是一个 URI 或 URI 模板。
• argument：包含以下内容的对象：
  • name：参数名称
  • value：当前值
• context：包含以下内容的对象：
  • arguments：已解析的参数名称到其值的映射。

CompleteResult

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

错误处理

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

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

实现注意事项

1. 服务端 SHOULD（应该）：

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

2. 客户端 SHOULD（应该）：

   • 对频繁的补全请求进行防抖处理
   • 在适当的情况下缓存补全结果
   • 优雅地处理缺失或不完整的结果

安全

实现方 MUST（必须）：

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