Metadata-Version: 2.4
Name: hane-mcp-client
Version: 1.2.2
Summary: Cliente MCP leve para o servidor HANE — extracao de entidades e analise semantica de documentos ERP/fiscal/juridico
Author-email: HaneIA Tecnologia <contato@haneia.com.br>
Maintainer-email: Jacion Silva <jacion.silva@haneia.com.br>
License: Proprietary
Project-URL: Homepage, https://github.com/JacionSilva/hane
Project-URL: Repository, https://github.com/JacionSilva/hane
Keywords: mcp,ner,nlp,hane,advpl,totvs,fiscal,juridico,claude
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=3.2.4
Requires-Dist: pypdf>=4.0
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# hane-mcp-client

[![PyPI](https://img.shields.io/pypi/v/hane-mcp-client.svg)](https://pypi.org/project/hane-mcp-client/)
[![Python](https://img.shields.io/pypi/pyversions/hane-mcp-client.svg)](https://pypi.org/project/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**

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

**2. Pegue sua API Key** em [haneia.com.br](https://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):

```json
{
  "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**: [contato@haneia.com.br](mailto: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](https://haneia.com.br/privacidade.html) (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:

```json
"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](https://haneia.com.br) · [contato@haneia.com.br](mailto:contato@haneia.com.br) · Software registrado no INPI (BR 51 2026 002247-9)
