omie-mcp

Claude와 Omie API를 통합하기 위한 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라는 두 번째 전송 방식이 있습니다. 이는 동일한 도구들(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, 그리고 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 — 특정 도구 하나의 페이로드 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로 전환하는 것에 대해 이미 언급한 보안 경고와 동일합니다. 의도: 지금은 로컬에서 개발용으로 사용하고, 최소한의 보안(인증, 입력 검증)을 구현한 후에야 실제 노출 서비스로 전환합니다.

아키텍처

필요에 따라 선택되는 두 가지 모듈 형식이 있습니다:

• Passthrough(플랫) — 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를 변경할 필요가 없습니다. 모듈을 만들고 registry에서 import하기만 하면 됩니다.

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(처음 3개는 파괴적), IOrdemProducaoGateway에 대한 CRUD, OpFakeGateway를 통해 실제 Omie에 접촉하지 않고 테스트 가능. 주의: 실시간 검증(폐기 가능한 제품/원자재/구조로 완전한 왕복) 결과, 제품은 구조(BOM)가 채워져 있어야만 OP를 수락하며, codigo_local_estoque는 단순 포함에서도 필수입니다(0 = 기본 위치), 공개 Omie 문서에서는 선택 사항으로 표시되어 있음에도 불구하고

• omie_op_listar — passthrough, 원시 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 — passthrough, 특정 제품의 등록 정보

• omie_produtos_listar — passthrough, 제품 목록(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 — passthrough, 제품군

• 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), 실제 Omie에 접촉하지 않고 EstruturaFakeGateway를 통해 테스트 가능. 주의: 실시간 검증(폐기 가능한 테스트 제품에서 포함→수정→삭제 라운드트립) 결과, 상위 제품은 '03 - 제조 중 제품' 또는 '04 - 완제품' 유형이어야 하며, intMalha는 IncluirEstrutura에서 필수(공개 문서에서는 선택 사항으로 표시)이고, AlterarEstrutura/ExcluirEstrutura는 idMalha와 함께 idProdMalha를 요구합니다.

재고 (src/modules/estoque/)

• omie_estoque_ajuste_incluir / omie_estoque_ajuste_excluir — 사용 사례(파괴적 작업), IEstoqueGateway.incluirAjuste/excluirAjuste에 대한 조정 CRUD, 실제 Omie에 접촉하지 않고 EstoqueFakeGateway를 통해 테스트 가능. 주의, 실시간으로 발견한 중요한 사항: motivo 필드는 'INI'/'INV'/'OPE'/'PDV'만 허용합니다(공개 문서에 없고 Omie의 검증 오류에만 나타남); 그리고 제품에 대한 어떤 재고 조정 후에는 해당 제품은 더 이상 삭제할 수 없습니다 — Omie가 그 제품에 영구적으로 연결된 "재고 이동(계산됨)"을 유지하기 때문이며, 조정 자체를 나중에 삭제해도 마찬가지입니다.

• omie_estoque_movimentos_listar — passthrough, 기간별 이동 목록 조회

• 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, 실제 Omie에 접촉하지 않고 PedidoVendaFakeGateway를 통해 테스트 가능. 주의: 실시간 검증(폐기 가능한 고객/제품으로 전체 라운드트립) 결과, 고객은 등록에 UF가 입력되어 있어야 하며(그렇지 않으면 Omie가 주문을 거부), codigo_categoria/codigo_conta_corrente는 단순 주문에서도 필수입니다.

• omie_pedido_venda_listar — passthrough, 주문 목록 조회(Omie 고유 etapa 필터 허용)

• omie_pedido_venda_etapas_listar — passthrough, 코드와 설명이 포함된 청구 단계 카탈로그(판매/OS/구매 칸반) — 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를 재사용합니다.

테스트 중 발견한 중요한 사항: 취소된 주문은 Omie가 etapa를 초기화하지 않습니다 — 취소된 주문이 해당 단계에서 취소된 경우 계속 "재고 분리"에 있는 것처럼 표시됩니다. 따라서 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 — passthrough, 특정 고객/공급업체(법인명, 상호, CNPJ/CPF, 연락처, 주소, 태그)

• omie_clientes_listar — passthrough, 고객/공급업체 목록 조회; clientesFiltro를 통한 고급 필터 허용(예: {"tags": [{"tag": "Fornecedor"}]})

• omie_fornecedores_listar — 가벼운 사용 사례: Fornecedor 태그로 이미 필터링된 omie_clientes_listar의 단축키, 법인명/상호/CNPJ-CPF 검색 및 apenas_ativos(비활성 항목을 클라이언트 측에서 제거 — clientesFiltro.tags 필터는 같은 호출에서 상태 필터와 직접 결합되지 않기 때문)

• omie_clientes_incluir / omie_clientes_alterar / omie_clientes_excluir — 사용 사례(파괴적 작업), IClientesGateway.incluirCliente/alterarCliente/excluirCliente에 대한 CRUD, 실제 Omie에 접촉하지 않고 ClientesFakeGateway를 통해 테스트 가능. 주의: 실시간 검증(생성→수정→삭제 라운드트립) 결과, Omie 공개 문서에서 선택 사항으로 표시하더라도 codigo_cliente_integracao는 IncluirCliente에서 필수입니다.

현재 범위: 읽기 전용(조회/목록). 사용자 요청에 따라 고객/공급업체의 전체 CRUD(포함, 수정, 삭제)는 나중으로 미룹니다 — MCP에 최소한의 보안이 구현된 후에만(rate limit/보안 섹션 및 src/httpServer.ts 참조).

당좌 계정 (src/modules/contasCorrentes/)

• omie_contas_correntes_listar — passthrough, 코드, 설명, 은행, 유형 및 등록된 초기 잔액이 포함된 당좌 계정(은행, 현금, 카드, 결제 단말기) 목록

• omie_extrato_conta_corrente_consultar — 사용 사례: 특정 기간의 당좌 계정 거래 내역(날짜/설명/금액/카테고리/조정 상태가 포함된 이동, 이전/현재/조정/가용 잔액). Omie 메서드: ListarExtrato(리소스 financas/extrato), 실제 Omie에 접촉하지 않고 ContasCorrentesFakeGateway를 통해 테스트 가능. 이동에 대한 일반 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: Cartão NuBank, Stone, Banco do Brasil, Wix, iFood, Sicoob, Itaú, Cartão Elo LEANDRO, Amazon, CAIXA LOJA — Omie에 등록된 나머지 ~39개 계정(예: 오래된 카드 및 특정 결제 대행사)은 제외); 모든 계정을 보려면 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 사용)는 use-case 내에서 병렬이 아닌 순차적으로 실행됩니다. 이는 아래 섹션에 이미 문서화된 rate limit에 추가되는 제한으로, 동일 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 — 유스 케이스 (생성/연장/취소는 파괴적), 수취채권 제목에 대한 보울레토 CRUD (financas/contareceberboleto: GerarBoleto/ObterBoleto/ProrrogarBoleto/CancelarBoleto), 실제 Omie에 접촉하지 않고 ContasReceberFakeGateway를 통해 테스트 가능. 주의: 라이브 테스트 결과 이 Omie 계정에는 은행 계약/보울레토가 구성되어 있지 않습니다 — ProrrogarBoleto는 "Não temos suporte para geração da remessa de pagamento para o banco -sem instituição-"를 반환합니다. GerarBoleto도 같은 이유로 실패할 가능성이 높습니다(프로덕션 고객의 제목으로 실제 보울레토를 생성하지 않기 위해 라이브 테스트는 하지 않음). ObterBoleto/CancelarBoleto는 라이브로 검증되었습니다(안전하게 "nenhum boleto gerado"를 반환하며 부작용 없음).

