omie-mcp

Omie のAPIとClaudeを統合するためのMCP（Model Context Protocol）サーバーです。

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という2つ目のトランスポートがあります。これは同じツール（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キーはこの段階（ローカル、シングルユーザー）の最小限の保護です — 将来これを外部に公開する場合、それだけでは不十分です。

追加の保護レイヤーが2つあります：

• レート制限 — 1分間に最大120リクエスト（固定ウィンドウ）。これを超えると429を返します。

• 破壊的操作の確認 — Omieのデータを含める・変更する・削除するツール（omie_op_incluir/alterar/excluir、omie_estoque_ajuste_incluir、omie_requisicao_compra_incluir、omie_pedido_compra_incluir、およびcallがIncluir/Alterar/Excluir/Cancelar/Deletarで始まるomie_chamar_api経由の呼び出し）は、ペイロードに"confirmar": trueが必要です。そうでないと400を返します — 偶発的な破壊的呼び出し（バグのあるスクリプト、ループなど）を防ぎます。

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）を渡すと、各ツールのペイロードのJSON Schemaも一緒に返します。

• GET /tools/<nome>/schema — 特定の1つのツールのペイロードのJSON Schema（フィールド、型、必須項目、各項目の説明）— フロントエンドが推測せずに正しいフォーム/ペイロードを構築するのに役立ちます。

• GET /tools/<nome>?campo=valor&outroCampo=valor — URLから直接ツールを呼び出します（Postman/curlなしでブラウザでテスト可能）。クエリ文字列の各値は可能な場合はJSONとして解釈され（true、123、"texto"）、それ以外は文字列のままです。

• POST /tools/<nome> — ツールを呼び出します。リクエストボディ（JSON）がツールのペイロードです。大きな/ネストしたペイロード（例：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に変換することについて既に述べたセキュリティ上の注意と同じです（セキュリティのセクションを参照）。意図は：今はローカルで開発に使用し、最小限のセキュリティ（認証、入力検証）を実装した後にのみ、実際に公開されたサービスに移行することです。

アーキテクチャ

ニーズに応じて選択される2つのモジュール形式があります：

• パススルー（フラット） — src/tools/<modulo>.ts、Omieのresource+callに1:1でマッピングするToolDefの配列で、独自のロジックはありません。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

レイヤードモジュールは、レポートが2つのドメインにまたがる場合に別のモジュールのゲートウェイに依存できます（例：produtosはestoqueのEstoqueOmieGatewayを使用して製品ごとの在庫金額を計算します。ordemProducaoはprodutosのProdutosOmieGatewayを使用してOPの説明を解決します）— これはモジュール間の明示的な依存関係であり、Omieへのアクセスコードの重複ではありません。

利用可能なツール

完全な技術リファレンス（各ツールの名前、パラメータの詳細、破壊的なもの、一般的な制限）：docs/FERRAMENTAS.md。pnpm run doc-ferramentasでコードから自動生成されます。以下のセクションはビジネスコンテキストと各モジュールの発見事項（「なぜ」）に焦点を当てています。生成されたものは「何を」（スキーマ）に焦点を当てています。

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（最初の3つは破壊的）、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を再利用）し、生のetapaCodigoに加えてconcluidaフィールド（true/false、信頼できる）も含みます

OPのステージ（cEtapa）はアカウントごとに設定可能なかんばんコードです（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も受け入れます — ファミリーでフィルタリングし、1回の呼び出しで計算済みの在庫が付いてきます

製品構成（src/modules/estrutura/）

• omie_estrutura_listar — ユースケース: 構造（BOM／部品表）が登録されている製品を、製品名と各投入材料名付きで一覧表示します（Omie は ListerEstruturas リソース geral/malha で既にこの内容を返すので、製品マスタと突き合わせる必要はありません）。

