MCP Three-Way Invoice Match

Compare localmente as quantidades e os preços dos SKUs da fatura do fornecedor com ordens de compra, recibos e faturas anteriores.

GitHub

Documentação

Servidor MCP de conciliação de fatura de fornecedor em três vias

Servidor MCP para conciliação em três vias: fatura de fornecedor comparada com ordens de compra e recebimentos aceitos por SKU. Verificação de fatura de fornecedor, ordem de compra e recebimento por SKU exato.

Funciona com Claude Desktop, Claude Code, Cursor e qualquer cliente do Model Context Protocol. Roda na sua própria máquina: este servidor não possui endpoint hospedado, então instale-o a partir do pacote ou do código-fonte.

Página do produto: https://mcp.zovo.one/s/three-way-match — recursos, limites gratuitos e caminhos de instalação suportados.

Experimente o exemplo editável de conciliação no seu navegador antes de instalar. Não é necessária conta; as verificações do exemplo rodam no seu navegador sem enviar valores de campos.

Instalação

Claude Desktop, um clique. Baixe three-way-match.mcpb do catálogo de pacotes e clique duas vezes nele.

A partir do código-fonte. O espelho é autocontido: todas as dependências de @theluckystrike/* são incluídas, então um clone novo compila sem configuração adicional.

git clone https://github.com/theluckystrike/mcp-three-way-match.git
cd mcp-three-way-match
npm install && npm run build

Em seguida, aponte seu cliente para o ponto de entrada compilado:

{
  "mcpServers": {
    "three-way-match": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-three-way-match/dist/index.js"]
    }
  }
}

@theluckystrike/mcp-three-way-match ainda não está publicado no npm, portanto um comando npx -y @theluckystrike/mcp-three-way-match falhará. Os três caminhos acima são os que funcionam e cada um é exercitado pela CI.

three-way-match demo

Espelho somente leitura de mcp-servers/servers/three-way-match. Consulte MIRROR.md.

Verifique uma fatura de fornecedor contra sua ordem de compra e recibos de entrega no Claude ou em outro cliente MCP. Este servidor local compara cada SKU exato, preço unitário e quantidade faturada com a ordem de compra, entregas aceitas acumuladas e quantidades que você informou como já faturadas. Ele detecta erros de SKU compensatórios mesmo quando os totais gerais da fatura e da ordem de compra coincidem, e retorna os valores de origem por trás de cada exceção. Forneça documentos estruturados; este servidor não extrai PDFs, não realiza OCR, não se conecta a um ERP, não registra pagamentos nem aprova uma fatura.

Criado por theluckystrike. MIT. Suporte: support@zovo.one.

Instalação

Claude Desktop: baixe three-way-match.mcpb v0.22.8 e abra-o. SHA-256: 6397928ec44ea9d5c406a66f4eb7aa9a2f34f5731bf8ef9972fadfdac882f040. Outros clientes podem usar as instruções de código-fonte abaixo.

Requer Node.js 18 ou mais recente. Compile a partir do checkout do código-fonte; o pacote npm não está publicado. Nenhuma chave de API ou conta é necessária para executar as ferramentas gratuitas.

git clone https://github.com/theluckystrike/mcp-servers.git
cd mcp-servers
npm install
node scripts/bootstrap-timezone.mjs
npm run build --workspace @theluckystrike/mcp-license
npm run build --workspace @theluckystrike/mcp-three-way-match

Use o caminho absoluto para servers/three-way-match/dist/index.js no seu checkout. O servidor fala stdio; seu cliente MCP o inicia. Não coloque uma URL HTTP em seu lugar.

Claude Desktop: mescle esta entrada em mcpServers em ~/Library/Application Support/Claude/claude_desktop_config.json no macOS (ou %APPDATA%\Claude\claude_desktop_config.json no Windows), substituindo /absolute/path pelo local do seu checkout:

{
  "mcpServers": {
    "three-way-match": {
      "command": "node",
      "args": ["/absolute/path/mcp-servers/servers/three-way-match/dist/index.js"]
    }
  }
}

Claude Code:

claude mcp add three-way-match -- node /absolute/path/mcp-servers/servers/three-way-match/dist/index.js

Cursor: mescle o mesmo JSON em .cursor/mcp.json no seu projeto ou ~/.cursor/mcp.json. Reinicie seu cliente, chame license_status e execute o exemplo abaixo. Um resultado tools/list sozinho não verifica a conciliação.

Para Claude Desktop, baixe three-way-match.mcpb e abra-o para instalar. SHA-256: 6397928ec44ea9d5c406a66f4eb7aa9a2f34f5731bf8ef9972fadfdac882f040. Este é um servidor stdio local; nenhum endpoint hospedado está disponível.

Ferramentas

Ferramenta	Argumentos e resultado
`three_way_match`	PO, recibos, fatura, `prior_invoiced` obrigatório, `save` opcional; retorna relatório completo e resultado do salvamento.
`report_list`	`offset` opcional (0), `limit` (20, máximo 100); retorna UUIDs salvos e resumos.
`report_get`	`id`; documentos de origem, todos os problemas e evidências por SKU.
`report_page`	`id`, `section`, `offset`/`limit` opcionais, `receipt_index`/`sku`; páginas gratuitas de cada problema, evidência de SKU e linha de origem.
`report_delete`	`id`; remove esse relatório salvo e libera um slot de armazenamento.
`report_export_csv`	`id`, `offset`/`limit` opcionais; texto CSV além de moeda, status e códigos de problema em nível de documento; exportações grandes paginam.
`license_status`	Sem argumentos; status offline gratuito/Pro e link de checkout.
`license_activate`	`key`; verifica e armazena uma chave Pro offline.

Contrato de entrada

Uma PO e uma fatura de fornecedor atual por chamada. Não há correspondência difusa: SKU, fornecedor e referências de PO são strings exatas, sensíveis a maiúsculas/minúsculas, sem espaços em branco ao redor ou caracteres de controle. Referências de documentos e SKUs têm 1–120 caracteres. As referências de documentos de PO, fatura e recibo devem ser distintas. SKUs duplicados dentro de um documento ou dentro de prior_invoiced, e referências de recibo duplicadas, produzem invalid; linhas ambíguas são excluídas da comparação. SKUs repetidos em diferentes documentos de recibo são esperados e se acumulam.

Quantidades são unidades inteiras de 0 a 1.000.000.000; quantidades de linha de PO e fatura devem ser positivas. Quantidades fracionárias são rejeitadas. accepted_quantity e rejected_quantity são contagens disjuntas, não uma contagem bruta e seu subconjunto. Unidades rejeitadas nunca aumentam a quantidade disponível para faturamento. Recibos devem conter datas YYYY-MM-DD válidas; inclua apenas recibos relevantes para esta verificação. Datas são evidência, não um corte automático de data de fatura.

Cada entrada monetária é um valor inteiro em unidades menores de 0 a Number.MAX_SAFE_INTEGER (9.007.199.254.740.991). Para USD, 100 significa $1,00; para uma moeda sem casas decimais, use suas próprias unidades menores. Forneça o código de moeda de três letras em maiúsculas tanto na PO quanto na fatura. Não ocorre conversão de moeda nem consulta a catálogo de códigos de moeda. Preços unitários devem corresponder exatamente, sem tolerância. Produtos monetários e totais usam aritmética inteira; resultados inseguros produzem invalid com unsafe_money_arithmetic, nunca um valor arredondado.

invoice.total_minor é o total das linhas de mercadorias fornecidas. Não há ajustes implícitos de imposto, frete, desconto, arredondamento ou crédito. Represente encargos acordados como SKUs explícitos de PO/fatura com preço e evidência de recibo apropriada, ou prepare um total de mercadorias excluindo ajustes antes de chamar. Não forneça um total de fatura tudo-incluído omitindo seus ajustes.

prior_invoiced é obrigatório, mesmo quando vazio. Forneça as quantidades cumulativas completas anteriormente faturadas para cada SKU contra esta PO, excluindo esta fatura atual. [] afirma explicitamente nenhuma. Quantidades atuais mais anteriores devem caber tanto nos recibos aceitos quanto na PO. Salvar relatórios não atualiza esse histórico nem detecta referências de fatura repetidas entre verificações; histórico incorreto ou omitido pode permitir faturamento repetido não detectado. Relatórios são instantâneos de evidência, não um livro contábil.

Os limites se aplicam igualmente a gratuito e Pro: 1–500 linhas de PO, 1–500 linhas de fatura, até 500 SKUs anteriores e até 100 recibos de 1–500 linhas cada. Um array de recibos vazio é válido e produz exceções de recibo ausente para SKUs de PO faturados. Referências vazias ou malformadas, SKUs em branco/ausentes, decimais, números de entrada inseguros e datas inválidas são rejeitados como erros de entrada. SKUs desconhecidos são exceções explícitas de unordered_sku.

Totais iguais podem esconder erros de SKU

Chame three_way_match com:

{
  "po": {
    "reference": "PO-1", "supplier": "Supply Co", "currency": "USD",
    "lines": [
      {"sku": "A", "quantity": 10, "unit_price_minor": 100},
      {"sku": "B", "quantity": 10, "unit_price_minor": 100}
    ]
  },
  "receipts": [{
    "reference": "GR-1", "po_reference": "PO-1", "supplier": "Supply Co", "date": "2026-10-16",
    "lines": [
      {"sku": "A", "accepted_quantity": 5, "rejected_quantity": 0},
      {"sku": "B", "accepted_quantity": 15, "rejected_quantity": 0}
    ]
  }],
  "invoice": {
    "reference": "INV-1", "po_reference": "PO-1", "supplier": "Supply Co", "currency": "USD",
    "lines": [
      {"sku": "A", "quantity": 10, "unit_price_minor": 100},
      {"sku": "B", "quantity": 10, "unit_price_minor": 100}
    ],
    "total_minor": 2000
  },
  "prior_invoiced": [],
  "save": false
}

O relatório tem status: "exceptions", apesar de totais iguais de PO/fatura de 2.000 unidades menores e quantidades agregadas iguais. O SKU A tem invoiced_above_accepted (10 faturados, 5 aceitos); o SKU B tem accepted_above_order (15 aceitos, 10 pedidos). Alterar os preços unitários da fatura para 90 em A e 110 em B também preserva o total geral, mas produz dois problemas de unit_price_mismatch.

Entregas parciais podem corresponder

Usando a mesma PO, forneça um recibo contendo apenas A com accepted_quantity: 4, rejected_quantity: 2. Fature apenas A com quantity: 4, unit_price_minor: 100, total_minor: 400 e mantenha prior_invoiced: []. Isso retorna matched. A tem seis unidades ainda não entregues; B não precisa aparecer nesta fatura parcial. Um segundo recibo correspondente adiciona sua quantidade aceita; quantidades rejeitadas permanecem como evidência separada. Após faturar anteriormente duas unidades de A, forneça prior_invoiced: [{"sku":"A","quantity":2}] e fatura no máximo mais duas contra essas quatro unidades aceitas.

Lendo o relatório

matched significa que a evidência fornecida passa nestas verificações exatas; não autoriza pagamento. exceptions identifica incompatibilidades de documentos, SKUs desconhecidos, recibos ausentes, quantidades aceitas/faturadas excessivas, diferenças de preço ou um total de fatura declarado inconsistente. invalid identifica ambiguidade ou dinheiro computado inseguro; resolva antes de interpretar a comparação. Referências de PO/fornecedor incompatíveis em recibos são sinalizadas e esses recibos não suportam faturamento.

Cada problema tem code, severity, source, sku opcional e uma mensagem concreta. Cada linha de SKU ordenada inclui números de linha de origem baseados em um da PO/fatura; quantidades pedidas, aceitas, rejeitadas, anteriores e atuais da fatura; ambos os preços unitários; quantidade faturada cumulativa; quantidade disponível antes desta fatura; quantidade restante não entregue; referências/números de linha de recibo e sinalizadores de inclusão; e códigos de problema. O relatório retém os documentos completos fornecidos, então uma linha duplicada nunca desaparece da evidência de auditoria. Faltas parciais são mostradas como quantidades restantes e não falham por si mesmas uma fatura parcial suportada.

Relatórios pequenos retornam inline. Um relatório cuja resposta MCP escapada excederia 8 MiB retorna uma visão geral explícita de paginated: true com status, totais, contagens, cabeçalhos de documentos de origem e report_id. Toda a evidência permanece gratuita através de report_page. Selecione section de issues, lines, po_lines, invoice_lines, prior_invoiced, receipts, receipt_lines ou line_receipts; use offset (padrão 0) e limit (padrão 100, máximo 100), seguindo next_offset até null. Páginas de lines contêm evidência escalar e receipt_count; obtenha essas entradas de recibo com line_receipts e o sku exato. receipt_lines requer o receipt_index baseado em zero do array de recibos original. Páginas de receipts contêm cabeçalhos de documentos e contagens de linhas. Juntas, essas seções preservam cada linha de origem e cada problema computado.

Relatórios salvos usam seu UUID persistente para páginas, e report_get retorna a mesma visão geral limitada para relatórios salvos grandes. Relatórios grandes não salvos, incluindo falhas de limite de salvamento e armazenamento, usam IDs de preview:<UUID>: o processo mantém suas duas últimas pré-visualizações grandes por 30 minutos. Reinicialização, expiração ou uma terceira pré-visualização podem despejá-las; reenvie o diagnóstico original para recriar a pré-visualização gratuita. IDs de pré-visualização pertencem ao processo do servidor atualmente em execução. O SDK subjacente também limita mensagens stdio recebidas a 10 MiB; solicitações codificadas devem caber nesse limite de transporte mesmo quando contagens de linhas individuais cabem no esquema.

CSV inclui uma linha por SKU, preços exatos em unidades menores, quantidades e códigos de problema de linha; problemas de documento permanecem no JSON acompanhante e no relatório completo. CSV é retornado como texto, não gravado em um caminho arbitrário fornecido pelo chamador. Caracteres iniciais semelhantes a fórmulas são escapados para uso em planilhas.

Exportações CSV que cabem no mesmo orçamento de resposta de 8 MiB permanecem inline. Exportações maiores retornam um primeiro bloco de até 1.000 linhas com paginated, offset, returned, total_rows e next_offset. Passe esse next_offset como offset em outra chamada de report_export_csv; limit opcional é 1–1.000. Cada bloco repete o cabeçalho; retenha um cabeçalho ao combinar blocos.

Gratuito e Pro

Recurso	Gratuito	Pro
Verificações diagnósticas completas e evidência de origem	Todas as verificações, até 500 linhas de PO/fatura	Igual
Verificações de recibos e faturas anteriores	Mesmos limites documentados	Igual
Relatórios salvos	3 por vez	Sem limite de contagem de relatórios
Listar/obter/excluir e exportação CSV	Incluído	Incluído
Quando `save: true` atinge o limite gratuito, o relatório completo ainda é retornado com `saved: false`, `save_error: "free_saved_report_cap"` e o link de checkout. Um erro de armazenamento também preserva o relatório de diagnóstico. Exclua um relatório salvo antigo para reutilizar um slot gratuito. Um arquivo de relatório salvo é limitado a 64 MiB ao ser salvo e lido; isso é uma proteção de integridade de armazenamento, não um limite do Pro.

Obtenha o Pro: $19 pagamento único. Todos os servidores: pacote de $39. Ative a chave com license_activate ou defina MCP_LICENSE_KEY. As chaves verificam offline.

Todos os dados permanecem locais. A correspondência não faz solicitações de rede. Relatórios JSON salvos ficam em ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/three-way-match/; XDG_DATA_HOME deve ser absoluto e a hierarquia do diretório de armazenamento não pode conter symlinks. Os arquivos usam renomeação atômica e as mutações compartilham um bloqueio entre processos. Os relatórios incluem dados de documentos comerciais: gerencie o acesso local e os backups de acordo. A ativação da licença grava o arquivo de configuração de licença local compartilhado.

Desenvolvimento

npm run build --workspace @theluckystrike/mcp-three-way-match
npm test --workspace @theluckystrike/mcp-three-way-match

Os testes exercitam erros de compensação de quantidade/preço, recibos rejeitados e múltiplos, parciais, faturamento anterior explícito, SKUs/referências desconhecidas e duplicadas, incompatibilidades de moeda/PO/fornecedor, datas, limites de inteiros, política de salvamento gratuito/Pro, armazenamento atômico e um round trip de inicialização/ferramentas/chamada MCP stdio. O Docker compila a partir da raiz do repositório com docker build -f servers/three-way-match/Dockerfile ..