@expertcustom/funilaria-mcp

Servidor MCP (Model Context Protocol) con las tools tipadas que la IA de Aurora usa para escribir y leer en el portal Funilaria & Pintura.

Sustituye a mcp-fetch montando la petición HTTP a mano con el secreto escrito en el system prompt: aquí cada operación es una tool con schema, descripción y error en portugués.

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

Según la ADR-001, este paquete es adaptador: ninguna regla de negocio vive aquí. Cada tool llama a un endpoint que ya existe, y el servicio del backend sigue siendo el dueño de la decisión.

Tools — quién las define es el backend

Este paquete no sabe qué tools existen. Al arrancar busca GET /mcp/catalogo y publica lo que venga; la ejecución va por POST /mcp/ejecutar, y el backend resuelve el nombre hacia el servicio.

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

El motivo es operativo: antes, una tool nueva costaba editar este paquete, compilar, commitear, publicar y reinstalar el MCP en Aurora — cinco pasos para exponer un endpoint que ya existía en el backend. Ahora es un commit de un solo módulo, en backend/src/mcp.

La lista actual sale de GET /mcp/catalogo. No hay copia aquí a propósito: una copia envejece y acaba mintiendo.

Cuando el catálogo no responde, el servidor publica una única tool, funilaria_catalogo_indisponible, cuya descripción explica qué comprobar. Sin ella, el síntoma sería "han desaparecido las tools" y el diagnóstico empezaría por el lugar equivocado.

El catálogo se busca una vez, al arrancar: el cliente MCP lee tools/list justo después de conectar y no vuelve a preguntar. Una tool añadida en el backend entra en la próxima reinstalación del servidor en Aurora.

Related MCP server: Telegram Bot MCP Server

Autenticación

Credencial de servicio con shopId explícito es el camino principal, tanto para escribir como para leer. Header x-aurora-secret, el mismo valor de AURORA_WEBHOOK_SECRET en el backend; no representa a ninguna persona, representa al servicio.

Una IA que atiende a varios talleres no tiene sesión, así que el taller es parámetro, nunca contexto implícito. Del lado del backend eso es el @AllowService() en las rutas de lectura de stock: el JwtAuthGuard acepta el secreto en lugar del JWT y el ShopContextGuard pasa a exigir el shopId — un id inexistente responde 404 Taller no encontrado, y no una lista vacía que se confundiría con "taller sin stock".

Sesión de usuario (JWT de POST /auth/entrar) sigue existiendo para los comandos de CLI, pero ya no vale para las tools: POST /mcp/ejecutar es siempre una llamada de servicio, y el taller es siempre un parámetro explícito. Una IA que atiende a varios talleres nunca tuvo sesión; mantener los dos modos solo creaba un camino en el que shopId omitido significaba cosas distintas.

Configuración — env es el camino principal

En producción, quien levanta este proceso es el runtime de Aurora, que inyecta las variables: no hay terminal, y no se ejecuta ningún comando de login. El servidor funciona con el disco totalmente vacío.

Los apodos existen para el error clásico de copiar el .env del backend y que el secreto "desaparezca" por el prefijo distinto — AURORA_WEBHOOK_SECRET es exactamente el mismo valor en ambos lados.

El secreto nunca está hardcodeado ni se lee del prompt. El archivo ~/.config/funilaria-mcp/credentials.json (modo 0600) es una comodidad de desarrollo local; la env siempre gana y nunca se escribe en disco.

En el arranque, el servidor escribe en stderr (stdout es del protocolo MCP) una línea que dice qué está configurado y de qué env viene cada cosa — nunca el valor. Es lo que aparece en el log de Aurora cuando alguien se equivoca con el nombre de la variable:

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

Firma HMAC

Cuando FUNILARIA_SIGNING_SECRET existe, toda escritura lleva también:

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

Es la mejora mapeada en la ADR-001 (cierra replay y fuga por log). El backend todavía no la verifica — un header desconocido se ignora, así que se puede activar el lado del servidor sin romper a quien ya está corriendo.

Instalación

En la IA de Aurora (producción)

Registra el servidor con las variables en el propio registro del MCP — nada de login, nada de secreto en el 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, para desarrollar

# 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

Pendientes en el backend

Las cuatro pendientes originales (webhook de stock inalcanzable, lectura sin credencial de servicio, secreto comprobado después de la validación, distancia como código muerto) fueron corregidas en el backend y revalidadas contra localhost:3334. Lo que queda:

1. La IA no tiene forma de descubrir el shopId. Es el único dato que necesita saber de memoria, y hoy solo llega por FUNILARIA_SHOP_ID — lo que ata un servidor a un taller y tumba el caso multi-taller que motivó el diseño de servicio.

   El punto más barato de resolver es lanzar_consumo: el backend ya identificó empleado y taller por el número de WhatsApp, pero devuelve solo el texto de confirmación. Si IntakeResult incluyera shopId y memberId, la conversación fluiría — "he usado 100ml de barniz" → "¿cuánto he gastado este mes?" sería consultar_balance con los dos ids en la mano. Sin eso, la segunda pregunta no tiene respuesta posible.

2. GET /stock/movimientos quedó fuera del @AllowService(). El shopId está declarado en el ListMovementsDto, pero la ruta no acepta credencial de servicio — el parámetro no tiene forma de usarse. O se marca la ruta, o se quita el campo del DTO para no sugerir una capacidad que no existe.

3. La firma HMAC todavía no se verifica. El cliente ya envía x-timestamp y x-signature cuando hay secreto de firma (ver arriba). Falta el lado del servidor para cerrar replay y fuga por log, como prevé la ADR-001.

Desarrollo

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