• omie_estrutura_buscar_por_produto — ユースケース: 製品の構造を、名前・説明（またはその一部）やコードで検索します。Omie の内部コードを事前に知る必要はありません。例：「製品100kgの構造は？」。ListerEstruturas を全ページ取得し、クライアント側でフィルタリングします（このエンドポイントには Omie のテキスト検索はありません）。

• omie_estrutura_incluir / omI estrutura_alterar / omI estrutura**　—**ユースケース**（破壊的）、構造項目に対する CRUD（IEstruturaGateway.incluirItensEstrutura/alterarItensEstrutura/excluirItemEstrutura）。EstruturaFakeGatewayを使用して、実際の Omie に触れずにテストできます。**注意:** ライブ検証（使い捨てテスト製品での 追加→変更→**削除 ラウンドトリップ）により、親製品は'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_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 — ユースケース（後の3つは破壊的）、IPedidoVendaGateway に対する CRUD。PedidoVendaFakeGateway で実際の Omie に触れずにテストできます。： ライブ検証（使い捨ての顧客と製品で完全往復）により、顧客マスタには必ず UF（都道府県）が設定されている必要があり（無い場合は Omie が注文を拒否）、また codigo_categoria／codigo_conta_corrente は単純な注文でも必須です。

• omie_pedido_venda_listar — パススルー。注文一覧（Omie 標準の etapa フィルタ対応）。

• ymie_pedido_venda_etapas_listar — パススルー。販売ステータス（売上・OS・購買のカンバン）の請求ステージのカタログをコードおよび説明付きで件数表示します。OS のステージとは異なり、こちらは固定され文脈に記載されています。 *' omie_pedido_venda_produtos_para_separar — ユースケース: 出荷のために在庫から仕分けが必要な製品を件数（ステージ「Separar Estoque」の注文で、デフォルトコードは 20 件）。キャンセル済みを除外し、住所ごとに多い合計（合計数量が件数）を返します。

• omie_pedido_venda_listar_com_cliente — ユースケース: 顧客名（modules/clientesFornecedores の ClientesOmieGateway を再利用）、ステージの開始説明、および注文明細（商品・SKU・説明・数量・単位）を解決した注文一覧を返し、cancelado／faturado は真偽値にし、注文合計金額も返します。省略可能なフィルタ（etapa_codigo）を修得します。省略すると、すべてのステージを返し、デフォルトではキャル無し（上記スクールとは異なります）。

• omie_pedido_venda_separar_estoque_listar — ユーースケース: 日常で最も利用されるレポートへのショートカット — 書式は omie_pedido_venda_listar_com_cliente と同じですが、etapa_codigo を「Separar Estoque」に固定し、キャルルされ**デフォルトで※除外します（incluir_cancelados パラメータを使うと、キャンセルも含みます）。内部的には PedidosComClienteUseCase を再利用します。

検証からの重要な発見: Omie はキャンセルされた注文の etapa をリセットしません。キャンセルされた注文は、その段階でキャンセルされていても、あたかも「Separar Estoque」にあるかのうことを一覧できるのは、そのためです。#実際に入前のとみなしません一方、omie_pedido_venda_listar_com_cliente は一般的な一覧であり、扱いを decide/呼出し元に委ねるため cancelado を公開しています。

顧客・仕入先（src/modules/clientesFornecedores/）

Omie では、顧客と仕入先は同じ登録データ（geral/clientes）であり、単に tag（Cliente、Fornecedor、Colaborador、Sócios。複数持てます）で区別されます。独立した geral/fornecedres は存在しません。

• omie_clientes_consultar — パススルー、特定の顧客・仕入先を取得（正式名称、代表標不同、CNPJ/CPF、連絡先、住所、タグ）。

• omie_clientes_listar — パススルー、顧客・仕入先を一覧表示。clientesFiltro （例: {"tags": [{"tag": "Fornecedor"}]}）による高度なフィルタをサポート。

