@expertcustom/funilaria-mcp

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

Er ersetzt mcp-fetch, indem er HTTP-Anfragen von Hand mit dem im Systemprompt geschriebenen Geheimnis aufbaut: Hier ist jede Operation ein Tool mit Schema, Beschreibung und Fehler auf Portugiesisch.

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

Gemäß ADR-001 ist dieses Paket ein Adapter: Hier wohnt keine Geschäftslogik. Jedes Tool ruft einen bereits existierenden Endpoint auf, und der Backend-Dienst bleibt der Entscheidungsträger.

Tools – wer definiert, ist das Backend

Dieses Paket weiß nicht, welche Tools existieren. Beim Start ruft es GET /mcp/catalogo ab und veröffentlicht, was kommt; die Ausführung läuft über POST /mcp/executar, und das Backend löst den Namen zum Dienst auf.

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

Der Grund ist operativ: Früher kostete ein neues Tool das Bearbeiten dieses Pakets, das Bauen, Committen, Veröffentlichen und Neuinstallieren des MCP im Aurora – fünf Schritte, um einen Endpoint freizuschalten, der bereits im Backend existierte. Jetzt ist es ein Commit eines einzigen Moduls in backend/src/mcp.

Die aktuelle Liste stammt von GET /mcp/catalogo. Es gibt hier absichtlich keine Kopie davon: Eine Kopie altert und beginnt zu lügen.

Wenn der Katalog nicht antwortet, veröffentlicht der Server ein einziges Tool, funilaria_catalogo_indisponivel, dessen Beschreibung erklärt, was zu prüfen ist. Ohne es wäre das Symptom „die Tools sind verschwunden" und die Diagnose würde an der falschen Stelle beginnen.

Der Katalog wird einmal, beim Start, abgerufen: Der MCP-Client liest tools/list direkt nach dem Verbinden und fragt nicht erneut. Ein im Backend hinzugefügtes Tool kommt bei der nächsten Neuinstallation des Servers im Aurora.

Related MCP server: Telegram Bot MCP Server

Authentifizierung

Dienst-Anmeldedaten mit explizitem shopId sind der Hauptweg, 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ätten bedient, hat keine Sitzung, also ist die Werkstatt ein Parameter, niemals impliziter Kontext. Auf der Backend-Seite ist das das @AllowService() in den Lese-Routen des Bestands: Der JwtAuthGuard akzeptiert das Geheimnis anstelle des JWT, und der ShopContextGuard verlangt dann den shopId – eine nicht existierende ID antwortet mit 404 Oficina não encontrada und nicht mit einer leeren Liste, die mit „Werkstatt ohne Bestand" verwechselt werden könnte.

Benutzersitzung (JWT von POST /auth/entrar) existiert weiterhin für die CLI-Befehle, gilt aber nicht mehr für die Tools: POST /mcp/executar ist immer ein Dienstaufruf, und die Werkstatt ist immer ein expliziter Parameter. Eine KI, die mehrere Werkstätten bedient, hatte nie eine Sitzung; beide Modi beizubehalten schuf nur einen Weg, auf dem ein weggelassener shopId verschiedene Dinge bedeutete.

Konfiguration – env ist der Hauptweg

In Produktion startet die Laufzeit von Aurora diesen Prozess, die die Variablen injiziert: Es gibt kein Terminal, und es wird kein Login-Befehl ausgeführt. Der Server funktioniert mit völlig leerem Datenträger.

Die Aliase existieren für den klassischen Fehler, die .env des Backends zu kopieren und das Geheimnis „verschwinden" zu lassen, weil das Präfix anders ist – AURORA_WEBHOOK_SECRET ist auf beiden Seiten exakt derselbe Wert.

Geheimnisse sind nie hartcodiert und werden nie aus dem Prompt gelesen. Die Datei ~/.config/funilaria-mcp/credentials.json (Modus 0600) ist eine Bequemlichkeit für die lokale Entwicklung; die env gewinnt immer und wird nie auf die Platte geschrieben.

Beim Boot schreibt der Server auf stderr (stdout gehört zum MCP-Protokoll) eine Zeile, die sagt, was konfiguriert ist und aus welcher env jede Sache stammt – nie den Wert. Das ist, was im Log von Aurora erscheint, wenn jemand den Variablennamen falsch schreibt:

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

Wenn FUNILARIA_SIGNING_SECRET existiert, bringt jedes Schreiben auch mit:

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

Das ist die in ADR-001 kartierte Verbesserung (schließt Replay und Leck durch Logs). Das Backend prüft noch nicht – unbekannte Header werden ignoriert, also kann man die Server-Seite aktivieren, ohne die laufenden Systeme zu brechen.

Installation

In der KI von Aurora (Produktion)

Registrieren Sie den Server mit den Variablen direkt in der MCP-Registrierung – kein Login, kein Geheimnis im Systemprompt:

{
  "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, zum Entwickeln

# 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 erreichbarer Bestands-Webhook, Lesen ohne Dienst-Anmeldedaten, Geheimnis nach der Validierung geprüft, Distanz als toter Code) wurden im Backend korrigiert und gegen localhost:3334 erneut validiert. Was übrig blieb:

1. Die KI hat keine Möglichkeit, den shopId herauszufinden. Es ist die einzige Information, die sie auswendig wissen muss, und heute kommt sie nur über FUNILARIA_SHOP_ID – was einen Server an eine Werkstatt bindet und den Multi-Werkstatt-Fall zerstört, der das Dienst-Design motiviert hat.

   Der günstigste Punkt zum Lösen ist lancar_consumo: Das Backend hat bereits Mitarbeiter und Werkstatt über die WhatsApp-Nummer identifiziert, gibt aber nur den Bestätigungstext zurück. Wenn IntakeResult shopId und memberId enthielte, würde das Gespräch fließen – „Ich habe 100 ml Lack verwendet" → „Wie viel habe ich diesen Monat ausgegeben?" wäre consultar_balancete mit beiden IDs in der Hand. Ohne das hat die zweite Frage keine mögliche Antwort.

2. GET /estoque/movimentos blieb außerhalb von @AllowService(). Der shopId ist im ListMovementsDto deklariert, aber die Route akzeptiert keine Dienst-Anmeldedaten – der Parameter kann nicht verwendet werden. Entweder markiert man die Route oder entfernt das Feld aus dem DTO, um keine Fähigkeit vorzutäuschen, die es nicht gibt.

3. HMAC-Signatur wird noch nicht geprüft. Der Client sendet bereits x-timestamp und x-signature, wenn ein Signatur-Geheimnis vorhanden ist (siehe oben). Es fehlt die Server-Seite, um Replay und Leck durch Logs zu schließen, wie in ADR-001 vorgesehen.

Entwicklung

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