@expertcustom/funilaria-mcp

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

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

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

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

Инструменты — кто определяет, так это бэкенд

Этот пакет не знает, какие инструменты существуют. При запуске он запрашивает GET /mcp/catalogo и публикует то, что приходит; выполнение идёт через POST /mcp/executar, и бэкенд сопоставляет имя с сервисом.

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

Причина операционная: раньше новый инструмент стоил правки этого пакета, сборки, коммита, публикации и переустановки MCP в Aurora — пять шагов, чтобы выставить конечную точку, которая уже существовала в бэкенде. Теперь это коммит одного модуля в backend/src/mcp.

Текущий список берётся из GET /mcp/catalogo. Здесь намеренно нет его копии: копия устаревает и начинает лгать.

Когда каталог не отвечает, сервер публикует единственный инструмент funilaria_catalogo_indisponivel, описание которого объясняет, что проверить. Без него симптомом было бы «инструменты исчезли», и диагностика началась бы не с того места.

Каталог запрашивается один раз, при запуске: клиент MCP читает tools/list сразу после подключения и больше не спрашивает. Инструмент, добавленный в бэкенд, попадает при следующей переустановке сервера в Aurora.

Related MCP server: Telegram Bot MCP Server

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

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

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

Сессия пользователя (JWT от POST /auth/entrar) по-прежнему существует для команд CLI, но больше не действует для инструментов: POST /mcp/executar — это всегда вызов сервиса, и мастерская всегда является явным параметром. ИИ, обслуживающий несколько мастерских, никогда не имел сессии; сохранение обоих режимов создавало бы путь, где опущенный shopId означал бы разные вещи.

Конфигурация — env является основным путём

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

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

Секрет никогда не захардкожен и не читается из промпта. Файл ~/.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 (закрывает повтор и утечку через логи). Бэкенд пока не проверяет — неизвестный заголовок игнорируется, так что можно включить сторону сервера, не ломая тех, кто уже работает.

Установка

В ИИ Aurora (продакшен)

Зарегистрируйте сервер с переменными в самой записи MCP — никакого входа, никакого секрета в системном промпте:

{
  "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

Остающиеся задачи в бэкенде

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

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

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

2. GET /estoque/movimentos остался вне @AllowService(). shopId объявлен в ListMovementsDto, но маршрут не принимает сервисное учётное данное — параметр невозможно использовать. Либо пометить маршрут, либо убрать поле из 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