• omie_fornecedores_listar — 軽量ユースケース: Fornecedor タグで事前に絞り込んだ 、Mie_clientes_listar のショートカット。正式名称・商号仮称・CNPJ-CPF で検索でき、apenas_ativos 付きで（非アクティブをクライアント側で除外します。Py_clientes のタグフィルタは、同じ呼び出し内で状態フィルタと直接組み合わせできないためです）。

• omie_clientes_incluir / omie_clientes_alterar / omie_clientes_excluir — ユースケース（破壊的）、IClientesGateway.incluir/Cliente/alterCliente/excluirCliente に対する CRUD。ClientesFakeGateway で実際の Omie に触れずにテストできます。**: ** ライブ検証（作成→変更→削除のラウンドトリップ）では、codigo_cliente_integracao が IncluirCliente で必須であることが若干確認されています。公開元ドキュメントは任意としています。

現在のスコープ: 読み取り専用（照会・一覧）。ユーザーのリクエストにより、顧客・仕入先の完全なCRUD（作成・変更・削除）やは後対応。Mee に最小限の安全対策が導入された段階（次のレート制限／セキュリティのスタンションと src/httpServer.ts ）で実施します。

当座口座（src/modules/contasCorrentes/）

• ome_contas_correntes_listar — パススルー。当座口座（銀行、現金、カード、決済端末）でコード、説明、銀行、タイプ、初期残高を対応一覧を表示します。

• omio_extrato_conta_corrente_consultar — ユースケース: 指定した期間内の当座口座取引明細（日付・説明・金額・カテゴリ・消込状況、開始残高・終了残高・入金済・利用可能残高）。Omie メソッド: ListarExtrato（リソース financas/extrato）。 ContasCorrentesFakeGateway で実際の Omie に触れずにテスト可能。また、取引では汎用的な filtros パラメータ（例：ネinchiェフ, カテゴリ）をサポートします。実口座へのライブ検証済み。

キャッシュフロー（src/modules/fluxoCaixa/）

• omIX_fluxo_caixa_gerar — ユースケース: 収入、支出、期間損益、累計損益を表形式で作成します。日または月ごと、またキャッシュ口座別にグループ化されます。Omie にこのレポートは予め含まれておらず、financas/mf の ListarMovimentos は、長払い※の振替を、1件ずつ100件/ページで提供するのみです。したがって、このツールは、指定期間内の全仕訳を取得し、実行を済済（支払日／受領日で実行され、’受領し）と 予定（未処理・未収、針済み、予定最終日（カレシッジ粉））へ、取消済みを除外して集計し、当座口座名を解決します（src/modules/contasCorrentes/ の ContasCorrentesOmieGateway を再利用）。Excelスプレッドシートへの将来の出力を想定した形式てるデフォルトでは（apenas_favoritas: true）ユーザー定義のお気に入り口座に限定されます（src/modules/fluxo/caixa/application/contas-favoritas.ts：ヌバンク、ストーン、ブラジル銀行、Wix、iFood、Sicoob、Itaú、Elo LEANDRO、アマゾン、CAIXA LOJA— その他Omieに登録されている約39口座、例：口座古いカードや特定の収納事業者、は除外されます）。 apenas_favoritas: false で全口座を、または cod_contas_conta_corrente も、カスタム・リストを表示できます。

（オプションで、実際の残高を参照）：既定では累計残高は、指定期間内の純変動のみ。実際の銀行残高ではありません — ため、Omie APIが口座ごとの毎日残高履歴を公開していない。 use_real_balance: true を指定すると、各当座に登録済みの saldo_inicial／saldo_data （omie_contas_correntes_listar で取得）を頼りに作成します。 saldo_data から指定期間の開始までの実現仕訳を追加し、実銀行残高に近い saldoReal を計算します。これは MCP 内に固定値として埋め込まれているわけでなく、Omie の登録データから読み出できるため、誰か口座ごとに実残高を（例： 01/01）設定すると、コードを変更しなくても自動的に反映されます。saldo_data／saldo_inicial が設定されていない口座（または saldo_data が期間開始日後である口座）では、ここで推測される数値の代わりに saldoRealAcumulado: null を取得します。この変位オフセットを計算する顧客には、追加の呼び出しが発生します（最も古い saldo_data から期間開始までの運動）— saldo_data を過去に設定しすぎると遅い可能性があります。

