#三大原语

MCP 最值得学的部分是 原语（primitives）：Server 能向 Client 提供哪些上下文。官方分成三类，差别在于 谁决定使用它们。

类比 HTTP：Resource 像 GET（取数据、原则上不改世界）；Tool 像 POST（做事，可能有副作用）。Prompt 更像用户点名运行的「保存查询」。

#Tools：模型调用的动作

每个 Tool 有名称、说明和 JSON Schema 入参。模型根据对话决定是否调用；Host 通常会弹出 审批，尤其是写操作。

概念上的发现请求（现行规范每个请求都带 _meta，这里只保留与方法相关的字段）：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

发现结果里会有工具列表，例如加法：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "add",
        "description": "Add two numbers.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "a": { "type": "integer" },
            "b": { "type": "integer" }
          },
          "required": ["a", "b"]
        }
      }
    ]
  }
}

调用：

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "add",
    "arguments": { "a": 1, "b": 2 }
  }
}

用官方 Python SDK 时，你 不用手写 这些 JSON：类型注解就是 schema，docstring 就是说明。见 Python 服务器。

设计要点：一个 Tool 做一件事；名称稳定（weather_current 优于含糊的 get）；副作用写进 description，方便 Host 决定要不要先问用户。

#Resources：应用装进上下文的数据

Resource 用 URI 标识，并声明 MIME 类型。Host 决定读哪些、如何截取后再交给模型。

两种形态：

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "resources/read",
  "params": { "uri": "greeting://Ada" }
}

返回体是资源内容（文本或二进制的编码表示），不是「模型已经读过」的保证——Host 可能只把摘要塞进 Prompt。

不要 把密钥、完整生产连接串、未脱敏的用户数据做成 Resource。Resource 常被整个贴进上下文，比 Tool 返回值更容易泄漏。

#Prompts：用户点名的模板

Prompt 由用户从斜杠命令、命令面板或按钮触发，而不是模型偷偷选用。prompts/get 填入参数后，Server 返回一条或多条消息，Host 再发给模型。

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "prompts/get",
  "params": {
    "name": "summarize",
    "arguments": { "text": "MCP is USB-C for AI." }
  }
}

适合：领域工作流（「按我们的 PR 清单审查」）、示范如何搭配本 Server 的 Tools / Resources。不适合：把整本员工手册硬塞进模板——那更该做成 Resource。

#发现顺序（心智模型）

sequenceDiagram
    participant C as Client
    participant S as Server
    C->>S: server/discover
    S-->>C: 版本 / 能力 / 身份
    C->>S: tools/list
    S-->>C: 工具 schema 列表
    C->>S: tools/call
    S-->>C: 执行结果

server/discover 可选，但能一次拿到能力与缓存提示（ttlMs、cacheScope）。列表接口也可以分页（cursor）。SDK 与 Inspector 会替你走完这些步骤。

#已弃用：Sampling（了解即可）

旧规范允许 Server 用 sampling/createMessage 反向 请 Host 调用模型。自 2026-07-28 起 Sampling（以及 Roots、Logging 作为核心能力）被 弃用，至少还有十二个月的过渡期。新教程和新项目不要再实现 Sampling。 需要模型时，在你的应用或 Host 侧直接调供应商 API。本课后文不再展开。

客户端仍可能支持 elicitation（中途向用户要确认或补参），现行规范用 Multi Round-Trip Requests 表达，而不是一条永远开着的双向流。

#下一步

• 传输层
• 快速上手
• Python 服务器