Gorelo

Gorelo MCP 服务

适用于 AI 助手和 WYRE Conduit 网关的 Gorelo PSA（专业服务自动化）REST API MCP 服务，全面覆盖公共 API（工单、客户、联系人、资产、账单、项目、文档、警报等）。

身份验证

为你的 Gorelo 组织生成 API 密钥，并将其作为 X-API-Key 请求头发送——此服务会在每次请求中处理该操作。无需交换令牌。

配置

复制 .env.example，并设置以下变量。

环境变量	说明
GORELO_API_KEY	用于 stdio 和 AUTH_MODE=env 的 Gorelo 公共 API 密钥。网关 Compose 服务不会读取此变量。
GORELO_REGION	us（默认值）或 au——账户所在区域的 API 主机。不是凭据。
MCP_TRANSPORT	stdio（默认值）或 http。
AUTH_MODE	env（默认值，读取上述变量）或 gateway（凭据由 Conduit 网关注入，并通过每个请求的 X-Gorelo-* 请求头传入）。网关模式绝不会回退到 GORELO_API_KEY。容器映像和 Compose 的默认值为 gateway。
CONDUIT_S2S_SECRET	启动 HTTP 传输时必需。如果值为空或为已知占位值（changeme、change-me、secret、example、placeholder、replace-me、your-secret、your-s2s-secret、s2s-secret、replace-with-a-real-secret），进程会记录错误并以非零状态退出。未设置此值时，Compose 不会启动。切勿提交真实值。此值绝不会被记录。
MCP_ALLOW_INSECURE_DEV	仅用于本地开发，且必须恰好设为 1，以便在没有 CONDUIT_S2S_SECRET 的情况下启动 HTTP。进程会记录警告，不会强制校验 X-Gateway-S2S，且只绑定到 127.0.0.1。如果 MCP_HTTP_HOST 不是环回地址，则会被覆盖并记录。占位密钥仍会导致启动失败。
MCP_HTTP_HOST	配置密钥后使用的绑定地址。未设置时为 0.0.0.0。容器映像设为 0.0.0.0。没有密钥时，将改用 127.0.0.1，忽略此变量。
MCP_HTTP_PORT	HTTP 端口。默认为 8080。
GORELO_PRESET、GORELO_ENABLE_DESTRUCTIVE、GORELO_ENABLE_BILLING_WRITES、GORELO_TOOLS_INCLUDE、GORELO_TOOLS_EXCLUDE	工具选择；参见工具选择。
LOG_LEVEL	debug | info（默认值）| warn | error。

/health 无需身份验证，不会调用 getCredentials()，也不会返回 API 密钥。stdio 传输不会使用 CONDUIT_S2S_SECRET。

HTTP 身份验证

设置 MCP_TRANSPORT=http 和 CONDUIT_S2S_SECRET 后，每个 /mcp 请求都必须包含 X-Gateway-S2S。其值格式为 t=<unix seconds>,v1=<hex hmac-sha256>，其中 HMAC 是使用 CONDUIT_S2S_SECRET 作为密钥，对字面字符串 t=<unix seconds> 计算得到的 SHA-256。缺少请求头或请求头无效时，返回 401。该验证信息在时钟误差为五分钟以内时有效。

在 AUTH_MODE=gateway 模式下，/mcp 还要求提供 X-Gorelo-Api-Key。X-Gorelo-Region 为可选项；如果提供，其值必须恰好为 us 或 au，否则返回 400。该请求的凭据仅来自 API 密钥请求头。缺少密钥时返回 401，且不会回退到 GORELO_API_KEY。

POST /mcp HTTP/1.1
X-Gateway-S2S: t=1710000000,v1=<hmac-sha256 hex of "t=1710000000">
X-Gorelo-Api-Key: <tenant api key>
X-Gorelo-Region: us

请求限制