テスト中重要な事件: Omie はパラメータが異なる場合でも、同じコールメソッドの同時実行を拒否します（「Já existe essa requisição desse mesmo check executed」）。そのため、実現済み・予定（どちらも ListarMovimentos を利用）を実行は、ユースケース内で並列実行ではなく順次行イちょっとします。これは以下のレート上限に加えて、同一 call の同時実行制約です。

長期間は大量のページを生成ことがあります（例：約3週間分の受約だけでも3,700件を超えます）— 1回の呼び出しでは約3ヶ月まで保持してください。

買掛金（src/modules/contasPagar/）

• ome_contas_pagar_listar — ユースケース: financas/contapagar （ListarContasPagar）の連携を仕入れ先名を解決して表示します（クライアトLienteMoldeから ClientesOmieGateway を再利用します。そこから Omie はコードのみを返します）。金額、成熟期限、状態（PAID/OPEN/OVER），ノート，カテゴリ、および所在地を返します。ページング（ページ分割）かつ、任意の data_alteracao_de／data のフィルタ付き。

売掛金（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のCRUDです（financas/contareceberboleto: GerarBoleto/ObterBoleto/ProrrogarBoleto/CancelarBoleto）。実際のOmieに触れずに ContasReceberFakeGateway でテスト可能です。注意: ライブテストで、この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" を安全に返します）。

テストでの重要な発見: これら2つのエンドポイントのOmieの日付フィルターパラメータ（filtrar_por_data_de/filtrar_por_data_ate）は、期限日ではなく取引の最終更新日（info.dAlt）でフィルタリングされます。1日分の範囲を要求し、返されたレコードの data_vencimento と比較して確認済みです（期限日はさまざまで、dAlt は要求した範囲内に常にあります）。そのため、MCPツールは、APIが持っていない動作を示唆しないように、パラメータを data_alteracao_de/data_alteracao_ate（data_vencimento_de/ate ではなく）として公開しています。これら2つのエンドポイントには、期限日によるネイティブフィルターは（テスト済みですが）存在しません。その場合は omie_fluxo_caixa_gerar を使用してください。これは financas/mf を使用し、期限/支払いで正しくフィルタリングします。

omie_fluxo_caixa_gerar との違い: これら2つのツールは生の取引を公開します（取引ごとの仕入先/顧客、集計なし）。債権を1件ずつ確認するのに便利です。キャッシュフローは期間/口座ごとにすべてを集計します。

キャッシュ予算 (src/modules/orcamentoCaixa/)

• omie_orcamento_caixa_consultar — ユースケース: Omieネイティブのキャッシュ予算（予算 × 実績）を財務カテゴリ別、月/年単位で参照します。Omieメソッド: ListarOrcamentos（リソース financas/caixa）。実際のOmieに触れずに OrcamentoCaixaFakeGateway でテスト可能です。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のCRUDです（financas/pix: ListarPix/ObterPix/ObterStatusPix/GerarPix/CancelarPix）。実際のOmieに触れずに PixFakeGateway でテスト可能です。Boleto とは異なり、このOmieアカウントにはPIXが設定され有効です（テストしたベースに379件の実レコード）。Listar/Obter/ObterStatus は実際のアカウントに対してライブ検証済みです。Gerar/Cancelar は慎重さのため本番の債権に対してライブテストしていません（実際にPIX請求を生成/キャンセルすることになり、安全なラウンドトリップが保証されないため。Boleto と同じ配慮です）。

