尧图网站建设 
后端前端企业应用MCP 服务【免费下载链接】ever-gauzyEver® Gauzy™ - Open Business Management Platform (ERP/CRM/HRM/ATS/PM) - https://gauzy.co项目地址https://gitcode.com/GitHub_Trending/ev/ever-gauzy点击查看免费下载本文以 Ever Gauzy 仓库中 packages/mcp-server/src/lib/config/TOOLS_CONFIG.md 为核心骨架完整解析 Gauzy MCP Server 的集中式工具注册表Tools Registry设计从TOOLS_REGISTRY数据结构、六大辅助函数的使用方式到新增工具/新类别的扩展流程再深入到register-all-tools.ts、tool-helper.ts、mcp-server.ts等源码揭示“注册表 → 注册模块 → 运行时调用”的完整链路。读完本文你将掌握如何查询、维护、扩展并理解 Gauzy MCP Server 的全部 MCP 工具体系。一、什么是 MCP Tools Registry为什么需要集中式注册表Gauzy MCP Server 是 Ever Gauzy 开源商业管理平台ERP/CRM/HRM/ATS/PM对外暴露的 MCPModel Context Protocol服务端它把 Gauzy 后端 API 的能力员工管理、任务、项目、每日计划、组织联系人、计时器、发票、报销、目标、候选人、支付、仓库、管道、技能等封装成一个个可供 LLM 客户端如 Claude Desktop调用的工具Tool。当一个 MCP Server 拥有数百个工具时如果每个工具的定义散落在各个业务模块中会出现几个典型问题重复与不一致多处硬编码工具清单新增工具时漏改某一处难以统计无法快速获知“这个服务器一共暴露了多少工具、每个类别各有多少个”维护成本高要找出某工具属于哪个类别、是否已注册需要全局搜索。TOOLS_CONFIG.md所在目录packages/mcp-server/src/lib/config正是为了解决这些问题而设计的集中式配置中心其核心文件是 tools-registry.ts。该文件在文件头注释中明确自述“Central registry of all available MCP tools. This file serves as the single source of truth for tool definitions and can be imported wherever tool information is needed.”即这是所有 MCP 工具定义的“单一事实来源”Single Source of Truth。二、注册表的数据结构ToolRegistry 接口与 TOOLS_REGISTRY 常量2.1 类型定义TOOLS_REGISTRY的数据结构非常简单清晰export interface ToolRegistry { [category: string]: string[]; }它是一个以类别名category为键、以工具名tool name字符串数组为值的普通对象。类别名采用 camelCase如dailyPlans、organizationContacts工具名采用 snake_case如get_employees、start_timer。2.2 完整的 TOOLS_REGISTRY 内容在 tools-registry.ts 中当前仓库实际注册的全部类别与工具如下这是本文档的“原汁原味”清单务必完整继承类别category包含的工具authenticationlogin、logout、get_auth_status、refresh_auth_token、auto_loginemployeesget_employees、get_employee_count、get_employees_pagination、get_working_employees、get_working_employees_count、get_organization_members、get_employee、get_employee_statistics、get_current_employee、create_employee、update_employee、update_employee_profile、soft_delete_employee、restore_employee、bulk_create_employeestasksget_tasks、get_task_count、get_tasks_pagination、get_tasks_by_employee、get_my_tasks、get_team_tasks、create_task、get_task、update_task、delete_task、bulk_create_tasks、bulk_update_tasks、bulk_delete_tasks、get_task_statistics、assign_task_to_employee、unassign_task_from_employeeprojectsget_projects、get_project_count、get_projects_pagination、get_projects_by_employee、get_my_projects、get_project、create_project、update_project、delete_project、bulk_create_projects、bulk_update_projects、bulk_delete_projects、get_project_statistics、assign_project_to_employee、unassign_project_from_employeedailyPlansget_daily_plans、get_my_daily_plans、get_team_daily_plans、get_employee_daily_plans、get_daily_plans_for_task、get_daily_plan、create_daily_plan、update_daily_plan、delete_daily_plan、add_task_to_daily_plan、remove_task_from_daily_plan、remove_task_from_many_daily_plans、get_daily_plan_count、get_daily_plan_statistics、bulk_create_daily_plans、bulk_update_daily_plans、bulk_delete_daily_plansorganizationContactsget_organization_contacts、get_organization_contact_count、get_organization_contacts_pagination、get_organization_contacts_by_employee、get_organization_contact、create_organization_contact、update_organization_contact、update_organization_contact_by_employee、delete_organization_contact、bulk_create_organization_contacts、bulk_update_organization_contacts、bulk_delete_organization_contacts、get_organization_contact_statistics、assign_contact_to_employee、unassign_contact_from_employee、get_contact_projects、invite_organization_contacttimertimer_status、start_timer、stop_timertesttest_api_connection、get_server_info、test_mcp_capabilities统计一下authentication5 个、employees15 个、tasks16 个、projects15 个、dailyPlans17 个、organizationContacts17 个、timer3 个、test3 个合计91 个工具。这个数字与 mcp-server.ts 中通过listTools()枚举_registeredTools后打印的日志Found ${toolsList.length} tools是呼应的。注意注册表中列出的 8 个类别只是“组织维度”的抽象。真正被注册到 MCP Server 上的工具远不止这些——在register-all-tools.ts中还有products、product-categories、invoices、expenses、goals、key-results、deals、candidates、payments、merchants、incomes、equipment、comments、reports、time-off、employee-awards、activity-logs、warehouses、pipelines、skills等 20 个注册模块见下文第四节。换言之TOOLS_REGISTRY是“精选常用工具”的集中索引而注册模块才是完整工具集的实现载体。从源码结构看注册表并不强制要求与注册模块一一对应这为维护者按业务侧重点自由组织类别留出了空间。三、辅助函数如何查询与统计工具tools-registry.ts在导出TOOLS_REGISTRY常量的同时还导出了 6 个实用辅助函数全部是纯函数不依赖任何运行时状态可在任意模块中直接 import 使用。3.1 导入方式import { TOOLS_REGISTRY, getToolCounts, getTotalToolCount, getToolsByCategory, isToolRegistered, getToolCategory } from ../config/tools-registry.js;注意TOOLS_CONFIG.md中展示的导入路径../config/tools-registry.js是相对于src/lib/tools/等使用方目录的写法而从仓库根目录看该模块的实际位置是 packages/mcp-server/src/lib/config/tools-registry.ts。同时 config/index.ts 通过export * from ./tools-registry把整个注册表模块对外统一导出因此也可以从../config/index.js或包入口index.ts引入。3.2 六个辅助函数逐一详解1getToolsByCategory(category)获取某类别的全部工具const authTools getToolsByCategory(authentication); // 返回: [login, logout, get_auth_status, refresh_auth_token, auto_login]底层实现tools-registry.ts直接索引TOOLS_REGISTRY[category]若类别不存在则返回空数组[]不会抛异常——这是容错设计方便调用方安全地处理未知类别。2getToolCategories()列出所有已注册类别const categories getToolCategories(); // 返回: [authentication, employees, tasks, projects, dailyPlans, organizationContacts, timer, test]底层实现使用Object.keys(TOOLS_REGISTRY)返回的数组顺序与对象字面量定义顺序一致tools-registry.ts。3getToolCounts()按类别统计工具数量const counts getToolCounts(); // 返回: { authentication: 5, employees: 15, tasks: 16, projects: 15, dailyPlans: 17, organizationContacts: 17, timer: 3, test: 3 }底层实现用reduce遍历所有类别把每个类别数组的.length映射到同名键tools-registry.ts。4getTotalToolCount()全部工具总数const total getTotalToolCount(); // 返回: 91底层实现Object.values(TOOLS_REGISTRY).reduce((sum, tools) sum tools.length, 0)tools-registry.ts。5isToolRegistered(toolName)判断工具是否已注册const exists isToolRegistered(get_employees); // 返回: true const notExists isToolRegistered(nonexistent_tool); // 返回: false底层实现Object.values(TOOLS_REGISTRY).some(tools tools.includes(toolName))只要任一类别包含该名称即返回truetools-registry.ts。6getToolCategory(toolName)反查工具所属类别const category getToolCategory(start_timer); // 返回: timer const unknown getToolCategory(no_such_tool); // 返回: null底层实现遍历Object.entries(TOOLS_REGISTRY)找到包含该工具的类别立即返回全部找不到则返回nulltools-registry.ts。返回值用null而非undefined或空字符串语义更明确。额外导出getAllTools()在 tools-registry.ts 中还有一个文档里未单独列举但非常实用的函数getAllTools()它用Object.values(TOOLS_REGISTRY).flat()把所有类别的工具合并成一个扁平字符串数组适合做全局去重校验或生成工具清单。3.3 典型使用场景统计报表启动时打印各业务域的工具规模判断模块是否完整权限/能力探测在 UI 或 Agent 端根据getToolCategory判断某个工具归属的业务域一致性校验用isToolRegistered在测试中断言某个工具已上线动态菜单按类别枚举工具生成客户端可展示的工具树。四、从注册表到运行时工具注册的完整链路注册表只是“目录”真正让工具可被 LLM 调用的是运行时注册链路。这条链路在源码中有清晰的三层结构。4.1 第一层按业务域拆分的注册模块packages/mcp-server/src/lib/tools 目录下共有 31 个文件含register-all-tools.ts、index.ts、tool-helper.ts、utils.ts、input-schema-json.spec.ts及 28 个业务工具模块如 employees.ts、tasks.ts、projects.ts、auth.ts、timer.ts、daily-plan.ts、organization-contact.ts等。每个模块导出形如registerXxxTools(server: McpServer, sessionId?)的函数内部调用server.tool(...)或封装后的registerTool(...)完成注册。以 employees.ts 为例registerEmployeeTools通过registerTool注册get_employeesexport const registerEmployeeTools (server: McpServer) { registerTool( server, get_employees, Get list of employees for the authenticated users organization with pagination, { page: z.number().optional().default(1).describe(Page number for pagination), // ... 更多 Zod 参数 }, async (args) { /* 实现调用 Gauzy API */ } ); };这里的入参 schema 使用 Zod 定义z.number().optional().default(1)表示page可选、默认 1工具描述description会被 MCP 协议带给 LLM作为其决定是否调用该工具的依据。4.2 第二层统一装配入口 registerAllMcpToolsregister-all-tools.ts 是“总装配车间”registerAllMcpTools(server, sessionId)按固定顺序调用 28 个业务模块的注册函数register-all-tools.tsexport function registerAllMcpTools(server: McpServer, sessionId?: string): void { registerAuthTools(server, sessionId); registerTimerTools(server); registerProjectTools(server); registerTaskTools(server); registerEmployeeTools(server); registerDailyPlanTools(server); registerOrganizationContactTools(server); registerTestTools(server); registerProductTools(server); registerProductCategoryTools(server); registerInvoiceTools(server); registerExpenseTools(server); registerGoalTools(server); registerKeyResultTools(server); registerDealTools(server); registerCandidateTools(server); registerPaymentTools(server); registerMerchantTools(server); registerIncomeTools(server); registerEquipmentTools(server); registerCommentTools(server); registerReportTools(server); registerTimeOffTools(server); registerEmployeeAwardTools(server); registerActivityLogTools(server); registerWarehouseTools(server); registerPipelineTools(server); registerSkillTools(server); }这段代码既是生产环境启动时的注册入口也被“schema 回归测试”复用文件头注释“Shared by production server bootstrap and schema regression tests.”。从源码结构看会话相关的工具如registerAuthTools接收sessionId其余模块不需要——这印证了注册表维护时无需感知会话细节的设计。4.3 第三层服务器引导与运行时调用mcp-server.ts 中的createMcpServer(sessionId?)创建ExtendedMcpServer实例后立即调用registerAllMcpTools(server, sessionId)并在日志中输出 “All tools registered successfully”mcp-server.ts。ExtendedMcpServer继承官方McpServer并新增两个公开方法listTools()mcp-server.ts从内部_registeredTools枚举所有已注册工具将 Zod schema 转换成 JSON schema优先zodSchema.toJSON()否则动态import(zod-to-json-schema)再兜底为空对象返回统一的ToolDescriptor[]{ name, description, inputSchema }invokeTool(name, args)mcp-server.ts按名称查找工具并执行其callback且在日志中通过mask()把pass|secret|token|key|auth|credential等敏感参数打码为***避免凭证泄露到日志。createMcpServerAsync还会先初始化sessionManager再创建服务createAndStartMcpServer进一步通过TransportFactory创建并连接传输层stdio / HTTP / WebSocket最终可供 Claude Desktop 等外部客户端连接。而 server-info.ts 中的SERVER_INFO声明了服务器的能力位tools: true、resources: false、prompts: false并列出schemaValidation / bulkOperations / relationSupport / paginationSupport / statisticsSupport / assignmentOperations / authentication / tokenRefresh等特性protocol.ts 则固定了协议版本PROTOCOL_VERSION 2025-06-18。4.4 关键设计tool-helper 为何存在在工具数量达到数百个tool-helper.ts注释中明确提到 “324 tools in this codebase”时官方server.tool()方法基于 Zod 的复杂泛型推导会让 TypeScript 在编译期内存耗尽。为此 tool-helper.ts 提供了registerTool/registerNoArgsTool两个轻量封装registerTool(server, name, description, schema, callback)把schema包进z.object()后以(server.registerTool as any)方式调用运行时仍保留 Zod 校验registerNoArgsTool(server, name, description, callback)注册无参数工具回调统一返回{ content: [{ type: text, text }] }结构的ToolResult。这正是注册表设计哲学在工程实现上的延伸注册表是“目录”tool-helper 是“高效装配工具”二者共同降低大规模 MCP 工具集的可维护成本。五、维护指南新增工具与新增类别5.1 新增一个工具三步走以文档示例“新增archive_employee归档员工”为例步骤 1在业务工具模块中实现并注册在 packages/mcp-server/src/lib/tools/employees.ts文档中写作src/tools/employees.ts相对路径已按仓库根目录归一化中用registerTool注册新工具// 在 src/lib/tools/employees.ts registerTool( server, archive_employee, Archive an employee, { employeeId: z.string().uuid().describe(Employee ID to archive), // 其他参数按需定义 }, async (args) { // 调用 Gauzy API 实现归档逻辑 return { content: [{ type: text, text: Employee archived successfully }] }; } );注意只有在此处注册工具才会真正出现在 MCP Server 的_registeredTools中并被listTools()枚举、被invokeTool()调用。步骤 2把工具名加入注册表对应类别在 tools-registry.ts 的employees数组中追加export const TOOLS_REGISTRY: ToolRegistry { employees: [ get_employees, create_employee, // ... existing tools archive_employee // 新增工具 ] // ... other categories };步骤 3可选但推荐补全统计与校验加入注册表后getToolsByCategory(employees)、getToolCounts()、getTotalToolCount()、isToolRegistered(archive_employee)、getToolCategory(archive_employee)的结果会自动同步更新无需额外代码——这正是集中式注册表“一处维护、处处生效”的收益。5.2 新增一个类别当出现全新业务域例如报表时直接在TOOLS_REGISTRY中增加一个新键export const TOOLS_REGISTRY: ToolRegistry { // ... existing categories reporting: [generate_report, get_report_templates, export_report] };新增类别后getToolCategories()会自动包含reporting。建议类别命名遵循现有 camelCase 惯例工具命名遵循 snake_case 惯例保持风格统一。5.3 从硬编码清单迁移到注册表如果代码中已有硬编码的工具清单迁移前硬编码const tools { authentication: [login, logout, ...], employees: [get_employees, ...] };迁移后使用注册表import { TOOLS_REGISTRY } from ../config/tools-registry.js; const tools TOOLS_REGISTRY;一旦切换到注册表后续所有类别与工具的增删只需改 tools-registry.ts 一处全项目共享同一份权威数据。六、设计收益与最佳实践总结对照 TOOLS_CONFIG.md 的 “Benefits” 一节结合源码验证集中式注册表带来五点明确收益单一事实来源Single Source of Truth所有工具定义集中在tools-registry.ts杜绝多份清单漂移类型安全Type SafetyToolRegistry接口约束了类别→工具名的结构配合 TypeScript 静态检查保证一致性易维护Easy Maintenance新增工具只需改一处统计、校验函数自动生效内置工具函数Utility Functions6 个纯函数覆盖按类别取、按名反查、计数、总数、存在性判断等常见操作可复用Reusabilityconfig/index.ts统一导出任何模块运行时、测试、UI都能按需引入。实践中的最佳姿势可归纳为注册业务模块实现 registerAllMcpTools 装配负责“工具真实可用”注册表tools-registry.ts负责“工具可被检索与统计”两者互为表里。新增功能时先实现注册、再登记入表迁移旧代码时优先切换到注册表以保持整个 MCP Server 工具面的整洁与一致。如需进一步深入可继续阅读工具注册总入口 register-all-tools.ts、员工工具实现示例 employees.ts、服务器引导与调用逻辑 mcp-server.ts、服务器能力声明 server-info.ts 及 包级说明文档 README。赞分享后端前端企业应用MCP 服务【免费下载链接】ever-gauzyEver® Gauzy™ - Open Business Management Platform (ERP/CRM/HRM/ATS/PM) - https://gauzy.co项目地址https://gitcode.com/GitHub_Trending/ev/ever-gauzy点击查看免费下载相关推荐DeepChat Node/TypeScript MCP Server 实现指南从项目脚手架到生产级工具注册DeepChat Node/TypeScript MCP Server 实现指南从项目脚手架到生产级工具注册 本文是一份面向 DeepChat 生态的 NodAI Agent人工智能AI 应用桌面应用MCP ClientsActivepieces 的 Node/TypeScript MCP Server 实现指南从项目搭建到生产级工具注册Activepieces 的 Node/TypeScript MCP Server 实现指南从项目搭建到生产级工具注册 导读 本文是 Activepieces工作流自动化低代码AI 应用人工智能AI AgentMCP 服务后端前端PraisonAI TypeScript Agent 工具注册完全指南四种函数注册方式与 MCP SSE 远程工具集成PraisonAI TypeScript Agent 工具注册完全指南四种函数注册方式与 MCP SSE 远程工具集成 导读 本文以 PraisonAI Ty人工智能AI AgentAgent 框架多智能体工作流自动化RAGMCP 服务上一篇btop资源监控工具5个步骤打造你的专业级系统监控仪表盘下一篇FreeCAD高级渲染策略专业级性能优化实践指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ever Gauzy MCP Server 工具注册表配置完全指南：从集中式注册到源码级实现
后端前端企业应用MCP 服务【免费下载链接】ever-gauzyEver® Gauzy™ - Open Business Management Platform (ERP/CRM/HRM/ATS/PM) - https://gauzy.co项目地址https://gitcode.com/GitHub_Trending/ev/ever-gauzy点击查看免费下载本文以 Ever Gauzy 仓库中 packages/mcp-server/src/lib/config/TOOLS_CONFIG.md 为核心骨架完整解析 Gauzy MCP Server 的集中式工具注册表Tools Registry设计从TOOLS_REGISTRY数据结构、六大辅助函数的使用方式到新增工具/新类别的扩展流程再深入到register-all-tools.ts、tool-helper.ts、mcp-server.ts等源码揭示“注册表 → 注册模块 → 运行时调用”的完整链路。读完本文你将掌握如何查询、维护、扩展并理解 Gauzy MCP Server 的全部 MCP 工具体系。一、什么是 MCP Tools Registry为什么需要集中式注册表Gauzy MCP Server 是 Ever Gauzy 开源商业管理平台ERP/CRM/HRM/ATS/PM对外暴露的 MCPModel Context Protocol服务端它把 Gauzy 后端 API 的能力员工管理、任务、项目、每日计划、组织联系人、计时器、发票、报销、目标、候选人、支付、仓库、管道、技能等封装成一个个可供 LLM 客户端如 Claude Desktop调用的工具Tool。当一个 MCP Server 拥有数百个工具时如果每个工具的定义散落在各个业务模块中会出现几个典型问题重复与不一致多处硬编码工具清单新增工具时漏改某一处难以统计无法快速获知“这个服务器一共暴露了多少工具、每个类别各有多少个”维护成本高要找出某工具属于哪个类别、是否已注册需要全局搜索。TOOLS_CONFIG.md所在目录packages/mcp-server/src/lib/config正是为了解决这些问题而设计的集中式配置中心其核心文件是 tools-registry.ts。该文件在文件头注释中明确自述“Central registry of all available MCP tools. This file serves as the single source of truth for tool definitions and can be imported wherever tool information is needed.”即这是所有 MCP 工具定义的“单一事实来源”Single Source of Truth。二、注册表的数据结构ToolRegistry 接口与 TOOLS_REGISTRY 常量2.1 类型定义TOOLS_REGISTRY的数据结构非常简单清晰export interface ToolRegistry { [category: string]: string[]; }它是一个以类别名category为键、以工具名tool name字符串数组为值的普通对象。类别名采用 camelCase如dailyPlans、organizationContacts工具名采用 snake_case如get_employees、start_timer。2.2 完整的 TOOLS_REGISTRY 内容在 tools-registry.ts 中当前仓库实际注册的全部类别与工具如下这是本文档的“原汁原味”清单务必完整继承类别category包含的工具authenticationlogin、logout、get_auth_status、refresh_auth_token、auto_loginemployeesget_employees、get_employee_count、get_employees_pagination、get_working_employees、get_working_employees_count、get_organization_members、get_employee、get_employee_statistics、get_current_employee、create_employee、update_employee、update_employee_profile、soft_delete_employee、restore_employee、bulk_create_employeestasksget_tasks、get_task_count、get_tasks_pagination、get_tasks_by_employee、get_my_tasks、get_team_tasks、create_task、get_task、update_task、delete_task、bulk_create_tasks、bulk_update_tasks、bulk_delete_tasks、get_task_statistics、assign_task_to_employee、unassign_task_from_employeeprojectsget_projects、get_project_count、get_projects_pagination、get_projects_by_employee、get_my_projects、get_project、create_project、update_project、delete_project、bulk_create_projects、bulk_update_projects、bulk_delete_projects、get_project_statistics、assign_project_to_employee、unassign_project_from_employeedailyPlansget_daily_plans、get_my_daily_plans、get_team_daily_plans、get_employee_daily_plans、get_daily_plans_for_task、get_daily_plan、create_daily_plan、update_daily_plan、delete_daily_plan、add_task_to_daily_plan、remove_task_from_daily_plan、remove_task_from_many_daily_plans、get_daily_plan_count、get_daily_plan_statistics、bulk_create_daily_plans、bulk_update_daily_plans、bulk_delete_daily_plansorganizationContactsget_organization_contacts、get_organization_contact_count、get_organization_contacts_pagination、get_organization_contacts_by_employee、get_organization_contact、create_organization_contact、update_organization_contact、update_organization_contact_by_employee、delete_organization_contact、bulk_create_organization_contacts、bulk_update_organization_contacts、bulk_delete_organization_contacts、get_organization_contact_statistics、assign_contact_to_employee、unassign_contact_from_employee、get_contact_projects、invite_organization_contacttimertimer_status、start_timer、stop_timertesttest_api_connection、get_server_info、test_mcp_capabilities统计一下authentication5 个、employees15 个、tasks16 个、projects15 个、dailyPlans17 个、organizationContacts17 个、timer3 个、test3 个合计91 个工具。这个数字与 mcp-server.ts 中通过listTools()枚举_registeredTools后打印的日志Found ${toolsList.length} tools是呼应的。注意注册表中列出的 8 个类别只是“组织维度”的抽象。真正被注册到 MCP Server 上的工具远不止这些——在register-all-tools.ts中还有products、product-categories、invoices、expenses、goals、key-results、deals、candidates、payments、merchants、incomes、equipment、comments、reports、time-off、employee-awards、activity-logs、warehouses、pipelines、skills等 20 个注册模块见下文第四节。换言之TOOLS_REGISTRY是“精选常用工具”的集中索引而注册模块才是完整工具集的实现载体。从源码结构看注册表并不强制要求与注册模块一一对应这为维护者按业务侧重点自由组织类别留出了空间。三、辅助函数如何查询与统计工具tools-registry.ts在导出TOOLS_REGISTRY常量的同时还导出了 6 个实用辅助函数全部是纯函数不依赖任何运行时状态可在任意模块中直接 import 使用。3.1 导入方式import { TOOLS_REGISTRY, getToolCounts, getTotalToolCount, getToolsByCategory, isToolRegistered, getToolCategory } from ../config/tools-registry.js;注意TOOLS_CONFIG.md中展示的导入路径../config/tools-registry.js是相对于src/lib/tools/等使用方目录的写法而从仓库根目录看该模块的实际位置是 packages/mcp-server/src/lib/config/tools-registry.ts。同时 config/index.ts 通过export * from ./tools-registry把整个注册表模块对外统一导出因此也可以从../config/index.js或包入口index.ts引入。3.2 六个辅助函数逐一详解1getToolsByCategory(category)获取某类别的全部工具const authTools getToolsByCategory(authentication); // 返回: [login, logout, get_auth_status, refresh_auth_token, auto_login]底层实现tools-registry.ts直接索引TOOLS_REGISTRY[category]若类别不存在则返回空数组[]不会抛异常——这是容错设计方便调用方安全地处理未知类别。2getToolCategories()列出所有已注册类别const categories getToolCategories(); // 返回: [authentication, employees, tasks, projects, dailyPlans, organizationContacts, timer, test]底层实现使用Object.keys(TOOLS_REGISTRY)返回的数组顺序与对象字面量定义顺序一致tools-registry.ts。3getToolCounts()按类别统计工具数量const counts getToolCounts(); // 返回: { authentication: 5, employees: 15, tasks: 16, projects: 15, dailyPlans: 17, organizationContacts: 17, timer: 3, test: 3 }底层实现用reduce遍历所有类别把每个类别数组的.length映射到同名键tools-registry.ts。4getTotalToolCount()全部工具总数const total getTotalToolCount(); // 返回: 91底层实现Object.values(TOOLS_REGISTRY).reduce((sum, tools) sum tools.length, 0)tools-registry.ts。5isToolRegistered(toolName)判断工具是否已注册const exists isToolRegistered(get_employees); // 返回: true const notExists isToolRegistered(nonexistent_tool); // 返回: false底层实现Object.values(TOOLS_REGISTRY).some(tools tools.includes(toolName))只要任一类别包含该名称即返回truetools-registry.ts。6getToolCategory(toolName)反查工具所属类别const category getToolCategory(start_timer); // 返回: timer const unknown getToolCategory(no_such_tool); // 返回: null底层实现遍历Object.entries(TOOLS_REGISTRY)找到包含该工具的类别立即返回全部找不到则返回nulltools-registry.ts。返回值用null而非undefined或空字符串语义更明确。额外导出getAllTools()在 tools-registry.ts 中还有一个文档里未单独列举但非常实用的函数getAllTools()它用Object.values(TOOLS_REGISTRY).flat()把所有类别的工具合并成一个扁平字符串数组适合做全局去重校验或生成工具清单。3.3 典型使用场景统计报表启动时打印各业务域的工具规模判断模块是否完整权限/能力探测在 UI 或 Agent 端根据getToolCategory判断某个工具归属的业务域一致性校验用isToolRegistered在测试中断言某个工具已上线动态菜单按类别枚举工具生成客户端可展示的工具树。四、从注册表到运行时工具注册的完整链路注册表只是“目录”真正让工具可被 LLM 调用的是运行时注册链路。这条链路在源码中有清晰的三层结构。4.1 第一层按业务域拆分的注册模块packages/mcp-server/src/lib/tools 目录下共有 31 个文件含register-all-tools.ts、index.ts、tool-helper.ts、utils.ts、input-schema-json.spec.ts及 28 个业务工具模块如 employees.ts、tasks.ts、projects.ts、auth.ts、timer.ts、daily-plan.ts、organization-contact.ts等。每个模块导出形如registerXxxTools(server: McpServer, sessionId?)的函数内部调用server.tool(...)或封装后的registerTool(...)完成注册。以 employees.ts 为例registerEmployeeTools通过registerTool注册get_employeesexport const registerEmployeeTools (server: McpServer) { registerTool( server, get_employees, Get list of employees for the authenticated users organization with pagination, { page: z.number().optional().default(1).describe(Page number for pagination), // ... 更多 Zod 参数 }, async (args) { /* 实现调用 Gauzy API */ } ); };这里的入参 schema 使用 Zod 定义z.number().optional().default(1)表示page可选、默认 1工具描述description会被 MCP 协议带给 LLM作为其决定是否调用该工具的依据。4.2 第二层统一装配入口 registerAllMcpToolsregister-all-tools.ts 是“总装配车间”registerAllMcpTools(server, sessionId)按固定顺序调用 28 个业务模块的注册函数register-all-tools.tsexport function registerAllMcpTools(server: McpServer, sessionId?: string): void { registerAuthTools(server, sessionId); registerTimerTools(server); registerProjectTools(server); registerTaskTools(server); registerEmployeeTools(server); registerDailyPlanTools(server); registerOrganizationContactTools(server); registerTestTools(server); registerProductTools(server); registerProductCategoryTools(server); registerInvoiceTools(server); registerExpenseTools(server); registerGoalTools(server); registerKeyResultTools(server); registerDealTools(server); registerCandidateTools(server); registerPaymentTools(server); registerMerchantTools(server); registerIncomeTools(server); registerEquipmentTools(server); registerCommentTools(server); registerReportTools(server); registerTimeOffTools(server); registerEmployeeAwardTools(server); registerActivityLogTools(server); registerWarehouseTools(server); registerPipelineTools(server); registerSkillTools(server); }这段代码既是生产环境启动时的注册入口也被“schema 回归测试”复用文件头注释“Shared by production server bootstrap and schema regression tests.”。从源码结构看会话相关的工具如registerAuthTools接收sessionId其余模块不需要——这印证了注册表维护时无需感知会话细节的设计。4.3 第三层服务器引导与运行时调用mcp-server.ts 中的createMcpServer(sessionId?)创建ExtendedMcpServer实例后立即调用registerAllMcpTools(server, sessionId)并在日志中输出 “All tools registered successfully”mcp-server.ts。ExtendedMcpServer继承官方McpServer并新增两个公开方法listTools()mcp-server.ts从内部_registeredTools枚举所有已注册工具将 Zod schema 转换成 JSON schema优先zodSchema.toJSON()否则动态import(zod-to-json-schema)再兜底为空对象返回统一的ToolDescriptor[]{ name, description, inputSchema }invokeTool(name, args)mcp-server.ts按名称查找工具并执行其callback且在日志中通过mask()把pass|secret|token|key|auth|credential等敏感参数打码为***避免凭证泄露到日志。createMcpServerAsync还会先初始化sessionManager再创建服务createAndStartMcpServer进一步通过TransportFactory创建并连接传输层stdio / HTTP / WebSocket最终可供 Claude Desktop 等外部客户端连接。而 server-info.ts 中的SERVER_INFO声明了服务器的能力位tools: true、resources: false、prompts: false并列出schemaValidation / bulkOperations / relationSupport / paginationSupport / statisticsSupport / assignmentOperations / authentication / tokenRefresh等特性protocol.ts 则固定了协议版本PROTOCOL_VERSION 2025-06-18。4.4 关键设计tool-helper 为何存在在工具数量达到数百个tool-helper.ts注释中明确提到 “324 tools in this codebase”时官方server.tool()方法基于 Zod 的复杂泛型推导会让 TypeScript 在编译期内存耗尽。为此 tool-helper.ts 提供了registerTool/registerNoArgsTool两个轻量封装registerTool(server, name, description, schema, callback)把schema包进z.object()后以(server.registerTool as any)方式调用运行时仍保留 Zod 校验registerNoArgsTool(server, name, description, callback)注册无参数工具回调统一返回{ content: [{ type: text, text }] }结构的ToolResult。这正是注册表设计哲学在工程实现上的延伸注册表是“目录”tool-helper 是“高效装配工具”二者共同降低大规模 MCP 工具集的可维护成本。五、维护指南新增工具与新增类别5.1 新增一个工具三步走以文档示例“新增archive_employee归档员工”为例步骤 1在业务工具模块中实现并注册在 packages/mcp-server/src/lib/tools/employees.ts文档中写作src/tools/employees.ts相对路径已按仓库根目录归一化中用registerTool注册新工具// 在 src/lib/tools/employees.ts registerTool( server, archive_employee, Archive an employee, { employeeId: z.string().uuid().describe(Employee ID to archive), // 其他参数按需定义 }, async (args) { // 调用 Gauzy API 实现归档逻辑 return { content: [{ type: text, text: Employee archived successfully }] }; } );注意只有在此处注册工具才会真正出现在 MCP Server 的_registeredTools中并被listTools()枚举、被invokeTool()调用。步骤 2把工具名加入注册表对应类别在 tools-registry.ts 的employees数组中追加export const TOOLS_REGISTRY: ToolRegistry { employees: [ get_employees, create_employee, // ... existing tools archive_employee // 新增工具 ] // ... other categories };步骤 3可选但推荐补全统计与校验加入注册表后getToolsByCategory(employees)、getToolCounts()、getTotalToolCount()、isToolRegistered(archive_employee)、getToolCategory(archive_employee)的结果会自动同步更新无需额外代码——这正是集中式注册表“一处维护、处处生效”的收益。5.2 新增一个类别当出现全新业务域例如报表时直接在TOOLS_REGISTRY中增加一个新键export const TOOLS_REGISTRY: ToolRegistry { // ... existing categories reporting: [generate_report, get_report_templates, export_report] };新增类别后getToolCategories()会自动包含reporting。建议类别命名遵循现有 camelCase 惯例工具命名遵循 snake_case 惯例保持风格统一。5.3 从硬编码清单迁移到注册表如果代码中已有硬编码的工具清单迁移前硬编码const tools { authentication: [login, logout, ...], employees: [get_employees, ...] };迁移后使用注册表import { TOOLS_REGISTRY } from ../config/tools-registry.js; const tools TOOLS_REGISTRY;一旦切换到注册表后续所有类别与工具的增删只需改 tools-registry.ts 一处全项目共享同一份权威数据。六、设计收益与最佳实践总结对照 TOOLS_CONFIG.md 的 “Benefits” 一节结合源码验证集中式注册表带来五点明确收益单一事实来源Single Source of Truth所有工具定义集中在tools-registry.ts杜绝多份清单漂移类型安全Type SafetyToolRegistry接口约束了类别→工具名的结构配合 TypeScript 静态检查保证一致性易维护Easy Maintenance新增工具只需改一处统计、校验函数自动生效内置工具函数Utility Functions6 个纯函数覆盖按类别取、按名反查、计数、总数、存在性判断等常见操作可复用Reusabilityconfig/index.ts统一导出任何模块运行时、测试、UI都能按需引入。实践中的最佳姿势可归纳为注册业务模块实现 registerAllMcpTools 装配负责“工具真实可用”注册表tools-registry.ts负责“工具可被检索与统计”两者互为表里。新增功能时先实现注册、再登记入表迁移旧代码时优先切换到注册表以保持整个 MCP Server 工具面的整洁与一致。如需进一步深入可继续阅读工具注册总入口 register-all-tools.ts、员工工具实现示例 employees.ts、服务器引导与调用逻辑 mcp-server.ts、服务器能力声明 server-info.ts 及 包级说明文档 README。赞分享后端前端企业应用MCP 服务【免费下载链接】ever-gauzyEver® Gauzy™ - Open Business Management Platform (ERP/CRM/HRM/ATS/PM) - https://gauzy.co项目地址https://gitcode.com/GitHub_Trending/ev/ever-gauzy点击查看免费下载相关推荐DeepChat Node/TypeScript MCP Server 实现指南从项目脚手架到生产级工具注册DeepChat Node/TypeScript MCP Server 实现指南从项目脚手架到生产级工具注册 本文是一份面向 DeepChat 生态的 NodAI Agent人工智能AI 应用桌面应用MCP ClientsActivepieces 的 Node/TypeScript MCP Server 实现指南从项目搭建到生产级工具注册Activepieces 的 Node/TypeScript MCP Server 实现指南从项目搭建到生产级工具注册 导读 本文是 Activepieces工作流自动化低代码AI 应用人工智能AI AgentMCP 服务后端前端PraisonAI TypeScript Agent 工具注册完全指南四种函数注册方式与 MCP SSE 远程工具集成PraisonAI TypeScript Agent 工具注册完全指南四种函数注册方式与 MCP SSE 远程工具集成 导读 本文以 PraisonAI Ty人工智能AI AgentAgent 框架多智能体工作流自动化RAGMCP 服务上一篇btop资源监控工具5个步骤打造你的专业级系统监控仪表盘下一篇FreeCAD高级渲染策略专业级性能优化实践指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考