hane-mcp-client 1.2.2

Cliente MCP leve para o servidor HANE — extracao de entidades e analise semantica de documentos ERP/fiscal/juridico

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.

---

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.

---

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.

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 — fale com a gente: [e-mail].

---

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.

haneia.com.br · [e-mail] · Software registrado no INPI (BR 51 2026 002247-9)