1. 什么是补全？ #

补全（Completions）是 MCP 服务器为 提示 和 资源 的参数提供的自动建议，类似 IDE 的代码补全。用户填写参数时，服务器根据当前输入和已填参数，返回上下文相关的候选值。

协议版本：2025-11-25

2. 本章你将学到 #

• 补全的能力声明与协议消息
• 如何请求补全（单参数、多参数上下文）
• 引用类型（提示 vs 资源）
• 补全结果、错误处理与实现建议

3. 典型流程 #

用户选择 code_review 提示，在「语言」参数框输入「py」→ 客户端发 completion/complete，指定 ref/prompt + code_review，argument: { name: "language", value: "py" } → 服务器返回 ["python", "pytorch", "pyside"] → 客户端以下拉列表展示，用户选「python」。若还有「框架」参数，用户输入「fla」时，客户端在 context.arguments 中带上 language: "python"，服务器据此返回 ["flask"]。

4. 能力 #

服务器必须声明 completions 能力：

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

5. 协议消息 #

5.1 请求补全（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
    }
  }
}

多参数上下文示例：

用户已选 language: "python"，正在填「框架」参数，输入「fla」：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "completion/complete",
  "params": {
    "ref": { "type": "ref/prompt", "name": "code_review" },
    "argument": { "name": "framework", "value": "fla" },
    "context": {
      "arguments": { "language": "python" }
    }
  }
}

响应：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "completion": {
      "values": ["flask"],
      "total": 1,
      "hasMore": false
    }
  }
}

5.2 引用类型 #

5.3 补全结果 #

6. 流程示意 #

7. 数据结构 #

7.1 请求（CompleteRequest） #

7.2 响应（CompleteResult） #

8. 错误处理 #

9. 实现建议 #

10. 安全要点 #