Activepieces MCP Server 最佳实践指南命名、工具设计、分页、传输与安全规范【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces导读本文是 Activepieces 仓库中 MCP 服务器最佳实践文档 的深度展开版。它面向需要为 LLM如 Claude、Cursor、Windsurf构建高质量 MCPModel Context Protocol服务器的开发者系统讲解服务器与工具的命名约定、JSON/Markdown 双格式响应、分页元数据、stdio 与 Streamable HTTP 传输选型、安全加固、工具注解、错误处理、测试与文档要求。读完本文你将掌握一套可直接落地、可被 Agent 顺畅发现与调用的 MCP 服务器设计与实现规范并理解 Activepieces 内部托管 MCP 服务器mcp-server-builder.ts是如何将这些最佳实践固化为代码的。一、速查卡Quick Reference原文档首先给出了一页纸式的速查条目它们是后续所有章节的浓缩开发时应当时刻对照维度规范Python 服务器命名{service}_mcp例如slack_mcpNode/TypeScript 服务器命名{service}-mcp-server例如slack-mcp-server工具命名snake_case 且带服务前缀格式{service}_{action}_{resource}工具命名示例slack_send_message、github_create_issue响应格式同时支持 JSON 与 MarkdownJSON 面向程序化处理Markdown 面向人类可读分页始终尊重limit参数返回has_more、next_offset、total_count默认每页 20–50 条传输层远程/多客户端场景用 Streamable HTTP本地/命令行工具用 stdio避免 SSE已被 Streamable HTTP 取代这些约定并非空谈。在 Activepieces 中McpToolDefinition类型packages/core/shared/src/lib/automation/mcp/mcp.ts就为每个工具定义了title、description、inputSchema与annotations而服务器侧在注册工具时正是把工具名作为 LLM 可见的唯一标识符mcp-server-builder.ts因此命名是否清晰、是否有前缀直接影响 Agent 能否在众多工具中快速命中正确的那一个。二、服务器命名规范Server Naming ConventionsPython{service}_mcp全小写、下划线分隔示例slack_mcp、github_mcp、jira_mcp。Node/TypeScript{service}-mcp-server全小写、连字符分隔示例slack-mcp-server、github-mcp-server、jira-mcp-server。命名要点名称应当通用且能准确描述被集成的服务应当能从任务描述中轻易推断出该服务器是干什么的不要带版本号版本信息应交给包管理或 manifest而不是包名保持一致的前缀体系便于在工具列表中按服务归类。仓库中的托管服务器也遵循同样的精神buildMcpServer创建的服务器实例名为Activepieces版本号1.0.0独立于名称之外mcp-server-builder.ts名称只承担描述服务的职责。三、工具命名与设计Tool Naming and Design工具命名四原则使用 snake_casesearch_users、create_project、get_channel_info包含服务前缀要预见到你的 MCP 服务器可能与其他服务器并存于同一个客户端。用slack_send_message而非send_message用github_create_issue而非create_issue避免与其他服务器的工具重名冲突动作导向action-oriented以动词开头get、list、search、create、update、delete 等让 Agent 一眼看出工具行为具体明确避免宽泛名称越具体越不容易产生歧义。工具设计要点描述必须窄而明确工具描述要无歧义地说明功能不能模棱两可描述必须与真实功能精确一致描述是 LLM 决定何时调用该工具的唯一依据夸大或含糊都会导致错误调用提供工具注解annotationsreadOnlyHint、destructiveHint、idempotentHint、openWorldHint四类注解帮助客户端理解工具行为详见第七章保持操作聚焦与原子化一个工具只做一件事避免大而全的万能工具。仓库中的落地方式Activepieces 的流式 MCP 工具在注册时由服务器自动生成名称const baseName (mcpToolNameInput ?? flow.version.displayName) _ flow.id.substring(0, 4) const toolName mcpToolNameUtils.createToolName(baseName)见 mcp-server-builder.ts工具名规范化工具由 mcp-tool-name-util.ts 从activepieces/core-piece-types导出。同时在 MCP Tool 触发器 中toolName与toolDescription是必填属性——后者即描述必须精确匹配功能这一要求在可视化搭建场景下的直接体现toolName: Property.ShortText({ displayName: Name, description: Used to call this tool from MCP clients like Claude Desktop, Cursor, or Windsurf, required: true, }), toolDescription: Property.LongText({ displayName: Description, description: Used to describe what this tool does and when to use it, required: true, }),四、响应格式Response Formats所有返回数据的工具都应支持多种格式以兼顾程序化处理与人类阅读JSON 格式response_formatjson机器可读的结构化数据包含全部可用字段与元数据字段名与类型保持一致供程序化处理使用。Markdown 格式response_formatmarkdown通常为默认人类可读的格式化文本善用标题、列表与排版提升清晰度将时间戳转换为人类可读格式展示显示名称并在括号中附带 ID省略冗长的元数据。仓库佐证Activepieces 的runFlowAsTool返回值同时携带人类可读文本与结构化 JSON成功时输出✅ Successfully executed flow ...加 JSON 块失败时输出❌ Error executing flow ...加错误详情 JSONmcp-server-builder.ts。McpToolResult类型同样同时包含contenttext 数组与可选的structuredContentmcp.ts这正是Markdown 给人看、JSON 给机器用的双轨设计。五、分页Pagination对于会列出资源的工具始终尊重limit参数实现分页使用offset或基于游标cursor的分页返回分页元数据has_more、next_offset/next_cursor、total_count绝不一次性把所有结果载入内存对大数据集尤其重要默认设置合理上限每页 20–50 条是常见取值。示例分页响应{ total: 150, count: 20, offset: 0, items: [...], has_more: true, next_offset: 20 }设计意图LLM 的上下文窗口有限一次返回数千条记录既浪费 token 又降低回答质量。分页元数据让 Agent 可以按需翻页先看第一页判断是否值得继续而不是被迫一次性拉全量数据——这对应了 SKILL.md 中上下文管理让工具返回聚焦、相关的数据的原则见 SKILL.md。六、传输层选项Transport OptionsStreamable HTTP适用场景远程服务器、Web 服务、多客户端并发场景特性基于 HTTP 的双向通信支持多个客户端同时连接可作为 Web 服务部署支持服务器到客户端的通知server-to-client notifications使用时机同时服务多个客户端、以云服务形态部署、与 Web 应用集成。stdio适用场景本地集成、命令行工具特性通过标准输入/输出流通信设置简单无需网络配置作为客户端子进程运行使用时机构建本地开发环境工具、与桌面应用集成、单用户单会话场景注意stdio 服务器不应向 stdout 打日志会污染协议数据流应使用 stderr 记录日志。传输选型对比标准stdioStreamable HTTP部署方式本地远程客户端单个多个复杂度低中等实时性无有仓库中的工程化佐证Activepieces 自身的托管 MCP 服务器即采用 HTTP 形态对外服务服务器基于modelcontextprotocol/sdk/server/mcp.js的McpServer构建mcp-server-builder.ts并注册了占位资源与空 promptregisterEmptyResourcesAndPromptsmcp-server-builder.ts。这意味着即便你的服务器以流式 HTTP 提供主要工具能力也建议补齐资源Resource与提示词Prompt的注册使协议面保持完整客户端枚举能力时不会落空。七、安全最佳实践Security Best Practices认证与授权Authentication AuthorizationOAuth 2.1使用来自权威 CA 的证书启用安全的 OAuth 2.1处理请求前先校验访问令牌只接受明确指定给本服务器的令牌防止令牌混淆攻击。API KeysAPI Key 存放在环境变量中绝不写进代码在服务器启动时校验 Key认证失败时给出清晰、可操作的错误信息。输入校验Input Validation净化文件路径防止目录遍历攻击校验 URL 与外部标识符检查参数的大小与取值范围在系统调用中防止命令注入对所有输入使用 schema 校验Pydantic / Zod。错误处理安全视角不向客户端暴露内部错误细节安全相关错误在服务端记录日志提供有帮助但不过度泄露的错误信息出错后正确清理资源。DNS Rebinding 防护针对本地 Streamable HTTP 服务器开启 DNS rebinding 防护校验所有入站连接的Origin头绑定127.0.0.1而不是0.0.0.0。DNS rebinding 的威胁模型浏览器中的恶意页面可先解析到合法域名再在 DNS 层面将域名解析回127.0.0.1从而绕过同源策略访问你本机的 MCP 服务。校验 Origin 只绑回环地址可以显著缩小攻击面。仓库佐证权限不是注解而是强制检查Activepieces 的托管服务器在注册每个工具前都会通过PermissionChecker做权限校验并将检查结果作为工具执行的守卫mcp-server-builder.tsconst flowPermissionError permissionChecker.check(Permission.WRITE_RUN, toolName) server.registerTool(toolName, {...}, async (args) { if (flowPermissionError) { return flowPermissionError } const result await runFlowAsTool({...}) return result })这印证了下一章的核心结论注解只是提示真正的安全必须依赖服务端的强制校验。八、工具注解Tool Annotations为帮助客户端尤其是 LLM 客户端理解工具行为应为每个工具提供四类注解注解类型默认值描述readOnlyHintbooleanfalse工具不会修改其运行环境destructiveHintbooleantrue工具可能执行破坏性更新idempotentHintbooleanfalse相同参数重复调用不产生额外效果openWorldHintbooleantrue工具与外部实体交互重要注解是提示hints不是安全保证。客户端不应仅凭注解做安全攸关的决策——是否允许执行某个破坏性操作必须由服务端授权体系裁决。仓库中的注解实践McpToolDefinition类型把注解建模为可选字段mcp.tsannotations?: { readOnlyHint?: boolean destructiveHint?: boolean idempotentHint?: boolean openWorldHint?: boolean }而在 mcp-server-builder.ts 中不同类别的工具使用了差异化的注解组合可作为参考样板// 流式工具会触发现有流执行、与外部世界交互、非只读 const FLOW_TOOL_ANNOTATIONS { readOnlyHint: false, destructiveHint: false, openWorldHint: true } // 锁定占位工具纯只读、不触达外部 const LOCKED_PLACEHOLDER_ANNOTATIONS { readOnlyHint: true, destructiveHint: false, openWorldHint: false } // 可控制占位工具可能破坏性、触达外部 const CONTROLLABLE_PLACEHOLDER_ANNOTATIONS { readOnlyHint: false, destructiveHint: true, openWorldHint: true }九、错误处理Error Handling使用标准 JSON-RPC 错误码工具错误应放在结果对象内报告通过isError标记而不是协议级错误——协议级错误会中断会话结果级错误则允许客户端读取错误内容并继续推理提供有帮助、具体、带下一步建议的错误信息不暴露内部实现细节出错时正确清理资源。示例结果内错误报告try { 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. }] }; }注意错误文案的写法Try using filteractive_only直接给出了可执行的下一步这正是可操作错误信息的范式——告诉 Agent 怎么修而不是只告诉它坏了。仓库中的一致实现Activepieces 的runFlowAsTool在流程执行失败时返回isError: true并附带可读的错误 JSONmcp-server-builder.tsconst isOkay Math.floor(response.status / 100) 2 const text isOkay ? ✅ Successfully executed flow ${flowDisplayName}\n\nOutput:\n\\\json\n${JSON.stringify(response, null, 2)}\n\\\ : ❌ Error executing flow ${flowDisplayName}\n\nError details:\n\\\json\n${JSON.stringify(response, null, 2) || Unknown error occurred}\n\\\ return { content: [{ type: text, text }], ...(isOkay ? {} : { isError: true }) }McpToolResult类型同样显式声明了可选的isError字段mcp.ts从类型层面保证错误即结果这一约定贯穿全链路。十、测试要求Testing Requirements全面的测试应覆盖以下五个维度功能测试以合法/非法输入验证工具是否正确执行集成测试测试与外部系统的真实交互安全测试验证认证、输入净化、速率限制性能测试检查负载下的行为、超时表现错误处理测试确保错误报告正确、资源清理到位。补充工程实践对应 SKILL.md 的 Review Test 阶段TypeScript运行npm run build验证编译用 MCP Inspector 交互式调试npx modelcontextprotocol/inspectorPython运行python -m py_compile your_server.py校验语法同样用 MCP Inspector 验证工具行为。此外SKILL.md 的 Phase 4 还要求在实现完成后创建评测集evaluations针对你的 MCP 服务器设计 10 个独立、只读、复杂、真实、可验证、稳定的问题用 XML 格式组织成qa_pair检验 LLM 是否真的能借助你的服务器完成现实任务——这是功能测试之上更高一层的Agent 可用性测试。十一、文档要求Documentation Requirements为所有工具与能力提供清晰的文档每个主要功能至少给出3 个可运行示例记录安全考量说明所需的权限与访问级别记录速率限制与性能特征。为什么文档是 MCP 服务器质量的一部分MCP 服务器没有传统意义上的UI它的用户界面就是工具描述与文档。Agent 依据描述决定调用哪个工具、填什么参数人类开发者依据文档决定如何部署、如何授权、预期什么性能。toolDescription之于工具正如 README 之于仓库——MCP Tool 触发器 将描述设为必填项正是这一原则在 Activepieces 产品化场景中的强制落地。结语MCP 服务器的质量不取决于代码多炫而取决于LLM 能否用它顺畅地完成真实任务SKILL.md 开宗明义。本文覆盖的命名、双格式响应、分页、传输选型、安全、注解、错误处理、测试与文档九大规范正是从工具可发现性、可组合性、健壮性与安全性四个维度支撑这一目标的完整 checklist。开发者可以对照 mcp_best_practices.md 原文逐项自查也可参考本仓库的 TypeScript 实现指南 与 Python 实现指南 获取具体语言的项目结构与代码样板再结合 评测指南 验证最终效果。【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Activepieces MCP Server 最佳实践指南：命名、工具设计、分页、传输与安全规范
Activepieces MCP Server 最佳实践指南命名、工具设计、分页、传输与安全规范【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces导读本文是 Activepieces 仓库中 MCP 服务器最佳实践文档 的深度展开版。它面向需要为 LLM如 Claude、Cursor、Windsurf构建高质量 MCPModel Context Protocol服务器的开发者系统讲解服务器与工具的命名约定、JSON/Markdown 双格式响应、分页元数据、stdio 与 Streamable HTTP 传输选型、安全加固、工具注解、错误处理、测试与文档要求。读完本文你将掌握一套可直接落地、可被 Agent 顺畅发现与调用的 MCP 服务器设计与实现规范并理解 Activepieces 内部托管 MCP 服务器mcp-server-builder.ts是如何将这些最佳实践固化为代码的。一、速查卡Quick Reference原文档首先给出了一页纸式的速查条目它们是后续所有章节的浓缩开发时应当时刻对照维度规范Python 服务器命名{service}_mcp例如slack_mcpNode/TypeScript 服务器命名{service}-mcp-server例如slack-mcp-server工具命名snake_case 且带服务前缀格式{service}_{action}_{resource}工具命名示例slack_send_message、github_create_issue响应格式同时支持 JSON 与 MarkdownJSON 面向程序化处理Markdown 面向人类可读分页始终尊重limit参数返回has_more、next_offset、total_count默认每页 20–50 条传输层远程/多客户端场景用 Streamable HTTP本地/命令行工具用 stdio避免 SSE已被 Streamable HTTP 取代这些约定并非空谈。在 Activepieces 中McpToolDefinition类型packages/core/shared/src/lib/automation/mcp/mcp.ts就为每个工具定义了title、description、inputSchema与annotations而服务器侧在注册工具时正是把工具名作为 LLM 可见的唯一标识符mcp-server-builder.ts因此命名是否清晰、是否有前缀直接影响 Agent 能否在众多工具中快速命中正确的那一个。二、服务器命名规范Server Naming ConventionsPython{service}_mcp全小写、下划线分隔示例slack_mcp、github_mcp、jira_mcp。Node/TypeScript{service}-mcp-server全小写、连字符分隔示例slack-mcp-server、github-mcp-server、jira-mcp-server。命名要点名称应当通用且能准确描述被集成的服务应当能从任务描述中轻易推断出该服务器是干什么的不要带版本号版本信息应交给包管理或 manifest而不是包名保持一致的前缀体系便于在工具列表中按服务归类。仓库中的托管服务器也遵循同样的精神buildMcpServer创建的服务器实例名为Activepieces版本号1.0.0独立于名称之外mcp-server-builder.ts名称只承担描述服务的职责。三、工具命名与设计Tool Naming and Design工具命名四原则使用 snake_casesearch_users、create_project、get_channel_info包含服务前缀要预见到你的 MCP 服务器可能与其他服务器并存于同一个客户端。用slack_send_message而非send_message用github_create_issue而非create_issue避免与其他服务器的工具重名冲突动作导向action-oriented以动词开头get、list、search、create、update、delete 等让 Agent 一眼看出工具行为具体明确避免宽泛名称越具体越不容易产生歧义。工具设计要点描述必须窄而明确工具描述要无歧义地说明功能不能模棱两可描述必须与真实功能精确一致描述是 LLM 决定何时调用该工具的唯一依据夸大或含糊都会导致错误调用提供工具注解annotationsreadOnlyHint、destructiveHint、idempotentHint、openWorldHint四类注解帮助客户端理解工具行为详见第七章保持操作聚焦与原子化一个工具只做一件事避免大而全的万能工具。仓库中的落地方式Activepieces 的流式 MCP 工具在注册时由服务器自动生成名称const baseName (mcpToolNameInput ?? flow.version.displayName) _ flow.id.substring(0, 4) const toolName mcpToolNameUtils.createToolName(baseName)见 mcp-server-builder.ts工具名规范化工具由 mcp-tool-name-util.ts 从activepieces/core-piece-types导出。同时在 MCP Tool 触发器 中toolName与toolDescription是必填属性——后者即描述必须精确匹配功能这一要求在可视化搭建场景下的直接体现toolName: Property.ShortText({ displayName: Name, description: Used to call this tool from MCP clients like Claude Desktop, Cursor, or Windsurf, required: true, }), toolDescription: Property.LongText({ displayName: Description, description: Used to describe what this tool does and when to use it, required: true, }),四、响应格式Response Formats所有返回数据的工具都应支持多种格式以兼顾程序化处理与人类阅读JSON 格式response_formatjson机器可读的结构化数据包含全部可用字段与元数据字段名与类型保持一致供程序化处理使用。Markdown 格式response_formatmarkdown通常为默认人类可读的格式化文本善用标题、列表与排版提升清晰度将时间戳转换为人类可读格式展示显示名称并在括号中附带 ID省略冗长的元数据。仓库佐证Activepieces 的runFlowAsTool返回值同时携带人类可读文本与结构化 JSON成功时输出✅ Successfully executed flow ...加 JSON 块失败时输出❌ Error executing flow ...加错误详情 JSONmcp-server-builder.ts。McpToolResult类型同样同时包含contenttext 数组与可选的structuredContentmcp.ts这正是Markdown 给人看、JSON 给机器用的双轨设计。五、分页Pagination对于会列出资源的工具始终尊重limit参数实现分页使用offset或基于游标cursor的分页返回分页元数据has_more、next_offset/next_cursor、total_count绝不一次性把所有结果载入内存对大数据集尤其重要默认设置合理上限每页 20–50 条是常见取值。示例分页响应{ total: 150, count: 20, offset: 0, items: [...], has_more: true, next_offset: 20 }设计意图LLM 的上下文窗口有限一次返回数千条记录既浪费 token 又降低回答质量。分页元数据让 Agent 可以按需翻页先看第一页判断是否值得继续而不是被迫一次性拉全量数据——这对应了 SKILL.md 中上下文管理让工具返回聚焦、相关的数据的原则见 SKILL.md。六、传输层选项Transport OptionsStreamable HTTP适用场景远程服务器、Web 服务、多客户端并发场景特性基于 HTTP 的双向通信支持多个客户端同时连接可作为 Web 服务部署支持服务器到客户端的通知server-to-client notifications使用时机同时服务多个客户端、以云服务形态部署、与 Web 应用集成。stdio适用场景本地集成、命令行工具特性通过标准输入/输出流通信设置简单无需网络配置作为客户端子进程运行使用时机构建本地开发环境工具、与桌面应用集成、单用户单会话场景注意stdio 服务器不应向 stdout 打日志会污染协议数据流应使用 stderr 记录日志。传输选型对比标准stdioStreamable HTTP部署方式本地远程客户端单个多个复杂度低中等实时性无有仓库中的工程化佐证Activepieces 自身的托管 MCP 服务器即采用 HTTP 形态对外服务服务器基于modelcontextprotocol/sdk/server/mcp.js的McpServer构建mcp-server-builder.ts并注册了占位资源与空 promptregisterEmptyResourcesAndPromptsmcp-server-builder.ts。这意味着即便你的服务器以流式 HTTP 提供主要工具能力也建议补齐资源Resource与提示词Prompt的注册使协议面保持完整客户端枚举能力时不会落空。七、安全最佳实践Security Best Practices认证与授权Authentication AuthorizationOAuth 2.1使用来自权威 CA 的证书启用安全的 OAuth 2.1处理请求前先校验访问令牌只接受明确指定给本服务器的令牌防止令牌混淆攻击。API KeysAPI Key 存放在环境变量中绝不写进代码在服务器启动时校验 Key认证失败时给出清晰、可操作的错误信息。输入校验Input Validation净化文件路径防止目录遍历攻击校验 URL 与外部标识符检查参数的大小与取值范围在系统调用中防止命令注入对所有输入使用 schema 校验Pydantic / Zod。错误处理安全视角不向客户端暴露内部错误细节安全相关错误在服务端记录日志提供有帮助但不过度泄露的错误信息出错后正确清理资源。DNS Rebinding 防护针对本地 Streamable HTTP 服务器开启 DNS rebinding 防护校验所有入站连接的Origin头绑定127.0.0.1而不是0.0.0.0。DNS rebinding 的威胁模型浏览器中的恶意页面可先解析到合法域名再在 DNS 层面将域名解析回127.0.0.1从而绕过同源策略访问你本机的 MCP 服务。校验 Origin 只绑回环地址可以显著缩小攻击面。仓库佐证权限不是注解而是强制检查Activepieces 的托管服务器在注册每个工具前都会通过PermissionChecker做权限校验并将检查结果作为工具执行的守卫mcp-server-builder.tsconst flowPermissionError permissionChecker.check(Permission.WRITE_RUN, toolName) server.registerTool(toolName, {...}, async (args) { if (flowPermissionError) { return flowPermissionError } const result await runFlowAsTool({...}) return result })这印证了下一章的核心结论注解只是提示真正的安全必须依赖服务端的强制校验。八、工具注解Tool Annotations为帮助客户端尤其是 LLM 客户端理解工具行为应为每个工具提供四类注解注解类型默认值描述readOnlyHintbooleanfalse工具不会修改其运行环境destructiveHintbooleantrue工具可能执行破坏性更新idempotentHintbooleanfalse相同参数重复调用不产生额外效果openWorldHintbooleantrue工具与外部实体交互重要注解是提示hints不是安全保证。客户端不应仅凭注解做安全攸关的决策——是否允许执行某个破坏性操作必须由服务端授权体系裁决。仓库中的注解实践McpToolDefinition类型把注解建模为可选字段mcp.tsannotations?: { readOnlyHint?: boolean destructiveHint?: boolean idempotentHint?: boolean openWorldHint?: boolean }而在 mcp-server-builder.ts 中不同类别的工具使用了差异化的注解组合可作为参考样板// 流式工具会触发现有流执行、与外部世界交互、非只读 const FLOW_TOOL_ANNOTATIONS { readOnlyHint: false, destructiveHint: false, openWorldHint: true } // 锁定占位工具纯只读、不触达外部 const LOCKED_PLACEHOLDER_ANNOTATIONS { readOnlyHint: true, destructiveHint: false, openWorldHint: false } // 可控制占位工具可能破坏性、触达外部 const CONTROLLABLE_PLACEHOLDER_ANNOTATIONS { readOnlyHint: false, destructiveHint: true, openWorldHint: true }九、错误处理Error Handling使用标准 JSON-RPC 错误码工具错误应放在结果对象内报告通过isError标记而不是协议级错误——协议级错误会中断会话结果级错误则允许客户端读取错误内容并继续推理提供有帮助、具体、带下一步建议的错误信息不暴露内部实现细节出错时正确清理资源。示例结果内错误报告try { 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. }] }; }注意错误文案的写法Try using filteractive_only直接给出了可执行的下一步这正是可操作错误信息的范式——告诉 Agent 怎么修而不是只告诉它坏了。仓库中的一致实现Activepieces 的runFlowAsTool在流程执行失败时返回isError: true并附带可读的错误 JSONmcp-server-builder.tsconst isOkay Math.floor(response.status / 100) 2 const text isOkay ? ✅ Successfully executed flow ${flowDisplayName}\n\nOutput:\n\\\json\n${JSON.stringify(response, null, 2)}\n\\\ : ❌ Error executing flow ${flowDisplayName}\n\nError details:\n\\\json\n${JSON.stringify(response, null, 2) || Unknown error occurred}\n\\\ return { content: [{ type: text, text }], ...(isOkay ? {} : { isError: true }) }McpToolResult类型同样显式声明了可选的isError字段mcp.ts从类型层面保证错误即结果这一约定贯穿全链路。十、测试要求Testing Requirements全面的测试应覆盖以下五个维度功能测试以合法/非法输入验证工具是否正确执行集成测试测试与外部系统的真实交互安全测试验证认证、输入净化、速率限制性能测试检查负载下的行为、超时表现错误处理测试确保错误报告正确、资源清理到位。补充工程实践对应 SKILL.md 的 Review Test 阶段TypeScript运行npm run build验证编译用 MCP Inspector 交互式调试npx modelcontextprotocol/inspectorPython运行python -m py_compile your_server.py校验语法同样用 MCP Inspector 验证工具行为。此外SKILL.md 的 Phase 4 还要求在实现完成后创建评测集evaluations针对你的 MCP 服务器设计 10 个独立、只读、复杂、真实、可验证、稳定的问题用 XML 格式组织成qa_pair检验 LLM 是否真的能借助你的服务器完成现实任务——这是功能测试之上更高一层的Agent 可用性测试。十一、文档要求Documentation Requirements为所有工具与能力提供清晰的文档每个主要功能至少给出3 个可运行示例记录安全考量说明所需的权限与访问级别记录速率限制与性能特征。为什么文档是 MCP 服务器质量的一部分MCP 服务器没有传统意义上的UI它的用户界面就是工具描述与文档。Agent 依据描述决定调用哪个工具、填什么参数人类开发者依据文档决定如何部署、如何授权、预期什么性能。toolDescription之于工具正如 README 之于仓库——MCP Tool 触发器 将描述设为必填项正是这一原则在 Activepieces 产品化场景中的强制落地。结语MCP 服务器的质量不取决于代码多炫而取决于LLM 能否用它顺畅地完成真实任务SKILL.md 开宗明义。本文覆盖的命名、双格式响应、分页、传输选型、安全、注解、错误处理、测试与文档九大规范正是从工具可发现性、可组合性、健壮性与安全性四个维度支撑这一目标的完整 checklist。开发者可以对照 mcp_best_practices.md 原文逐项自查也可参考本仓库的 TypeScript 实现指南 与 Python 实现指南 获取具体语言的项目结构与代码样板再结合 评测指南 验证最终效果。【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考