@expertcustom/funilaria-mcp

一个 MCP（Model Context Protocol）服务器，提供 Aurora 的 AI 在 Funilaria & Pintura 门户上写入和读取时使用的类型化工具。

它取代了 mcp-fetch：不再手工组装 HTTP 请求并把密钥写在 system prompt 里——这里的每个操作都是一个带 schema、描述和葡萄牙语错误提示的工具。

IA do Aurora ──stdio──> npx @expertcustom/funilaria-mcp ──HTTPS──> backend NestJS

根据 ADR-001，这个包是 适配器：这里不包含任何业务规则。每个工具调用的都是已经存在的端点，决策权仍归后端服务所有。

工具

认证

带有显式 shopId 的服务凭据既是写入路径也是读取路径的主要方式。请求头 x-aurora-secret 与后端 AURORA_WEBHOOK_SECRET 使用同一个值；它不代表任何个人，只代表服务。

一个同时服务多家车间的 AI 不会有会话，因此车间是一个 参数，绝不是隐含上下文。后端通过库存读取路由上的 @AllowService() 体现这一点：JwtAuthGuard 允许用该密钥代替 JWT，ShopContextGuard 则进一步强制要求传入 shopId —— 不存在的 id 会返回 404 Oficina não encontrada，而不是返回一个可能被误认为“车间没有库存”的空列表。

用户会话方式（POST /auth/entrar 的 JWT）仍支持用于本地开发：在不传 shopId 的情况下，车间来自会话。Access token 有效期约 15 分钟，因此客户端会通过 refresh token 自动续期，并写回 rotated 后的 token 对。在这种模式下还传入 shopId 会被立即拒绝，并附带解释——因为路由会把会话中的车间当作请求的车间返回。

配置 —— env 是主要方式

生产环境中，启动此进程的是 Aurora 的运行时，由它注入变量：没有终端，也不会执行任何登录命令。服务器可以在空磁盘上运行。

这些别名是为了解决一个典型错误：复制后端的 .env 后，因为前缀不同导致密钥“消失” —— AURORA_WEBHOOK_SECRET 在两侧实际上是完全相同的一个值。

密钥永远不会硬编码，也不会从 prompt 读取。~/.config/funilaria-mcp/credentials.json（权限 0600）只是本地开发的便利设施；env 始终优先，并且永远不会被写入磁盘。

启动时，服务器会在 stderr（stdout 归 MCP 协议使用）中写一行内容，说明配置了什么，以及每项配置来自哪个 env —— 绝不写出密钥值。这就是有人写错变量名时 Aurora 日志中出现的那行内容：

[funilaria-mcp] API: https://api.exemplo.com (FUNILARIA_API_URL) · Credencial de serviço: configurada via AURORA_WEBHOOK_SECRET · ...
[funilaria-mcp] Sem credencial de serviço: as tools de escrita vão recusar toda chamada. Defina FUNILARIA_SERVICE_SECRET no ambiente deste processo.

HMAC 签名

每当存在 FUNILARIA_SIGNING_SECRET 时，所有写入操作还会额外携带：

x-timestamp: <epoch em segundos>
x-signature: sha256=<HMAC-SHA256(`${timestamp}.${corpo}`)>

这是 ADR-001 中设计的改进（防止重放和日志泄漏）。后端目前还不会验证 —— 未知的 header 会被忽略，因此可以先启用服务端这一侧，而不会影响正在运行的系统。

安装

在 Aurora 的 AI 中（生产环境）

在 MCP 配置本身中注册服务器和变量 —— 无需登录，也无需在 system prompt 中放入密钥：

{
  "command": "npx",
  "args": ["-y", "@expertcustom/funilaria-mcp"],
  "env": {
    "FUNILARIA_API_URL": "https://<api-do-portal>",
    "FUNILARIA_SERVICE_SECRET": "<mesmo valor de AURORA_WEBHOOK_SECRET>"
  }
}

本地，用于开发

# opção A — env no shell (igual à produção)
FUNILARIA_API_URL=http://localhost:3334 FUNILARIA_SERVICE_SECRET=... npx @expertcustom/funilaria-mcp

# opção B — guardar em ~/.config para não exportar em todo shell
npx @expertcustom/funilaria-mcp login-servico

# sessão de usuário: só é necessária para consultar_estoque sem shopId
npx @expertcustom/funilaria-mcp login

# conferir o que está valendo e de onde veio (nunca imprime segredo)
npx @expertcustom/funilaria-mcp status

# registrar no Claude Code
claude mcp add funilaria --env FUNILARIA_API_URL=http://localhost:3334 -- npx -y @expertcustom/funilaria-mcp

后端的待办事项

原本的四项问题（库存 webhook 不可达、读取缺少服务凭据、密钥在验证之后才被检查、以及 distance 作为死代码）局已在后端修复，并已针对 localhost:3334 重新验证。剩下的问题如下：

1. AI 无法得知 shopId。 这个字段它没有任何方式能发现，而现在只能通过 FUNILARIA_SHOP_ID 传入 —— 这在“一个服务只能绑定一个车间”的同时，也破坏了设计服务时想要支持的多车间场景。

   最廉价的切入点是指定 lancar_consumo：后端已经根据 WhatsApp 号码识别了员工和车间，但只返回一个确认文本。如果 IntakeResult 能包含 shopId 和 memberId，对话就可以继续。“用了 100ml 清漆” → “这个月我花了多少？” 只需到手后带着这两个 id 去调用 consultar_balancete. 如果没有这两个 id，后面的这两个问题根本无法得到回答。

2. GET /estoque/movimentos 没有包含在 @AllowService() 中。 shopId 已声明在 ListMovimentosDto 上，但路由不接受服务凭据 —— 这个参数根本没法再用。要么标记该路由，要么从 DTO 中移除该字段，否则会暗示原本就不存在的能力。

3. 仍未校验 HMAC 签名。 当存在签名密钥时，客户端已经会发送 x-timestamp 和 x-signature（见上文）。服务端尚未实现这一侧，以便在 ADR-001 所要求的方向上关闭重放攻击和日志泄露。

开发

npm install
npm run build     # tsc estrito, gera dist/
npm start         # sobe o servidor MCP em stdio