@expertcustom/funilaria-mcp

MCP (Model Context Protocol) server with the typed tools that Aurora's AI uses to write and read on the Funilaria & Pintura portal.

It replaces mcp-fetch by building the HTTP request by hand with the secret written in the system prompt: here each operation is a tool with schema, description, and error in Portuguese.

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

Per ADR-001, this package is an adapter: no business rules live here. Every tool calls an endpoint that already exists, and the backend service remains the owner of the decision.

Tools — the backend defines them

This package does not know which tools exist. On startup it fetches GET /mcp/catalogo and publishes whatever comes back; execution goes through POST /mcp/executar, and the backend resolves the name to the service.

subida  ──> GET  /mcp/catalogo   → lista publicada em tools/list
chamada ──> POST /mcp/executar   → { name, args }

The reason is operational: before, a new tool cost editing this package, building, committing, publishing, and reinstalling the MCP in Aurora — five steps to expose an endpoint that already existed in the backend. Now it's a single module commit in backend/src/mcp.

The current list comes from GET /mcp/catalogo. There is deliberately no copy of it here: a copy ages and starts lying.

When the catalog does not respond, the server publishes a single tool, funilaria_catalogo_indisponivel, whose description explains what to check. Without it, the symptom would be "the tools disappeared" and the diagnosis would start in the wrong place.

The catalog is fetched once, on startup: the MCP client reads tools/list right after connecting and does not ask again. A tool added in the backend goes live on the next server reinstall in Aurora.

Related MCP server: Telegram Bot MCP Server

Authentication

Service credential with explicit shopId is the main path, both for writing and reading. Header x-aurora-secret, the same value as AURORA_WEBHOOK_SECRET in the backend; it does not represent any person, it represents the service.

An AI that serves multiple shops has no session, so the shop is a parameter, never implicit context. On the backend side this is the @AllowService() on the stock reading routes: the JwtAuthGuard accepts the secret in place of the JWT, and the ShopContextGuard then requires the shopId — a nonexistent id responds with 404 Oficina não encontrada, not an empty list that could be mistaken for "shop with no stock".

User session (JWT from POST /auth/entrar) still exists for CLI commands, but no longer applies to the tools: POST /mcp/executar is always a service call, and the shop is always an explicit parameter. An AI that serves multiple shops never had a session; keeping both modes only created a path where an omitted shopId meant different things.

Configuration — env is the main path

In production, whoever starts this process is the Aurora runtime, which injects the variables: there is no terminal, and no login command is executed. The server works with a completely empty disk.

The aliases exist for the classic mistake of copying the backend's .env and the secret "disappearing" because of the different prefix — AURORA_WEBHOOK_SECRET is exactly the same value on both sides.

Secrets are never hardcoded or read from the prompt. The file ~/.config/funilaria-mcp/credentials.json (mode 0600) is a local development convenience; the env always wins and is never written to disk.

On boot, the server writes to stderr (stdout is for the MCP protocol) a line saying what is configured and which env each thing came from — never the value. That is what appears in the Aurora log when someone gets the variable name wrong:

[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 signing

When FUNILARIA_SIGNING_SECRET exists, every write also carries:

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

This is the improvement mapped in ADR-001 (closes replay and log leakage). The backend does not verify it yet — unknown headers are ignored, so you can enable the server side without breaking what is already running.

Installation

In Aurora's AI (production)

Register the server with the variables in the MCP registration itself — no login, no secret in the 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>"
  }
}

Local, for development

# 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

Backend pending items

The four original pending items (unreachable stock webhook, reading without service credential, secret checked after validation, distance as dead code) were fixed in the backend and revalidated against localhost:3334. What remains:

1. The AI has no way to discover the shopId. It is the only piece of data it needs to know by heart, and today it only arrives via FUNILARIA_SHOP_ID — which ties one server to one shop and breaks the multi-shop case that motivated the service design.

   The cheapest point to solve is lancar_consumo: the backend already identifies the employee and shop by the WhatsApp number, but only returns the confirmation text. If IntakeResult included shopId and memberId, the conversation would flow — "I used 100ml of varnish" → "how much did I spend this month?" would be consultar_balancete with both ids in hand. Without that, the second question has no possible answer.

2. GET /estoque/movimentos was left out of @AllowService(). The shopId is declared in ListMovementsDto, but the route does not accept service credentials — the parameter has no way to be used. Either mark the route, or remove the field from the DTO so it does not suggest capability that does not exist.

3. HMAC signing is still not verified. The client already sends x-timestamp and x-signature when there is a signing secret (see above). The server side is missing to close replay and log leakage, as ADR-001 provides.

Development

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