Spedy NFS-e MCP

一个 Invokta Action Engine，通过经过身份验证的 MCP Streamable HTTP 端点公开 Spedy NFS-e 开具和状态操作。

该引擎包含三个能力：

• openapi.emitir-nfse：创建 NFS-e 并将其加入队列以进行异步开具。

• openapi.consultar-nfse：读取单个 NFS-e 的当前状态。

• openapi.listar-nfse：使用 Spedy 过滤器和分页列出 NFS-e 记录。

所有能力都需要经过身份验证的主体。Spedy 凭据保留在服务端，绝不会作为 MCP 工具输入被接受。

首次运行

npm run check
npm run build
npm run mcp:http

随附的本地配置在 http://127.0.0.1:3400/mcp 提供 MCP 服务。客户端必须发送 Authorization: Bearer <MCP_BEARER_TOKEN>。

已提交的 .env.example 和被忽略的本地 .env 包含模拟值。在发出真实请求之前，请替换 MCP_BEARER_TOKEN 和 SPEDY_API_KEY。默认连接器目标是 Spedy 的沙箱环境；绝不会隐式选择生产环境。

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

配置

开具是异步的。emitir-nfse 的成功结果意味着 Spedy 已接受并将请求加入队列；请使用 consultar-nfse 或 Spedy webhooks 来观察授权或拒绝结果。始终提供稳定的 integrationId 以使重试具有幂等性。

项目结构

• src/capabilities/ 拥有领域操作及其输入、输出、访问和执行契约。

• src/engine.ts 注册稳定的能力 ID 并提供引擎拥有的依赖项。

• src/direct.ts 是最小的可执行冒烟测试路径。

• test/engine.test.ts 通过公共引擎边界验证行为。

• AGENTS.md 记录项目不可妥协的架构和交付规则。

• .agents/skills/develop-invokta-project/SKILL.md 为兼容的代理提供完整的变更工作流程。

审查生成的能力

1. 阅读 AGENTS.md 和生成的开发技能。

2. 为你需要的领域结果添加一个失败的引擎级测试。

3. 更新或替换 src/capabilities/ 下的模块，然后在 src/engine.ts 中注册其字面能力 ID。

4. 保持直接和生成的适配器入口点指向同一个导出的引擎；不要在适配器中重复能力处理器。

5. 运行 npm run check，然后在部署前在 devtools 中检查该能力。

交互式开发

npm run devtools

构建引擎并启动 Invokta devtools，通常在 http://localhost:4100/ 上。打开命令打印的 URL 以浏览能力、通过你选择的执行路径从基于 schema 的 JSON 调用它们、跟踪实时调用轨迹、切换测试身份，并阅读 doctor 报告。源代码更改会自动重建并重启托管的引擎。

使用以下命令运行只读的 devtools 诊断：

npm run devtools:doctor

启动 MCP HTTP

npm run build
npm run mcp:http

打包服务器并使用以下命令探测现有端点：

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

在部署前，请审查每个生成能力的领域含义和访问规则。