Catalogue MCP

Uma lista de preços e tabela de tarifas que os servidores de cotações e faturas leem por SKU.

Documentação

mcp-catalogue

Servidor MCP para lista de preços de produtos e tabela de tarifas. Uma lista de preços e uma tabela de tarifas, mantidas onde a fatura e o orçamento podem ler ambas.

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/catalogue — 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 (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/catalogue 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/catalogue/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 catalogue.mcpb do último lançamento 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-catalogue.git
cd mcp-catalogue
npm install && npm run build

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

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

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

catalogue demo

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

No Registro Oficial MCP (io.github.theluckystrike/catalogue). Uma lista de preços e uma tabela de tarifas, mantidas onde a fatura e o orçamento podem ler ambas. Dê a um produto um código, um nome, uma unidade e um preço em unidades menores, com o dia em que esse preço entra em vigor. Dê a um cargo uma tarifa horária da mesma forma. Em seguida, entregue ao catálogo uma lista do que um cliente tinha, e ele devolve os itens de linha já precificados: a quantidade, a descrição, o preço unitário e a taxa de IVA, no formato exato de argumento que invoice_create aceita e no formato exato de argumento que quote_create aceita.

Nada é inventado e nada é armazenado duas vezes. Um SKU contém suas LINHAS de preço, cada uma com uma data de validade; o preço em uma data é calculado na chamada, então aumentar um preço em julho não reescreve o que o trabalho de junho foi orçado. Um código desconhecido retorna uma recusa nomeando o código, nunca um preço adivinhado.

A publicação npm para @theluckystrike/mcp-catalogue está pendente, então npx -y @theluckystrike/mcp-catalogue retorna 404 hoje. Até lá, o pacote de um clique .mcpb ou um clone+compilação é o caminho que funciona.

Instalação

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Claude Code

claude mcp add catalogue -- npx -y @theluckystrike/mcp-catalogue

Cursor

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

Ferramentas

Ferramenta	O que faz
`sku_set`	Adiciona uma linha de catálogo ou redefine o preço de uma: código, nome, unidade, taxa de IVA opcional e um preço em unidades menores para uma moeda, nível e data de validade
`sku_get`	O preço de um SKU em uma data, nomeando a linha de onde veio e qualquer preço posterior já registrado
`sku_list`	O catálogo com o preço em vigor, filtrado por prefixo de código, moeda e nível
`sku_delete`	Exclui uma linha criada por engano. Somente aquela que nada depende. Gratuito em todos os níveis
`rate_set`	Define uma tarifa horária na tabela de tarifas de um cargo, a partir do dia em que se aplica, opcionalmente vinculada a um SKU
`rate_get`	A tarifa horária para um cargo em uma data, ou todas as tabelas de tarifas
`lines_resolve`	Precifica uma lista de linhas de sku e cargo em itens prontos para `invoice_create` e `quote_create`
`price_list_text`	A lista de preços como texto simples: preços em vigor, datas de validade e depois as tarifas de mão de obra
`price_list_pdf`	A lista de preços como PDF A4, por moeda e nível
`catalogue_report`	SKUs, linhas em vigor, linhas que uma linha posterior já substitui, linhas sem preço na moeda padrão
`license_status` / `license_activate`	Gratuito ou Pro, e onde atualizar

Gratuito vs Pro

	Gratuito	Pro
SKUs no catálogo	25	ilimitado
Linhas de preço por SKU	100	100
Tabelas de tarifas	ilimitadas	ilimitadas
Definir, precificar, listar, resolver linhas	sim	sim
Lista de preços (texto)	sim	sim
Excluir um SKU não utilizado	sim	sim
Níveis de preço além de `standard`	não	sim
Lista de preços (PDF)	não	sim
Relatório de catálogo	não	sim

Obtenha Pro: https://mcp.zovo.one/buy/catalogue ($19 único para este servidor, $39 para todos, vitalício). As chaves são verificadas offline; nada é enviado a lugar algum.

De onde vem o preço

Uma linha de preço é (currency, tier, valid_from, amount). O preço em uma data é o mais recente valid_from na ou antes dessa data, para essa moeda e esse nível. Definir uma linha em uma chave que já existe SUBSTITUI-a, então duas linhas nunca podem compartilhar uma chave e "o preço naquele dia" nunca é um cara ou coroa. Uma data anterior a todas as linhas não tem preço e é recusada; um preço que ainda não existia não é um preço.

Nada aqui converte moeda. Um preço em EUR exibido sob um título em PLN seria um número inventado, então um SKU sem preço na moeda solicitada é listado como não tendo nenhum, e catalogue_report os conta.

A percepção medida

Os dois servidores que este catálogo alimenta aceitam o mesmo preço em escalas diferentes, e a diferença é exatamente 100x. O item de invoice_create carrega unit_price em unidades MAIORES ("Preço por unidade em unidades maiores, ex.: 90 para 90 EUR", servers/invoice/src/index.ts); o item de quote_create carrega unit_price_minor em unidades MENORES ("9000 = 90,00 EUR, 90 = JPY 90. Nunca um decimal", servers/quotes/src/index.ts). Ambos os campos são chamados de preço unitário, ambos aceitam um número simples, e nenhuma ferramenta consegue dizer que o número que recebeu foi escalado para a outra: 45000 passado como unit_price é uma linha de fatura válida para EUR 45.000,00.

Medido na resolução trabalhada em test/unit.test.mjs: o payload correto rende EUR 2.613,63, e os mesmos itens com o campo do servidor de orçamento alimentado no motor do servidor de fatura rendem EUR 261.363,00, que o conjunto de testes afirma ser exatamente 100x. Em uma moeda de 3 decimais, como KWD, é 1000x. Portanto, o catálogo armazena unidades menores, que é a única forma sem perdas, e constrói AMBOS os payloads ele mesmo em uma chamada, imprimindo a escala contra cada um. Essa é toda a razão pela qual lines_resolve retorna dois payloads em vez de um "preço" que o chamador remodela.

A segunda metade disso: todo preço armazenado é um número inteiro de unidades menores, então o próprio computeTotals de invoice_create arredonda a forma de unidades maiores direto de volta ao inteiro de onde veio. rounding_drift_minor em uma resolução é zero por construção e o conjunto de testes afirma isso, que é a forma verificável por máquina de "a fatura mostrará o valor que a lista de preços mostrou".

Privacidade

Todos os dados permanecem locais: ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/catalogue/. Nenhuma chamada de rede é feita por qualquer ferramenta. O único arquivo fora desse diretório que este servidor toca é o perfil de negócios compartilhado, somente leitura, para a moeda padrão, a taxa de IVA padrão e o nome no topo da lista de preços. Ele não cria fatura nem orçamento.

Construído por theluckystrike.

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 MCP dos documentos: https://gitmcp.io/theluckystrike/mcp-catalogue