税務書類 / NF-e (src/modules/nfe/)

• omie_nfe_listar / omie_nfe_consultar — ユースケース: Omieで発行済み/登録済みの税務書類（NF-e）を produtos/nfconsultar（ListarNF/ConsultarNF）で照会します。実際のOmieに触れずに NfeFakeGateway でテスト可能です。一覧は概要（番号、系列、キー、顧客、金額、取消済みかどうか）を返し、照会は詳細（項目、伝票によって生成された財務債権）を返します。モジュールは意図的に読み取り専用: 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 による再利用可能な製品特性（例: "Cor"、"Tamanho"）のCRUDです。CaracteristicaFakeGateway でテスト可能です。カテゴリとは異なり、ライブテストでCRUD全体が問題なく機能することが確認されています（完全なラウンドトリップ、痕跡なし）。

カテゴリと部門 (src/modules/categoriasDepartamentos/)

• omie_categoria_incluir / omie_categoria_alterar / omie_categoria_consultar / omie_categoria_listar — ユースケース（最初の2つは破壊的操作）。財務カテゴリ（geral/categorias）のCRUDです。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）のCRUDです。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 でテスト可能です。ネイティブフィルター（名前、UF、コードなど）と汎用パラメータ 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アカウントのCRUDです（crm/contas — B2B営業ファネル。顧客/仕入先マスタとは異なります）。実際のOmieに触れずに ContaFakeGateway でテスト可能です。注意、ライブ検証での発見: 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）のCRUDです。常にアカウントに紐付けられます。

• omie_crm_oportunidade_incluir / omie_crm_oportunidade_alterar / omie_crm_oportunidade_excluir / omie_crm_oportunidade_consultar / omie_crm_oportunidade_listar — ユースケース（最初の3つは破壊的操作）。ファネルの商談（crm/oportunidades）のCRUDです。注意、ライブ検証での発見: アカウントと連絡先に加えて、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）です。最後の2つは商談を作成するための前提条件です。

• ライブ検証済み。完全かつ安全なラウンドトリップ（テスト用のアカウント、連絡先、商談を作成し、痕跡を残さず削除）で確認されています。

このサイクルのスコープ外（リクエストなし、優先度低）: タスク（crm/tarefas）とアカウント特性（crm/contascaract）— ユーザーが必要になったときにのみ実装します。

サービス / 作業指示書 / NFS-e (src/modules/servicos/)

• omie_servico_incluir / omie_servico_alterar / omie_servico_excluir / omie_servico_consultar / omie_servico_listar — use-case（最初の3つは破壊的）、提供サービスの登録のCRUD（servicos/servico）、ServicoFakeGatewayを介して実際のOmieに触れずにテスト可能。 注意、実際の発見: AlterarCadastroServico は intEditar にネストされた識別子を要求する（自然に思える cabecalho ではない）— 公開ドキュメントではこれが明確にされていない。

• omie_os_incluir / omie_os_alterar / omie_os_excluir / omie_os_consultar / omie_os_listar — use-case（最初の3つは破壊的）、サービスオーダー（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_servicos_lc116_listar — use-case: コンプリメンタリー法116の有効なコード255件を一覧表示（サービスをオーダー作成前に正しいコードを見つけるために使用）。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 — use-case（最初の3つは破壊的）、IPedidoCompraGateway（produtos/pedidocompra）に対する完全なCRUD、PedidoCompraFakeGateway を介して実際のOmieに触れずにテスト可能。注意、実際の重要な発見事項: (1) nCodCC（codigo_conta_corrente として渡される）は、その名前にもかかわらず、部門コードや原価センターコードではなく 当座預金口座コード（geral/contacorrente）を要求する — 部門コードを使用するとOmieは「Conta Corrente não cadastrada（当座預金口座が登録されていません）」と拒否する。(2) lExibirPedidosPendentes/lExibirPedidosFaturados/lExibirPedidosRecebidos/lExibirPedidosEncerrados/lExibirPedidosCancelados/lExibirPedidosParcias — PesquisarPedCompra はデフォルトですべての注文を非表示にするため、各状況を明示的に要求する必要がある（例："lExibirPedidosPendentes": 1）。重要: これはドキュメントに明確に記載されていない、実際に検証された発見事項です。(3) ページに結果がない場合、Omieは空のリストではなくエラー SOAP-ENV:Client を返すことがある — ゲートウェイはこれを空のリストに変換する。

