云博士带小白自然语言AI编程做A股选股产品AI神经网络全谱系架构全景精讲哈佛博后带你玩转深度学习实战图解 MCP 三类角色与调用链路课程归属MCP工具接入实战 · 第 1 节本文目标弄清 Host、Client、Server 的职责边界并用一个本地文件读取工具验证调用链路。当 AI 应用需要读取文件、查询数据库或访问公开网页时仅靠模型生成文本并不能完成这些外部操作。MCPModel Context Protocol模型上下文协议为应用与外部能力之间提供了标准化的连接方式。本文从三类角色出发搭建一个最小的本地文件读取服务观察工具如何被发现、调用、执行并返回结果。完成后你应能解释一次 MCP 调用的责任边界并能用命令行验证服务端确实执行了工具。一、先明确 MCP 解决什么问题没有统一协议时每个 AI 应用都可能为文件、数据库或网页服务编写各自的适配层。工具越多重复集成和维护成本越高。MCP 约定了客户端与服务端交换能力描述、调用请求和结果的方式但它不会自动替模型决定业务目标也不保证工具本身安全。图 1MCP 的三类角色MCP 消息用户HostAI 宿主应用Client协议客户端Server工具/上下文服务本地文件、数据库或外部 APIHost 是承载用户交互和模型调用的应用例如带有 AI 能力的桌面应用或自建 Agent 程序。Client 负责与某个 MCP Server 建立协议连接、发现能力并发送调用请求。Server 则把自身能力以协议约定的形式暴露出来并在收到合法请求后执行对应逻辑。图中的箭头表示概念上的请求和结果方向并不意味着每种传输都使用同一种网络连接。对于本地 stdioClient 通常启动 Server 子进程通过标准输入和标准输出交换消息对于远程 Streamable HTTP消息通过 HTTP 端点传输。两种方式的传输不同但 Host、Client、Server 的职责仍应分清。表 1角色职责与常见误区角色主要职责不应混淆的事情Host接收用户请求、组织模型交互、管理可用客户端及授权策略不等于 MCP ServerClient连接 Server、发现能力、发起协议请求、接收结果不负责实现所有业务工具逻辑Server声明并执行工具、提供资源或提示模板不一定包含模型也不必直接面对用户ToolServer 暴露的一项可调用操作不是独立的 MCP 角色Model理解请求、决定是否需要调用工具等模型的文字回复不等于工具真实执行二、工具、资源和提示模板有什么区别MCP 不只用于“调用函数”。服务端可以暴露 Tools、Resources 和 Prompts。它们用途不同客户端是否支持某项能力也取决于具体实现。表 2三类服务端能力能力主要用途例子Tools执行可调用的操作通常由模型或应用决定何时调用read_text_file、query_ordersResources提供可读取的上下文内容通常通过 URI 标识file:///demo/guide.txtPrompts提供可复用的提示模板或任务起点“总结这份资料并列出依据”不要把它们理解成三种不同的服务器。一个 MCP Server 可以同时提供多种能力。工具调用通常带有参数并产生执行结果Resource 更接近可寻址的上下文Prompt 则帮助客户端构造可复用的提示内容。具体结果如何呈现给模型仍由 Host 和 Client 的集成逻辑决定。图 2一次工具调用的逻辑时序ServerClient模型Host用户ServerClient模型Host用户提出读取文件的请求提供请求与可用工具信息建议调用 read_text_file请求调用指定工具发送工具名与参数校验参数并读取文件返回工具执行结果交付协议结果将结果纳入后续上下文生成面向用户的回答展示结果这张时序图是常见的 Agent 集成模式不是说 MCP 协议本身强制所有 Host 都必须调用某个模型。模型可以决定是否使用工具Host 也可以由程序逻辑直接调用工具。MCP 负责标准化 Client 与 Server 之间的能力交互不规定整个 AI 产品的完整决策流程。三、准备一个可复现的最小案例本节只实现一个文件读取工具不提前加入数据库、网页抓取或复杂 Agent 循环。案例使用教学文本路径被限制在项目的data/input/目录中避免将任意系统路径开放给调用者。表 3环境与项目结构项目本文设置终端WSL2 UbuntuPython3.11MCP SDKmcp2.2.0传输本地 stdio测试资料data/input/intro.txt验收目标Client 能发现工具并得到文件内容官方 Python SDK 的当前文档说明 Python 3.10 或更高版本可用并提供 Client、Server 以及 stdio、Streamable HTTP 等传输支持。本文固定安装mcp2.2.0避免示例在不同时间解析到不同主版本。安装前仍应根据目标平台检查依赖是否能正常解析如果需要复现完全一致的传递依赖还应保存锁文件。参考官方 SDK 文档 和 官方发行记录。在 WSL2 Ubuntu 终端执行mkdir-pmcp_lab/server mcp_lab/client mcp_lab/data/inputcdmcp_lab python3.11-mvenv .venvsource.venv/bin/activate python-mpipinstall--upgradepip python-mpipinstallmcp2.2.0python-mpip freezerequirements-lock.txt如果系统没有python3.11先在 Ubuntu 中安装对应 Python 版本或使用已有的 Python 3.11 环境。不要在一个终端创建虚拟环境、却在另一个未激活虚拟环境的终端运行脚本。创建data/input/intro.txtMCP 将 AI 应用与外部工具连接起来。 工具可以读取受限目录中的教学资料。 调用结果必须以真实执行结果为依据。项目结构如下mcp_lab/ ├── server/ │ └── server.py ├── client/ │ └── client.py ├── data/ │ └── input/ │ └── intro.txt └── requirements-lock.txt四、编写 MCP Server把函数变成工具在server/server.py中定义一个只允许读取演示目录内文本文件的工具。这里使用官方 SDK 2.x 的MCPServer接口不要直接套用旧版示例中的FastMCP导入路径跨主版本迁移应以官方迁移指南为准。frompathlibimportPathfrommcp.server.mcpserverimportMCPServerfrommcp.server.stdioimportstdio_server BASE_DIR(Path(__file__).resolve().parents[1]/data/input).resolve()serverMCPServer(mcp-file-demo)defsafe_file_path(relative_path:str)-Path:将相对路径限制在教学资料目录中。candidate(BASE_DIR/relative_path).resolve()ifcandidate!BASE_DIRandBASE_DIRnotincandidate.parents:raiseValueError(路径超出允许的资料目录)ifnotcandidate.is_file():raiseFileNotFoundError(指定文件不存在)returncandidateserver.tool()defread_text_file(relative_path:str)-dict:读取 data/input 目录中的 UTF-8 文本文件。try:pathsafe_file_path(relative_path)textpath.read_text(encodingutf-8)return{status:ok,data:{relative_path:relative_path,text:text,},source:[relative_path],error:None,}exceptFileNotFoundErrorasexc:return{status:error,data:None,source:[relative_path],error:{code:NOT_FOUND,message:str(exc)},}except(OSError,ValueError)asexc:return{status:error,data:None,source:[relative_path],error:{code:READ_FAILED,message:str(exc)},}asyncdefmain()-None:asyncwithstdio_server()as(read_stream,write_stream):awaitserver.run(read_stream,write_stream)if__name____main__:importanyio anyio.run(main)代码中的server.tool()将函数登记为 Server 的工具能力。工具函数返回的字典是本案例约定的业务结果结构并不意味着status、data、source、error是 MCP 协议的顶层字段SDK 会按照工具结果的实际机制封装返回内容。Host 或 Client 仍需按 SDK 的结果类型读取文本或结构化数据。路径校验是最小的安全边界先把路径解析成绝对路径再确认它位于允许目录内。生产系统还应考虑符号链接、文件大小、编码异常、访问权限和敏感数据等风险。不要把这个教学工具直接开放给不受信任的远程调用者。五、编写 MCP Client发现并调用工具在client/client.py中启动本地 Server 子进程连接后先列出工具再调用read_text_file。这一步验证的不只是“服务端脚本能启动”而是 Client 确实通过 MCP 协议发现并请求了工具。importasyncioimportsysfrompathlibimportPathfrommcpimportClientfrommcp.client.stdioimportStdioServerParameters ROOTPath(__file__).resolve().parents[1]SERVER_FILEROOT/server/server.pyasyncdefmain()-None:paramsStdioServerParameters(commandsys.executable,args[str(SERVER_FILE)],cwdstr(ROOT),)asyncwithClient(params)asclient:toolsawaitclient.list_tools()names[tool.namefortoolintools.tools]print(发现的工具,names)resultawaitclient.call_tool(read_text_file,{relative_path:intro.txt},)print(工具调用结果)print(result)if__name____main__:asyncio.run(main())版本提示官方 MCP Python SDK 2.x 是一次重大版本升级Client 和 Server 的 API 与 1.x 存在差异。本文按官方 2.x API 组织示例由于本文没有在当前运行环境中实际安装并执行该 SDK不能把代码声称为实测通过。正式复现时应安装固定版本并执行下方验收用例若依赖解析或公开 API 有差异应记录实际版本与调整内容。图 3从发现能力到执行工具的流程是否是否启动 Client启动 stdio Server建立消息通道list_tools发现工具存在 read_text_filecall_tool传入相对路径检查服务启动与工具注册Server 校验路径文件可读读取文本并返回结果返回错误结果Client 展示结果这个流程有两个独立检查点首先确认能力列表中出现目标工具其次确认调用后得到与文件内容一致的结果。仅看到工具名称不代表工具已经成功执行仅看到一段看似正确的文本也不能证明它来自真实文件。六、运行与验收看证据不只看回答在项目根目录、已激活的虚拟环境中执行python client/client.py预期可观察到两类信息一是发现工具列表包含read_text_file二是工具结果中包含intro.txt的三行文本。以上是预期结果不是本次环境的实测日志。实际输出的具体对象格式由安装的 SDK 版本决定验收时应检查结果中的工具名称、返回内容以及是否存在错误而不要要求打印文本与示例逐字符一致。表 4最小验收用例用例输入通过判据正常读取intro.txt返回内容与教学文件一致文件不存在missing.txt返回可识别的错误不伪造正文路径越界../../.env拒绝访问允许目录之外的路径工具发现调用list_tools()列表包含read_text_file服务启动失败使用不存在的脚本路径Client 报告连接或启动失败可用以下方式检查路径边界逻辑。该命令测试的是路径校验函数的行为不替代 MCP Client/Server 的端到端测试python -PY import importlib.util from pathlib import Path file_path Path(server/server.py).resolve() spec importlib.util.spec_from_file_location(demo_server, file_path) module importlib.util.module_from_spec(spec) spec.loader.exec_module(module) assert module.safe_file_path(intro.txt).name intro.txt try: module.safe_file_path(../../.env) except ValueError: print(越界路径已拒绝) else: raise SystemExit(失败越界路径未被拒绝) PY注意直接导入 Server 模块会触发工具注册但不会自动启动 stdio 服务。若 SDK 版本在导入阶段存在额外初始化要求应改用独立测试模块验证纯路径函数避免将测试辅助代码与服务启动逻辑耦合。七、常见故障如何定位表 5故障现象与排查路径现象常见原因排查方法ModuleNotFoundError: mcp未激活虚拟环境或装错解释器检查which python和python -m pip show mcpClient 无法启动 Server脚本路径、工作目录或命令错误打印SERVER_FILE确认文件存在工具列表为空装饰器注册失败或启动了错误脚本检查 Server 注册代码和 Client 启动参数工具调用返回错误参数名不匹配、文件不存在或权限不足核对工具 schema、相对路径和错误对象输出中混入调试文字Server 向 stdout 打印普通日志stdio 模式下将诊断日志写入 stderrstdio 的标准输出是协议消息通道不应随意打印调试文本否则可能破坏消息解析。调试时优先使用日志输出到标准错误流并分别查看 Client 与 Server 的异常。八、理解边界MCP 不等于自动安全也不等于 AgentMCP 标准化的是应用之间的能力发现和调用方式。它不会自动判断某个文件是否应该读取不会替业务系统决定用户权限也不会保证模型每次都选择正确的工具。实际应用仍需要在 Host 层落实用户授权、工具白名单、参数检查、超时、审计日志和敏感信息处理。可以用下面的分工来记忆模型负责推理建议根据用户目标判断是否需要某项能力。Host 负责应用策略管理交互、模型上下文、权限与用户确认。Client 负责协议交互发现服务端能力并发送调用请求。Server 负责能力实现验证参数、执行操作并返回结果。工具结果负责提供证据应用应检查真实返回值而不是仅凭模型说“已完成”。后续章节可以在这条链路上逐步增加参数 Schema、结构化结果、Resources、Prompts、数据库查询和远程传输。每次扩展都应保留同样的验收原则验证服务是否暴露能力、客户端是否真实发起调用、执行结果是否符合预期。参考资料Model Context Protocol 官方文档MCP Python SDK 官方文档MCP Python SDK 官方仓库与发行记录MCP Python SDK 版本与支持策略CSDN Markdown 编辑器帮助参考Mermaid 流程图语法Mermaid 时序图语法