Goods Receipt MCP

Notas de recebimento de mercadorias contra ordens de compra: tolerâncias de excesso/falta, unidades danificadas e em falta, discrepâncias, exportação em CSV.

GitHubExperimente este MCPPatrocinado

Documentação

mcp-goods-receipt

Servidor MCP para notas de recebimento de mercadorias contra ordens de compra: unidades recebidas, danificadas e em falta, com um relatório de discrepância. O registro de recebimento para ordens de compra: o que chegou, contra qual linha, em qual quantidade e condição.

Funciona com Claude Desktop, Claude Code, Cursor e qualquer cliente Model Context Protocol. Roda na sua própria máquina, ou hospedado sem instalação.

Página do produto: https://mcp.zovo.one/s/goods-receipt — o que faz, as ferramentas que expõe e um endpoint de token ao vivo.

Instalação

Hospedado, nada para instalar. Obtenha um token em https://mcp.zovo.one/mcp/connect (a página de conexão) ou https://mcp.zovo.one/mcp/token (o mesmo token como JSON); um token anônimo gratuito é emitido na hora e uma chave Pro funciona da mesma forma. Em seguida, aponte um cliente MCP para https://mcp.zovo.one/mcp/goods-receipt via streamable-http e envie o token como Authorization: Bearer <token>.

Se o seu cliente não puder definir cabeçalhos, coloque o token no caminho: https://mcp.zovo.one/mcp/goods-receipt/t/<token>. Ambas as formas funcionam. A URL simples sem token responde 401 em tools/call, então o token não é opcional.

Claude Desktop, um clique. Baixe goods-receipt.mcpb da última versão e clique duas vezes nele.

