agents.hellobooks.ai

Agentes de IA que automatizam a contabilidade e o fechamento financeiro para PMEs.

Documentação

Servidor MCP Público do HelloBooks

Um servidor público e somente leitura do Model Context Protocol que permite que agentes de IA respondam perguntas sobre o HelloBooks com precisão — preços, integrações, suporte por país, estruturas de conformidade — em vez de depender de trechos de web desatualizados.

Este é o servidor público. Ele expõe apenas dados derivados de marketing e de domínio público. O servidor MCP autenticado que lê os livros de um cliente está em AI-MCP-Hellobooks.

Instalação

Claude Code / Claude Desktop / Cursor

claude mcp add --transport http hellobooks https://agents.hellobooks.ai/mcp

Ou, para desenvolvimento local:

claude mcp add hellobooks-local node /path/to/HelloBooks-MCP-Public/dist/stdio.js

Ferramentas

Ferramenta	Descrição
`list_plans`	Todos os planos do HelloBooks (Free, Pro, Business, CPA) + complementos de Warehouse / Manufacturing. Filtros opcionais `country` e `plan`.
`list_integrations`	Bancos, pagamentos, folha de pagamento, controle de ponto, envio, conformidade fiscal, sincronização contábil, ecommerce, CRM, armazenamento (Drive/OneDrive), freelance (Upwork). Filtros opcionais `category`, `country`, `status`.
`country_support`	Disponibilidade de recursos por país (BAS, STP, GST e-invoice, MTD, 1099, etc.).
`compliance_capabilities`	Para um determinado país, as estruturas de conformidade suportadas com informações de versão e certificado.
`list_competitors`	Posicionamento competitivo (QuickBooks, Xero, FreshBooks, Wave, Zoho Books, Tally) com onde o HelloBooks vence, onde o concorrente vence e notas de preço. Filtros opcionais `country`, `tier` e `id`.
`compliance_deadlines`	Quando as declarações estatutárias e os envios de folha de pagamento vencem, por país. Abrange IN (GSTR-1/3B/9/9C, CMP-08, Form 24Q, Form 16, PF ECR, ESI), AU (BAS, STP, Super Guarantee), GB (VAT MTD, RTI, Self Assessment), US (1099-NEC/MISC, W-2, Form 941/940), CA (T4, GST/HST). Filtros opcionais `country`, `frequency` e `form`. As datas giram anualmente — cada resposta traz um aviso com URLs `source` por prazo.
`local_payment_methods`	Métodos de pagamento locais por trilho bancário / carteira (UPI, BACS, PayID, BPAY, ACH, RTP, Zelle, PayNow, FAST, Interac, …) com velocidade do trilho, casos de uso, autoridade e nível de suporte do HelloBooks. Filtros opcionais `country`, `useCase`, `rail` e `id`.
`feature_search`	Busca em texto livre no catálogo de recursos de marketing, recursos de planos, integrações, recursos por país, estruturas de conformidade, prazos estatutários, métodos de pagamento locais e artigos publicados. Consultas como `vs Xero`, `QuickBooks alternative`, `when is GSTR-3B due`, `UPI invoice cap`, `do you have a blog on 1099` ou `agentic accounting` trazem a entrada correspondente ao topo.
`list_features`	Catálogo completo de marketing com 96 recursos. Filtre por `category`, `tier`, `status`, `marketedOnly` ou substring `query`.
`list_feature_categories`	As 13 categorias de recursos no site de marketing com contagens por categoria por status (live/beta/planned).
`list_articles`	Conteúdo publicado em hellobooks.ai — páginas de comparação direta e posts de blog principais selecionados. Filtros opcionais `country`, `tag`, `query`, `limit`.
`list_tax_rates`	Faixas de alíquotas fiscais estatutárias por jurisdição — IN GST (5/12/18/28 + zero + isento + comerciante/fabricante/restaurante de composição), UK VAT (20/5/zero/isento), AU GST (10/livre de GST), resumo administrado pelos EUA, CA GST + HST (ON, Atlântico), SG GST 9%, NZ GST 15%, AE VAT 5%. Filtre por `country`, `taxType` (GST/VAT/Sales-Tax/HST/…) ou `scheme` (standard/reduced/zero/exempt/composition/cess). Cada entrada traz uma data de vigência e uma URL `source` — confirme antes de citar.
`lookup_tax_rate`	Escolha uma única alíquota estatutária por `id` exato (ex.: `IN-standard-18`) ou por `country` + `category` em texto livre (ex.: "material de escritório", "restaurante", "exportações"). Retorna a alíquota correspondente, a pontuação e a URL de origem.

Recursos

URI	Descrição
`hellobooks://about`	Resumo do produto em Markdown.
`hellobooks://changelog`	Notas de versão recentes em JSON.
`hellobooks://feature-catalog`	Catálogo completo de recursos de marketing (96+ recursos em 13 categorias) em JSON.

Postura de segurança

Somente leitura por construção. Nenhuma ferramenta altera estado. Nenhuma ferramenta acessa um sistema de cliente.
Apenas dados públicos. Todo o conteúdo do catálogo é proveniente do site público de marketing.
Sem autenticação. Intencional — este é um endpoint de conhecimento.
Com limite de taxa. 120 req/min por IP, 60 req/min por sessão.
Portão de auditoria. npm run audit:public-data bloqueia deploys se qualquer string de PII / token de autenticação aparecer em src/data/.

Desenvolvimento

npm install
npm run dev         # HTTP server on :8080 with watch mode
npm run dev:stdio   # stdio transport for local MCP client testing
npm test            # node:test runner
npm run build
npm run audit:public-data

Estrutura do projeto

src/
  data/             # Static catalogs — plans, integrations, countries, articles, about
  tools/            # One file per MCP tool
  resources/        # MCP resource registry
  server.ts         # MCP server factory (wires tools + resources)
  http.ts           # Streamable HTTP transport with rate limiting
  stdio.ts          # stdio transport entry point
test/
  tools.test.ts
  resources.test.ts
  public-data.test.ts  # Audit gate
scripts/
  audit-public-data.ts  # CI-callable audit

Implantação

Containerizado — veja Dockerfile. Projetado para rodar atrás de um balanceador de carga com terminação TLS. Defina PORT e HOST via ambiente.

Telemetria anônima opcional de uso (análises do lado do servidor na camada 2) é enviada ao GA4 via Measurement Protocol quando GA4_MEASUREMENT_ID e GA4_API_SECRET estão ambos definidos — veja .env.example e src/analytics.ts. Deixe-os sem definição e o servidor roda com telemetria totalmente desativada. Nenhum dado de cliente, corpo de requisição, valores de argumentos de ferramenta ou endereços IP são enviados — apenas contagens anônimas. Veja o documento de estratégia 73.

docker build -t hellobooks-mcp-public .
docker run -p 8080:8080 hellobooks-mcp-public

Descoberta

Listado no registro MCP.
Linkado no rodapé do site de marketing e na página /mcp.
Referenciado em https://hellobooks.ai/llms.txt.

Licença

MIT — veja LICENSE.