@expertcustom/funilaria-mcp

MCP-Server (Model Context Protocol) mit den typisierten Werkzeugen, die die Aurora der KI zum Schreiben und Lesen im Portal Funilaria & Pintura verwendet.

Es ersetzt mcp-fetch, das HTTP-Anfragen von Hand mit dem Geheimnis aufbaut, das in den System-Prompt geschrieben ist: Hier ist jede Operation ein Werkzeug mit Schema, Beschreibung und Fehlern auf Portugiesisch.

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

Gemäß ADR-001 ist dieses Paket ein Adapter: Hier lebt keine Geschäftsregel. Jedes Werkzeug ruft einen bereits existierenden Endpoint auf, und der Backend-Dienst bleibt der Eigentümer der Entscheidung.

Tools

Authentifizierung

Dienst-Zugangsdaten mit explizitem shopId sind der Hauptpfad, sowohl zum Schreiben als auch zum Lesen. Header x-aurora-secret, derselbe Wert wie AURORA_WEBHOOK_SECRET im Backend; er repräsentiert keine Person, sondern den Dienst.

Eine KI, die mehrere Werkstätte betreut, hat keine Sitzung, daher ist die Werkstatt Parameter, niemals impliziter Kontext. Dies übernimmt auf der Backend-Seite @AllowService() in den Lese-Routen für den Bestand: Das JwtAuthGuard akzeptiert das Geheimnis anstelle des JWT, und die ShopContextGuard verlangt nun shopId — eine nicht existierende ID antwortet mit 404 Oficina não encontrada, nicht mit einer leeren Liste, die mit „werkstatt ohne Bestand“ verwechselt werden könnte.

Benutzersitzung (JWT von POST /auth/entrar) wird weiterhin für die lokale Entwicklung verwendet: Ohne shopId stammt die Werkstatt aus der Sitzung. Der Access Token hält ca. 15 Minuten, also verlängert der Client ihn selbst über den Refresh-Token und speichert das rotierte Paar neu. Ein shopId in diesem Modus zu übergeben wird sofort abgelehnt, mit Erklärung — die Route würde die Werkstatt der Sitzung zurückgeben, als wäre sie die angeforderte.

Konfigur in Not: env

Konfiguration – env ist der Hauptweg

In Produktion startet das Aurora-Runtime diesen Prozess und injiziert die Variablen: Es gibt kein Terminal und es wird kein Login-Befehl ausgeführt. Der Server funktioniert vollständig ohne native Daten. Offensichtlich.

Die Aliase gibt es für den typischen Fehler, die .env > des Backends zu kopieren und das Geheimnis wegen des anderen Präfixes „verschwinden“ zu lassen — AURORA_WEBHOOK_SECRET hat auf beiden Seiten genau den gleichen Wert.

Die der alte Titel „Le secret" wird niemals hartcodiert und auch nicht aus dem Prompt geles. Sie besteht in der Datei ~/.config/funilaria-mcp/credentials.json (Modus 0600); diese ist eine Bequemlichkeit für lokale Entwicklung. Die Umgebungsvariable hat eine Vorrangstellung und wird nie auf den Datenträger geschrieben.

Das Boot-Protokoll schreibt der Server in stderr (stdout gehört zum MCP-Protokoll) eine Zeile, die aussagt, was konfiguriert ist und welche dabei aus welcher Umgebungsvariable stammt — niemals den Wert. Der entsprechende Eintrag erscheint dann im Log von Aurora, wenn jemand den Namen der Variablen falsch einträgt:

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

Wenn FUNILARIA_SIGNING_SECRET existiert, enthält jeder Schreibvorgang auch:

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

Das ist die in ADR-001 geplante Verbesserung (schließt Replay und Log-Leck). Das Backend prüft noch nicht – unbekannte header werden ignoriert, daher kann man die Server-Seite aktivieren, ohne bereits in Betriebs existierende zu beschädigen.

Installation

Im Aurora-KI (Produktion)

Registriere den Server mit den Variablen direkt in der MCP-Registrierung – kein Login, kein Geheimnis im 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>"
  }
}

Lokal, für Entwicklung

# 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

Offene Punkte im Backend

Die vier ursprünglichen offenen Punkte (nicht aufrufbarer Webhook für Bestand, Lektüre ohne Dienst-Zugangsdaten, Geheimnis nach der Validierung geprüft, Distanz als „toter“) Code) wurden im Backend behoben und erneut gegen localhost:3300 abgeglichen, bestätigt. Was bleibt:

1. Die KI hat keine Möglichkeit, das shopId herauszufinden. Es ist die einzige Information, die sie auswendig kennen muss, und heute erreicht sie nur über FUNILARIA_SHOP_ID — verbindet eine Server mit einer Werkstatt und zerstört das Multi-Werkstatt-Szenario, das ausdrücklich den Entwurf des Dienstes motiviert hat.

   Der günstigste Punkt ist lancar_consumo: Das Backend hat bereits Mitarbeiter und Autorität identifiziert über die WhatsApp-Nummer, gibt aber nur den Bestätigungstext zurück. Wenn IntakeResult einen shopId und memberId enthalten würde, would be a conversation flow — „Ich habe 100 ml Lack verbraucht" -> „Wie viel ich diesen Monat ausgegeben" würde consultar_balancete with the two ids in use. Ohne das gibt es keine Antwort auf diese zweite Frage.

2. GET /estoque/movimentos blieb außerhalb von @AllowService(). The shopId is declared in ListMovimentos Dto, but the route accepts no service access — the parameter cannot be used. Either the route is specified or the field is removed from the DTO, so not com capability than not is present.

3. Die HMAC-Signatur wird noch nicht geprüft. Der Client sendet bereits x-timestamp und x-signature, wenn es ein Signaturgeheimnis gibt (siehe oben). Es fehlt noch server side for the closing of the replay and log holes, as ADR-001 behält.

Development

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