• HTTP 请求正文上限为 256 KiB（262144 字节）。X-Gateway-S2S 校验通过后，如果 Content-Length 超出上限，则返回包含 JSON-RPC 错误的 413；没有 Content-Length 的正文则由 MCP SDK 传输限制。未经身份验证的请求仍会先收到 401。
• tools/call 参数上限为 10,000 个元素（包括任意深度的每个数组项和对象键）。超出上限的输入会返回 isError 工具结果，且绝不会被分发。

这些限制用于应对 CVE-2026-111768 / GHSA-46jr-4wx8-v453（验证期间的内存耗尽）和 GHSA-f897-62hf-6gxq（缺少请求正文和批次上限）。

工具

112 个工具，在构建时根据 Gorelo 的 OpenAPI 规范生成（spec/gorelo-openapi.json，于 2026-10-20 获取：117 个操作，排除 5 个）。名称遵循 gorelo_<verb>_<noun> 格式。早期版本中的 24 个读取工具保留原名；其参数未变（筛选条件使用 pageSize/statusIds 等 camelCase 名称，数组形式；get_client/get_contact/get_asset/get_time_entry 工具使用 id）。

级别根据 HTTP 方法划分：

Tier	Methods	Count	Annotations	Default
读取	GET	58	readOnlyHint: true	开启
写入	POST / PUT / PATCH	36	readOnlyHint: false，destructiveHint: false	开启（网关会控制写入），但账单写入除外（见下文）
破坏性	DELETE	18	readOnlyHint: false，destructiveHint: true	关闭；设置 GORELO_ENABLE_DESTRUCTIVE=true

标记为 admin 的写入工具可创建或更改客户、联系人、商品目录、发票或付款。

默认情况下，金钱相关操作为只读：除时间条目外，Billing 标签下的四个写入操作（gorelo_create_invoice、gorelo_create_payment、gorelo_create_item、gorelo_update_item，即所有非 DELETE 写入操作）会从 tools/list 中隐藏，且调用时会被拒绝，除非设置 GORELO_ENABLE_BILLING_WRITES=true。readonly 预设会一律隐藏这些操作。Billing 下的 DELETE 操作属于普通的破坏性工具。时间条目的创建/更新不受影响。

机器可读的分类（read / write / destructive / admin / billing_write / excluded_binary / excluded_sensitive）由 node scripts/generate-tools.mjs --tiers <file> 生成。

请求正文通过单个 body 参数传递（即 Gorelo 为该端点说明的 JSON 对象）。多值筛选条件（statusIds、clientIds 等）使用数组，并以逗号拼接后发送。

警报

工具	级别	描述
gorelo_list_alerts	读取	列出 Gorelo 中所有客户的警报。
gorelo_create_alert	写入	在 Gorelo 中针对某个客户发出新警报，例如来自外部监控工具的警报。

资产

工具	级别	描述
gorelo_get_asset	read	按 ID 获取单个 Agent（受管理设备）资产。
gorelo_get_custom_asset	read	按 ID 获取单个自定义资产。
gorelo_get_uptime_check	read	按 ID 获取单个运行时间检查。
gorelo_list_assets	read	使用游标分页列出服务提供商的 Agent（受管理设备）资产。结果按 createdOn 降序排列（最新的在前）。
gorelo_list_custom_asset_hardware_types	read	列出自定义资产可使用的硬件类型。
gorelo_list_custom_assets	read	使用游标分页列出服务提供商的自定义（非 Agent）资产。结果按 createdOn 降序排列（最新的在前）。
gorelo_list_uptime_checks	read	使用游标分页列出服务提供商的运行时间检查。结果按 createdOn 降序排列（最新的在前）。
gorelo_create_custom_asset	write	创建自定义资产，即没有安装 Gorelo Agent 的设备，例如打印机或防火墙。请使用 gorelo_list_custom_asset_hardware_types 获取有效的硬件类型。
gorelo_create_uptime_check	write	创建运行时间检查，按计划对主机执行 ping、请求网址或连接 TCP 端口。
gorelo_update_custom_asset	write	更新自定义资产。仅发送要更改的字段。
gorelo_update_uptime_check	write	更新运行时间检查。仅发送要更改的字段。
gorelo_delete_asset	destructive	从 Gorelo 删除受管理设备（Agent 资产）。此操作具有破坏性，且无法通过 Conduit 撤销。
gorelo_delete_custom_asset	destructive	从 Gorelo 删除自定义资产。此操作具有破坏性，且无法通过 Conduit 撤销。
gorelo_delete_uptime_check	destructive	删除运行时间检查并停止相应监控。此操作具有破坏性，且无法通过 Conduit 撤销。

