Skip to main content
Glama
Spedy NFS-e MCP

Spedy NFS-e MCP

by vinilana

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: Prefeitura PE Recife: NFS-e (Nota Fiscal Eletrônica de Serviços)

配置

变量

用途

MCP_BEARER_TOKEN

保护 MCP HTTP 端点;最少 32 个字符。

SPEDY_API_KEY

由连接器作为服务端 X-Api-Key 发送。

SPEDY_BASE_URL

Spedy API 源地址,通常为 https://sandbox-api.spedy.com.br。请勿附加 /v1。

INVOKTA_HTTP_HOST

绑定主机;默认为 127.0.0.1。

INVOKTA_HTTP_PORT

绑定端口;本地示例使用 3400,适配器在未设置时默认为 3000。

开具是异步的。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

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers