hane-mcp-client

Pare de gastar tokens enviando documentos inteiros para o LLM.

hane-mcp-client conecta o Claude Code (ou qualquer cliente MCP) ao pipeline HANE — um extrator de entidades com compressão semântica hierárquica que entrega ao LLM apenas a informação estruturada de um documento, sem chamar nenhum LLM internamente e sem expor o conteúdo bruto.

Resultado típico: ~70% menos tokens no prompt, em PT-BR, para contratos, notas fiscais, código ERP e documentos jurídicos.

🚀 Experimente agora, sem instalar nem precisar de chave: demo ao vivo em haneia.com.br — cole um trecho e veja a compressão acontecer.

---

O problema que ele resolve

No fluxo normal, para o Claude analisar um arquivo de 1.000 palavras ele precisa lê-lo para o contexto — e você paga por cada token, duas vezes (entrada do arquivo + reprocessamento):

Claude lê o arquivo    →  ~1.000 tokens no contexto
Claude reenvia o texto →  +1.000 tokens
Total: ~2.000 tokens por documento

Com o HANE, o arquivo é lido no seu disco, processado e o Claude recebe só as entidades comprimidas:

annotate_file_local("contrato.pdf")  →  1 linha
HANE extrai e comprime               →  ~80 tokens de entidades
Total: ~80 tokens  ·  o Claude nunca vê o documento bruto

~25× menos tokens no documento — e o conteúdo sensível não transita pelo modelo.

Exemplo real

Entrada — seção CALENDÁRIO de um edital público (Programa Scale IA 2026 — Sebrae Startups + AKCIT/CEIA/UFG):

5. CALENDÁRIO. Período de inscrições do Programa Scale IA, com etapas em
São Paulo (Feira do Empreendedor 2026) e Florianópolis: 26/04/2026,
05/05/2026, 06/05/2026, 30/05/2026, 27/06/2026, 25/07/2026, 15/08/2026,
12/09/2026, 03/10/2026 e Demo Day de 19 a 22/10/2026.

Saída do HANE — domínio juridico, −66% tokens, sem chamar nenhum LLM:

[Data]         26/04/2026 | 05/05/2026 | 06/05/2026 | 30/05/2026 | 27/06/2026 |
               25/07/2026 | 15/08/2026 | 12/09/2026 | 03/10/2026
[Cidade]       São Paulo | Florianópolis
[Periodo]      Feira do Empreendedor 2026 | 19 a 22/10/2026
[ORGANIZACAO]  Programa Scale IA

É isso que o Claude recebe — só os fatos estruturados, não o documento inteiro. (Run real do pipeline; a cobertura por entidade varia com o domínio e o threshold.)

---

Por que confiar nos números

Medições reais do pipeline HANE (não estimativas de marketing):

Métrica	Valor	Contexto
Redução de tokens no prompt	~70%	média em lote de documentos
F1 de extração	0.853	28 manuais técnicos TOTVS
Custo GPT-4o em lote	$2.99 → $0.44	mesmos 28 documentos, pós-compressão
Caso real (TJ-GO)	−86% tokens	63 acórdãos, latência E2E mediana 147ms
Latência pós-otimização	11,4× mais rápido	248s → 21s por documento

Motor por trás do client: pipeline HANE de 6 camadas (grafo semântico comprimido → NER hierárquico por ontologia → budget adaptativo por entropia → cache matricial de padrões → extração determinística por regex → grafo de memória de contexto entre turnos). Software registrado no INPI (BR 51 2026 002247-9).

---

Início rápido (3 passos)

1. Instale

pip install hane-mcp-client
# ou, sem instalar de forma permanente:
uvx hane-mcp-client

2. Pegue sua API Key em haneia.com.br — há plano de avaliação (trial).

3. Configure o Claude Code — adicione ao ~/.claude.json (já apontando para a API oficial; basta colar sua chave):

{
  "mcpServers": {
    "hane": {
      "command": "uvx",
      "args": ["hane-mcp-client"],
      "env": {
        "HANE_MODE": "rest",
        "HANE_API_URL": "https://haneia.com.br",
        "HANE_API_KEY": "COLE_SUA_API_KEY_AQUI"
      }
    }
  }
}

Reinicie o Claude Code e as ferramentas HANE ficam disponíveis no chat. Sem servidor para subir, sem modelo para baixar — a API oficial já está no ar.

Requer Python 3.10+. Este pacote é só o cliente (a ponte MCP, ~15 kB): o modelo e o pipeline rodam no servidor HANE, o que mantém o client leve (apenas fastmcp + pypdf) e o motor protegido.

---

Ferramentas disponíveis

Ferramenta	O que faz
annotate_file_local	Lê um arquivo do disco (.pdf, .docx, .txt, .prw, .py…) e retorna só as entidades comprimidas. O Claude nunca vê o conteúdo bruto.
extract_entities	Extrai entidades de um texto colado no chat, por domínio.
compare_documents	Diff semântico entre duas versões de um documento — o que mudou de fato, não diferença de texto cru.
estimate_tokens	Estima a economia de tokens antes de processar (leve, sem GPU).
get_status	Estado do servidor HANE e configuração de privacidade.
get_context_summary	(Camada 6 / CMG) Grafo de contexto acumulado na sessão — entidades já estabelecidas, em formato compacto para o prompt.
reset_context	(Camada 6 / CMG) Reinicia o contexto da sessão (próxima extração começa do turno 1).

