后端前端企业应用MCP 服务【免费下载链接】ever-gauzyEver® Gauzy™ - Open Business Management Platform (ERP/CRM/HRM/ATS/PM) - https://gauzy.co项目地址https://gitcode.com/GitHub_Trending/ev/ever-gauzy点击查看免费下载本篇技术指南以 integration-activepieces/README.md 为骨架深入剖析 Ever Gauzy 与 ActivePieces 自动化平台之间的官方集成插件gauzy/plugin-integration-activepieces。文章覆盖插件的安装、构建、测试与发布流程并基于仓库源码逐项拆解「连接管理」与「MCP Server 管理」两大核心能力对应的 REST 接口、配置项与底层实现原理。读完本文你将能够在自己的 NestJS / Ever Gauzy 应用中完成 ActivePieces 集成配置、连接资源的增删查改以及 MCP Server 的更新与令牌轮换。一、插件概览为 Ever Gauzy 接入 ActivePieces 自动化平台ActivePieces 是一个开源的 AI 自动化平台允许用户通过可视化流程Flows把各类应用与 AI Agent 串联起来。Ever Gauzy开源商业管理平台覆盖 ERP/CRM/HRM/ATS/PM 等模块通过本插件以租户Tenant维度管理 ActivePieces 上的资源所有 API 调用统一使用 ActivePieces 平台的 API Key 进行鉴权——该能力按官方说明需要ActivePieces Platform / Enterprise 版本才能使用。插件在 activepieces.module.ts 中声明为标准的 NestJS 模块并对外提供两类能力能力域服务控制器功能连接管理Connection Managementactivepieces.service.tsactivepieces.controller.ts为 Ever-gauzy piece 创建、列出、查询、删除 ActivePieces 应用连接MCP Server 管理activepieces-mcp.service.tsactivepieces-mcp.controller.ts列出、更新、轮换 ActivePieces MCP Server 的令牌模块依赖方面插件同时引入了gauzy/core中的集成基础设施IntegrationModule、IntegrationTenantModule、IntegrationSettingModule、IntegrationMapModule等以及RoleModule/RolePermissionModule/UserModule等核心模块并通过HttpModule.register({ baseURL: ACTIVEPIECES_API_URL })统一向 ActivePieces API 发起 HTTP 请求。作为 Gauzy 插件体系的成员integration-activepieces.plugin.ts 使用Plugin()装饰器注册实现IOnPluginBootstrap与IOnPluginDestroy生命周期接口在插件启动与销毁时输出日志同时暴露configuration回调允许对主插件配置对象进行自定义修改后再返回。二、环境变量与全局配置插件运行依赖两类全局配置均在 activepieces.config.ts 与 config/activepieces.ts 中定义配置项环境变量默认值说明ACTIVEPIECES_BASE_URLACTIVEPIECES_BASE_URLhttps://cloud.activepieces.comActivePieces 平台根地址自托管部署时可替换apiKeyGAUZY_ACTIVEPIECES_API_KEY空字符串全局 API Key作为租户级 Key 缺失时的兜底由默认值推导出的 API 路径如下API 根地址{ACTIVEPIECES_BASE_URL}/api/v1连接端点{API}/app-connectionsMCP Server 端点{API}/mcp-serversPiece 名称常量Ever-gauzy连接创建时使用的 pieceName环境变量GAUZY_ACTIVEPIECES_API_KEY同时在 environment.ts 与 environment.prod.ts 中被读取并通过registerAs(activepieces)注册到 NestJS Config 体系供服务层以this.configService.get(activepieces)?.apiKey的方式访问。三、安装、注册与集成初始化3.1 安装插件使用你偏好的包管理器安装npm install gauzy/plugin-integration-activepieces # 或 yarn add gauzy/plugin-integration-activepieces从 package.json 可以看出该包的运行时约束Node.js22、Yarn1.22peerDependencies 为nestjs/common与nestjs/core^11.1.26内部依赖gauzy/common、gauzy/config、gauzy/contracts、gauzy/core、gauzy/plugin、gauzy/utils等平台包并以nestjs/axiosaxios作为 HTTP 客户端rxjs处理异步请求流。3.2 在应用中注册插件对外导出IntegrationActivepiecesPlugin见 src/index.ts将其加入应用的插件集合即可完成挂载import { IntegrationActivepiecesPlugin } from gauzy/plugin-integration-activepieces; // 应用配置 plugins 数组中追加 plugins: [ IntegrationActivepiecesPlugin ]3.3 通过 REST 接口初始化集成注册完成后调用POST /api/integration/activepieces/setup并携带 API Key 完成租户级初始化需要INTEGRATION_ADD权限{ apiKey: sk-..., organizationId: 可选不传则按租户维度保存 }请求体由 SetupActivepiecesIntegrationDto 校验apiKey为必填字符串。服务端在 activepieces.service.ts 的setupIntegration()中完成三件事按provider ACTIVE_PIECES查找或创建全局集成记录Integration在当前租户下查找或创建「集成租户」IntegrationTenant并写入api_key与is_enabledtrue两个设置项若租户已存在集成记录则对既有设置做原地合并更新保留数据库主键而非重复插入。成功后返回{ integrationTenantId: ... }该 ID 是后续所有连接与 MCP 管理接口的入参。四、连接管理Connection Management详解连接管理的所有接口都挂在Controller(/integration/activepieces)下见 activepieces.controller.ts并统一受TenantPermissionGuard与Permissions装饰器双重保护。4.1 创建 / 更新连接UpsertPOST /api/integration/activepieces/connection请求体由 CreateActivepiecesIntegrationDto 定义字段必填说明accessToken是ActivePieces 访问令牌示例ap_1234567890abcdefprojectId是连接将被创建到的 ActivePieces 项目 ID示例proj_1234567890abcdefconnectionName否连接显示名缺省时使用Ever Gauzy - {tenantId}服务端upsertConnection()activepieces.service.ts会构造标准 upsert 请求体并 POST 到/app-connectionsexternalIdgauzy-tenant-{tenantId}若传了organizationId则追加-org-{organizationId}作为当前租户的唯一外部标识pieceName固定为Ever-gauzytypeSECRET_TEXTvalue.secret_text承载 accessTokenmetadata写入tenantId、organizationId缺省为default、createdAtISO 时间戳与gauzyVersion: 1.0.0供后续按租户过滤使用。成功后插件会把access_token、connection_id、project_idJSON 数组序列化与is_enabledtrue持久化到当前租户的集成设置中并返回 ActivePieces 的连接对象额外附带integrationId。4.2 列出连接GET /api/integration/activepieces/connections/:integrationId查询参数由 ActivepiecesConnectionsListQueryDto 校验参数必填约束 / 默认值说明projectId是非空字符串目标项目 IDcursor否字符串分页游标scope否枚举ActivepiecesConnectionScope当前仅PROJECT连接范围pieceName否字符串按 piece 名过滤displayName否字符串按显示名过滤status否枚举ActivepiecesConnectionStatusACTIVE/ERROR按状态过滤limit否整数1–100默认 10返回条数4.3 查询与删除接口说明GET /integration/activepieces/connections/tenant/:integrationId/:projectId获取当前租户自己的连接列表服务端拉取项目连接后用metadata.tenantId 当前租户ID二次过滤GET /integration/activepieces/connection/:integrationId读取集成租户设置中的connection_id随后向 ActivePieces 拉取单条连接详情DELETE /integration/activepieces/connection/:integrationId删除连接需要INTEGRATION_DELETE权限返回 204未找到连接记录时返回 4044.4 状态查询与集成信息GET /integration/activepieces/status/:integrationId读取is_enabled设置兼容布尔与 JSON 字符串两种存储形态返回{ enabled: true | false }GET /integration/activepieces/integration-tenant/:integrationId返回包含integration与settings关联关系的集成租户完整信息。五、MCP Server 管理详解MCPModel Context ProtocolServer 管理接口挂在Controller(/integration/activepieces/mcp)下见 activepieces-mcp.controller.ts核心服务实现位于 activepieces-mcp.service.ts。方法路径权限说明GET/integration/activepieces/mcp?projectId...INTEGRATION_VIEW按项目列出 MCP Server支持limit、cursor、name过滤GET/integration/activepieces/mcp/tenant?projectId...INTEGRATION_VIEW返回当前租户的 MCP Server按名称包含租户 ID 或gauzy过滤GET/integration/activepieces/mcp/:serverIdINTEGRATION_VIEW查询单个 ServerserverId缺失或为空时返回 400PATCH/integration/activepieces/mcp/:serverIdINTEGRATION_EDIT更新 Server 名称与工具列表POST/integration/activepieces/mcp/:serverId/rotateINTEGRATION_EDIT轮换 Server 令牌请求体为空更新请求体由 ActivepiecesMcpUpdateDto 定义name非空字符串与tools非空数组均可选每个 tool 项支持id、type、pieceMetadata对象与flowId字段且字符串字段会先trim再校验。服务端通过POST请求${MCP_SERVERS_URL}/{serverId}与${MCP_SERVERS_URL}/{serverId}/rotate完成更新与令牌轮换。安全细节所有 MCP 相关响应在返回前都会经过sanitizeMcpServer()处理——用解构方式剔除token字段只把公开数据id、name、projectId、tools等暴露给调用方。该脱敏逻辑与 contracts 中定义的IActivepiecesMcpServerPublic类型OmitIActivepiecesMcpServer, token一一对应。MCP 服务在底层封装了统一的request()帮助方法activepieces-mcp.service.ts统一注入Authorization: Bearer {apiKey}请求头、设置8 秒超时并把 Axios 错误统一转换为HttpException。六、API Key 解析顺序与错误处理两个服务都实现了「租户优先、全局兜底」的 API Key 解析策略见 activepieces.service.ts若传入integrationTenantId先查询当前租户下该集成租户的设置命中api_key则直接使用未命中时回退读取全局配置configService.get(activepieces)?.apiKey即GAUZY_ACTIVEPIECES_API_KEY两者皆无则抛出InternalServerErrorException提示设置环境变量或先执行setupIntegration。值得一提的容错逻辑在upsertConnection()中即使当前租户尚未执行过setupIntegration找不到集成租户插件也不会中断而是记录 warning 并回退到全局GAUZY_ACTIVEPIECES_API_KEY继续调用 ActivePieces API。错误处理上服务层对 HTTP 调用使用 RxJS 的catchError管道401 响应映射为UnauthorizedException其他响应包装为InternalServerErrorException/HttpException并保留原始状态码与错误消息来自error.response.data.error.message。七、数据模型与设置项Contracts 层插件依赖的 ActivePieces 数据模型集中在 packages/contracts/src/lib/activepieces-integration-config.model.ts主要包括连接类型ActivepiecesConnectionTypeSECRET_TEXT、OAUTH2、CLOUD_OAUTH2、PLATFORM_OAUTH2、BASIC_AUTH、CUSTOM_AUTH。本插件创建连接时固定使用SECRET_TEXT。连接范围ActivepiecesConnectionScope当前仅PROJECT。连接状态ActivepiecesConnectionStatusACTIVE、ERROR。持久化设置名ActivepiecesSettingName插件在集成租户的settings表中使用以下键名设置名枚举值用途API_KEYapi_key租户级 API KeyACCESS_TOKENaccess_token连接访问令牌REFRESH_TOKENrefresh_token刷新令牌预留TOKEN_TYPE/EXPIRES_IN/EXPIRES_AT同名令牌元数据预留CONNECTION_IDconnection_idActivePieces 连接 IDPROJECT_IDproject_id项目 ID 数组JSON 序列化IS_ENABLEDis_enabled集成启用标记CLIENT_ID/CLIENT_SECRET/CALLBACK_URL/POST_INSTALL_URL/STATE_SECRET同名OAuth 流程预留字段连接对象IActivepiecesConnection完整字段包括id、created、updated、externalId、displayName、type、pieceName、projectIds、platformId、scope、status、ownerId、owner、metadata、flowIds、integrationId。MCP Server 对象IActivepiecesMcpServer则包含id、created、updated、name、projectId、token、agentId、tools每个 tool 带pieceMetadata与flow信息。八、构建、测试与发布该插件在 Nx 工作区中注册为库项目plugin-integration-activepieces见 project.json构建产物输出到dist/packages/plugins/integration-activepieces。8.1 构建yarn nx build plugin-integration-activepieces构建使用nx/js:tscexecutormain指向 src/index.ts并把包内*.md作为资产一并拷贝到产物目录。8.2 运行单元测试yarn nx test plugin-integration-activepieces测试由nx/jest:jestexecutor 驱动使用仓库统一的 jest.config.ts 配置。8.3 发布构建完成后进入产物目录执行 npm 发布cd dist/packages/plugins/integration-activepieces npm publish该包以gauzy/plugin-integration-activepieces当前版本0.1.0命名遵循 AGPL-3.0 许可协议。九、从源码结构看实现要点与使用限制租户隔离是设计主线从 externalId 命名规则gauzy-tenant-{tenantId}、连接的 metadata 租户标记到getTenantConnections()/getTenantMcpServers()的二次过滤插件的所有资源操作都以当前请求上下文RequestContext.currentTenantId()为边界可安全运行在多租户部署中。双重鉴权HTTP 层使用 ActivePieces API KeyBearer头调用外部平台Ever Gauzy 侧则依赖TenantPermissionGuard与INTEGRATION_ADD/INTEGRATION_VIEW/INTEGRATION_EDIT/INTEGRATION_DELETE权限控制接口访问。面向自托管可配置通过ACTIVEPIECES_BASE_URL环境变量即可指向私有部署的 ActivePieces 实例GAUZY_ACTIVEPIECES_API_KEY则用于提供全局兜底密钥。使用前提按照 README 说明平台级 API Key 仅在 ActivePieces 的 Platform / Enterprise 版本中可用社区自托管部署是否支持取决于你所使用的 ActivePieces 版本能力。十、快速验证流程实战清单安装插件包并在 Ever Gauzy 应用中注册IntegrationActivepiecesPlugin设置环境变量GAUZY_ACTIVEPIECES_API_KEY或调用POST /integration/activepieces/setup保存租户级 Key调用POST /integration/activepieces/connection创建 Ever-gauzy piece 的连接SECRET_TEXT类型保存返回的integrationId通过GET /integration/activepieces/connections/:integrationId?projectId...核对连接列表通过GET /integration/activepieces/mcp?projectId...查看 MCP Server用PATCH /:serverId更新配置用POST /:serverId/rotate轮换令牌运行yarn nx test plugin-integration-activepieces验证插件行为再按需执行构建与发布流程。赞分享后端前端企业应用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 中集成 Activepiecesgauzy/plugin-integration-activepieces-ui 插件深度解析在 Ever Gauzy 中集成 Activepiecesgauzy/plugin integration activepieces ui 插件深度解析 导后端前端企业应用MCP 服务Cog 机器学习模型容器化实战从 cog.yaml 到生产级 HTTP 推理服务Cog 机器学习模型容器化实战从 cog.yaml 到生产级 HTTP 推理服务 Cog 是一个面向机器学习模型的开源容器化工具让你用一份 cog.yaml后端前端企业应用MCP 服务在 Modal 无服务器 GPU 上按需部署 Tabby完整实操指南在 Modal 无服务器 GPU 上按需部署 Tabby完整实操指南 Modal 是一个 serverless GPU 平台通过它运行 Tabby 可以实现后端前端企业应用MCP 服务上一篇Go 夜读Go 开发者 Vim 环境配置全解析.vimrc 完整方案下一篇rn-fetch-blob开发者进阶手册自定义配置与扩展开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考