计费

工具	层级	描述
gorelo_get_contract	read	获取一份合同，包括每条服务项目中的产品和人工。
gorelo_get_invoice	read	获取一张发票，包括其附件和明细项。
gorelo_get_item	read	根据 ID 获取一个目录项目（产品或组合包）。
gorelo_get_time_entry	read	获取一条工时记录。
gorelo_list_billing_roles	read	列出为服务提供商配置的计费角色。记录工单工时时，使用角色的 Id 作为 BillingRoleId。
gorelo_list_contracts	read	列出计费合同，以及每份合同包含的服务项目。
gorelo_list_invoices	read	列出服务提供商的发票，并按条件筛选和排序。
gorelo_list_item_categories	read	列出产品所属的类别及其子类别。
gorelo_list_items	read	列出服务提供商的项目目录，包括产品和组合包。
gorelo_list_taxes	read	列出为服务提供商配置的税率。
gorelo_list_time_entries	read	列出所有工单和任务中的工时记录，并根据筛选条件缩小范围。
gorelo_list_work_types	read	列出为服务提供商配置的工作类型。记录工单工时时，使用工作类型的 Id 作为 WorkTypeId。
gorelo_create_invoice	write (admin, billing)	为客户开具手动发票，并添加明细项。
gorelo_create_item	write (admin, billing)	在项目目录中创建产品或组合包。
gorelo_create_payment	write (admin, billing)	记录通过 Gorelo 之外的渠道收到的付款，并将其关联到已批准的发票。
gorelo_create_time_entry	write	记录工单工时。
gorelo_update_item	write (admin, billing)	部分更新项目。仅发送需要更改的字段。
gorelo_update_time_entry	write	部分更新工时记录。仅发送需要更改的字段。
gorelo_delete_contract	destructive	从 Gorelo 删除计费合同。此操作具有破坏性，且无法通过 Conduit 撤销。
gorelo_delete_invoice	destructive	根据发票状态删除或作废发票。此操作具有破坏性，且无法通过 Conduit 撤销。
gorelo_delete_item	destructive	从项目目录中删除产品或组合包。此操作具有破坏性，且无法通过 Conduit 撤销。
gorelo_delete_payment	destructive	删除通过 Gorelo API 记录的付款，例如通过 gorelo_create_payment 记录的付款。此操作具有破坏性，且无法通过 Conduit 撤销。
gorelo_delete_time_entry	destructive	删除已记录的工时。此操作具有破坏性，且无法通过 Conduit 撤销。

客户

工具	层级	描述
gorelo_get_client	read	根据 id 获取单个客户。
gorelo_list_client_locations	read	列出指定客户的地点。
gorelo_list_clients	read	使用游标分页列出服务提供商的客户。结果按客户 id 升序排列（最早的在前）。
gorelo_create_client	write (admin)	为服务提供商创建客户（及其默认地点）。
gorelo_update_client	write (admin)	更新现有客户。仅更改已提供的非 null 字段。
gorelo_delete_client	destructive	从 Gorelo 删除客户。此操作具有破坏性，且无法通过 Conduit 撤销。

联系人

