附录 A.2 API 与命令速查表

附录 A.2 API 与命令速查表

本节摘要:本节是写代码时的速查入口,把高频 API 与命令压缩成可查的表。覆盖五个高频领域:服务端装饰器、客户端核心方法、传输参数、协议 mode 取值、CLI 命令。每张表都设计成「扫一眼就能找到用法」,供你编码时随手查阅。

一、服务端装饰器速查

# 典型用法速查
@mcp.tool(annotations=ToolAnnotations(read_only=True))
def get_data(key: str) -> dict: ...

@mcp.resource("db://users/{user_id}")
def get_user(user_id: str) -> dict: ...

@mcp.prompt()
def summarize(text: str) -> str: ...
​

二、客户端核心方法速查

# 典型用法速查
async with Client("http://localhost:8000/mcp") as client:
    tools = await client.list_tools()
    result = await client.call_tool("add", {"a": 1, "b": 2})
    if result.is_error:
        ...
    value = result.structured_content["result"]
​

三、传输参数速查

stdio 传输(StdioServerParameters)

流式 HTTP 传输

服务端启动

四、协议 mode 取值速查

async with Client(url, mode="auto") as client: ...      # 默认
async with Client(url, mode="legacy") as client: ...     # 强制 legacy
async with Client(url, mode="2026-07-28") as client: ... # 强制现代
​

五、CLI 命令速查

需要 mcp[cli] 安装。在服务端文件所在目录执行:

# 典型用法
uv run mcp dev server.py        # 用 uv 跑
mcp dev server.py               # 直接跑
​

六、常用导入速查

# 服务端
from mcp.server import MCPServer
from mcp.server.mcpserver import Context, ToolAnnotations
from mcp.server import Server                    # 低层
from mcp.server.auth import AuthSettings         # 认证
from mcp.server.extension import Extension, MethodBinding   # 扩展
from mcp.shared.middleware import ServerMiddleware           # 中间件

# 客户端
from mcp import Client
from mcp.client.stdio import stdio_client, StdioServerParameters
from mcp.client.streamable_http import streamable_http_client
from mcp.client.session_group import ClientSessionGroup
from mcp.client.auth import OAuthClientProvider

# 类型
from mcp import types

# Resolve 与依赖
from typing import Annotated
from mcp.shared import resolve                   # Resolve, Elicit
​

七、字段速查:CallToolResult

调工具返回的结构,常用字段:

result = await client.call_tool("add", {"a": 1, "b": 2})
# result.content:               [TextContent(type="text", text="3")]
# result.structured_content:    {"result": 3}      ← 标量被包一层
# result.is_error:              False
​

本节要点回顾

1. 五张速查表:服务端装饰器、客户端方法、传输参数、mode 取值、CLI 命令。
2. 每张表「扫一眼就能找到用法」,设计成随手查阅。
3. 常用导入速查列出高频导入路径,避免记不住。
4. CallToolResult 字段速查:content(模型)、structured_content(应用)、is_error(判断)。
5. 编码卡壳时查本节,比翻文档快。

速查表清楚了,最后一节是常见报错与排查,以及 v1→v2 迁移要点。