Spedy NFS-e MCP

Eine Invokta Action Engine, die Spedy-NFS-e-Emissions- und -Statusoperationen über einen authentifizierten MCP-Streamable-HTTP-Endpunkt bereitstellt.

Die Engine enthält drei Capabilities:

• openapi.emitir-nfse: erstellt eine NFS-e und reiht sie zur asynchronen Ausstellung in die Warteschlange ein.

• openapi.consultar-nfse: liest den aktuellen Status einer NFS-e.

• openapi.listar-nfse: listet NFS-e-Datensätze mit Spedy-Filtern und Pagination auf.

Alle Capabilities erfordern einen authentifizierten Principal. Spedy-Anmeldeinformationen bleiben serverseitig und werden niemals als MCP-Tool-Eingabe akzeptiert.

Erster Start

npm run check
npm run build
npm run mcp:http

Die enthaltene lokale Konfiguration stellt MCP unter http://127.0.0.1:3400/mcp bereit. Clients müssen Authorization: Bearer <MCP_BEARER_TOKEN> senden.

Die eingecheckte .env.example und die ignorierte lokale .env enthalten Mock-Werte. Ersetzen Sie MCP_BEARER_TOKEN und SPEDY_API_KEY, bevor Sie echte Anfragen stellen. Das Standardziel des Connectors ist die Spedy-Sandbox; die Produktionsumgebung wird niemals implizit ausgewählt.

Related MCP server: Receita Federal NFS-e: Notas Recebidas MCP

Konfiguration

Die Ausstellung erfolgt asynchron. Ein erfolgreiches emitir-nfse-Ergebnis bedeutet, dass Spedy die Anfrage angenommen und in die Warteschlange eingereiht hat; verwenden Sie consultar-nfse oder Spedy-Webhooks, um die Autorisierung oder Ablehnung zu beobachten. Geben Sie immer eine stabile integrationId an, damit Wiederholungen idempotent sind.

Projektübersicht

• src/capabilities/ umfasst die Domain-Aktionen und ihre Eingabe-, Ausgabe-, Zugriffs- und Ausführungsverträge.

• src/engine.ts registriert stabile Capability-IDs und stellt Engine-eigene Abhängigkeiten bereit.

• src/direct.ts ist der kleinste ausführbare Smoke-Pfad.

• test/engine.test.ts weist das Verhalten über die öffentliche Engine-Grenze nach.

• AGENTS.md hält die nicht verhandelbaren Architektur- und Bereitstellungsregeln des Projekts fest.

• .agents/skills/develop-invokta-project/SKILL.md gibt kompatiblen Agenten einen vollständigen Änderungsworkflow.

Generierte Capabilities überprüfen

1. Lesen Sie AGENTS.md und das generierte Entwicklungs-Skill.

2. Fügen Sie einen fehlschlagenden Engine-Ebene-Test für das gewünschte Domain-Ergebnis hinzu.

3. Aktualisieren oder ersetzen Sie das Modul unter src/capabilities/ und registrieren Sie anschließend die exakte Capability-ID in src/engine.ts.

4. Behalten Sie direkte und generierte Adapter-Einstiegspunkte auf derselben exportierten Engine bei; duplizieren Sie den Capability-Handler nicht in einem Adapter.

5. Führen Sie npm run check aus und prüfen Sie die Capability danach in den Devtools, bevor Sie sie bereitstellen.

Interaktive Entwicklung

npm run devtools

Der Befehl erstellt die Engine und startet die Invokta-DevTools, normalerweise unter http://localhost:4100/. Öffnen Sie die vom Befehl ausgegebene URL, um Capabilities zu durchsuchen, sie aus dem schemabefüllten JSON über den von Ihnen gewählten Ausführungspfad aufzurufen, der Live-Aufrufverfolgung zu folgen, Testidentitäten zu wechseln und den Doctor-Bericht zu lesen. Die gehostete Engine wird bei Quellcode-Änderungen automatisch neu erstellt und neu gestartet.

Führen Sie die schreibgeschützten DevTools-Diagnosen mit folgendem Befehl aus:

npm run devtools:doctor

MCP HTTP starten

npm run build
npm run mcp:http

Verpacken Sie den Server und testen Sie einen vorhandenen Endpunkt mit folgendem Befehl:

npm run deploy:package
npm run deploy:probe -- --url https://engine.example/mcp

Überprüfen Sie die Domain-Bedeutung und Zugriffsregel jeder generierten Capability vor der Bereitstellung.