• omie_requisicao_compra_incluir / omie_requisicao_compra_alterar / omie_requisicao_compra_excluir / omie_requisicao_compra_consultar / omie_requisicao_compra_listar — use-case（最初の3つは破壊的）、IRequisicaoCompraGateway（produtos/requisicaocompra）に対する完全なCRUD、RequisicaoCompraFakeGateway を介して実際のOmieに触れずにテスト可能。注意、実際の重要な発見事項: 他のエンドポイントとは異なり、AlterarRequisicaoCompra はリクエストのルートに requisicaoCadastro オブジェクトを必要とし、requisicaoCompra の下ではない — 公開ドキュメントにはこの詳細が記載されておらず、これがないとOmieは「Requisicao nao encontrada（要求が見つかりません）」エラーを返す。

• omie_requisicao_compra_incluir / omie_requisicao_compra_alterar / omie_requisicao_compra_excluir / omie_requisicao_compra_consultar / omie_requisicao_compra_listar — use-case（最初の3つは破壊的）、RequisicaoCompraGateway（produtos/requisicaocompra）に対する完全なCRUD、RequisicaoCompraFakeGateway を介して実際のOmieに触れずにテスト可能。注意、実際の重要な発見: 他のエンドポイントとは異なり、IncluirRequisicaoCompra/AlterarRequisicaoCompra のフィールドは param に直接配置される — 公開ドキュメントが示す requisicao: {...} ラッパーは存在しない（使用するとOmieは「Tag [REQUISICAO] nao faz parte da estrutura（タグ[REQUISICAO]は構造の一部ではありません）」と拒否する）。

購買（src/modules/compras/）

• omie_pedido_compra_incluir / omie_pedido_compra_alterar / omie_pedido_compra_excluir / omie_pedido_compra_consultar / omie_pedido_compra_listar — use-case（最初の3つは破壊的）、IPedidoCompraGateway（produtos/pedidocompra）上の完全なCRUD、PedidoCompraFakeGateway を介して実際のOmieに触れずにテスト可能。注意、実際の重要な発見事項: (1) nCodCC（codigo_conta_corrente として渡される）は、名前にもかかわらず当座預金口座コード（geral/contacorrente）を要求し、部門や原価センターのコードではない — Omieは「Conta Corrente não cadastrada（当座預金口座が未登録）」と拒否する。(2) PesquisarPedCompra（リスト表示）はデフォルトですべての注文を非表示にする — 各状況フラグ（lExibirPedidosPendentes、lExibirPedidosFaturados、lExibirPedidosRecebidos、lExibirPedidosEncerrados、lExibirPedidosCancelados、lExibirPedidosParciais）を明示的に要求する必要がある（ゲートウェイがこれを正規化する）。(3) nCodCC は部門コードではなく、当座預金口座のコード (geral/contacorrente) を要求する — 部門コードを使用するとOmieは「Conta Corrente não cadastrada」と拒否する。

汎用（src/modules/geral/）

• omie_chamar_api — 任意のOmie APIエンドポイント（resource、method、param）への汎用パススルー。クライアント、財務、サービス、在庫などを扱う。MCP は認証情報のみを提供し、呼び出しを検証しないため、すべての validate 関数は pass を返す。注意： これはユーザーに完全な自由度を与える — 開発者が結果を解釈して対応するツール呼び出しを選択する。