omie-mcp

用于将 Claude 与 Omie API 集成的 MCP（模型上下文协议）服务器。

允许 Claude 通过 MCP 工具查询并在 Omie ERP 中执行操作。在此 v1 版本中，重点是 车间 模块（生产订单、产品结构、库存和投入品采购），并提供一个通用工具，已覆盖 Omie 的 所有其他模块（通用、CRM、财务、销售/NF-e、服务/NFS-e、会计面板）。

配置

1. 安装依赖：

   pnpm install

   此仓库的包管理器是 pnpm（工作区）。不要在根目录运行 npm install 或 npm run。唯一的例外是有意从 packages/omie-data 内部运行 npm test / npm run build。

   根目录的 devDependency vite 不被任何代码使用——它仅用于固定 vitest 的 peer dependency 解析。没有它，pnpm 会解析到 vite@5， 与 vitest@4（要求 vite ^6 || ^7 || ^8）不兼容， 整个测试套件会在初始化时崩溃。不要将其作为“孤立依赖”移除—— 没有任何测试会捕获这种移除。

2. 将 .env.example 复制为 .env，并填写你的 Omie App Key 和 App Secret（从 https://developer.omie.com.br/my-apps/ 获取）：

   cp .env.example .env

3. 编译：

   pnpm run build

4. 在你的 MCP 客户端（例如 Claude Desktop / Claude Code）中注册服务器，指向 dist/index.js，并设置环境变量 OMIE_APP_KEY 和 OMIE_APP_SECRET。

   配置示例（claude_desktop_config.json 或等效文件）：

   {
     "mcpServers": {
       "omie": {
         "command": "node",
         "args": ["/caminho/completo/para/omie-mcp/dist/index.js"],
         "env": {
           "OMIE_APP_KEY": "sua_app_key",
           "OMIE_APP_SECRET": "seu_app_secret"
         }
       }
     }
   }

本地 HTTP API（可选，供自己的前端/后端使用）

除了 MCP 服务器（stdio，供 Claude 使用）之外，还有第二个传输方式—— src/httpServer.ts——它将 相同的工具（allTools + handleToolCall，与 MCP 相同的注册表）暴露为简单的 REST API，供 想要构建前端或其他后端消费此逻辑而不使用 MCP 协议的人使用。

需要 API 密钥：使用 pnpm run gerar-api-key 生成，放入 .env 中的 HTTP_API_KEY——没有它服务器拒绝启动。所有路由都要求 Authorization: Bearer <HTTP_API_KEY> 头（否则返回 401）。目前仅 监听 127.0.0.1；API 密钥是此阶段（本地、单用户）的最低要求—— 如果将来暴露到外部，仅凭它是不够的。

额外的两层保护：

• 速率限制 — 每分钟最多 120 个请求（固定窗口）；超过 则返回 429。

• 破坏性操作确认 — 在 Omie 中包含、更改或删除数据的工具（omie_op_incluir/alterar/excluir、 omie_estoque_ajuste_incluir、omie_requisicao_compra_incluir、 omie_pedido_compra_incluir，以及任何通过 omie_chamar_api 且其 call 以 Incluir/Alterar/Excluir/Cancelar/Deletar 开头的调用）要求 在 payload 中包含 "confirmar": true，否则返回 400——避免意外 的破坏性调用（有 bug 的脚本、循环等）。

pnpm run gerar-api-key  # gera a chave e mostra a linha pra colar no .env
pnpm run dev:http    # desenvolvimento (tsx)
pnpm run start:http  # produção (build + node dist/httpServer.js)

• GET /tools — 列出所有可用工具（名称 + 描述）。传递 ?schema（例如 /tools?schema）以同时包含每个工具的 payload JSON Schema。

• GET /tools/<nome>/schema — 单个特定工具的 payload JSON Schema （字段、类型、哪些是必填的、每个字段的描述）——有助于 前端构建正确的表单/payload，而无需猜测。

• GET /tools/<nome>?campo=valor&outroCampo=valor — 直接通过 URL 调用工具 （可以在浏览器中测试，无需 Postman/curl）。查询字符串中的每个值 在可能时被解释为 JSON（true、123、"texto"）， 否则保留为字符串。

• POST /tools/<nome> — 调用工具；请求体（JSON）是 工具的 payload。对于大型/嵌套 payload（例如 codigos_conta_corrente 中的数组）更可取。

示例：

# ver o payload esperado por uma ferramenta
curl -H "Authorization: Bearer $HTTP_API_KEY" http://127.0.0.1:3939/tools/omie_fluxo_caixa_gerar/schema

# chamar direto pela URL (também funciona colado na barra do navegador)
curl -H "Authorization: Bearer $HTTP_API_KEY" "http://127.0.0.1:3939/tools/omie_familias_listar?pagina=1&registros_por_pagina=5"

# chamar via POST (corpo JSON)
curl -H "Authorization: Bearer $HTTP_API_KEY" -X POST http://127.0.0.1:3939/tools/omie_fluxo_caixa_gerar \
  -H "Content-Type: application/json" \
  -d '{"data_inicio":"01/07/2026","data_fim":"31/07/2026","agrupamento":"dia"}'

