Spedy NFS-e MCP

Un Invokta Action Engine que expone las operaciones de emisión y estado de Spedy NFS-e a través de un endpoint HTTP MCP Streamable autenticado.

El motor contiene tres capacidades:

• openapi.emitir-nfse: crea y pone en cola una NFS-e para su emisión asíncrona.

• openapi.consultar-nfse: lee el estado actual de una NFS-e.

• openapi.listar-nfse: lista registros de NFS-e con filtros y paginación de Spedy.

Todas las capacidades requieren un principal autenticado. Las credenciales de Spedy permanecen en el lado del servidor y nunca se aceptan como entrada de herramienta MCP.

Primera ejecución

npm run check
npm run build
npm run mcp:http

La configuración local incluida sirve MCP en http://127.0.0.1:3400/mcp. Los clientes deben enviar Authorization: Bearer <MCP_BEARER_TOKEN>.

El .env.example incluido y el .env local ignorado contienen valores simulados. Reemplace MCP_BEARER_TOKEN y SPEDY_API_KEY antes de realizar solicitudes reales. El destino predeterminado del conector es el sandbox de Spedy; la producción nunca se selecciona implícitamente.

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

Configuración

La emisión es asíncrona. Un resultado exitoso de emitir-nfse significa que Spedy aceptó y puso en cola la solicitud; use consultar-nfse o los webhooks de Spedy para observar la autorización o el rechazo. Siempre proporcione un integrationId estable para que los reintentos sean idempotentes.

Mapa del proyecto

• src/capabilities/ posee las acciones de dominio y sus contratos de entrada, salida, acceso y ejecución.

• src/engine.ts registra IDs de capacidad estables y suministra dependencias propiedad del motor.

• src/direct.ts es la ruta de humo ejecutable más pequeña.

• test/engine.test.ts demuestra el comportamiento a través del límite público del motor.

• AGENTS.md registra la arquitectura y las reglas de entrega no negociables del proyecto.

• .agents/skills/develop-invokta-project/SKILL.md brinda a los agentes compatibles un flujo de trabajo de cambio completo.

Revisar las capacidades generadas

1. Lea AGENTS.md y la habilidad de desarrollo generada.

2. Agregue una prueba de nivel de motor que falle para el resultado de dominio que necesita.

3. Actualice o reemplace el módulo bajo src/capabilities/, luego registre su ID de capacidad literal en src/engine.ts.

4. Mantenga los puntos de entrada directos y generados del adaptador en el mismo motor exportado; no duplique el manejador de capacidad en un adaptador.

5. Ejecute npm run check, luego inspeccione la capacidad en las devtools antes de implementarla.

Desarrollar interactivamente

npm run devtools

Compila el motor e inicia las devtools de Invokta, normalmente en http://localhost:4100/. Abra la URL impresa por el comando para explorar capacidades, invocarlas desde JSON sembrado por esquema a través de la ruta de ejecución que seleccione, seguir el rastro de invocación en vivo, cambiar identidades de prueba y leer el informe del doctor. Los cambios en el código reconstruyen y reinician automáticamente el motor alojado.

Ejecute los diagnósticos de solo lectura de las devtools con:

npm run devtools:doctor

Iniciar MCP HTTP

npm run build
npm run mcp:http

Empaquete el servidor y pruebe un endpoint existente con:

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

Revise el significado de dominio y la regla de acceso de cada capacidad generada antes de la implementación.