Camada 6 — memória de contexto (CMG). Além de comprimir cada documento, o HANE comprime entre turnos de uma sessão: em chamadas seguintes, envia ao LLM só o delta (entidades novas), não o histórico inteiro. Em modo REST, passe session_id no extract_entities e a resposta traz o bloco cmg com o delta; em modo MCP, use get_context_summary / reset_context. Economia inter-turnos típica: 73–78%.

Memória entre sessões no Claude Code (opcional)

Para que uma nova conversa do Claude Code comece já com o contexto das anteriores (entidades técnicas do projeto), instale os hooks de sessão:

pip install -U hane-mcp-client       # pré-requisito: versão >= 1.2.8
hane-mcp-client --install-hooks      # registra os hooks no ~/.claude/settings.json (com backup)
hane-mcp-client --uninstall-hooks    # remove

Pré-requisitos: hane-mcp-client ≥ 1.2.8 e reiniciar o Claude Code após instalar (os hooks só passam a valer numa nova sessão).

O que faz (100% local, sem servidor): a cada mensagem extrai entidades (~0ms, sem modelo), mantém um grafo por projeto em .cmg_graph.json, e ao abrir uma nova sessão injeta um resumo compacto (~180 tokens) do que já foi estabelecido. Opt-in e reversível — o merge no settings.json preserva seus outros hooks.

Telemetria do que o CMG economizou entre janelas de conversa:

hane-mcp-client --cmg-stats    # turnos, tokens sem CMG vs com CMG, % economizado

Domínios suportados em extract_entities

Domínio	Ideal para
fiscal	NF-e, SPED, DANFE, ICMS, CFOP, NCM
juridico	contratos, cláusulas, partes, prazos, nº de processo
erp	Protheus / TOTVS, módulos, parâmetros MV_
advpl	código .prw/.tlpp, funções, tabelas SA/SB
financeiro	CNAB, remessa, retorno, débitos
medico	prontuários, CID, diagnósticos
code	Python, JavaScript, SQL e outras linguagens
auto	detecção automática de domínio

---

On-premise (sua infraestrutura, seus dados)

Para quem não pode enviar documentos para fora — órgãos públicos, jurídico, saúde, fiscal — o HANE roda on-premise, em container Docker na sua rede:

• Documentos nunca saem da sua infraestrutura
• Licença assinada (RSA-PSS), validação local
• Mesmas ferramentas, apontando o client para o seu servidor (HANE_API_URL=http://seu-servidor:8000)

A contratação on-premise é feita sob demanda — Falar com a equipe → (resposta em até 24h). Ou por e-mail: contato@haneia.com.br.

---

Modos de operação e privacidade (LGPD)

Onde o seu texto trafega depende da combinação de modo e destino. Seja explícito sobre isso ao tratar dados pessoais:

Cenário	Configuração	Onde o texto vai	Anonimização
On-premise	rest + HANE_API_URL=http://seu-servidor	Não sai da sua rede	Desnecessária
SaaS oficial	rest + HANE_API_URL=https://haneia.com.br	Servidor HaneIA, tratado conforme a Política de Privacidade (LGPD)	Não atua no client
MCP remoto	mcp + HANE_ANONYMIZE=true	Servidor MCP remoto	Mascara CPF e e-mail pessoal antes do envio

Anonimização no client (HANE_ANONYMIZE)

Ativa somente com HANE_MODE=mcp — quando o texto trafega por um servidor MCP remoto que você não controla:

"env": { "HANE_MODE": "mcp", "HANE_ANONYMIZE": "true" }

O que é mascarado antes de o texto sair da sua máquina, em conformidade com a Lei 13.709/2018 (LGPD):

Dado	Regra	Vira
CPF	\d{3}.\d{3}.\d{3}-\d{2}	[CPF]
E-mail pessoal	domínios gmail / hotmail / outlook / yahoo / icloud / live	[EMAIL]

• CNPJ e razão social NÃO são mascarados — identificam pessoa jurídica, que está fora do escopo da LGPD (Art. 5º, I). Os dados de empresa permanecem para a extração de entidades.
• O resultado inclui um contador lgpd_anonimizacao: {cpf, email} com o número de substituições feitas — auditável.
• get_status reporta anonimizacao_ativa e o escopo em vigor.

Em HANE_MODE=rest a anonimização não roda: ou o texto fica na sua infraestrutura (on-premise) ou vai para a API oficial sob a Política de Privacidade da HaneIA. Para mascaramento client-side antes do envio, use mcp + HANE_ANONYMIZE=true.

Variáveis de ambiente

Variável	Padrão	Descrição
HANE_MODE	rest	rest ou mcp
HANE_API_URL	http://localhost:8000	URL base da REST API (oficial: https://haneia.com.br)
HANE_MCP_URL	http://localhost:8081/mcp	URL do servidor MCP remoto
HANE_API_KEY	—	Chave da REST API
HANE_MCP_TOKEN	—	Bearer token do MCP
HANE_ANONYMIZE	false	Anonimiza CPF/e-mail (só em HANE_MODE=mcp)

---

Sobre a HaneIA

HANE — Hierarchical Adaptive NER Encoder. Desenvolvido pela HANEIA TECNOLOGIA E INOVAÇÃO LTDA, focado em documentos brasileiros em português.

Falar com a equipe → · Site: haneia.com.br · E-mail: contato@haneia.com.br · Software registrado no INPI (BR 51 2026 002247-9)