⚠️ 仅限本地使用。 监听 127.0.0.1（不接受来自机器外部的连接）， 无身份验证，无来源验证。在添加身份验证之前，不要将此端口暴露到 机器/本地网络之外——与之前关于将 omie-mcp 转换为远程 Connector 的安全警告相同 （见安全部分）。意图是：现在本地使用 来开发，只有在实现最低安全性（身份验证、输入验证）后才迁移到真正暴露的服务。

架构

存在 两种模块格式，根据需求选择：

• 直通（扁平） — src/tools/<modulo>.ts，一个 ToolDef 数组，1:1 映射 到 Omie 的 resource+call，没有自己的逻辑。当 Omie 已经 以用户需要的方式返回数据时使用（大多数情况）。

• 分层模块 — src/modules/<modulo>/，包含 application/use-cases、 infrastructure/gateways 和 presentation/mcp。当 Omie API 不 直接提供数据时使用——例如 estoque 没有“产品总库存”，只有按库存位置（分页）的位置； use-case 获取所有内容并求和。在这种情况下，业务规则（分页、过滤、聚合）不能存在于 OmieClient（它是通用的）或工具定义（它只是 MCP 元数据）内部。

在两种格式中，ToolDef（src/tools/types.ts）是公共契约： PassthroughToolDef（resource/call）或 UseCaseToolDef（自定义 execute）。 src/tools/registry.ts 将所有模块聚合到一个数组（allTools）中，并 决定走哪条路径；src/index.ts 仅迭代该数组并将每个 工具注册到 MCP 服务器——添加新模块不需要修改 index.ts，只需创建模块并将其导入注册表。

src/
  omieClient.ts             # cliente HTTP genérico (auth, retries, throttle) — nunca tem regra de negócio
  index.ts                   # bootstrap do servidor MCP (stdio), registra allTools + genérica
  httpServer.ts               # bootstrap do servidor HTTP (local, opcional) — mesmo allTools + genérica
  tools/
    types.ts                 # ToolDef (Passthrough | UseCase), helper defineTool()
    registry.ts               # agrega os módulos e expõe handleToolCall()
    generic.ts                 # ferramenta omie_chamar_api (fallback p/ qualquer endpoint)
    compras.ts                  # passthrough: Requisição e pedido de compra
  modules/
    ordemProducao/                 # módulo em camadas (cruza com produtos/)
      application/
        use-cases/                    # ex: listar OPs já com descrição do produto
        dto/
      infrastructure/
        gateways/
      presentation/
        mcp/
      ordemProducao-register.ts
      index.ts
    estoque/                       # módulo em camadas (tem lógica própria)
      application/
        use-cases/                    # regra de negócio (ex: somar estoque entre locais)
        dto/                            # schemas zod + tipos de entrada/saída do use-case
      infrastructure/
        gateways/                        # isola as chamadas Omie específicas do módulo
      presentation/
        mcp/                              # definição das ToolDefs expostas via MCP
      estoque-register.ts                  # agrega as tools do módulo
      index.ts                              # barrel export
    produtos/                      # módulo em camadas (mesma estrutura, cruza com estoque/)
      application/
        use-cases/                    # ex: listar produtos com quantidade/valor em estoque
        dto/
      infrastructure/
        gateways/
      presentation/
        mcp/
      produtos-register.ts
      index.ts
    pedidoVenda/                   # módulo em camadas
      application/
        use-cases/                    # ex: produtos que precisam ser separados p/ despacho
        dto/
      infrastructure/
        gateways/
      presentation/
        mcp/
      pedidoVenda-register.ts
      index.ts
    clientesFornecedores/           # módulo em camadas (gateway reutilizável por outros módulos)
      infrastructure/
        gateways/
      presentation/
        mcp/
      clientesFornecedores-register.ts
      index.ts
    contasCorrentes/                # módulo em camadas (gateway reutilizável, mesmo padrão de clientesFornecedores)
      infrastructure/
        gateways/
      presentation/
        mcp/
      contasCorrentes-register.ts
      index.ts
    fluxoCaixa/                     # módulo em camadas (cruza com contasCorrentes/)
      application/
        use-cases/                    # agrega lançamentos em fluxo de caixa por dia/mês/conta
        dto/
      infrastructure/
        gateways/
      presentation/
        mcp/
      fluxoCaixa-register.ts
      index.ts
    contasPagar/                    # módulo em camadas (resolve nome do fornecedor via clientesFornecedores)
      application/
        use-cases/
        dto/
      infrastructure/
        gateways/
      presentation/
        mcp/
      contasPagar-register.ts
      index.ts
    contasReceber/                  # módulo em camadas (resolve nome do cliente via clientesFornecedores)
      application/
        use-cases/
        dto/
      infrastructure/
        gateways/
      presentation/
        mcp/
      contasReceber-register.ts
      index.ts

当报告跨越两个领域时，分层模块可以依赖另一个模块的网关 （例如 produtos 使用 estoque 的 EstoqueOmieGateway 来计算每个产品的库存价值；ordemProducao 使用 produtos 的 ProdutosOmieGateway 来解析 OP 的描述）——这是模块之间的显式依赖， 不是对 Omie 访问代码的重复。

可用工具

完整技术参考（每个工具的名称、逐个参数、哪些是 破坏性的以及一般限制）：docs/FERRAMENTAS.md，通过 pnpm run doc-ferramentas 从代码自动生成。以下部分侧重于业务上下文 和每个模块的发现（“为什么”）；生成的文件侧重于“什么”（schema）。

