# MCP Builder - 模型上下文协议服务器开发 ##什么是MCP？模型上下文协议 (MCP) 是 Anthropic 创建的开放标准，使 Claude 等 AI 助手能够安全地连接到外部数据源和工具。将其视为一个通用适配器，允许 Claude 通过标准化接口与任何系统、API 或数据源进行交互。 **主要优点：** * **标准化**：适用于所有集成的一种协议 * **安全**：内置身份验证和权限控制 * **灵活性**：支持工具、资源和提示 * **可扩展性**：专为生产工作负载而设计 * **模块化**：为不同域创建可重用的MCP服务器 ## 架构概述 MCP 遵循客户端-服务器架构： ┌──────────────┐ ┐──────────────┐ ┌──────────────┐ │ Claude │ ←──MCP──→ │ MCP 服务器 │ ←──────→ │ 外部 API │ │（客户端）│ │（您的代码）│ │ 数据库 │ └──────────────┘ └──────────────┘ └──────────────┘ **组件：** * **客户端**：Claude Desktop、Claude Code 或自定义应用程序 * **服务器** ：您的 MCP 实现（Python、TypeScript 等） * **传输** ：通信通道（stdio、HTTP、SSE） * **协议** ：标准化消息格式（JSON-RPC 2.0）详细的协议规范请参见[协议规范参考]()。 ## 核心组件 ### 1\.工具：公开 Claude 可以调用的函数工具是赋予克劳德新能力的主要方式。每个工具都是 Claude 可以使用特定参数调用的函数。 **工具定义结构：** { “名称”：“工具名称”， "description": "清楚地描述该工具的用途", “输入模式”：{ “类型”：“对象”， “属性”：{ “参数1”：{ “类型”：“字符串”， "description": "参数说明" } }, “必需”：[“参数1”] } } **关键原则：** * **清晰的命名** ：使用描述性的、面向操作的名称（例如，“search_database”，而不是“db_query”） * **全面描述** ：解释该工具的作用、何时使用它以及它返回什么 * **强大的模式** ：使用 JSON Schema 来验证输入并指导 Claude * **错误处理** ：出现问题时返回清晰的错误消息有关完整的架构设计模式和最佳实践，请参阅[工具架构参考]()。 ### 2\.资源：提供数据/文档访问资源允许 Claude 访问文件、文档或结构化数据。与工具（执行操作）不同，资源提供信息。 **资源类型：** * **静态**：固定内容（例如文档文件） * **动态**：按需生成（例如数据库查询） * **模板** ：参数化资源（例如用户配置文件） **资源 URI 模式：** file:///path/to/file.txt # 本地文件 http://example.com/api/docs # HTTP 资源 custom://database/users/123 # 自定义方案 template://report/{user_id} # 模板资源 ### 3\.提示：可重复使用的提示模板提示是用户可以调用的预定义消息模板。它们有助于标准化常见工作流程和最佳实践。 **提示定义：** { “名称”：“代码审查”， "description": "全面的代码审查清单", “参数”：[ { “名称”：“语言”， "description": "编程语言", “必需”：正确 } ] } ### 4\.认证方式 MCP支持多种认证方式： * **无身份验证**（仅限开发） * **API 密钥身份验证**（简单，中等安全性） * **OAuth 2.0**（第三方，安全性高） * **不记名令牌**（API-to-API，高安全性）有关完整的安全实施指南，请参阅[安全最佳实践]()。 ## 服务器实现工作流程 ### 第一阶段：项目设置创建您的 MCP 服务器项目： # 创建项目目录 mkdir my-mcp-server cd my-mcp-服务器 # 初始化Python项目紫外线初始化紫外线添加MCP # 创建服务器文件触摸服务器.py ### 第 2 阶段：基本服务器结构 **最小工作服务器：** 从 mcp.server 导入服务器从 mcp.server.stdio 导入 stdio_server 从 mcp.types 导入工具、文本内容导入异步应用程序=服务器（“我的MCP服务器”） @app.list_tools() 异步 def list_tools(): 返回[ 工具( 名称=“我的工具”， description="此工具功能的描述", 输入架构={ “类型”：“对象”， “属性”：{ “参数”：{“类型”：“字符串”} }, “必需”：[“参数”] } ） ] @app.call_tool() async def call_tool(名称: str, 参数: dict): 如果名称==“my_tool”：参数=参数[“参数”] 结果= f“已处理：{param}” 返回[TextContent（类型=“文本”，文本=结果）] 异步 def main(): 与 stdio_server() 异步为（read_stream，write_stream）：等待app.run（read_stream，write_stream，app.create_initialization_options（））如果 __name__ == "__main__": asyncio.run（主（）） ### 第 3 阶段：工具注册和处理程序 **注册模式：** @app.list_tools() 异步 def list_tools(): 返回[ 工具( 名称=“计算器添加”，描述=“添加两个数字”，输入架构={ “类型”：“对象”， “属性”：{ "a": {"type": "number", "description": "第一个数字"}, "b": {"type": "number", "description": "第二个数字"} }, “必需”：[“a”，“b”] } ） ] **处理程序模式：** @app.call_tool() async def call_tool(名称: str, 参数: dict): 如果名称==“calculator_add”：返回等待handle_calculator_add（参数）其他：引发 ValueError(f"未知工具：{name}") 异步 def handle_calculator_add(参数: dict): a = 参数[“a”] b = 参数[“b”] 结果 = a + b 返回 [TextContent(type="text", text=f"{a} + {b} = {结果}")] ### 第 4 阶段：资源实施 **静态和动态资源示例：** 从 mcp.types 导入资源、ResourceContents、TextResourceContents @app.list_resources() 异步 def list_resources(): 返回[资源（uri =“文件：///docs/readme.md”，名称=“README”，描述=“文档”，mimeType=“文本/markdown”）] @app.read_resource() 异步 def read_resource(uri: str): 如果 uri.startswith("file://"): 将 open(uri[7:], 'r') 作为 f: 返回资源内容（内容= [TextResourceContents（ uri=uri, mimeType="text/markdown", text=f.read())]) 有关完整实现，请参阅[资源服务器示例]()。 ### 第 5 阶段：错误处理和测试 **错误响应模式：** async def call_tool(名称: str, 参数: dict): 尝试：返回[TextContent（类型=“文本”，文本=等待execute_tool（名称，参数））] 除了 ValueError 为 e： return [TextContent(type="text", text=f"无效输入：{str(e)}", isError=True)] 除了异常 e： logger.exception("意外错误") 返回 [TextContent(type="text", text=f"错误: {type(e).__name__}", isError=True)] **测试：** # 使用 MCP 检查器进行测试 npx @modelcontextprotocol/inspector python server.py 有关综合策略，请参阅[测试和调试指南]()。 ### 第 6 阶段：Claude 桌面集成 **配置：** 编辑`claude_desktop_config.json`： * macOS：`~/Library/Application Support/Claude/` * Windows: `%APPDATA%\Claude/` * Linux: `~/.config/Claude/` { “mcp服务器”：{ “我的服务器”：{ “命令”：“蟒蛇”， “args”：[“/绝对/路径/to/server.py”]， “env”：{“API_KEY”：“您的密钥”} } } } ## 最佳实践 ### 工具架构设计 **使用描述性名称：** # ✅ 好 “通过电子邮件搜索客户” “计算运费” # ❌ 不好 “搜索” “计算” **提供全面的描述：** # ✅ 好描述=“” 通过电子邮件地址搜索客户。返回客户资料，包括： - 联系方式 - 订单历史记录 - 账户状态 ”“” # ❌ 不好描述=“搜索客户” **使用枚举作为固定选项：** # ✅ 好 “状态”：{ “类型”：“字符串”， "enum": ["待定", "已批准", "已拒绝"], "description": "申请状态" } ### 错误处理策略对错误与自定义异常进行分类并提供可操作的消息：类验证错误（异常）：通过类 AuthenticationError（异常）：通过 async def call_tool(名称: str, 参数: dict): 尝试：返回等待执行工具（名称，参数）除了 ValidationError 为 e： return [TextContent(type="text", text=f"无效输入：{str(e)}", isError=True)] ### 安全考虑始终验证输入并使用环境变量作为机密： # 输入验证 def validate_url(url: str) -> bool: 如果 urlparse(url).scheme 不在 ['http', 'https'] 中： raise ValidationError("仅允许 HTTP/HTTPS URL") # 秘密管理 API_KEY = os.getenv("API_KEY") # ✅ 好 # API_KEY = "sk-1234" # ❌ 不好 - 切勿硬编码！ ### 性能优化使用连接池和并行异步操作： # ✅ 并行执行结果=等待asyncio.gather（* [fetch_user_data（uid）用于user_ids中的uid]） # ❌ 顺序执行（慢）对于 user_ids 中的 user_id：结果 = 等待 fetch_user_data(user_id) ## 常见陷阱 ### 架构验证错误 **缺少所需的验证：** # ❌ 不好：没有验证异步 def handle_create_user(参数: dict): username = argument["username"] # 如果丢失将会崩溃！ # ✅ 好：验证输入异步 def handle_create_user(参数: dict): 如果“用户名”不在参数中：返回 [TextContent(type="text", text="错误：需要用户名", isError=True)] 用户名=参数[“用户名”] ### 身份验证问题 **不安全的存储：** # ❌ 不好：硬编码 API 密钥 API_KEY =“sk-1234567890abcdef” # ✅ 好：环境变量 API_KEY = os.getenv("API_KEY") 如果不是API_KEY：引发 ValueError("需要 API_KEY 环境变量") ### 传输配置 **路径问题：** # ❌ 不好：相对路径 { “命令”：“蟒蛇”， "args": ["server.py"] # 不起作用！ } # ✅ 好：绝对路径 { “命令”：“蟒蛇”， “args”：[“/Users/用户名/projects/mcp-server/server.py”] } ### 错误传播 **无声的失败：** # ❌ 坏：无声的失败 async def call_tool(名称: str, 参数: dict): 尝试：返回等待执行工具（名称，参数）除了例外：返回 [TextContent(type="text", text="出了点问题")] # ✅ 好：描述性错误 async def call_tool(名称: str, 参数: dict): 尝试：返回等待执行工具（名称，参数）除了 ValueError 为 e： return [TextContent(type="text", text=f"无效输入：{str(e)}", isError=True)] 除了异常 e： logger.exception("意外错误") 返回 [TextContent(type="text", text=f"错误: {type(e).__name__}", isError=True)] **不标记错误：** # ❌ 不好返回 [TextContent(type="text", text="错误：失败")] # ✅ 好返回 [TextContent(type="text", text="错误：失败", isError=True)] ## 其他资源 ### 官方文档 * MCP规范： * Python SDK： * TypeScript SDK： ### 详细参考资料 * [协议规范]() \- 完整的协议细节、消息格式、传输机制 * [工具架构指南]() \- 全面的架构模式和验证 * [安全最佳实践]() \- 身份验证、授权、输入验证、机密管理 * [测试和调试]() \- 单元测试、集成测试、MCP 检查器使用、调试技术 * [生产部署]() \- 生产配置、监控、扩展、Docker 部署 ### 完整示例 * [简单计算器服务器]() \- 基本算术工具 * [REST API 包装器]() \- GitHub API 集成 * [数据库服务器]() \- 安全的数据库查询访问 * [资源服务器]() \- 静态和动态资源 ### 工具 * MCP 检查器： * 克劳德桌面： ## 快速参考 ### 服务器模板 (Python) 从 mcp.server 导入服务器从 mcp.server.stdio 导入 stdio_server 从 mcp.types 导入工具、文本内容导入异步应用程序=服务器（“我的服务器”） @app.list_tools() 异步 def list_tools(): 返回 [工具(名称=“my_tool”，描述=“...”，inputSchema={...})] @app.call_tool() async def call_tool(名称: str, 参数: dict): 如果名称==“my_tool”：返回[TextContent（类型=“文本”，文本=“结果”）] 异步 def main(): 与 stdio_server() 异步为（read_stream，write_stream）：等待app.run（read_stream，write_stream，app.create_initialization_options（））如果 __name__ == "__main__": asyncio.run（主（）） ### 常见模式 **错误处理：** 返回 [TextContent(type="text", text="错误消息", isError=True)] **异步操作：** 结果=等待 asyncio.gather(*任务) **输入验证：** 如果参数中没有“required_param”：返回 [TextContent(type="text", text="缺少参数", isError=True)] ** ** **MCP Builder 技能指南结束** 有关完整的工作示例和详细的技术参考，请浏览“examples/”和“references/”目录。

MCP生成器

包含技能