Credit Note MCP

Notas de crédito contra uma fatura ou avulsas: rascunhos, finalização, renderização, totais.

Documentação

mcp-credit-note

Servidor MCP para notas de crédito e créditos contra uma fatura ou avulsos. Notas de crédito contra uma fatura ou avulsas: rascunhos, finalização, renderização e totais, tudo em unidades monetárias inteiras.

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

Página do produto: https://mcp.zovo.one/s/credit-note — 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 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/credit-note 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/credit-note/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 credit-note.mcpb do último lançamento e clique duas vezes nele.

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

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

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

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

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

credit-note demo

Espelho somente leitura de mcp-servers/servers/credit-note. Veja MIRROR.md.

No Registro Oficial do MCP (io.github.theluckystrike/credit-note). Notas de crédito (créditos) para freelancers e pequenas empresas, mantidas da forma como a papelada as mantém. Emita um crédito contra uma fatura ou avulso: o destinatário, o motivo (mercadoria devolvida, cobrança a maior, correção de desconto, problema no serviço, outro), itens de linha com quantidade, preço unitário e alíquota de imposto, e a moeda. Toda nota de crédito começa como um rascunho que você pode revisar e excluir; a finalização grava o número final CN-YYYY-NNNN e o congela, porque uma nota de crédito finalizada é um documento que o cliente pode ter visto. Renderize uma em Markdown para colar em um e-mail, ou em uma página HTML imprimível autossuficiente, e obtenha os totais creditados por moeda, motivo e mês. Todo valor é um número inteiro de unidades monetárias, e nada é enviado a lugar algum.

Criado por theluckystrike.

A publicação no npm para @theluckystrike/mcp-credit-note está pendente, então npx -y @theluckystrike/mcp-credit-note retorna 404 hoje. Até lá, clonar+compilar é o caminho que funciona.

Instalação

Claude Desktop

macOS ~/Library/Application Support/Claude/claude_desktop_config.json, Windows %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "credit-note": {
      "command": "npx",
      "args": ["-y", "@theluckystrike/mcp-credit-note"]
    }
  }
}

Claude Code

claude mcp add credit-note -- npx -y @theluckystrike/mcp-credit-note

Cursor

~/.cursor/mcp.json (global) ou .cursor/mcp.json (projeto), mesma entrada do Claude Desktop.

Ferramentas

ferramenta	o que faz
`credit_note_create`	Emite uma nota de crédito contra uma fatura ou avulsa: destinatário, motivo, linhas com quantidade, preço unitário em unidades monetárias e alíquota de imposto, moeda. Retorna um rascunho `CN-DRAFT-YYYY-NNNN`
`credit_note_update`	Revisa um rascunho enquanto ainda é rascunho: destinatário, motivo, linhas, moeda, referência da fatura, data de emissão ou notas. Novas linhas substituem todas as antigas. Uma nota finalizada é recusada pelo nome
`credit_note_finalize`	Grava o número final `CN-YYYY-NNNN` e congela a nota: a partir daqui ela não pode ser editada ou excluída, apenas renderizada e listada
`credit_note_list`	Lista notas de crédito com número, destinatário, motivo, status, data de emissão e total. Filtra por destinatário, motivo, status e período de data de emissão
`credit_note_get`	Lê uma nota de crédito completa pelo número CN ou id do rascunho: cada linha, as linhas de imposto, os totais, o motivo e as notas
`credit_note_delete`	Exclui um rascunho inserido incorretamente. Uma nota finalizada é recusada: é um documento que o cliente pode ter visto
`credit_note_render`	Renderiza uma nota de crédito como Markdown para colar em um e-mail, ou como uma página HTML imprimível autossuficiente. Rascunhos são renderizados com um aviso de RASCUNHO
`credit_note_summary`	Total creditado por moeda em notas finalizadas, dividido por motivo e por mês, em um período opcional de data de emissão
`license_status` / `license_activate`	Gratuito ou Pro, e a chave

Gratuito vs Pro

	Gratuito	Pro
Notas de crédito finalizadas	10, vitalício	Ilimitado
Rascunhos (`credit_note_create`, `credit_note_update`)	Ilimitado	Ilimitado
Excluir um rascunho (`credit_note_delete`)	Sim	Sim
Listagem, leitura (`credit_note_list`, `credit_note_get`)	Ilimitado	Ilimitado
Renderização (`credit_note_render`)	Ilimitado, rodapé de uma linha	Ilimitado, sem rodapé
Totais (`credit_note_summary`)	Ilimitado	Ilimitado

Finalizar é o ato medido porque é o que transforma um rascunho no documento que o cliente vê. Todo o resto é gratuito e ilimitado: um nível gratuito que retém o documento renderizado ou os totais é uma demonstração, e dez notas de crédito finalizadas reais é um ano de trabalho para um freelancer que credita uma fatura de vez em quando.

Obtenha Pro: https://mcp.zovo.one/buy/credit-note, $19 pagamento único para este servidor, ou $39 para o pacote.

A regra de arredondamento

Todo valor é um número inteiro de unidades monetárias (centavos), e a matemática das linhas é documentada para que o documento impresso se reproduza em uma calculadora:

O preço unitário entra como unidades monetárias inteiras, então nada é arredondado na entrada. O bruto da linha é quantidade x preço unitário, arredondado meio para cima uma vez: gross = round_half_up(quantity * unit_price_minor). Uma quantidade inteira é exata; uma fracionária (2,5 horas a EUR 33,33) cai no centavo mais próximo, e 2,5 x 3333 = 8332,5 arredonda para 8333, nunca o 8332 do arredondamento bancário.
O imposto é calculado por linha e arredondado meio para cima por linha: tax = round_half_up(gross * rate / 100).
O total da linha é bruto + imposto, e os totais da nota são somas inteiras simples dos valores de linha já arredondados.

Arredonde por linha, depois some: um total nunca pode divergir das linhas impressas além do arredondamento já visível nessas linhas, então a linha de imposto a 23% tem sua própria base (apenas as linhas de 23%), não o subtotal inteiro.

Numeração

Rascunhos carregam um id CN-DRAFT-YYYY-NNNN que nenhum cliente vê. O número final CN-YYYY-NNNN é atribuído apenas na finalização, no ano da data de emissão, e o contador é gravado antes do registro, então uma falha queima um número em vez de reutilizá-lo. Como rascunhos nunca têm um número final e notas finalizadas não podem ser excluídas, a série final nunca tem lacunas.

Privacidade

Todos os dados permanecem locais, em ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/credit-note/. Dois arquivos: notes.json, counter.json. Nada é enviado a lugar algum, não há conta, nenhuma chave de API e nenhuma chamada de rede neste servidor. Chaves de licença são verificadas offline. As renderizações em Markdown e HTML são retornadas como texto; este servidor não grava arquivos de documento.

Criado por theluckystrike. https://github.com/theluckystrike

Use estas documentações 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 de documentação MCP: https://gitmcp.io/theluckystrike/mcp-credit-note