MCPModel Context Protocol框架新课程教案课程名称MCP 框架精讲与实践适用对象AI 应用开发者、LLM 集成工程师目标全面掌握 MCP 协议架构、核心概念、开发方式与使用规范能够构建标准 MCP 服务器与客户端。格式可直接导出 PDF 的 Markdown 教案目录MCP 概述与架构传输机制与生命周期核心概念Resources核心概念Prompts核心概念Tools高级特性Sampling、Roots、Logging使用规范与功能表达开发实战构建天气 MCP Server配置与部署示例附录知识点速查表1. MCP 概述与架构1.1 什么是 MCP定义模型上下文协议Model Context Protocol由 Anthropic 提出并开源的开放协议用于标准化应用向大语言模型LLM提供上下文的方式。类比就像 USB-C 统一了设备连接MCP 统一了 AI 模型与外部数据源、工具的连接方式。目标消除各 LLM 客户端/插件生态的碎片化。让数据、工具、提示模板可一次构建多处复用。实现安全、双向的上下文交换。1.2 核心架构架构采用客户端-服务器模型包含三个关键角色角色描述示例MCP Host运行 LLM 的应用负责连接并管理多个 MCP ClientClaude Desktop、VSCode 插件、自研 APPMCP Client与 MCP Server 维持 1:1 连接的组件由 Host 管理Host 内建的协议客户端MCP Server提供上下文能力的轻量服务实现 Resources/Prompts/Tools文件系统服务器、数据库服务器、天气API服务器通信拓扑Host (内含多个 Client)↔Client↔Server一个 Host 可连接多个 Server每个 Server 对应一个 Client。1.3 能力协商初始化时客户端与服务器交换各自的能力Capabilities如resources: 是否支持资源与订阅prompts: 是否支持提示模板tools: 是否支持工具调用sampling: 服务器是否可反向请求 LLM 生成仅客户端声明roots: 是否支持文件根路径列表客户端声明logging: 是否支持日志2. 传输机制与生命周期2.1 传输方式MCP 使用 JSON-RPC 2.0 作为消息格式目前定义两种底层传输传输适用场景启动方式连接地址格式stdio本地子进程通信无需网络Client 直接 spawn Server 进程命令如python server.pyStreamable HTTP远程服务器支持流式响应Client 通过 HTTP 连接到 Serverhttp://host:port/mcpstdio通过标准输入/输出传递 JSON-RPC无加密仅本机。Streamable HTTP前身为 SSEClient 发送 HTTP POST 请求Server 通过分块传输响应流。需处理会话 ID 和重连。2.2 协议生命周期连接建立启动传输通道。初始化 (Initialize)Client 发initialize请求携带自身能力与客户端信息。Server 返回其能力与服务器信息。Client 发送initialized通知表示准备就绪。能力交换与协商基于双方声明的能力确定可用功能。正常运行交换资源读取、工具执行、提示获取等请求/通知。断开进程终止或 HTTP 会话超时。2.3 心跳与健康检查可通过ping请求/回复检测连接活性。3. 核心概念Resources3.1 定义资源Resources是将数据或文件内容以可寻址的 URI 暴露给 LLM 的接口。模型可像读取文件一样读取资源无需提前复制。3.2 资源类型文本资源返回文本内容带 MIME 类型text/*。二进制资源返回 base64 编码的 blobMIME 为image/png等。资源模板含参数的 URI 模板如weather://{city}/current支持动态匹配。3.3 资源交互方法方向描述resources/listClient→Server列出所有可用资源及模板resources/readClient→Server读取指定 URI 的内容resources/subscribeClient→Server订阅某资源的变更通知notifications/resources/updatedServer→Client资源更新时推送通知notifications/resources/list_changedServer→Client资源列表发生变化时通知3.4 使用规范资源 URI 应具有唯一性、描述性如file:///path/to/doc.mddb://users/table优先使用资源模板处理动态参数避免无限列表。大文件建议分页或使用资源内容内嵌Embedded Resource。4. 核心概念Prompts4.1 定义提示Prompts是参数化的提示模板由 Server 预定义支持多轮消息System/User/Assistant并可包含资源引用。4.2 功能表达模板可接受参数可选必填动态生成完整提示。消息可引用资源在content中嵌入resource类型指向某个资源 URI 或内容块。4.3 交互方法方法方向描述prompts/listClient→Server获取所有提示模板的清单prompts/getClient→Server根据名称和参数获取具体提示消息4.4 示例结构json { name: summarize_report, description: 总结季度报告, arguments: [ { name: quarter, required: true } ] } // 调用 prompts/get 返回 messages: { messages: [ { role: user, content: { type: text, text: 请总结以下报告... } }, { role: user, content: { type: resource, resource: { uri: report://2024/Q1 } } } ] }4.5 使用规范提示名称简洁、语义化。描述应清晰说明用途便于 Host 自动发现。参数说明需完整最好给出示例值。5. 核心概念Tools5.1 定义工具Tools是可由模型调用的函数用于执行计算、查询 API、修改数据等操作。MCP 将工具发现与执行标准化。5.2 工具 Schema每个工具包含name: 唯一名称如get_weatherdescription: 详细功能说明直接影响模型调用准确度inputSchema: JSON Schema 定义输入参数5.3 交互方法方法方向描述tools/listClient→Server列出可用工具及其 Schematools/callClient→Server调用指定工具并传参返回结果notifications/tools/list_changedServer→Client工具列表变更时通知5.4 调用结果返回content数组可以是文本、图像、嵌入式资源等。错误使用isError: true标记。5.5 使用规范描述应极尽详细说明何时使用、参数含义、返回格式因为 LLM 依赖描述进行函数选择。工具应是幂等的如果可能避免副作用歧义。复杂结果可使用结构化文本Markdown或资源引用。6. 高级特性Sampling、Roots、Logging6.1 Sampling服务器采样允许Server 向 Client 发起 LLM 生成请求实现“服务器主动要求模型思考”。典型场景工具内部需要智能总结、翻译或决策。方法sampling/createMessage由 Server 发送至 Client。安全性Client 必须明确声明支持sampling且可限制使用。6.2 Roots根目录Client 可向 Server 声明一组文件系统“根”路径如/home/user/project。Server 使用roots/list请求获取根列表Client→Server 方向有通知notifications/roots/list_changed。用于文件型 Server 确定可操作范围增强安全性。6.3 Logging日志Server 可通过notifications/logging/message向 Client 发送结构化日志。等级debug,info,warning,error。须在初始化时声明logging能力。6.4 错误处理基于 JSON-RPC 错误码预定义标准错误类型-32700解析错误-32600无效请求-32601方法未找到-32602无效参数-32603内部错误。业务逻辑错误在result中通过isError: true返回。7. 使用规范与功能表达7.1 设计原则单一职责一个 Server 聚焦一类能力如只有文件操作或只有数据库查询。描述即接口Tools/Prompts 的描述质量直接影响 LLM 调用的正确率。渐进式暴露通过资源模板、参数化提示避免一次性暴露海量数据。安全第一明确读写权限工具应校验输入遵循最小权限原则。7.2 功能表达检查清单Resources 是否覆盖静态数据和动态数据模板Prompts 是否封装了常用任务流是否包含参数说明Tools 的inputSchema是否精确且约束合理所有文本均用 Markdown 优化可读性是否注册了列表变更通知以支持动态更新传输选择本地用 stdio远程用 Streamable HTTP。7.3 开发方式推荐使用官方 SDKPython:mcp[cli](pip install mcp)TypeScript:modelcontextprotocol/sdkGo/Java社区 SDK构建 Server 的核心步骤创建服务器实例并声明能力。注册resources/list、resources/read等处理器。使用server.list_prompts()server.call_tool()装饰器定义功能。选择传输并启动server.run()。调试工具MCP Inspector(npx modelcontextprotocol/inspector) 可可视化测试 Server。8. 开发实战构建天气 MCP Server示例使用 Python SDK展示 Resources、Prompts、Tools 的综合运用。python import json from mcp.server import Server, NotificationOptions from mcp.server.stdio import stdio_server import mcp.types as types # 创建服务器实例 server Server(weather-server) # --- Resources --- server.list_resources() async def list_resources() - list[types.Resource]: return [ types.Resource( uriweather://current/Beijing, name北京当前天气, mimeTypetext/plain, description实时天气数据 ) ] server.read_resource() async def read_resource(uri: str) - str: if uri weather://current/Beijing: # 模拟获取数据 data {city: 北京, temp: 28, condition: 晴} return json.dumps(data, ensure_asciiFalse) raise ValueError(未知资源) # --- Prompts --- server.list_prompts() async def list_prompts() - list[types.Prompt]: return [ types.Prompt( nameweather_advice, description根据天气给出穿衣建议, arguments[ types.PromptArgument(namecity, requiredTrue) ] ) ] server.get_prompt() async def get_prompt(name: str, arguments: dict) - types.GetPromptResult: if name weather_advice: city arguments.get(city, 北京) return types.GetPromptResult( messages[ types.PromptMessage( roleuser, contenttypes.TextContent( typetext, textf请根据 {city} 的当前天气从资源读取给出具体的穿衣建议。 ) ) ] ) raise ValueError(未知提示) # --- Tools --- server.list_tools() async def list_tools() - list[types.Tool]: return [ types.Tool( nameget_forecast, description获取指定城市未来3天天气预报输入城市中文名返回摘要, inputSchema{ type: object, properties: { city: {type: string, description: 城市名如 上海} }, required: [city] } ) ] server.call_tool() async def call_tool(name: str, arguments: dict) - list[types.TextContent]: if name get_forecast: city arguments[city] # 模拟预报 forecast f{city}未来三天25-30°C多云转晴 return [types.TextContent(typetext, textforecast)] raise ValueError(未知工具) # 启动 async def main(): async with stdio_server() as (read, write): await server.run(read, write, server.create_initialization_options()) if __name__ __main__: import asyncio asyncio.run(main())9. 配置与部署示例9.1 在 Claude Desktop 中配置 stdio Server编辑claude_desktop_config.jsonjson{ mcpServers: { weather: { command: python, args: [path/to/weather_server.py] } } }重启 Claude Desktop即可通过对话调用 weather 工具和资源。9.2 Streamable HTTP 部署使用mcp包提供的 ASGI/WSGI 集成或直接使用 FastAPI 包装pythonfrom mcp.server.streamable_http import StreamableHTTPServerTransport # ... 定义 server 后 transport StreamableHTTPServerTransport(/mcp) app transport.get_asgi_app()Client 端配置连接 URL。10. 附录知识点速查表分类知识点关键方法/事项协议基础JSON-RPC 2.0、请求/响应/通知initialize,ping, 错误码传输stdio子进程标准输入输出无网络传输Streamable HTTPHTTP POST 流式响应会话管理能力resources, prompts, tools, sampling, roots, logging初始化协商资源静态资源、资源模板、内容类型resources/list,resources/read, 订阅更新提示参数化模板、多轮消息、嵌入资源prompts/list,prompts/get工具JSON Schema 输入、结构化输出tools/list,tools/call反向Server→Client 生成请求sampling/createMessage根文件系统作用域roots/list安全限制日志Server→Client 日志logging/message级别控制开发Python/TS SDK装饰器注册server.call_tool等调试MCP Inspector可视化测试工具部署Claude Desktop 配置、HTTP 部署配置mcpServers字段设计规范描述即接口、单一职责、安全校验Tools 描述详细化资源 URI 唯一