테스트 중 발견한 중요한 점: 이 두 엔드포인트의 Omie 날짜 필터 매개변수(filtrar_por_data_de/filtrar_por_data_ate)는 만기일이 아닌 항목의 마지막 수정일(info.dAlt)을 기준으로 필터링합니다. 1일 범위를 요청하고 반환된 레코드의 data_vencimento와 비교하여 확인했습니다(만기일은 다르지만 dAlt는 항상 요청한 범위 내에 있었습니다). 따라서 MCP 도구는 API에 없는 동작을 암시하지 않도록 매개변수를 data_alteracao_de/data_alteracao_ate로 노출합니다. 이 두 엔드포인트에는 만기일 기준 기본 필터가 없습니다(테스트 완료) — 이 경우 financas/mf를 사용하고 만기/지불 기준으로 올바르게 필터링하는 omie_fluxo_caixa_gerar를 사용하세요.

omie_fluxo_caixa_gerar와의 차이점: 이 두 도구는 원시 항목(집계 없이 항목별 공급업체/고객)을 노출하므로 항목별로 확인하는 데 유용합니다. 현금 흐름은 기간/당좌 계정별로 모든 것을 집계합니다.

현금 예산 (src/modules/orcamentoCaixa/)

• omie_orcamento_caixa_consultar — 유스 케이스: 월/연도별 재무 범주별 Omie 기본 현금 예산(계획 대 실적). Omie 메서드: ListarOrcamentos(financas/caixa 리소스), OrcamentoCaixaFakeGateway를 통해 실제 Omie에 접촉하지 않고 테스트 가능. omie_fluxo_caixa_gerar(지불/수취 계정에서 수동으로 계산, 당좌 계정/일별로 그룹화)와 달리 이는 범주(예: "1.01.01 Vendas")별로 그룹화된 Omie 자체의 기성 보고서입니다. 일반 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), 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를 통한 재사용 가능한 제품 특성(예: "색상", "크기") CRUD, CaracteristicaFakeGateway를 통해 테스트 가능. 카테고리와 달리 전체 CRUD가 문제없이 작동하는지 라이브로 테스트되었습니다(전체 왕복, 흔적 없음).