工具	权限级别	描述
gorelo_get_contact	读取	按 ID 获取单个联系人。
gorelo_list_contacts	读取	使用游标分页列出服务提供商的联系人，可按客户筛选。结果按联系人 ID 升序排列（最早的在前）。
gorelo_create_contact	写入（管理员）	在客户下创建联系人；如果未提供客户，则创建临时联系人。
gorelo_update_contact	写入（管理员）	更新联系人。仅发送要更改的字段。
gorelo_delete_contact	破坏性操作	从 Gorelo 中删除联系人。此操作具有破坏性，且无法通过 Conduit 撤销。

删除记录

工具	权限级别	描述
gorelo_list_deletions	读取	列出已删除的记录，以便通过此 API 保持同步的副本可以将其移除。使用游标分页，结果先按 DeletedOn 升序排列，再按类型 ID 排序，最后按 ID 排序。

文档

工具	权限级别	描述
gorelo_get_document	读取	获取单个文档。
gorelo_get_document_version	读取	获取文档的一个版本，包括正文和附件。
gorelo_list_document_related_items	读取	列出与文档相关的记录。
gorelo_list_document_versions	读取	列出文档的所有版本，最新版本在前。
gorelo_list_documents	读取	列出服务提供商的文档。
gorelo_create_document	写入	创建包含 HTML 正文的文档，可用于客户或内部用途，也可选择嵌套在另一个文档下。
gorelo_create_document_related_item	写入	将文档关联到其他记录。
gorelo_duplicate_document	写入	复制文档并创建为新文档。
gorelo_restore_document_version	写入	将较早的版本设为当前版本。
gorelo_update_document	写入	更新文档的标题、正文或位置。仅发送要更改的字段。
gorelo_delete_document_related_item	破坏性操作	从文档中移除一个关联项。

表单

工具	权限级别	描述
gorelo_list_form_responses	读取	列出表单已提交的回复，最新的在前。
gorelo_list_forms	读取	列出服务提供商的表单，最近更新的在前。
gorelo_create_form_submission_link	写入	创建一个链接，供他人填写并提交此表单。

组织

工具	权限级别	描述
gorelo_list_api_keys	读取	列出你的 Gorelo API 密钥，最新的在前。仅显示名称和详细信息，不会显示密钥值。
gorelo_list_groups	读取	列出为服务提供商配置的技术人员组。
gorelo_list_users	读取	使用游标分页列出服务提供商的用户（技术人员）。结果按用户 ID 升序排列（最早的在前）。

项目

工具	层级	描述
gorelo_get_project	read	获取单个项目。
gorelo_get_project_comment	read	返回项目的一条评论。
gorelo_get_project_task	read	完整返回单个任务。
gorelo_get_project_task_approval	read	获取任务的一项审批及其审批人。
gorelo_get_project_task_comment	read	返回任务的一条评论。
gorelo_list_project_comments	read	返回项目的评论，按时间从新到旧排列。
gorelo_list_project_sections	read	列出项目的分区。
gorelo_list_project_tags	read	列出为服务提供商配置的项目标签。
gorelo_list_project_task_comments	read	返回任务的评论，按时间从新到旧排列。
gorelo_list_project_task_conversations	read	列出任务的对话。
gorelo_list_project_tasks	read	列出项目的任务。
gorelo_list_project_types	read	列出为服务提供商配置的项目类型。
gorelo_list_projects	read	列出项目，按最新活动时间从近到远排列。
gorelo_create_project	write	在 Gorelo 中创建项目。
gorelo_create_project_comment	write	在项目上发布评论。
gorelo_create_project_section	write	在项目中添加分区。
gorelo_create_project_task	write	在项目看板上创建任务。
gorelo_create_project_task_approval	write	请求联系人审批任务中的某项内容。
gorelo_create_project_task_comment	write	在任务上发布评论。
gorelo_create_project_task_side_conversation	write	在任务上发起侧边对话。
gorelo_update_project	write	更新项目。仅发送要更改的字段。
gorelo_update_project_section	write	更新分区的标题或颜色。仅发送要更改的字段。
gorelo_update_project_task	write	更新任务。仅发送要更改的字段。
gorelo_delete_project	destructive	删除项目及其中的所有任务。此操作具有破坏性，且无法通过 Conduit 撤销。
gorelo_delete_project_comment	destructive	删除项目的一条评论。此操作具有破坏性，且无法通过 Conduit 撤销。
gorelo_delete_project_section	destructive	删除项目分区及其中的所有任务。此操作具有破坏性，且无法通过 Conduit 撤销。
gorelo_delete_project_task	destructive	删除项目任务。此操作具有破坏性，且无法通过 Conduit 撤销。
gorelo_delete_project_task_comment	destructive	删除任务的一条评论。此操作具有破坏性，且无法通过 Conduit 撤销。

