Ever Gauzy MCP Server 工具注册表配置完全指南：从集中式注册到源码级实现-平芜编程栈

后端
前端
企业应用
MCP 服务

【免费下载链接】ever-gauzy

Ever® 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）对外暴露的 MCP（Model 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）	包含的工具
`authentication`	`login`、`logout`、`get_auth_status`、`refresh_auth_token`、`auto_login`
`employees`	`get_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_employees`
`tasks`	`get_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_employee`
`projects`	`get_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_employee`
`dailyPlans`	`get_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_plans`
`organizationContacts`	`get_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_contact`
`timer`	`timer_status`、`start_timer`、`stop_timer`
`test`	`test_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 六个辅助函数逐一详解

（1）getToolsByCategory(category)：获取某类别的全部工具

const authTools = getToolsByCategory('authentication'); // 返回: ['login', 'logout', 'get_auth_status', 'refresh_auth_token', 'auto_login']

底层实现（tools-registry.ts）：直接索引TOOLS_REGISTRY[category]，若类别不存在则返回空数组[]，不会抛异常——这是容错设计，方便调用方安全地处理未知类别。

（2）getToolCategories()：列出所有已注册类别

const categories = getToolCategories(); // 返回: ['authentication', 'employees', 'tasks', 'projects', 'dailyPlans', 'organizationContacts', 'timer', 'test']

底层实现使用Object.keys(TOOLS_REGISTRY)，返回的数组顺序与对象字面量定义顺序一致（tools-registry.ts）。

（3）getToolCounts()：按类别统计工具数量

const counts = getToolCounts(); // 返回: { authentication: 5, employees: 15, tasks: 16, projects: 15, dailyPlans: 17, organizationContacts: 17, timer: 3, test: 3 }

底层实现用reduce遍历所有类别，把每个类别数组的.length映射到同名键（tools-registry.ts）。

（4）getTotalToolCount()：全部工具总数

const total = getTotalToolCount(); // 返回: 91

底层实现：Object.values(TOOLS_REGISTRY).reduce((sum, tools) => sum + tools.length, 0)（tools-registry.ts）。

（5）isToolRegistered(toolName)：判断工具是否已注册

const exists = isToolRegistered('get_employees'); // 返回: true const notExists = isToolRegistered('nonexistent_tool'); // 返回: false

底层实现：Object.values(TOOLS_REGISTRY).some(tools => tools.includes(toolName))，只要任一类别包含该名称即返回true（tools-registry.ts）。

（6）getToolCategory(toolName)：反查工具所属类别

const category = getToolCategory('start_timer'); // 返回: 'timer' const unknown = getToolCategory('no_such_tool'); // 返回: null

底层实现：遍历Object.entries(TOOLS_REGISTRY)，找到包含该工具的类别立即返回；全部找不到则返回null（tools-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_employees：

export const registerEmployeeTools = (server: McpServer) => { registerTool( server, 'get_employees', "Get list of employees for the authenticated user's 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 第二层：统一装配入口 registerAllMcpTools

export 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 Safety）：ToolRegistry接口约束了类别→工具名的结构，配合 TypeScript 静态检查保证一致性；
易维护（Easy Maintenance）：新增工具只需改一处，统计、校验函数自动生效；
内置工具函数（Utility Functions）：6 个纯函数覆盖按类别取、按名反查、计数、总数、存在性判断等常见操作；
可复用（Reusability）：config/index.ts统一导出，任何模块（运行时、测试、UI）都能按需引入。

实践中的最佳姿势可归纳为：注册（业务模块实现 + registerAllMcpTools 装配）负责“工具真实可用”，注册表（tools-registry.ts）负责“工具可被检索与统计”，两者互为表里。新增功能时先实现注册、再登记入表；迁移旧代码时优先切换到注册表，以保持整个 MCP Server 工具面的整洁与一致。

如需进一步深入，可继续阅读：工具注册总入口 register-all-tools.ts、员工工具实现示例 employees.ts、服务器引导与调用逻辑 mcp-server.ts、服务器能力声明 server-info.ts 及包级说明文档 README。