@expertcustom/funilaria-mcp

MCP-сервер (Model Context Protocol) с типизированными инструментами, которые ИИ Aurora использует для записи и чтения на портале Funilaria & Pintura.

Он заменяет mcp-fetch, собирая HTTP-запрос вручную с секретом, указанным в system prompt: здесь каждая операция — это инструмент со схемой, описанием и ошибкой на португальском.

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

В соответствии с ADR-001, этот пакет — адаптер: никакие бизнес-правила здесь не живут. Каждый инструмент вызывает уже существующий endpoint, а серверный сервис остаётся владельцем решения.

Инструменты

Аутентификация

Преименование сервисных полномочий с явным shopId — главный путь как для записи, так и для чтения. Заголовок x-aurora-secret, то же значение, что и AURORA_WEBHOOK_SECRET на сервере; он не представляет человека — он представляет сервис.

ИИ, обслуживающий несколько мастерских, не имеет сессии, поэтому мастерская — это параметр, а не неявный контекст. На стороне backend это и есть @AllowService() на маршрутах чтения камер JwtAuthGuard принимает секрет вместо JWT, а ShopContextGuard переходит к требованию shopId — несуществующий id даёт 404 Oficina não encontrada, а не пустой список, который можно было спутать с «oficina sem estaleiro».

Пользовательская сессия (JWT из POST /auth/entrar) по-прежнему поддерживается для локальной разработки: без shopId мастерская берётся из сессии. Access token длится ~15 мин, поэтому клиент сам обновляет его по refresh token и перезаписывает обновлённую пару. Передача shopId в этом режиме отклоняется сразу, с объяснением — маршрут вернул бы мастерскую из сессии, как если бы она была запрошена.

Конфигурация — env var — основной путь

В продакшене процесс запускает, а ИИ Aurora, и он вводит переменные: терминала нет, никакой команды входа не выполняется. Сервер работает с совершенно пустым диском.

Псевдонимы существуют из‑за классической ошибки копирования .env с backend и «исчеза нуля» секрета из‑за разного префикса — AURORA_WEBHOOK_SECRET — это одно и то же значение с обеих сторон.

Секрет никогда не хардкодится и не читается из system prompt. Файл ~/.config/funilaria-mcp/credentials.json (режим 0600) — удобство для локальной разработки; env‑переменная всегда имеет приоритет и никогда не записывается на диск.

При запуске сервер пишет в stderr (stdout — для протокола MCP) строку, в которой указано, что настроено и из какой переменной окружения пришло, — но никогда само значение. Это видно в логах 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 (закрывает повторную передачу и утечку через логи). Backend пока не проверяет — неизвестный заголовок игнорируется, поэтому можно включить серверную сторону без поломки уже работающих клиентов.

Установка

В ИИ Aurora (производство)

Зарегистрируйте сервер с переменными в самой записи 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

Незакрытые вопросы в бэкенде

Те четыре первоначальные задолга (недоступный вебхук остатков, чтение без service‑credentials, секрет, проверяемый после валидации, и «расстояние как мёртвый код») были исправлены в бэкенде и проверены повторно с localhost:3334. Что осталось:

1. ИИ не может узнать shopId. Это единственные данные, которые ему нужно знать точно, иными словами, а сегодня они приходят только через FUNILARIA_SHOP_ID — что привязывает сервер к одной мастерской и ломает многоцеховый случай, ради которого строилась сервисная схема.

   Самый дешёвый способ решения — lancar_consumo: backend уже находит сотрудника и мастерскую по номеру WhatsApp, но возвращает только подтверждающий текст. Если IntakeResult включит shopId и memberId, разговор пойдёт дальше: «использовал 100 мл лака» → «сколько я потратил за месяц?» будет consultar_balancete с обоими id под рукой. А так второй вопрос ответа не получит.

2. GET /estoque/movimentos остался вне @AllowService(). shopId объявлен в ListMovimientos, но маршрут не принимает service‑credential — параметр невозможно использовать. Нужно либо запомнить этот маршрут, либо убрать поле из 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