Claude Code 技能（.claude/skills/omie-skill/）：相同的技术参考，但 按模块拆分为缓存（cache/*.md + cache/_index.md），以便 Claude 只查询 相关模块，而不是整个 FERRAMENTAS.md——使用 omie_* 工具时节省上下文令牌。缓存由命令生成（pnpm run skill-cache，或 聊天中的 /omie-skill:atualizar-cache），不是自动的；参见 .claude/skills/omie-skill/SKILL.md 了解详情，以及 .claude/commands/omie-skill/ 了解 终端命令（/omie-skill:guia、/omie-skill:atualizar-cache、/omie-skill:verificar-cache）。 还有一些命令实际调用 API 并返回已格式化的结果（不是原始 JSON） 用于某些模块：/omie-skill:estoque、/omie-skill:produtos、/omie-skill:op、 /omie-skill:estrutura、/omie-skill:pedidos。

通用过滤器（filtros）： 多个“增强”列表工具（已解析 客户/产品名称等）接受可选参数 filtros：条件列表 { campo, operador, valor } 应用于结果的任何字段，即使是 Omie 本身不过滤的字段（src/shared/filtro.ts）。运算符：igual、diferente、contem （忽略大小写/重音）、maior_que、menor_que、entre（valor: [min, max]）。支持 通过点路径的嵌套字段（例如 cliente.razaoSocial）。所有条件必须匹配 （AND）。补充而非替代每个端点的原生过滤器（系列、阶段、日期 等），当存在时这些过滤器仍然更可取——它们在 Omie 服务器上运行，无需 在过滤前分页所有内容。

生产订单（src/modules/ordemProducao/）

• omie_op_incluir / omie_op_alterar / omie_op_excluir / omie_op_consultar — use-case （前三个是破坏性的），对 IOrdemProducaoGateway 的 CRUD，可通过 OpFakeGateway 测试，无需接触真实 Omie。注意： 已实时验证（使用可丢弃的产品/投入品/结构的完整往返）产品只有在已有结构（BOM）时才接受 OP，并且 codigo_local_estoque 即使在简单包含中也是必填的（0 = 默认位置），尽管 Omie 公共文档将其标记为可选

• omie_op_listar — 直通，列出原始 OP（产品仅作为代码，阶段作为原始代码）

• omie_op_listar_com_produto — use-case：列出已解析产品描述/SKU 的 OP（重用 produtos 模块的 ProdutosOmieGateway）以及 concluida 字段（true/false，可靠）以及原始 etapaCodigo

OP 的阶段（cEtapa）是 按账户可配置的 kanban 代码（3 到 6 个阶段， 名称由用户自己在 Omie 中定义），API 没有端点将代码翻译 为阶段名称——因此工具不尝试解释它，只暴露 concluida 字段（从 cConcluida 派生，该字段可靠）和原始代码，供已经知道 自己账户阶段含义的人使用。

产品（src/modules/produtos/）

• omie_produtos_consultar — 直通，特定产品的注册信息

• omie_produtos_listar — 直通，列出产品（quantidade_estoque 字段 不可靠， 始终为 0）。接受 filtrar_apenas_familia（系列代码，通过测试 WSDL 发现——未在帮助页面中记录）以限制为产品系列。还接受 filtrar_apenas_descricao（"%texto%" = 包含，"texto%" = 以...开头，等）以按名称搜索，无需分页所有内容

• omie_produtos_incluir / omie_produtos_alterar / omie_produtos_excluir — use-case （破坏性的），遵循与模块其他方法相同的网关+接口+假实现+测试模式 （IProdutosGateway.incluirProduto/alterarProduto/excluirProduto）——可通过 ProdutosFakeGateway 测试，无需接触真实 Omie。注意： 已实时验证（创建→更改→删除的往返）codigo（SKU）在 IncluirProduto 中是必填的，即使 Omie 公共文档将其标记为可选

• omie_familias_listar — 直通，产品系列

• omie_produtos_listar_com_estoque — use-case：列出产品，已计算库存数量和 价值（销售和平均成本），将产品注册信息与所有位置的库存位置交叉（重用 estoque 模块的 EstoqueOmieGateway）。还 接受 filtrar_apenas_familia — 按系列过滤，并在一次调用中已包含计算的库存

产品结构（src/modules/estrutura/）

• omie_estrutura_listar — 用例：列出已登记结构（BOM/技术清单）的产品，已包含产品名称和每个投入品的名称（Omie 在 ListarEstruturas 中直接返回这些数据，资源为 geral/malha — 无需与产品登记交叉比对）

• omie_estrutura_buscar_por_produto — 用例：通过名称/描述（或其片段）或代码查找产品的结构，无需事先知道 Omie 内部代码 — 例如：“100kg 产品的结构是什么”。分页遍历整个 ListarEstruturas 并在客户端过滤（Omie 在该端点不提供文本搜索）

• omie_estrutura_incluir / omie_estrutura_alterar / omie_estrutura_excluir — 用例（破坏性操作），结构项目的 CRUD（IEstruturaGateway.incluirItensEstrutura/alterarItensEstrutura/excluirItemEstrutura），可通过 EstruturaFakeGateway 测试，无需接触真实 Omie。注意： 已在线验证（在可丢弃的测试产品上执行 include→alter→excluir 往返测试），父产品必须是 '03 - 在制品' 或 '04 - 成品' 类型，intMalha 在 IncluirEstrutura 中是必填项（公开文档标记为可选），且 AlterarEstrutura/ExcluirEstrutura 要求 idProdMalha 与 idMalha 一起提供

库存（src/modules/estoque/）

• omie_estoque_ajuste_incluir / omie_estoque_ajuste_excluir — 用例（破坏性操作），基于 IEstoqueGateway.incluirAjuste/excluirAjuste 的调整 CRUD，可通过 EstoqueFakeGateway 测试，无需接触真实 Omie。注意，重要的在线发现： motivo 字段只接受 'INI'/'INV'/'OPE'/'PDV'（公开文档中未记录，只在 Omie 的验证错误中出现）；并且在对某个产品执行任何库存调整后，该产品永远不能再被删除 — Omie 会保留一个永久关联到它的“库存变动（已计算）”，即使之后删除了调整本身。

• omie_estoque_movimentos_listar — 透传，按期间列出变动

• omie_estoque_total_produto — 用例：汇总某个产品在所有库存地点的物理库存，因为 Omie 只按地点暴露库存位置

omie_estoque_consultar（ConsultarEstoque）已被移除：我们测试后发现该方法在当前 Omie API 中不存在（返回 Method "ConsultarEstoque" not exists）。

销售订单（src/modules/pedidoVenda/）

• omie_pedido_venda_consultar / omie_pedido_venda_incluir / omie_pedido_venda_alterar / omie_pedido_venda_excluir — 用例（后三个为破坏性操作），基于 IPedidoVendaGateway 的 CRUD，可通过 PedidoVendaFakeGateway 测试，无需接触真实 Omie。注意： 已在线验证（使用可丢弃的客户/产品完成完整往返测试），客户登记中必须填写 UF（否则 Omie 拒绝订单），且即使简单订单中 codigo_categoria/codigo_conta_corrente 也是必填项

• omie_pedido_venda_listar — 透传，列出订单（接受 Omie 原生的 etapa 过滤器）

• omie_pedido_venda_etapas_listar — 透传，开票阶段目录（销售/服务单/采购看板），包含代码和描述 — 与 OP 阶段不同，这里是固定的且有文档记录

• omie_pedido_venda_produtos_para_separar — 用例：列出需要从库存中拣货发货的产品（处于“拣货库存”阶段、默认代码为 20 的订单），已移除已取消的订单，并返回按产品聚合的摘要（总数量、出现在多少个订单中）

• omie_pedido_venda_listar_com_cliente — 用例：列出已包含客户名称的订单（复用 clientesFornecedores 模块中的 ClientesOmieGateway）、完整阶段名称以及已解析的订单项目（产品/SKU/描述/数量/单位），cancelado/faturado 作为布尔值，以及订单总金额。可选的 etapa_codigo 过滤器（不提供时返回所有阶段 — 默认不过滤已取消的，与上面的工具不同）

• omie_pedido_venda_separar_estoque_listar — 用例：日常最常查看的报表快捷方式 — 与 omie_pedido_venda_listar_com_cliente 格式相同，但 etapa_codigo 固定为“拣货库存”，且默认移除已取消的（incluir_cancelados 参数可查看已取消的）。内部复用 ListarPedidosComClienteUseCase。

测试中的重要发现：已取消的订单的 etapa 不会被 Omie 重置 — 如果订单在该阶段被取消，它仍会显示为处于“拣货库存”状态。因此 omie_pedido_venda_produtos_para_separar 在将订单视为真正待处理之前，始终与 infoCadastro.cancelado 交叉比对；而 omie_pedido_venda_listar_com_cliente 是通用列表，暴露 cancelado 供调用方自行决定如何处理。

客户与供应商（src/modules/clientesFornecedores/）

在 Omie 中，客户和供应商是同一个登记（geral/clientes），仅通过 tag 区分（Cliente、Fornecedor、Colaborador、Sócios，可以有多个）— 不存在单独的 geral/fornecedores 端点。

• omie_clientes_consultar — 透传，查询特定客户/供应商（公司名称、商号、CNPJ/CPF、联系人、地址、标签）

• omie_clientes_listar — 透传，列出客户/供应商；通过 clientesFiltro 接受高级过滤（例如：{"tags": [{"tag": "Fornecedor"}]}）

• omie_fornecedores_listar — 轻量用例：omie_clientes_listar 的快捷方式，已按 Fornecedor 标签过滤，支持按公司名称/商号/CNPJ-CPF 搜索以及 apenas_ativos（在客户端移除非活跃项，因为 clientesFiltro.tags 过滤器无法在同一次调用中直接与状态过滤器组合）

• omie_clientes_incluir / omie_clientes_alterar / omie_clientes_excluir — 用例（破坏性操作），基于 IClientesGateway.incluirCliente/alterarCliente/excluirCliente 的 CRUD，可通过 ClientesFakeGateway 测试，无需接触真实 Omie。注意： 已在线验证（创建→修改→删除往返测试），codigo_cliente_integracao 在 IncluirCliente 中是必填项，即使 Omie 公开文档标记为可选

当前范围：仅读取（查询/列表）。 根据用户要求，客户/供应商的完整 CRUD（新增、修改、删除）留待以后 — 只有在 MCP 具备最低安全性之后（参见速率限制/安全部分和 src/httpServer.ts）。

往来账户（src/modules/contasCorrentes/）

• omie_contas_correntes_listar — 透传，列出往来账户（银行、现金、信用卡、收单机），包含代码、描述、银行、类型和登记的初始余额

• omie_extrato_conta_corrente_consultar — 用例：某个期间内往来账户的对账单（变动包含日期/描述/金额/类别/对账状态，以及期初/期末/已对账/可用余额）。Omie 方法：ListarExtrato（资源 financas/extrato），可通过 ContasCorrentesFakeGateway 测试，无需接触真实 Omie。支持对变动使用通用参数 filtros（例如：性质、类别）。已针对真实账户在线验证。

现金流量（src/modules/fluxoCaixa/）

• omie_fluxo_caixa_gerar — 用例：以表格格式构建现金流量（流入、流出、期间余额和累计余额），按天或按月以及按往来账户分组。Omie 没有现成的此报表 — 只有 financas/mf ListarMovimentos，逐笔列出应付/应收款项，每页 100 条 — 因此此工具获取期间内的所有分录，将已实现（已支付/已收到，按支付日期）与预计（未结清、尚未清算，按到期日，排除已取消的）分开，并汇总所有数据，解析往来账户名称（复用 contasCorrentes 模块中的 ContasCorrentesOmieGateway）。格式设计为将来可直接导出为电子表格。默认情况下（apenas_favoritas: true）限制为用户定义的收藏账户（src/modules/fluxoCaixa/application/contas-favoritas.ts：NuBank 卡、Stone、巴西银行、Wix、iFood、Sicoob、Itaú、Elo LEANDRO 卡、Amazon、CAIXA LOJA — 其余约 39 个在 Omie 中登记的账户，例如旧卡和特定收单机构，被排除在外）；使用 apenas_favoritas: false 查看所有账户，或使用 codigos_conta_corrente 指定自定义列表。

真实余额（可选，usar_saldo_real: true）：默认情况下，累计余额只是查询期间内的净变动，而非真实银行余额 — Omie 不通过 API 暴露每个账户的每日余额历史。使用 usar_saldo_real: true 时，工具将计算锚定在每个往来账户中登记的 saldo_inicial/saldo_data 上（通过 omie_contas_correntes_listar）：将 saldo_data 与所请求期间开始之间的已实现分录相加，得出接近真实银行余额的 saldoRealAcumulado — 这不是 MCP 中硬编码的值，而是从 Omie 登记中读取的，因此当有人在其中配置每个账户的真实余额时（例如：在 01/01），计算会自动反映这一点，无需修改代码。未配置 saldo_data/saldo_inicial 的账户（或 saldo_data 晚于期间开始的账户）会收到 saldoRealAcumulado: null，而不是编造的数字。查找此偏移量会触发一次额外调用（各账户中最旧的 saldo_data 与期间开始之间的变动）— 如果 saldo_data 过于久远，可能会很慢。

测试中的重要发现：Omie 拒绝同一方法的两个并发调用（错误“Já existe uma requisição desse método sendo executada”），即使参数不同 — 因此已实现/预计的遍历（两者都使用 ListarMovimentos）在用例内按顺序运行，而非并行。这是对下面部分已记录的速率限制的额外限制，专门针对同一 call 的并发调用。

长期间会产生大量页面（例如：仅约 3 周的收款就已超过 3,700 条记录）— 建议每次调用最多约 3 个月的期间。

应付账款（src/modules/contasPagar/）

• omie_contas_pagar_listar — 用例：列出 financas/contapagar（ListarContasPagar）的分录，已包含解析后的供应商名称（复用 clientesFornecedores 模块中的 ClientesOmieGateway — Omie 只返回代码）、金额、到期日、状态（PAGO/ABERTO/VENCIDO）、税务单据、类别和备注。分页，可选过滤器 data_alteracao_de/data_alteracao_ate。

应收账款（src/modules/contasReceber/）

• omie_contas_receber_listar — 用例：列出 financas/contareceber 的流水（ListarContasReceber），已包含解析后的客户名称（复用 clientesFornecedores 模块的 ClientesOmieGateway）、金额、到期日、状态（PAGO/ABERTO/VENCIDO）、税务单据、订单号和类别。分页，支持可选的 data_alteracao_de/data_alteracao_ate 过滤器。

• omie_contas_receber_boleto_gerar / omie_contas_receber_boleto_obter / omie_contas_receber_boleto_prorrogar / omie_contas_receber_boleto_cancelar — 用例 （生成/展期/取消为破坏性操作），对应收账款票据进行 boleto 的增删改查（financas/contareceberboleto：GerarBoleto/ObterBoleto/ProrrogarBoleto/CancelarBoleto）， 可通过 ContasReceberFakeGateway 测试，无需接触真实的 Omie。注意： 经实时测试，此 Omie 账户未配置银行协议/boleto——ProrrogarBoleto 返回 “Não temos suporte para geração da remessa de pagamento para o banco -sem instituição-”；GerarBoleto 很可能因同样原因失败（未实时测试，以免为生产客户的票据生成真实的 boleto）。ObterBoleto/CancelarBoleto 已实时验证（安全返回“nenhum boleto gerado”，无副作用）。

测试中的重要发现：Omie 在这两个端点上的日期过滤参数（filtrar_por_data_de/filtrar_por_data_ate）按流水的最后修改日期（info.dAlt）过滤，而非到期日——通过请求 1 天的时间范围并与返回记录中的 data_vencimento 对比确认（到期日不同，而 dAlt 始终在请求范围内）。因此 MCP 工具将参数命名为 data_alteracao_de/data_alteracao_ate（而非 data_vencimento_de/ate），以免暗示 API 并不具备的行为。这两个端点没有（经测试）按到期日过滤的原生方式——如需此功能，请使用 omie_fluxo_caixa_gerar，它使用 financas/mf 并按到期/付款正确过滤。

与 omie_fluxo_caixa_gerar 的区别：这两个工具暴露原始流水（按流水区分供应商/客户，无聚合），适合逐笔核对；而现金流按期间/活期账户聚合所有内容。

现金预算（src/modules/orcamentoCaixa/）

• omie_orcamento_caixa_consultar — 用例：Omie 原生的现金预算（预算与实际对比），按财务类别、月份/年份。Omie 方法：ListarOrcamentos（资源 financas/caixa），可通过 OrcamentoCaixaFakeGateway 测试，无需接触真实的 Omie。与 omie_fluxo_caixa_gerar（根据应付/应收手动计算，按活期账户/天分组）不同，这是 Omie 自带的现成报告，按类别分组（例如：“1.01.01 Vendas”）。支持通用参数 filtros。已针对真实账户实时验证。

PIX（src/modules/pix/）

• omie_pix_listar / omie_pix_obter / omie_pix_obter_status / omie_pix_gerar / omie_pix_cancelar — 用例（生成/取消为破坏性操作），对应收账款票据进行 PIX 的增删改查（financas/pix：ListarPix/ObterPix/ObterStatusPix/GerarPix/CancelarPix），可通过 PixFakeGateway 测试，无需接触真实的 Omie。与 Boleto 不同，此 Omie 账户已配置并激活 PIX（测试库中有 379 条真实记录）——Listar/Obter/ObterStatus 已针对真实账户实时验证。出于谨慎，Gerar/Cancelar 未对生产票据进行实时测试（会实际生成/取消 PIX 收款，且无法保证安全往返——与 Boleto 相同的考虑）。

发票 / NF-e（src/modules/nfe/）

• omie_nfe_listar / omie_nfe_consultar — 用例：通过 produtos/nfconsultar（ListarNF/ConsultarNF）查询已在 Omie 中开具/登记的发票（NF-e），可通过 NfeFakeGateway 测试，无需接触真实的 Omie。列表返回摘要（编号、系列、密钥、客户、金额、是否取消）；查询返回详细信息（项目、发票生成的金融票据）。该模块特意设为只读：不签发也不取消 NF-e。查阅官方文档未找到与 IncluirPedidoVenda 等价的“从零签发 NF-e”端点（如 IncluirNFe(itens, cliente)）——API 主要将 NF-e 视为对 ERP 税务引擎已处理文档的查询/导入，且已签发的发票是具有法律效力的文件（不像其他模块那样可以“删除且不留痕迹”）。已针对真实账户实时验证（测试库中有 4765 张发票）。

入库单（src/modules/notaEntrada/）

• omie_nota_entrada_listar / omie_nota_entrada_consultar — 用例：通过 ListarNotaEnt/ConsultarNotaEnt（资源 produtos/notaentrada）查询已登记的入库单（采购货物的物理收货），可通过 NotaEntradaFakeGateway 测试。只读——与产品 NF-e 和 NFS-e 模块相同的谨慎态度：这是“请购 → 采购订单 → NF-e 收货 → 入库单”流程的最后阶段，是最终的税务/财务记录（实际影响库存和财务），没有安全的测试往返。供应商 NF-e 的收货（produtos/recebimentonfe）以及发票本身的计费（produtos/notaentradafat）因同样原因不在范围内。已针对真实账户实时验证（存在 3 张入库单）。

产品特性（src/modules/caracteristicasProduto/）

• omie_caracteristica_incluir / omie_caracteristica_alterar / omie_caracteristica_excluir / omie_caracteristica_consultar / omie_caracteristica_listar — 用例（前 3 个为破坏性操作），通过 geral/caracteristicas 对可复用的产品特性（例如：“颜色”、“尺寸”）进行增删改查，可通过 CaracteristicaFakeGateway 测试。与类别不同，经实时测试，完整的增删改查可无保留地工作（完整往返，无痕迹）。

类别与部门（src/modules/categoriasDepartamentos/）

• omie_categoria_incluir / omie_categoria_alterar / omie_categoria_consultar / omie_categoria_listar — 用例（前 2 个为破坏性操作），财务类别的增删改查（geral/categorias），可通过 CategoriaFakeGateway 测试。注意，重要的实时发现： (1) IncluirCategoria 不接收新类别的代码——它接收 categoria_superior（父组代码），Omie 自动生成子代码（例如：父级 2.09 生成子级 2.09.04）；(2) API 中不存在类别删除，使用 conta_inativa: 'S' 测试 AlterarCategoria 没有实际效果（之后再次查询确认）——通过 API 创建的类别将永久保留在账户中，无法删除或停用。这在此账户中留下了一个残留的测试类别（2.09.04，“Categoria Teste MCP Alterada”）——无害，但在此记录，以免日后造成困惑（与 estoque 模块中残留测试产品相同的模式）。

• omie_departamento_incluir / omie_departamento_alterar / omie_departamento_excluir / omie_departamento_consultar / omie_departamento_listar — 用例（前 3 个为破坏性操作），部门/成本中心的增删改查（geral/departamentos），可通过 DepartamentoFakeGateway 测试。注意，实时发现：IncluirDepartamento 中的 codigo 是父部门的代码（要包含在哪个部门下），而不是新部门的——Omie 在响应中生成并返回子部门的代码（与类别相同的模式）。与类别不同，ExcluirDepartamento 确实有效——已通过完整往返实时验证，无痕迹。

辅助注册表（src/modules/cadastrosAuxiliares/）

• omie_bancos_listar / omie_cidades_listar / omie_paises_listar / omie_ncm_listar / omie_unidade_consultar — 用例，由 Omie 维护的静态参考表（Bacen、IBGE、Receita Federal）：银行（geral/bancos）、城市（geral/cidades）、国家（geral/paises）、NCM（produtos/ncm）和计量单位（geral/unidade）。全部只读，可通过 CadastrosAuxiliaresFakeGateway 测试。支持原生过滤（名称、州、代码等）和通用参数 filtros。注意，实时发现：omie_unidade_consultar 需要精确代码（不进行分页/列出所有，与其他不同）——这是点查，不是列表。已针对真实账户实时验证。

CRM（src/modules/crm/）

• omie_crm_conta_incluir / omie_crm_conta_alterar / omie_crm_conta_excluir / omie_crm_conta_consultar / omie_crm_conta_listar — 用例（前 3 个为破坏性操作），CRM 账户的增删改查（crm/contas——B2B 销售漏斗，不同于客户/供应商注册表），可通过 ContaFakeGateway 测试，无需接触真实的 Omie。注意，实时发现：IncluirConta/AlterarConta 要求 endereco 和 telefone_email 块完整存在（即使只填写少量字段）——如果块完全缺失，Omie 会拒绝并提示“Tag [endereco]/[telefone_email] não informada!”。

• omie_crm_contato_incluir / omie_crm_contato_alterar / omie_crm_contato_excluir / omie_crm_contato_consultar / omie_crm_contato_listar — 用例（前 3 个为破坏性操作），CRM 联系人的增删改查（crm/contatos），始终关联到一个账户。

• omie_crm_oportunidade_incluir / omie_crm_oportunidade_alterar / omie_crm_oportunidade_excluir / omie_crm_oportunidade_consultar / omie_crm_oportunidade_listar — 用例（前 3 个为破坏性操作），漏斗机会的增删改查（crm/oportunidades）。注意，实时发现：除了账户和联系人外，还需要 codigo_solucao 和 codigo_origem——这些辅助注册表必须事先存在（Omie 自带“Solução 01”/“Solução 02”和默认来源，如“Ativo”）。

• omie_crm_fases_listar / omie_crm_solucoes_listar / omie_crm_origens_listar — 用例 （读取），CRM 辅助注册表（crm/fases、crm/solucoes、crm/origens）——后两者是创建机会的先决条件。

• 已通过完整、安全的往返实时验证（测试账户、联系人和机会，创建并删除，无痕迹）。

本周期范围之外（未要求，优先级低）：任务（crm/tarefas）和账户特性（crm/contascaract）——仅在用户需要时实现。

服务 / 服务订单 / NFS-e（src/modules/servicos/）

• omie_servico_incluir / omie_servico_alterar / omie_servico_excluir / omie_servico_consultar / omie_servico_listar — 用例（前三个为破坏性操作），已提供服务（servicos/servico）的CRUD， 可通过 ServicoFakeGateway 测试，无需接触真实 Omie。 注意，现场发现：AlterarCadastroServico 要求标识符嵌套在 intEditar 中（而不是像看起来自然的 cabecalho）——公开文档并未明确说明这一点。

• omie_os_incluir / omie_os_alterar / omie_os_excluir / omie_os_consultar / omie_os_listar — 用例（前三个为破坏性操作），服务订单（servicos/os）的CRUD，可通过 OrdemServicoFakeGateway 测试，无需接触真实 Omie。注意，重要的现场发现： (1) 每个项目要求 codigo_servico_municipal/codigo_servico_lc116 作为已在 LC116 表中 注册的代码（参见 omie_servicos_lc116_listar），而非自由文本——否则 Omie 会以 "Código da LC116 não cadastrada" 拒绝；(2) 每个项目中的 cRetemISS 为必填项，即使 公开文档中未标记为必填；(3) 表头中的客户必须填写 UF （与销售订单中已见的要求相同）。已通过完整且安全的往返测试现场验证 （可丢弃的测试客户，创建和删除均不留痕迹）。

• omie_nfse_listar — 用例：列出已开具的 NFS-e（servicos/nfse，ListarNFSEs）， 可通过 NfseFakeGateway 测试。仅只读 — 与产品 NF-e 模块相同的谨慎态度 （具有法律效力的税务文件，无安全的开具往返测试）。

• omie_servicos_lc116_listar — 用例：列出第 116 号补充法（服务分类）的 255 个有效代码， 用于在创建 OS 之前发现正确的代码。Omie 方法：ListarLC116（资源 servicos/lc116）。

超出本周期范围（未要求，低优先级）：周期性服务合同 （servicos/contrato）以及 OS/合同的批量开票（servicos/osp、servicos/oslote、 servicos/contratofat、servicos/contratolote）——仅在用户需要时实现。

采购（src/modules/compras/）

• omie_pedido_compra_incluir / omie_pedido_compra_alterar / omie_pedido_compra_excluir / omie_pedido_compra_consultar / omie_pedido_compra_listar — 用例（前三个为 破坏性操作），基于 IPedidoCompraGateway（produtos/pedidocompra）的完整CRUD，可通过 PedidoCompraFakeGateway 测试，无需接触真实 Omie。注意，重要的现场发现： (1) nCodCC（作为 codigo_conta_corrente 传递）要求一个往来账户（geral/contacorrente）的代码， 而非部门/成本中心的代码，尽管名称如此——如果使用部门代码，Omie 会以 "Conta Corrente não cadastrada" 拒绝；(2) PesquisarPedCompra（列表） 默认隐藏所有订单——必须显式请求每种状态 （lExibirPedidosPendentes/Faturados/Recebidos/Cancelados/Encerrados/RecParciais/ FatParciais，全部为 'S'），网关始终如此处理；(3) 当页面没有 记录时，Omie 返回错误（SOAP-ENV:Client-5113）而非空列表——已在 网关中规范化为返回空列表。

• omie_requisicao_compra_incluir / omie_requisicao_compra_alterar / omie_requisicao_compra_excluir / omie_requisicao_compra_consultar / omie_requisicao_compra_listar — 用例（前三个为破坏性操作），基于 IRequisicaoCompraGateway（produtos/requisicaocompra）的完整CRUD，可通过 RequisicaoCompraFakeGateway 测试，无需接触真实 Omie。注意，重要的现场发现： 与 Omie 的其他端点不同，IncluirReq/AlterarReq 的字段直接放在 param 的根级别——不存在公开文档所暗示的 requisicaoCadastro: {...} 包装器（ Omie 会以 "Tag [REQUISICAOCADASTRO] não faz parte da estrutura" 拒绝）。

通用（覆盖所有其他模块）

• omie_chamar_api — 接收 resource（模块路径）、call（方法）和 param（参数），允许访问 https://developer.omie.com.br/service-list/ 中列出的任何端点（客户、财务、CRM、销售、NF-e、服务等）

Omie 速率限制 — MCP 如何自我保护

Omie 通过两种方式阻止突发调用："不当消耗"（即速率 限制本身）和**"冗余消耗"（快速连续中非常相似的调用——在并行查询约 20 个客户 以生成订单报告时实际发生过）。保护是集中在 OmieClient**（src/omieClient.ts）中的，因此每个模块都会自动受益， 无需重新实现任何内容：

• 节流 — 每次调用都遵守自同一 OmieClient 实例上次调用以来的最小间隔（300ms）， 即使多个调用同时到达（Promise.all、mapWithConcurrency 等）。这降低了 在需要重试之前就落入"冗余消耗"的可能性。

• 带正确等待的重试 — 如果 Omie 仍然阻止，OmieClient 会再次尝试（最多 4 次），遵守 Omie 在错误消息中建议的时间 （例如："Aguarde 57 segundos"），而不是固定的短退避。

• mapWithConcurrency（src/shared/concurrency.ts）— 由按代码批量获取 多条记录的网关使用（ProdutosOmieGateway.consultarProdutosPorCodigo、 ClientesOmieGateway.consultarClientesPorCodigo），将自身代码的并发限制为 5 个同时调用，补充客户端的节流。

新模块规则：

1. 切勿在代码数组上调用 Promise.all/Promise.allSettled 而不限制 并发——始终使用 mapWithConcurrency。

2. 切勿并行运行同一方法（call）的两次调用，即使参数不同—— Omie 会以"Já existe uma requisição desse método sendo executada"拒绝 （在构建 fluxoCaixa 时发现，该功能需要对 ListarMovimentos 进行两次遍历）。按顺序运行（先 await 一个，再另一个）。

3. 不同方法的并行调用（例如：同时获取产品和库存）是安全的，不需要这些措施，客户端的节流已覆盖。

添加新模块

直通（Omie 已返回现成数据）：

1. 创建 src/tools/<modulo>.ts，导出一个 ToolDef 数组（使用 src/tools/types.ts 中的 defineTool()）。

2. 在 src/tools/registry.ts 中导入并将该数组连接到 allTools。

分层（需要聚合/组合 Omie 调用 — 以 src/modules/estoque/ 为参考复制）：

1. application/use-cases/ — 业务规则（接收网关，返回已准备好给用户的结果）。

2. application/dto/ — 输入 param 的 zod schema 和结果类型。

3. infrastructure/gateways/ — 仅 Omie 调用（resource/call），无业务规则。

4. presentation/mcp/ — 带有 execute 的 ToolDef，实例化网关 + 用例。

5. <modulo>-register.ts + index.ts — tools 数组的 barrel 导出。

6. 在 src/tools/registry.ts 中将该数组导入 allTools。

在两种情况下，src/index.ts 都会自动注册该工具 — 那里无需更改。

后续步骤（路线图）

• 根据需要添加财务、销售/NF-e 和 CRM 的专用模块（相同的文件模式）。

• 为大型列表添加自动缓存/分页。

• 添加使用 Omie API 模拟的自动化测试。

安全

切勿提交 .env 文件，也不要在公共仓库中暴露 OMIE_APP_KEY/OMIE_APP_SECRET。