工单

工具	级别	描述
gorelo_get_ticket	read	获取单个工单。
gorelo_get_ticket_approval	read	获取工单上的单个审批及其审批人。审批状态存储于此处——对话列表保持精简，不包含审批状态。
gorelo_get_ticket_comment	read	获取工单上的单条评论。其结构与评论列表项相同，但始终包含完整的 BodyHtml，因此没有 BodyTruncated 字段。
gorelo_list_ticket_comments	read	使用游标分页列出工单上的评论。评论默认按从旧到新的顺序读取，如同从上到下查看对话。
gorelo_list_ticket_conversations	read	列出工单上的对话。
gorelo_list_ticket_statuses	read	列出服务提供商配置的工单状态。
gorelo_list_ticket_tags	read	列出服务提供商配置的工单标签。
gorelo_list_ticket_types	read	列出服务提供商配置的工单类型。
gorelo_list_tickets	read	使用游标分页列出服务提供商的工单。默认按 updatedOn 降序排序。
gorelo_create_ticket	write	在 Gorelo 中创建工单。
gorelo_create_ticket_approval	write	在工单上创建审批。列出的每位联系人初始状态均为 Pending。
gorelo_create_ticket_comment	write	向工单添加评论。Gorelo 会将其显示为由 API 而非你发布，To 和 Cc 则取自工单的对话。
gorelo_create_ticket_side_conversation	write	在工单上创建旁支对话。之后使用此对话返回的 Id 作为 conversationId，并设置 conversationType=3，向其中发布评论。
gorelo_update_ticket	write	部分更新工单。仅发送要更改的字段。
gorelo_delete_ticket	destructive	删除工单及其工时记录。此操作具有破坏性，无法通过 Conduit 撤销。
gorelo_delete_ticket_comment	destructive	删除工单上的私人评论。此操作具有破坏性，无法通过 Conduit 撤销。

tools/list 大小

按 tools/list 结果的 JSON 大小计算（名称、描述、输入架构、注释）：

配置	工具数	字节数
GORELO_PRESET=readonly	58	39,718
默认（read + write，不含账单写入）	90	87,530
GORELO_ENABLE_DESTRUCTIVE=true + GORELO_ENABLE_BILLING_WRITES=true（全部）	112	102,064

对于上下文预算紧张的客户端，可使用预设或 GORELO_TOOLS_INCLUDE 缩减列表。

工具选择

环境变量	描述
GORELO_PRESET	all（默认：read + write）、readonly（仅 read）、crm（Clients、Contacts、Organization）、tickets（Tickets、Contacts、Clients）、monitoring（Alerts、Assets）。标签预设会匹配操作的任意 OpenAPI 标签。未知值会导致启动失败。
GORELO_ENABLE_DESTRUCTIVE	true 启用 DELETE 工具。其他任何值都会使其保持关闭。预设和筛选器都不会启用这些工具。
GORELO_ENABLE_BILLING_WRITES	true 启用发票、付款和条目的创建/更新。默认关闭；预设和筛选器都不会启用这些操作。
GORELO_TOOLS_INCLUDE	以逗号分隔的名称 glob（*、?）；仅保留匹配的工具，例如 gorelo_*_ticket*,gorelo_list_clients。
GORELO_TOOLS_EXCLUDE	以逗号分隔的名称 glob；排除匹配的工具。

预设和筛选器只会缩小集合。对 tools/list 隐藏的工具即使按名称调用也会被拒绝。若选择结果中没有工具，启动将失败。

排除项

有五个操作被有意排除在外。其中三个是因为 Conduit 网关没有经过确认的二进制工具结果或上传路径：

操作	原因
POST /v1/attachments	multipart 文件上传
GET /v1/invoices/{invoiceId}/pdf	返回二进制 PDF
GET /v1/documents/{documentId}/pdf	返回二进制 PDF

该列表位于 scripts/generate-tools.mjs 中的 EXCLUDED_BINARY。

另外两个操作在任何配置下都不会公开：POST /v1/api-keys 和 DELETE /v1/api-keys/{apiKeyId}（EXCLUDED_SENSITIVE；凭据的创建/撤销不属于 AI 工具接口的范围）。gorelo_list_api_keys 会保留：它只返回密钥元数据（id、名称、作用域、日期），绝不会返回密钥值。

行为

• 所有工具都由同一个通用执行器运行：路径参数会进行 URL 编码，主机始终是区域固定的基础 URL（us / au），并且会拒绝重定向。
• HTTP 429 最多重试 3 次（遵循 Retry-After，上限为 15s；否则使用指数退避）。
• 响应超过 100KB 时会截断，并附上明确的 [TRUNCATED: ...] 标记；请使用筛选条件或 pageSize 缩小结果范围，并继续使用游标获取后续内容。
• 403 会返回 此连接的 Gorelo API 密钥没有权限运行 <tool>（HTTP 403）。管理员可在 Gorelo 的 Settings → Integrations 中检查该密钥的权限。 401、404 和 422 各有对应的消息。错误和日志中绝不会包含 API 密钥。

重新生成

npm run generate         # rewrite src/generated/tools.ts from spec/gorelo-openapi.json
npm run generate:check   # exit 1 if the committed file is stale (also enforced by a test and CI)

若要采用新的 Gorelo API 版本，请替换 spec/gorelo-openapi.json，运行 npm run generate，检查差异（新操作无需编写代码，除非其使用的请求体格式不是 JSON；生成器会对此发出明确错误），然后提交这两个文件。

归属说明

操作到工具的映射方式、重试/退避逻辑和大小限制逻辑改编自 peetinc/gorelo-mcp-all（MIT，版权所有 (c) 2026 peetinc）。请参阅 THIRD_PARTY_NOTICES.md。

开发

npm install
npm run generate   # only after changing spec/gorelo-openapi.json
npm run build
npm test
npm run lint   # tsc --noEmit

Docker

容器内的镜像会监听 0.0.0.0（MCP_HTTP_HOST），并且默认使用 AUTH_MODE=gateway。请将端口发布到回环地址，并传入真实的 S2S 密钥。在网关模式下，Gorelo API 密钥会通过每个请求中的 X-Gorelo-Api-Key 传入；不会从环境中读取。不要传入 your-s2s-secret 或 changeme 等已知占位值。启动时会将这些值视为未设置并退出。

docker build -t gorelo-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  gorelo-mcp

当 CONDUIT_S2S_SECRET 未设置时，Compose 会拒绝启动；它会设置 AUTH_MODE=gateway，不会传入 GORELO_API_KEY，并发布 127.0.0.1:8080:8080。项目的 .env 文件仅用于插值。不要为网关服务添加 env_file。

CONDUIT_S2S_SECRET="$(openssl rand -hex 32)" docker compose up

单租户 HTTP（AUTH_MODE=env）仍然需要 S2S 密钥，然后使用 GORELO_API_KEY：

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e GORELO_API_KEY=your-value \
  -e GORELO_REGION=us \
  -p 127.0.0.1:8080:8080 \
  gorelo-mcp

不带密钥的本地 HTTP 仅用于开发。即使 MCP_HTTP_HOST 为 0.0.0.0，它也会绑定到 127.0.0.1，并记录警告：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run start:http