카테고리 및 부서 (src/modules/categoriasDepartamentos/)

• omie_categoria_incluir / omie_categoria_alterar / omie_categoria_consultar / omie_categoria_listar — 유스 케이스 (처음 2개는 파괴적), 재무 카테고리 CRUD (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개는 파괴적), 부서/원가 중심지 CRUD (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 계정 CRUD (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 연락처 CRUD (crm/contatos), 항상 계정에 연결됩니다.

• omie_crm_oportunidade_incluir / omie_crm_oportunidade_alterar / omie_crm_oportunidade_excluir / omie_crm_oportunidade_consultar / omie_crm_oportunidade_listar — 유스 케이스 (처음 3개는 파괴적), 파이프라인 기회 CRUD (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 — 유스 케이스 (처음 3개는 파괴적 작업), 제공 서비스 등록(servicos/servico)의 CRUD. ServicoFakeGateway를 통해 실제 Omie를 건드리지 않고 테스트할 수 있습니다. 주의, 라이브에서 발견한 사항: AlterarCadastroServico는 cabecalho가 아니라 intEditar 안에 중첩된 식별자를 요구합니다(자연스러워 보이는 cabecalho가 아님). 공개 문서는 이를 명확히 밝히지 않습니다.

• omie_os_incluir / omie_os_alterar / omie_os_excluir / omie_os_consultar / omie_os_listar — 유스 케이스 (처음 3개는 파괴적 작업), 서비스 오더(servicos/os)의 CRUD. OrdemServicoFakeGateway를 통해 실제 Omie를 건드리지 않고 테스트할 수 있습니다. 중요한 라이브 발견 사항: (1) 각 항목의 codigo_servico_municipal/codigo_servico_lc116은 LC116 테이블에 이미 등록된 코드여야 합니다(자유 텍스트 아님, omie_servicos_lc116_listar 참조). 그렇지 않으면 Omie가 "LC116 코드가 등록되지 않았습니다"라고 거부합니다. (2) cRetemISS는 공개 문서에 표시되어 있지 않더라도 각 항목에서 필수입니다. (3) 헤더의 고객은 UF가 채워져 있어야 합니다(판매 주문에서 이미 확인된 동일한 요구 사항). 임시 테스트 고객을 만들어 흔적 없이 삭제하는 완전하고 안전한 라운드트립으로 라이브에서 검증되었습니다.

• omie_nfse_listar — 유스 케이스: 이미 발행된 NFS-e(servicos/nfse, ListarNFSEs)를 조회하며, NfseFakeGateway를 통해 테스트할 수 있습니다. 읽기 전용 — 제품 NF-e 모듈과 동일한 주의사항(법적 효력이 있는 세무 문서이므로 발행의 안전한 라운드트립 없음).

• omie_servicos_lc116_listar — 유스 케이스: OS를 만들기 전에 올바른 코드를 찾는 데 사용되는 Lei Complementar 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 — 유스 케이스 (처음 3개는 파괴적 작업), IPedidoCompraGateway(produtos/pedidocompra)에 대한 전체 CRUD. PedidoCompraFakeGateway를 통해 실제 Omie를 건드리지 않고 테스트할 수 있습니다. 중요한 라이브 발견 사항: (1) nCodCC(codigo_conta_corrente로 전달)는 이름과 달리 부서/원가중심 코드가 아니라 conta corrente(geral/contacorrente) 코드를 요구합니다. Omie는 부서 코드를 사용하면 "Conta Corrente가 등록되지 않았습니다"라고 거부합니다. (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 — 유스 케이스 (처음 3개는 파괴적 작업), IRequisicaoCompraGateway(produtos/requisicaocompra)에 대한 전체 CRUD. RequisicaoCompraFakeGateway를 통해 실제 Omie를 건드리지 않고 테스트할 수 있습니다. 중요한 라이브 발견 사항: 다른 Omie 엔드포인트와 달리 IncluirReq/AlterarReq의 필드는 param의 루트에 직접 들어갑니다. 공개 문서의 것인 requisicaoCadastro: {...} 래퍼는 존재하지 않습니다(Omie는 "Tag [REQUISICAOCADASTRO]는구조의 일부가 아닙니다"라고 거부합니다).

공통 (다른 모든 모듈 포함)

• omie_chamar_api — resource(모듈 경로), call(메서드), param(파라미터)를 받아 https://developer.omie.com.br/service-list/에 나열된 모든 엔드포인트(클라이언트, 재무, CRM, 판매, NF-e, 서비스 등)에 접근할 수 있습니다.

Omie의 rate limit — MCP가 스스로를 보호하는 방식

Omie는 여러 짧은 시간에 몰려드는 호출을 두 가지 방식으로 차단합니다. "부적절한 사용"(rate limit 그 자체)과 "중복 사용"( 비슷한 호출이 빠르게 연속될 때 — 실제로 판매 보고서를 만들기 위해 클라이언트 약 20개를 병렬로 조회하다가 발생한 적이 있습니다). 이 보호는 OmieClient(src/omieClient.ts)에 중앙 집중되어 있으므로 모든 모듈이 자동으로 혜택을 받으며 다시 구현할 필요가 없습니다.

• Throttle — 모든 호출은 같은 OmieClient 인스턴스의 이전 호출 이후 최소 간격(300ms)을 지킵니다. 여러 호출이 동시에 들어와도 마찬가지입니다(Promise.all, mapWithConcurrency 등). 이렇게 하면 retry가 필요하기 전에 "중복 사용"에 걸릴 가능성이 줄어듭니다.

• 올바른 대기로 재시도 — 그럼에도 Omie가 차단하면 OmieClient는 Omie가 오류 메시지에서 제시한 시간(예: "57초 기다리세요")을 존중하며 최대 4회까지 다시 시도합니다. 시기는 무조건 짧게 고정된 backoff를 사용하는 것이 아닙니다.

• mapWithConcurrency (src/shared/concurrency.ts) — 코드별로 여러 레코드를 일괄 조회하는 게이트웨이(ProdutosOmieGateway.consultarProdutosPorCodigo, ClientesOmieGateway.consultarClientesPorCodigo)에서 사용되며, 자체 코드의 동시성을 5개의 동시 호출로 제한합니다. 이는 클라이언트의 throttle을 보완합니다.

새 모듈에 대한 규칙:

1. 코드 배열에 대해 동시성 제한 없이 Promise.all/Promise.allSettled를 절대 호출하지 마세요. 항상 mapWithConcurrency를 사용하세요.

2. 같은 메서드(call)의 두 호출을 병렬로 절대 실행하지 마세요. 매개변수가 달라도 마찬가지입니다. Omie는 "이 메서드의 요청이 이미 실행되고 있습니다"라고 거부합니다(ListarMovimentos 처리 횟수가 필요한 fluxoCaixa를 만들 때 확인됨). 순차적으로 실행하세요(await 하나 후 다른 것).

3. 다른 메서드의 병렬 호출(예: 동시에 제품과 재고를 조회)은 안전하며 추가 조치가 필요없습니다. 클라이언트의 throttle이 이미 처리하니까요.

새 모듈 추가

Passthrough (Omie가 이미 완성된 데이터를 그대로 반환하는 경우):

1. src/tools/<modulo>.ts를 만들고 ToolDef 배열을 내보냅니다(src/tools/types.ts의 defineTool() 사용).

2. 해당 배열을 import하여 src/tools/registry.ts의 allTools에 연결/추가합니다.

** 계층형** (Omie 호출을 집계/결합해야 하는 경우 — src/modules/estoque/를 참조):

1. application/use-cases/ — 비즈니스 규칙(게이트웨이를 받아 사용자에게 완성된 결과를 그대로 반환).

2. application/dto/ — 입력 param의 zod 스키마와 결과 타입.

3. infrastructure/gateways/ — Omie 호출(resource/call)만, 비즈니스 규칙 없음.

4. presentation/mcp/ — execute가 gateway + use-case를 실행하는 ToolDef.

5. <modulo>-register.ts + index.ts — tools 배열의 barrel export.

6. src/tools/registry.ts의 allTools에 배열을 import.

두 경우 모두 src/index.ts가 도구를 자동으로 등록하므로 그 파일은 변경할 필요가 없습니다.

다음 단계 (로드맵)

• 필요에 따라 재무, 판매/NF-e, CRM 전용 모듈을 추가합니다(동일한 파일 구조 적용).

• 큰 목록을 위한 자동 캐시/페이지네이션을 추가합니다.

• Omie API mock을 통한 자동화 테스트를 추가합니다.

보안

.env 파일은 절대 커밋하지 말고, 공개 저장소에 OMIE_APP_KEY/OMIE_APP_SECRET을 노출하지 마세요.