A partir do código-fonte. O espelho é autocontido: cada dependência @theluckystrike/* é incluída, então um clone novo compila sem configuração extra.

git clone https://github.com/theluckystrike/mcp-goods-receipt.git
cd mcp-goods-receipt
npm install && npm run build

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

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

@theluckystrike/mcp-goods-receipt ainda não está publicado no npm, então um comando npx -y @theluckystrike/mcp-goods-receipt falhará. Os três caminhos acima são os que funcionam e cada um é testado pelo CI.

goods-receipt demo

Espelho somente leitura de mcp-servers/servers/goods-receipt. Veja MIRROR.md.

No Registro Oficial MCP (io.github.theluckystrike/goods-receipt).

Ordens de compra e as notas de recebimento de mercadorias que as recebem. Uma OC carrega uma referência, um fornecedor e linhas datadas — sku, descrição, unidades inteiras pedidas — além de tolerâncias de excesso/falta em percentuais inteiros que decidem quando um recebimento é sinalizado. Uma GRN é emitida contra uma OC aberta, uma célula por linha: unidades recebidas, unidades danificadas e qualquer falta que você já saiba. A falta é derivada, não digitada — pedido menos recebido, limitado a zero — e aparece como discrepância no momento em que os números divergem.

A única regra que decide todo o resto

A tolerância de excesso é verificada contra o total acumulado em todas as GRNs emitidas na linha, não contra cada entrega isoladamente.

Três entregas de 40 contra um pedido de 100 a 10% são permitidas em unidades e dezenas, mas a terceira entrega é recusada, porque 120 recebidos de 100 pedidos quebra a tolerância de excesso, mesmo que nenhuma entrega individual tenha quebrado. Entregas parciais são permitidas — várias GRNs contra a mesma OC é o caso normal — e a regra acumulada é o que impede que elas recebam em excesso silenciosamente.

Duas regras menores decorrem disso:

Nada derivado é armazenado. Falta e discrepância são calculadas a cada chamada a partir das linhas da OC e das GRNs já registradas. Danos são a única coisa digitada, porque é a única coisa que o armazém realmente vê.
Recebimento além da tolerância é recusado, nunca limitado. A menos que as unidades extras sejam declaradas danificadas, um recebimento que quebra a tolerância de excesso não grava nada e explica o motivo. Unidades danificadas ainda contam para a verificação de tolerância — "chegou quebrado" não é licença para pedir 100 e receber 130.

As ferramentas

Ferramenta	O que faz
`po_add`	Criar uma ordem de compra: referência, fornecedor, linhas datadas, tolerâncias de excesso/falta
`grn_add`	Receber mercadorias contra uma OC aberta: recebido/danificado por linha, falta derivada
`grn_line_add`	Receber mais uma linha em uma GRN aberta
`grn_list`	GRNs mais recentes primeiro, filtradas por OC ou status
`grn_get`	Uma GRN: cada linha com recebido, danificado, falta e notas
`grn_discrepancy`	Linhas em falta, em excesso, danificadas ou fechadas com valores pendentes
`grn_close`	Fechar uma GRN quando a contagem estiver resolvida
`grn_status_report`	Cada OC: linhas abertas, recebido acumulado, o que ainda está pendente
`grn_export_csv`	GRNs como CSV (Pro)
`license_status`	Em qual nível esta instalação está e de onde veio a chave
`license_activate`	Armazenar uma chave Pro para este servidor

Início rápido

po_add  { "reference": "ACME-1001", "supplier": "Acme Trading",
          "lines": [ { "sku": "BRK-8", "description": "Bracket, steel", "ordered": 100 } ] }
grn_add { "po": "PO-0001",
          "lines": [ { "line": "L01", "received": 60 } ] }
grn_add { "po": "PO-0001",
          "lines": [ { "line": "L01", "received": 35, "damaged": 2 },
                     { "line": "L01", "received": 10 } ] }   // refused: 105 > 100 + 10%
grn_discrepancy {}                                        // L01 is 5 short of 100

Os IDs parecem com PO-0001 e GRN-0001; linhas dentro de uma OC são L01, L02, ….

Início rápido

{ "tool": "po_add", "args": { "reference": "ACME-1005", "supplier": "Acme Trading",
            "lines": [{ "sku": "BRK-01", "description": "Bracket, steel", "ordered": 10 }] } }
{ "tool": "grn_add", "args": { "po": "PO-0001", "lines": [{ "line": "L01", "received": 9, "damaged": 1 }] } }
{ "tool": "grn_discrepancy", "args": { "po": "PO-0001" } }

Uma GRN que chega além da tolerância de excesso é recusada; a falta é calculada como pedido menos recebido e mostrada como discrepância. grn_export_csv (Pro) grava todo o livro-razão como CSV.

Gratuito vs Pro

	Gratuito	Pro
Ordens de compra	até 2.000	até 2.000
GRNs	até 5.000	até 5.000
Linhas por OC / por GRN	até 200	até 200
`grn_list`, `grn_get`, `grn_discrepancy`, `grn_status_report`	sim	sim
`grn_export_csv`	não	sim

O domínio é limitado em todo o ambiente (2.000 OCs, 5.000 GRNs, 200 linhas) em todos os níveis — estas são regras rígidas para que uma loja não possa crescer além do que o formato de arquivo pode conter, não um paywall. O Pro desbloqueia exportação CSV para enviar recebimentos para uma planilha ou um ERP.

Obtenha o Pro: https://mcp.zovo.one/buy/goods-receipt (pagamento único), ou todos os servidores por um preço em https://mcp.zovo.one/buy/bundle

Privacidade

Todos os dados permanecem locais, em ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/goods-receipt/, em store.json (OCs e GRNs) e counter.json (as séries de OC e GRN). Não há chamada de rede em nenhum lugar deste servidor, nenhuma chave de API e nenhuma conta. O único arquivo que ele lê e que não é dele é o perfil de negócios compartilhado, e ele nunca grava nele.

Construído por theluckystrike. Suporte: support@zovo.one

Use estes documentos como um servidor MCP

Qualquer cliente MCP (Claude, Cursor, Windsurf, VS Code) pode ler a documentação deste repositório diretamente via GitMCP — sem instalação:

URL do MCP de Documentos: https://gitmcp.io/theluckystrike/mcp-goods-receipt