9.3 核心调用方法:调用工具、读取资源、获取提示词

9.3 核心调用方法:调用工具、读取资源、获取提示词

本节摘要:连接就绪后,接下来就是「消费服务端能力」。本节讲透 Client 的核心调用方法——call_tool(调工具,拿 content + structured_content)、list_tools / list_resources / list_resource_templates / list_prompts(列清单)、read_resource(读资源)、get_prompt(渲染提示词)。每个方法对应服务端的一个原语,形成「消费侧」的完整 API。读完本节,你能用客户端消费 MCP 服务的全部三类能力。

一、调用工具:call_tool

最核心的方法是 call_tool——调用服务端的工具:

async with Client(mcp) as client:
    result = await client.call_tool("add", {"a": 1, "b": 2})
​

call_tool 接两个参数:

• 工具名("add")
• 参数字典({"a": 1, "b": 2})

返回的 result 是一个结构化对象(回顾第 4.2 节),含:

result = await client.call_tool("add", {"a": 1, "b": 2})

# 给应用的:结构化数据(标量被包成 {"result": ...})
print(result.structured_content)   # {"result": 3}

# 给模型的:文本
print(result.content)              # [{"type": "text", "text": "3"}]

# 判断成功/失败
if result.is_error:
    print("工具失败")
​

二、列举清单:list_* 系列

调用前,你可能想知道「服务端有哪些工具/资源/提示词」。这就是 list_* 系列:

async with Client(mcp) as client:
    # 列出所有工具
    tools = await client.list_tools()
    for tool in tools:
        print(tool.name, tool.description, tool.input_schema)

    # 列出具体资源
    resources = await client.list_resources()

    # 列出资源模板
    templates = await client.list_resource_templates()

    # 列出提示词
    prompts = await client.list_prompts()
​

每个 list_* 返回对应的清单。注意资源有两个 list 方法——list_resources(具体资源)与 list_resource_templates(资源模板),对应第 5.1 节讲的两种资源形态。

三、读取资源:read_resource

读取资源用 read_resource,传完整 URI:

async with Client(mcp) as client:
    # 读具体资源
    config = await client.read_resource("config://app")
    print(config)    # 配置内容

    # 读资源模板(填参数实例化)
    greeting = await client.read_resource("greeting://World")
    print(greeting)  # "Hello, World!"
​

回顾第 5.1 节:读资源模板时,要传完整实例化 URI(greeting://World,不是模板模式 greeting://{name})。SDK 据此找到对应模板处理器,填参数,执行。

四、获取提示词:get_prompt

获取提示词用 get_prompt,传提示词名与参数:

async with Client(mcp) as client:
    # 获取提示词(带参数)
    messages = await client.get_prompt("summarize", {"text": "..."})
    for msg in messages:
        print(msg.role, msg.content)
​

返回的是一组消息(回顾第 5.3 节,提示词返回消息列表)。最常见的是一条用户消息,但也可能含系统消息(提示词返回多消息时)。

五、方法与原语的对应

把客户端方法与服务端原语放一起,对应关系清晰:

每个客户端方法背后,是对应的协议方法(JSON-RPC)。SDK 替你处理协议细节,你只调用高级方法。

六、一个完整的消费示例

把所有方法合起来,看一个完整的「消费 MCP 服务」示例:

import asyncio
from mcp import Client

async def main():
    async with Client("http://localhost:8000/mcp") as client:
        # 1. 先看看服务端有什么
        print("工具:", [t.name for t in await client.list_tools()])
        print("资源:", [r.uri for r in await client.list_resources()])
        print("模板:", [t.uri_template for t in await client.list_resource_templates()])
        print("提示词:", [p.name for p in await client.list_prompts()])

        # 2. 调一个工具
        result = await client.call_tool("add", {"a": 1, "b": 2})
        print(f"add 结果:{result.structured_content}")

        # 3. 读一个资源
        config = await client.read_resource("config://app")
        print(f"配置:{config}")

        # 4. 获取一个提示词
        messages = await client.get_prompt("summarize", {"text": "hello"})
        print(f"提示词消息:{messages}")

asyncio.run(main())
​

这就是「消费 MCP 服务」的标准模式:先 list 看有什么,再按需 call/read/get。

七、错误处理

调用方法时,可能遇到几种错误:

try:
    result = await client.call_tool("nonexistent", {})
except Exception as e:
    # 工具不存在、参数错、执行失败
    print(f"调用失败:{e}")

result = await client.call_tool("add", {"a": 1, "b": 2})
if result.is_error:
    # 工具执行了但返回错误(第 4.4 节)
    print(f"工具报错:{result.content}")
​

两类错误要区分:

• 异常(工具不存在、参数 schema 不符):调用失败,拿不到 result
• is_error=True(工具执行了但抛异常):拿到 result,但内容是错误信息

第 4.4 节讲过,工具抛异常会被 SDK 转成 is_error=True 的响应。客户端要检查这个标志,别假设 call_tool 成功返回就是工具执行成功。

💡 技巧:写客户端代码时,永远检查 is_error。即使工具名对、参数对,工具内部仍可能失败(数据库连不上、外部 API 超时)。不检查 is_error 直接用 structured_content,会基于错误数据继续,导致后续逻辑出错。

本节要点回顾

1. call_tool(name, args) 调工具,返回含 content、structured_content、is_error。
2. list_* 系列 列举工具/资源/资源模板/提示词的清单。
3. read_resource(uri) 读资源,传完整 URI(模板要填参数实例化)。
4. get_prompt(name, args) 获取提示词,返回消息列表。
5. 方法与原语一一对应,每个客户端方法背后是协议方法,SDK 处理细节。
6. 标准消费模式:先 list 看有什么,再按需 call/read/get。
7. 区分两类错误:异常(调用失败)vs is_error=True(工具执行报错),永远检查 is_error。

核心方法清楚了,下一节讲客户端的能力声明——告诉服务端「我支持什么」。