DeepCode MCP Server 构建最佳实践从命名规范、响应设计到安全加固的完整指南【免费下载链接】DeepCodeDeepCode: Open Agentic Coding (Agent Harness Loop Engineering Multi-Agent Orchestration)项目地址: https://gitcode.com/GitHub_Trending/deepc/DeepCode导读本文是 DeepCode 开源仓库内置mcp-builder技能中通用 MCPModel Context Protocol服务端构建指南的完整解读。它面向两类读者一是要为自己的服务Slack、GitHub、Jira 等编写高质量 MCP 服务器、让 LLM 能顺畅调用外部 API 的开发者二是要在 DeepCode 这一 Agentic Coding 平台中注册、配置与消费 MCP 服务器的使用者。读完本文你将掌握一套可直接落地的 MCP 服务器设计规范——包括服务器/工具命名、JSON 与 Markdown 双响应格式、分页元数据、stdio 与 Streamable HTTP 传输选型、OAuth 2.1 与 API Key 安全实践、工具注解语义以及完整的测试与文档要求并能从 DeepCode 的运行时实现core/mcp中看到这些规范在真实产品中的落地形态。一、文档定位mcp-builder 技能体系中的通用准则在 DeepCode 仓库中mcp-builder是一个内置技能其总纲文件 SKILL.md 将创建 MCP 服务器的流程划分为四个阶段深度调研与规划Phase 1、实现Phase 2、评审与测试Phase 3、创建评估Phase 4。其中阶段 1.3 明确要求加载本文档——mcp_best_practices.md并称之为Core guidelines / Universal MCP guidelines。该文档在整个技能体系中处于语言无关的通用规范层与另外三份文档构成完整体系文档仓库根目录相对路径作用reference/mcp_best_practices.md通用最佳实践命名、响应、分页、传输、安全、注解、错误处理、测试、文档本文主题reference/python_mcp_server.mdPython/FastMCP 专属实现指南Pydantic 校验、mcp.tool注册、完整示例reference/node_mcp_server.mdNode/TypeScript 专属实现指南Zod 校验、registerTool注册、完整示例reference/evaluation.mdMCP 服务器评估体系如何用 10 道可验证问题检验 LLM 对服务器的使用效果DeepCode 项目自述为 Open Agentic Coding (Agent Harness Loop Engineering Multi-Agent Orchestration)其自身的 MCP 运行时core/mcp/runtime.py实现了对这些规范的消费端支持——包括服务器启动生命周期、工具发现与注册、注解解析、审批模式等后文将逐一对应展开。二、命名规范让模型一眼找到正确的工具2.1 服务器命名Server Naming最佳实践文档给出了与语言绑定、且易于从任务描述推断的命名模式Python{service}_mcp小写 下划线例如slack_mcp、github_mcp、jira_mcpNode/TypeScript{service}-mcp-server小写 连字符例如slack-mcp-server、github-mcp-server、jira-mcp-server。命名应满足四条约束通用不绑定具体功能特性、能描述所集成的服务、易于从任务描述中推断、不含版本号或日期。这一约定在语言专属指南中被进一步落实为可运行的代码Python 侧初始化mcp FastMCP(example_mcp)见 python_mcp_server.mdTypeScript 侧初始化new McpServer({ name: example-mcp, version: 1.0.0 })见 node_mcp_server.md。在 DeepCode 消费端服务器名被严格校验core/mcp/models.py 中的validate_server_name()使用正则^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$即 180 个字符、仅允许字母数字与.、-、_否则抛出McpConfigurationError。这意味着服务端命名的易推断与消费端的可解析是相互配套的。2.2 工具命名Tool Naming工具命名规范可以浓缩为四条使用 snake_case如search_users、create_project、get_channel_info携带服务前缀要预见到你的 MCP 服务器会与其他 MCP 服务器并存用slack_send_message而非send_message用github_create_issue而非create_issue动作导向以动词开头get、list、search、create 等足够具体避免与其他服务器冲突的通用名。格式归纳为{service}_{action}_{resource}例如slack_send_message、github_create_issue。这条规范在 DeepCode 的运行时中得到了双重保障式的实现。见 core/mcp/naming.py 的visible_tool_name()每个来自 MCP 服务器的工具会被映射为mcp__{server}__{tool}形式如mcp__slack__send_message天然携带服务前缀名称长度上限 64 字符MAX_TOOL_NAME_LENGTH 64超出时用 SHA-256 摘要前 10 位十六进制做确定性后缀既保证唯一又可复现遇到重名时自动追加_1、_2编号不会覆盖其他已注册工具。也就是说即使服务器作者漏写了服务前缀DeepCode 也会在模型可见层强制带上mcp__server__前缀以避免跨服务器冲突原始工具名仍以McpToolIdentity.raw_name保留见 core/mcp/tools.py。这在 tests/test_mcp_runtime.py 等测试中有覆盖。三、工具设计描述要窄而准工具设计Tool Design部分强调工具描述必须窄范围、无歧义地描述其功能描述必须与实际功能精确匹配防幻觉提供工具注解readOnlyHint、destructiveHint、idempotentHint、openWorldHint保持操作聚焦且原子一个工具只做一件事。Python 实现指南进一步给出操作要点描述应由函数签名 docstring 自动生成FastMCP 特性docstring 中应包含参数说明、返回 JSON schema、使用示例Use when / Dont use when、错误处理说明。TypeScript 侧则强调description字段必须显式提供JSDoc 注释不会自动提取inputSchema必须是 Zod schema 对象而非 JSON schemaoutputSchema应尽量定义以输出结构化数据。四、响应格式JSON 与 Markdown 双轨并行最佳实践文档规定所有返回数据的工具都应支持多种格式通过response_format参数切换。JSON 格式response_formatjson——面向程序化处理机器可读的结构化数据包含所有可用字段与元数据字段名与类型保持一致。Markdown 格式response_formatmarkdown通常为默认——面向人类/LLM 阅读使用标题、列表与排版增强可读性将时间戳转换为人类可读格式如2024-01-15 10:30:00 UTC而非 epoch显示名 ID 并列展示如john.doe (U123456)省略冗余元数据如只保留一个头像 URL而非全部尺寸按逻辑对相关信息分组。Python 侧推荐用StrEnum定义ResponseFormat例如from enum import Enum class ResponseFormat(str, Enum): MARKDOWN markdown JSON json class UserSearchInput(BaseModel): query: str Field(..., descriptionSearch query) response_format: ResponseFormat Field( defaultResponseFormat.MARKDOWN, descriptionOutput format: markdown for human-readable or json for machine-readable )TypeScript 侧用z.nativeEnum(ResponseFormat).default(ResponseFormat.MARKDOWN)实现等价约束并在返回时同时给出content文本展示与structuredContent结构化数据——后者是 TypeScript SDK 支持文本 结构化双通道的现代模式。DeepCode 消费端的处理与此呼应core/mcp/tools.py 的_result_text()会遍历结果的content块提取文本并在没有文本块时回退读取structuredContent并序列化为 JSON——说明服务端返回的两种形态在 DeepCode 中都能被正确呈现给模型。五、分页规范永远尊重 limit 参数对于列出资源的工具最佳实践文档要求始终尊重limit参数实现分页使用offset或游标cursor分页返回分页元数据has_more、next_offset/next_cursor、total_count绝不把全部结果一次性加载进内存尤其针对大数据集默认限制合理通常 2050 条。文档给出的示例分页响应{ total: 150, count: 20, offset: 0, items: [...], has_more: true, next_offset: 20 }在 Python 实现指南中对应的字段约束是limitge1, le100默认 20与offsetge0默认 0且has_more通过total offset len(items)计算。TypeScript 指南还额外引入CHARACTER_LIMIT常量示例为 25000 字符防止响应过大撑爆上下文超限时截断并在消息中提示Use offset parameter or add filters to see more results.。这与 DeepCode 的上下文管理哲学一致Agent 的上下文窗口是稀缺资源工具应返回聚焦、相关的数据SKILL.md 阶段 1.1 的 Context Management 要求分页 过滤正是实现手段。六、传输层选型stdio 还是 Streamable HTTP6.1 两种传输的特性Streamable HTTP——适合远程服务器、Web 服务、多客户端场景基于 HTTP 的双向通信支持多个并发客户端可作为 Web 服务部署支持服务器到客户端的通知server-to-client notifications。stdio——适合本地集成、命令行工具标准输入/输出流通信设置简单无需网络配置作为客户端的子进程运行重要stdio 服务器不应向 stdout 打日志日志请走 stderr。文档还明确指出避免使用 SSE已弃用被 Streamable HTTP 取代。6.2 选型对照表评判维度stdioStreamable HTTP部署方式本地Local远程Remote客户端单个Single多个Multiple复杂度低Low中等Medium实时性无No有Yes6.3 DeepCode 中的传输契约与真实示例DeepCode 的服务器定义模型core/mcp/models.py 的McpServerDefinition将传输类型限定为type: Literal[stdio, sse, streamableHttp]并通过_transport_contract模型校验器强制执行互斥契约stdio服务器必须有command且不得定义任何 HTTP 字段url、headers、bearerTokenEnvVar等HTTP 类服务器sse/streamableHttp必须有合法的http/httpsURL且不得定义 stdio 进程字段command、args、cwd、env等required必需服务器不能deferLoading延迟加载传输类型不会从 URL 后缀或命令存在与否推断必须显式声明。内置预设文件 core/mcp/presets.json 给出了真实世界的选型样例{ id: browserbase, server: { type: streamableHttp, url: https://mcp.browserbase.com/mcp, envUrlParams: {browserbaseApiKey: BROWSERBASE_API_KEY}, toolTimeoutSeconds: 60, approvalMode: writes } }, { id: playwright, server: { type: stdio, command: npx, args: [-y, playwright/mcplatest], toolTimeoutSeconds: 60, approvalMode: writes } }可以看到云端托管的 Browserbase 用streamableHttp远程接入本地的 Playwright 用stdio拉起子进程——与最佳实践文档的选型标准完全一致。七、安全最佳实践认证、校验与防护7.1 认证与授权OAuth 2.1使用来自权威机构签发的证书进行安全的 OAuth 2.1处理请求前先校验访问令牌只接受明确面向你服务器签发的令牌。API KeysAPI Key 存于环境变量绝不写死在代码里服务器启动时即校验 Key 的有效性认证失败时给出清晰的错误消息。DeepCode 对此提供了更强的存储边界约束core/mcp/models.py 的validate_no_literal_secrets()会检测env与headers中任何看起来敏感的名称匹配authorization、cookie、api_key、password、secret、private_key等模式一旦发现即抛出McpConfigurationError强制改用envVars转发环境变量、credentialEnv引用用户连接的凭据格式provider:connection-id或bearerTokenCredential。同时 core/mcp/runtime.py 的McpSessionRuntime注释强调凭据只在连接启动前一刻解析绝不进入清单、诊断信息或序列化后的运行时计划。7.2 输入校验对文件路径做清洗防止目录遍历directory traversal校验 URL 与外部标识符检查参数大小与取值范围在系统调用中防止命令注入对所有输入使用schema 校验Pydantic / Zod。Python 侧推荐 Pydantic v2 写法model_config ConfigDict(str_strip_whitespaceTrue, validate_assignmentTrue, extraforbid)Field(..., min_length1, max_length100)约束 field_validator自定义校验。TypeScript 侧用 Zod.min(2, Query must be at least 2 characters)、.int()、.max(100)并用.strict()禁止多余字段。DeepCode 的McpServerDefinition对 header 名、环境变量名、URL 参数名也都有正则校验防止注入类攻击。7.3 错误处理不向客户端暴露内部错误安全相关的错误在服务端记录日志提供有用但不泄露细节的错误消息出错后正确清理资源。7.4 DNS Rebinding 防护本地 Streamable HTTP对于本地运行的 Streamable HTTP 服务器启用 DNS rebinding 防护校验所有入站连接的Origin头绑定127.0.0.1而非0.0.0.0。八、工具注解Tool Annotationshint 而非安全保证最佳实践文档给出了四个注解的语义表注解类型默认值含义readOnlyHintbooleanfalse工具不修改其环境destructiveHintbooleantrue工具可能执行破坏性更新idempotentHintbooleanfalse相同参数重复调用无额外效果openWorldHintbooleantrue工具与外部实体交互文档特别强调注解是提示hints不是安全保证guarantees。客户端不应仅凭注解做安全关键决策。这一原则在 DeepCode 中得到了教科书式的落实。见 core/mcp/tools.py 的McpToolAdapter.read_only属性property def read_only(self) - bool: # MCP annotations are hints, not grants. Unknown is deliberately # mutating so default/writes policies fail toward confirmation. return self.annotations.read_only代码注释直译即为注解是提示不是授权。当注解缺失时DeepCode 故意按可写mutating处理让默认/写策略向需要确认的方向失败fail toward confirmation即宁可让写操作触发人工审批也不因缺失注解而放行。注解通过 core/mcp/models.py 的McpToolAnnotations.from_sdk()从 SDK 定义解析并会以approvalModeauto/prompt/writes/approve叠加到全局权限之上形成 MCP 专属的审批层级。九、错误处理与错误消息设计最佳实践文档要求使用标准 JSON-RPC 错误码工具错误在 result 对象内上报而非协议层错误提供有帮助、具体、带下一步建议的错误消息不暴露内部实现细节出错时妥善清理资源。文档给出的 TypeScript 错误处理示例工具内部捕获并返回isErrortry { const result performOperation(); return { content: [{ type: text, text: result }] }; } catch (error) { return { isError: true, content: [{ type: text, text: Error: ${error.message}. Try using filteractive_only to reduce results. }] }; }注意两个细节一是错误通过isError: true放在结果对象中返回而不是中断 JSON-RPC 协议二是错误消息末尾附上了可执行的下一步建议Try using filteractive_only...——这正是Actionable Error Messages原则的体现SKILL.md 阶段 1.1。Python 指南进一步示范了按 HTTP 状态码分类的错误映射404→请检查 ID 是否正确、403→权限不足、429→触发限流请稍后重试、超时→请重试。DeepCode 消费端在 core/mcp/tools.py 的execute()中会读取result.isError并完整透传文本、附带approvalMode等元数据同时通过log_mcp_call记录调用遥测观测失败不影响工具结果。十、测试要求五类测试全覆盖最佳实践文档要求全面的测试覆盖功能测试Functional验证有效/无效输入下的正确执行集成测试Integration测试与外部系统的交互安全测试Security校验认证、输入清洗、限流性能测试Performance检查负载与超时下的行为错误处理Error Handling确保错误上报与资源清理正确。语言专属指南给出的构建与冒烟方法# TypeScript先构建再测试用 MCP Inspector 交互调试 npm run build npx modelcontextprotocol/inspector # Python语法校验 MCP Inspector python -m py_compile your_server.py npx modelcontextprotocol/inspector在 DeepCode 仓库中MCP 运行时自身的测试覆盖了 test_mcp_runtime.py、test_mcp_runtime_lazy.py延迟加载/按需激活、test_mcp_oauth.pyOAuth 流程等可作为测试方法的参照样例。十一、文档要求让每个工具都可被发现、被信任最佳实践文档对服务器作者提出的文档义务清晰记录所有工具与能力每个主要功能至少 3 个可工作的示例记录安全注意事项说明所需的权限与访问级别记录限流rate limits与性能特征。在 DeepCode 的消费端工具描述会被截断至 8000 字符展示给模型core/mcp/tools.py服务器的 instructions 也有截断上限server_instruction4000 字符、instruction_context8000 字符见 core/mcp/runtime.py——因此描述要精炼、要点前置不只是审美问题而是直接影响模型可读性的工程约束。十二、配套用评估闭环检验 MCP 服务器质量虽然评估细则在独立的 reference/evaluation.md 中但它与本文档的Testing Requirements构成闭环。其核心理念值得在此强调MCP 服务器的质量不以实现了多少工具衡量而以只给工具、不给其他上下文的情况下LLM 能否借此回答真实且困难的问题衡量。评估要求创建 10 道独立、只读、不可破坏、答案可字符串比对且随时间稳定基于历史数据的问题并通过scripts/evaluation.py支持-t stdio/sse/http、-m指定模型、-o输出报告运行得到准确率、平均耗时、平均工具调用数等指标。结语本文档所承载的规范——从{service}_{action}_{resource}命名、JSON/Markdown 双格式、分页元数据到传输选型、安全加固、注解语义与测试/文档义务——构成了一个语言无关的MCP 服务器质量底线。在 DeepCode 中这些规范既有 SKILL.md 层面的流程支撑又有 core/mcp 运行时层面的强制落实工具前缀化命名、注解按 hint 而非授权处理、凭据不入配置字面量、传输契约互斥校验还有 core/mcp/presets.json 的真实预设作为参照。无论你是要编写一个全新的 MCP 服务器还是要在 DeepCode 中接入第三方 MCP 服务本文给出的规范与实现对照都可以直接作为设计评审清单使用。【免费下载链接】DeepCodeDeepCode: Open Agentic Coding (Agent Harness Loop Engineering Multi-Agent Orchestration)项目地址: https://gitcode.com/GitHub_Trending/deepc/DeepCode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考