hane-mcp-client 1.2.0__tar.gz

hane_mcp_client-1.2.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: hane-mcp-client
+Version: 1.2.0
+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>
+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
+
+Cliente MCP leve para o servidor **HANE** — extração de entidades e análise semântica de documentos ERP, fiscal e jurídico.
+
+Conecta o Claude Code (e qualquer LLM compatível com MCP) ao pipeline HANE sem expor o código-fonte do servidor.
+
+## Instalação
+
+```bash
+pip install hane-mcp-client
+# ou, sem instalar permanentemente:
+uvx hane-mcp-client
+```
+
+## Configuração no Claude Code
+
+Adicione ao `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "hane": {
+      "command": "uvx",
+      "args": ["hane-mcp-client"],
+      "env": {
+        "HANE_MODE": "rest",
+        "HANE_API_URL": "http://localhost:8000",
+        "HANE_API_KEY": "sua_api_key"
+      }
+    }
+  }
+}
+```
+
+## Modos de operação
+
+| Variável `HANE_MODE` | Descrição |
+|---|---|
+| `rest` | Chama a REST API HANE (local ou remota) |
+| `mcp` | Conecta diretamente ao servidor MCP HANE via HTTP |
+
+## Ferramentas disponíveis
+
+- `extract_entities` — extração de entidades por domínio (ERP, fiscal, jurídico, código)
+- `annotate_file_local` — processa arquivo do disco sem expor conteúdo ao LLM
+- `compare_documents` — diff semântico entre dois documentos
+- `estimate_tokens` — estima economia de tokens antes de processar
+- `get_status` — status do servidor HANE
+
+## Requisitos
+
+- Python 3.10+
+- Servidor HANE acessível (on-premise via Docker ou SaaS em haneia.com.br)
+- API Key HaneIA
+
+## Documentação
+
+[haneia.com.br](https://haneia.com.br) · [contato@haneia.com.br](mailto:contato@haneia.com.br)

hane_mcp_client-1.2.0/README.md

@@ -0,0 +1,58 @@
+# hane-mcp-client
+
+Cliente MCP leve para o servidor **HANE** — extração de entidades e análise semântica de documentos ERP, fiscal e jurídico.
+
+Conecta o Claude Code (e qualquer LLM compatível com MCP) ao pipeline HANE sem expor o código-fonte do servidor.
+
+## Instalação
+
+```bash
+pip install hane-mcp-client
+# ou, sem instalar permanentemente:
+uvx hane-mcp-client
+```
+
+## Configuração no Claude Code
+
+Adicione ao `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "hane": {
+      "command": "uvx",
+      "args": ["hane-mcp-client"],
+      "env": {
+        "HANE_MODE": "rest",
+        "HANE_API_URL": "http://localhost:8000",
+        "HANE_API_KEY": "sua_api_key"
+      }
+    }
+  }
+}
+```
+
+## Modos de operação
+
+| Variável `HANE_MODE` | Descrição |
+|---|---|
+| `rest` | Chama a REST API HANE (local ou remota) |
+| `mcp` | Conecta diretamente ao servidor MCP HANE via HTTP |
+
+## Ferramentas disponíveis
+
+- `extract_entities` — extração de entidades por domínio (ERP, fiscal, jurídico, código)
+- `annotate_file_local` — processa arquivo do disco sem expor conteúdo ao LLM
+- `compare_documents` — diff semântico entre dois documentos
+- `estimate_tokens` — estima economia de tokens antes de processar
+- `get_status` — status do servidor HANE
+
+## Requisitos
+
+- Python 3.10+
+- Servidor HANE acessível (on-premise via Docker ou SaaS em haneia.com.br)
+- API Key HaneIA
+
+## Documentação
+
+[haneia.com.br](https://haneia.com.br) · [contato@haneia.com.br](mailto:contato@haneia.com.br)

hane_mcp_client-1.2.0/hane_mcp_client.egg-info/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: hane-mcp-client
+Version: 1.2.0
+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>
+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
+
+Cliente MCP leve para o servidor **HANE** — extração de entidades e análise semântica de documentos ERP, fiscal e jurídico.
+
+Conecta o Claude Code (e qualquer LLM compatível com MCP) ao pipeline HANE sem expor o código-fonte do servidor.
+
+## Instalação
+
+```bash
+pip install hane-mcp-client
+# ou, sem instalar permanentemente:
+uvx hane-mcp-client
+```
+
+## Configuração no Claude Code
+
+Adicione ao `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "hane": {
+      "command": "uvx",
+      "args": ["hane-mcp-client"],
+      "env": {
+        "HANE_MODE": "rest",
+        "HANE_API_URL": "http://localhost:8000",
+        "HANE_API_KEY": "sua_api_key"
+      }
+    }
+  }
+}
+```
+
+## Modos de operação
+
+| Variável `HANE_MODE` | Descrição |
+|---|---|
+| `rest` | Chama a REST API HANE (local ou remota) |
+| `mcp` | Conecta diretamente ao servidor MCP HANE via HTTP |
+
+## Ferramentas disponíveis
+
+- `extract_entities` — extração de entidades por domínio (ERP, fiscal, jurídico, código)
+- `annotate_file_local` — processa arquivo do disco sem expor conteúdo ao LLM
+- `compare_documents` — diff semântico entre dois documentos
+- `estimate_tokens` — estima economia de tokens antes de processar
+- `get_status` — status do servidor HANE
+
+## Requisitos
+
+- Python 3.10+
+- Servidor HANE acessível (on-premise via Docker ou SaaS em haneia.com.br)
+- API Key HaneIA
+
+## Documentação
+
+[haneia.com.br](https://haneia.com.br) · [contato@haneia.com.br](mailto:contato@haneia.com.br)

hane_mcp_client-1.2.0/hane_mcp_client.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+hane_mcp_client.py
+pyproject.toml
+hane_mcp_client.egg-info/PKG-INFO
+hane_mcp_client.egg-info/SOURCES.txt
+hane_mcp_client.egg-info/dependency_links.txt
+hane_mcp_client.egg-info/entry_points.txt
+hane_mcp_client.egg-info/requires.txt
+hane_mcp_client.egg-info/top_level.txt

hane_mcp_client-1.2.0/hane_mcp_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hane_mcp_client-1.2.0/hane_mcp_client.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hane-mcp-client = hane_mcp_client:main

hane_mcp_client-1.2.0/hane_mcp_client.egg-info/requires.txt

@@ -0,0 +1,6 @@
+fastmcp>=3.2.4
+pypdf>=4.0
+
+[dev]
+build
+twine

hane_mcp_client-1.2.0/hane_mcp_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+hane_mcp_client

hane_mcp_client-1.2.0/hane_mcp_client.py

@@ -0,0 +1,576 @@
+"""
+HANE MCP Client (v1.2 — LGPD anonimização)
+
+MCP Server leve para instalação no cliente.
+Conecta o Claude Code ao servidor HANE para extração de entidades e análise semântica
+de documentos ERP, fiscal, jurídico e código ADVPL.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+MODOS DE OPERAÇÃO (HANE_MODE)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  HANE_MODE=rest  (padrão)
+    Chama a REST API local (Docker) via HTTP.
+    O texto nunca sai da máquina do cliente — LGPD não se aplica ao trânsito.
+    Requer: Docker com hane-api:latest rodando (porta 8000).
+
+  HANE_MODE=mcp
+    Chama o servidor HANE remoto via protocolo MCP over HTTP (ex: ngrok).
+    O texto transita por infraestrutura externa — LGPD se aplica.
+    Requer: hane_mcp.py rodando e exposto (ex: ngrok porta 8081).
+    Recomendado: ativar HANE_ANONYMIZE=true para dados pessoais.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+VARIÁVEIS DE AMBIENTE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  HANE_MODE        : "rest" ou "mcp"               (padrão: rest)
+  HANE_API_URL     : URL base da REST API           (padrão: http://localhost:8000)
+  HANE_MCP_URL     : URL do servidor MCP remoto     (padrão: http://localhost:8081/mcp)
+  HANE_API_KEY     : chave REST                     (opcional)
+  HANE_MCP_TOKEN   : Bearer token MCP               (opcional)
+  HANE_ANONYMIZE   : "true" para anonimizar CPF e   (padrão: false)
+                     e-mails pessoais antes do envio
+                     Só tem efeito em HANE_MODE=mcp.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+LGPD — ANONIMIZAÇÃO (Lei 13.709/2018)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+A LGPD protege dados de pessoa natural (Art. 5º, I).
+Pessoa jurídica (CNPJ, razão social) está fora do escopo.
+
+O que é anonimizado quando HANE_ANONYMIZE=true:
+  • CPF       — regex \\d{3}\\.?\\d{3}\\.?\\d{3}-?\\d{2}
+                → substituído por [CPF]
+  • E-mail pessoal — domínios: gmail, hotmail, outlook, yahoo, icloud, live
+                → substituído por [EMAIL]
+
+O que NÃO é anonimizado (não é dado pessoal):
+  • CNPJ         — identifica pessoa jurídica, não natural
+  • Razão social / nome de empresa
+  • Valores fiscais (ICMS, PIS, COFINS, CFOP, CST, NCM)
+  • Endereço de empresa
+  • Código-fonte ADVPL (dado técnico)
+
+Quando usar HANE_ANONYMIZE:
+  ✅ HANE_MODE=mcp — texto transita por servidor remoto (ngrok, VPS)
+  ❌ HANE_MODE=rest — texto fica na máquina local (Docker), sem necessidade
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+CONFIGURAÇÃO NO CLAUDE CODE (~/.claude.json)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Opção 1 — uvx (PyPI, sem copiar arquivo):
+  {
+    "mcpServers": {
+      "hane": {
+        "command": "uvx",
+        "args": ["hane-mcp-client"],
+        "env": {
+          "HANE_API_URL": "http://localhost:8000",
+          "HANE_API_KEY": "SUA_API_KEY"
+        }
+      }
+    }
+  }
+
+  Opção 2 — python local (arquivo copiado):
+  {
+    "mcpServers": {
+      "hane": {
+        "command": "python",
+        "args": ["caminho/para/hane_mcp_client.py"],
+        "env": {
+          "HANE_MODE": "mcp",
+          "HANE_MCP_URL": "https://<seu-ngrok>.ngrok-free.dev/mcp",
+          "HANE_MCP_TOKEN": "seu_token_aqui",
+          "HANE_ANONYMIZE": "true"
+        }
+      }
+    }
+  }
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import re
+import urllib.error
+import urllib.request
+from typing import Any
+
+from fastmcp import FastMCP, Client
+from fastmcp.client.transports import StreamableHttpTransport
+
+HANE_MODE        = os.environ.get("HANE_MODE", "rest").lower()
+HANE_URL         = os.environ.get("HANE_API_URL", "https://haneia.com.br").rstrip("/")
+HANE_KEY         = os.environ.get("HANE_API_KEY", "")
+HANE_MCP_URL     = os.environ.get("HANE_MCP_URL", "http://localhost:8081/mcp")
+HANE_MCP_TOKEN   = os.environ.get("HANE_MCP_TOKEN", "")
+HANE_ANONYMIZE   = os.environ.get("HANE_ANONYMIZE", "false").lower() == "true"
+
+# Anonimização só faz sentido em modo remoto (texto transita por servidor externo)
+_ANONYMIZE_ACTIVE = HANE_ANONYMIZE and HANE_MODE == "mcp"
+
+# ── Padrões LGPD — apenas dados de pessoa natural (Art. 5º, I — Lei 13.709/2018) ──
+# CNPJ e razão social identificam pessoa jurídica — fora do escopo LGPD — não mascarados.
+_RE_CPF = re.compile(r"\b\d{3}\.?\d{3}\.?\d{3}-?\d{2}\b")
+_RE_EMAIL_PESSOAL = re.compile(
+    r"\b[A-Za-z0-9._%+\-]+@(?:gmail|hotmail|outlook|yahoo|icloud|live)\.[a-z]{2,}\b",
+    re.IGNORECASE,
+)
+
+
+def _anonymize(text: str) -> tuple[str, dict[str, int]]:
+    """
+    Mascara CPF e e-mails pessoais antes do envio ao servidor remoto.
+
+    Escopo LGPD (Art. 5º, I — Lei 13.709/2018):
+      Protege apenas dados de pessoa natural identificada ou identificável.
+      Pessoa jurídica (CNPJ, razão social) está fora do escopo — não é mascarada.
+
+    Retorna o texto anonimizado e um dict com contagem de substituições por tipo.
+    """
+    counters: dict[str, int] = {"cpf": 0, "email": 0}
+
+    def _replace_cpf(m: re.Match) -> str:
+        counters["cpf"] += 1
+        return "[CPF]"
+
+    def _replace_email(m: re.Match) -> str:
+        counters["email"] += 1
+        return "[EMAIL]"
+
+    text = _RE_CPF.sub(_replace_cpf, text)
+    text = _RE_EMAIL_PESSOAL.sub(_replace_email, text)
+    return text, counters
+
+mcp = FastMCP(
+    name="hane",
+    instructions=(
+        "Servidor HANE — extração de entidades e análise semântica de documentos.\n"
+        "Use extract_entities para extrair entidades de contratos, documentos fiscais ou qualquer texto.\n"
+        "Use compare_documents para identificar diferenças semânticas entre duas versões de um documento.\n"
+        "Use estimate_tokens para estimar a economia de tokens antes de processar.\n"
+        "Use get_status para verificar se a API HANE está online."
+    ),
+)
+
+
+# ----------------------------------------------
+# Transporte REST (modo padrão — Docker local)
+# ----------------------------------------------
+
+def _rest_post(path: str, body: dict) -> dict:
+    url = f"{HANE_URL}{path}"
+    data = json.dumps(body).encode("utf-8")
+    headers = {"Content-Type": "application/json"}
+    if HANE_KEY:
+        headers["X-API-Key"] = HANE_KEY
+    req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=120) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        return {"error": f"HTTP {e.code}", "detail": e.read().decode("utf-8", errors="replace")}
+    except Exception as exc:
+        return {"error": str(exc)}
+
+
+def _rest_post_file(path: str, domain: str = "auto", threshold: float = 0.45) -> dict:
+    """Envia arquivo ao endpoint /annotate/file via multipart/form-data.
+    Usado como fallback OCR: o servidor aplica pytesseract para PDFs escaneados."""
+    import pathlib
+    import mimetypes
+
+    boundary = "HANEBoundary20260418"
+    file_path = pathlib.Path(path)
+    content = file_path.read_bytes()
+    mime = mimetypes.guess_type(str(file_path))[0] or "application/octet-stream"
+
+    parts: list[bytes] = []
+    parts.append(
+        f'--{boundary}\r\nContent-Disposition: form-data; name="file"; filename="{file_path.name}"\r\n'
+        f"Content-Type: {mime}\r\n\r\n".encode()
+    )
+    parts.append(content)
+    parts.append(
+        f"\r\n--{boundary}\r\nContent-Disposition: form-data; name=\"threshold\"\r\n\r\n{threshold}\r\n".encode()
+    )
+    if domain != "auto":
+        parts.append(
+            f'--{boundary}\r\nContent-Disposition: form-data; name="dominio"\r\n\r\n{domain}\r\n'.encode()
+        )
+    parts.append(f"--{boundary}--\r\n".encode())
+
+    data = b"".join(parts)
+    url = f"{HANE_URL}/annotate/file"
+    headers = {"Content-Type": f"multipart/form-data; boundary={boundary}"}
+    if HANE_KEY:
+        headers["X-API-Key"] = HANE_KEY
+
+    req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=180) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        return {"error": f"HTTP {e.code}", "detail": e.read().decode("utf-8", errors="replace")}
+    except Exception as exc:
+        return {"error": str(exc)}
+
+
+def _rest_get(path: str) -> dict:
+    url = f"{HANE_URL}{path}"
+    headers = {"X-API-Key": HANE_KEY} if HANE_KEY else {}
+    req = urllib.request.Request(url, headers=headers, method="GET")
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        return {"error": f"HTTP {e.code}", "detail": e.read().decode("utf-8", errors="replace")}
+    except Exception as exc:
+        return {"error": str(exc)}
+
+
+# ----------------------------------------------
+# Transporte MCP over HTTP (ngrok / remoto)
+# ----------------------------------------------
+
+def _mcp_call(tool: str, arguments: dict) -> dict:
+    """Chama uma tool no servidor HANE MCP remoto via StreamableHttpTransport."""
+    headers = {"ngrok-skip-browser-warning": "true"}
+    if HANE_MCP_TOKEN:
+        headers["Authorization"] = f"Bearer {HANE_MCP_TOKEN}"
+
+    async def _run():
+        transport = StreamableHttpTransport(url=HANE_MCP_URL, headers=headers)
+        async with Client(transport) as client:
+            result = await client.call_tool(tool, arguments)
+            return result.data or {}
+
+    try:
+        return asyncio.run(_run())
+    except Exception as exc:
+        return {"error": str(exc)}
+
+
+# ----------------------------------------------
+# Dispatcher — escolhe REST ou MCP
+# ----------------------------------------------
+
+def _annotate(text: str, threshold: float = 0.45, domain: str = "auto") -> dict:
+    anonymized_info: dict[str, Any] = {}
+    if _ANONYMIZE_ACTIVE:
+        text, counters = _anonymize(text)
+        if any(counters.values()):
+            anonymized_info = {"lgpd_anonimizacao": counters}
+
+    if HANE_MODE == "mcp":
+        args: dict[str, Any] = {"text": text, "domain": domain}
+        result = _mcp_call("extract_entities", args)
+    else:
+        payload: dict[str, Any] = {"text": text, "threshold": threshold}
+        if domain != "auto":
+            payload["dominio"] = domain
+        result = _rest_post("/annotate", payload)
+
+    if anonymized_info:
+        result.update(anonymized_info)
+    return result
+
+
+def _health() -> dict:
+    if HANE_MODE == "mcp":
+        return _mcp_call("get_status", {})
+    return _rest_get("/health")
+
+
+# ----------------------------------------------
+# Ferramentas MCP
+# ----------------------------------------------
+
+@mcp.tool()
+def extract_entities(
+    text: str,
+    threshold: float = 0.45,
+    domain: str = "auto",
+) -> dict[str, Any]:
+    """
+    Extrai entidades nomeadas de um texto usando o modelo HANE.
+
+    Args:
+        text:      Texto a analisar (contrato, documento fiscal, texto livre, código...).
+        threshold: Confiança mínima para incluir entidade (0.0–1.0). Padrão: 0.45.
+        domain:    Domínio de extração. Use "auto" para detecção automática.
+                   Outros valores possíveis: "juridico", "fiscal", "rh", "advpl".
+
+    Returns:
+        Dicionário com:
+        - entities:          lista de entidades com text, label, score, start, end
+        - entity_count:      total de entidades encontradas
+        - entities_by_label: entidades agrupadas por categoria
+        - tokens_original:   tokens antes da compressão HANE
+        - tokens_processed:  tokens após compressão HANE
+        - token_savings_pct: percentual de economia de tokens
+        - latency_ms:        tempo de processamento em milissegundos
+        - lgpd_anonimizacao: contagem de CPFs/e-mails mascarados (apenas se HANE_ANONYMIZE=true)
+    """
+    result = _annotate(text, threshold, domain)
+
+    by_label: dict[str, list[str]] = {}
+    for ent in result.get("entities", []):
+        lbl = ent.get("label", "?")
+        txt = ent.get("text", "")
+        if lbl not in by_label:
+            by_label[lbl] = []
+        if txt not in by_label[lbl]:
+            by_label[lbl].append(txt)
+
+    result["entities_by_label"] = by_label
+    return result
+
+
+@mcp.tool()
+def compare_documents(
+    text_a: str,
+    text_b: str,
+    threshold: float = 0.45,
+) -> dict[str, Any]:
+    """
+    Compara dois documentos semanticamente e identifica o que mudou.
+
+    Útil para comparar versões de contratos, cláusulas, regulamentos ou documentos fiscais.
+    A comparação é feita por entidades extraídas — não por diferença de texto bruto.
+
+    Args:
+        text_a:    Documento original / versão de referência.
+        text_b:    Documento novo / versão atualizada.
+        threshold: Confiança mínima para considerar uma entidade (padrão: 0.45).
+
+    Returns:
+        Dicionário com:
+        - resumo:   {removidas, novas, mantidas, total_a, total_b}
+        - so_em_a:  entidades presentes apenas no documento A (removidas ou substituídas)
+        - so_em_b:  entidades presentes apenas no documento B (novas ou adicionadas)
+        - em_ambos: entidades em ambos, com score_a, score_b e delta de confiança
+        - metricas: economia de tokens e latência total
+    """
+    res_a = _annotate(text_a, threshold)
+    if "error" in res_a:
+        return {"error": f"Falha ao processar documento A: {res_a['error']}"}
+
+    res_b = _annotate(text_b, threshold)
+    if "error" in res_b:
+        return {"error": f"Falha ao processar documento B: {res_b['error']}"}
+
+    def _score(e: dict) -> float:
+        return float(e.get("score") or e.get("confidence") or 0.0)
+
+    def _index(result: dict) -> dict:
+        idx: dict[str, dict] = {}
+        for e in result.get("entities", []):
+            key = e["text"].lower() + "||" + e["label"]
+            if key not in idx or _score(e) > _score(idx[key]):
+                idx[key] = e
+        return idx
+
+    idx_a = _index(res_a)
+    idx_b = _index(res_b)
+    keys_a = set(idx_a)
+    keys_b = set(idx_b)
+
+    so_em_a = [
+        {"text": idx_a[k]["text"], "label": idx_a[k]["label"], "score_a": _score(idx_a[k])}
+        for k in keys_a - keys_b
+    ]
+    so_em_b = [
+        {"text": idx_b[k]["text"], "label": idx_b[k]["label"], "score_b": _score(idx_b[k])}
+        for k in keys_b - keys_a
+    ]
+    em_ambos = [
+        {
+            "text":    idx_a[k]["text"],
+            "label":   idx_a[k]["label"],
+            "score_a": round(_score(idx_a[k]), 3),
+            "score_b": round(_score(idx_b[k]), 3),
+            "delta":   round(_score(idx_b[k]) - _score(idx_a[k]), 3),
+        }
+        for k in keys_a & keys_b
+    ]
+
+    return {
+        "ok": True,
+        "resumo": {
+            "removidas": len(so_em_a),
+            "novas":     len(so_em_b),
+            "mantidas":  len(em_ambos),
+            "total_a":   len(idx_a),
+            "total_b":   len(idx_b),
+        },
+        "so_em_a":  so_em_a,
+        "so_em_b":  so_em_b,
+        "em_ambos": em_ambos,
+        "metricas": {
+            "economia_pct_a":    res_a.get("token_savings_pct"),
+            "economia_pct_b":    res_b.get("token_savings_pct"),
+            "latencia_ms_total": (res_a.get("latency_ms") or 0) + (res_b.get("latency_ms") or 0),
+        },
+    }
+
+
+@mcp.tool()
+def estimate_tokens(text: str) -> dict[str, Any]:
+    """
+    Estima a economia de tokens que o HANE proporcionaria ao processar este texto.
+    Operação leve — não carrega o modelo, não consome GPU.
+
+    Args:
+        text: Texto para estimativa.
+
+    Returns:
+        Dicionário com:
+        - tokens_estimados:  estimativa de tokens do texto original
+        - economia_estimada: percentual estimado de redução
+        - tokens_apos_hane:  estimativa de tokens após processamento
+        - recomendacao:      orientação sobre quando vale processar com HANE
+    """
+    tokens_est = max(1, len(text) // 4)
+
+    if tokens_est < 100:
+        economia = 50
+        recomendacao = "Texto curto — economia moderada. Use para textos maiores."
+    elif tokens_est < 500:
+        economia = 70
+        recomendacao = "Texto médio — boa economia esperada."
+    else:
+        economia = 78
+        recomendacao = "Texto longo — alta economia. HANE é muito eficiente aqui."
+
+    tokens_apos = int(tokens_est * (1 - economia / 100))
+
+    return {
+        "tokens_estimados":  tokens_est,
+        "economia_estimada": economia,
+        "tokens_apos_hane":  tokens_apos,
+        "recomendacao":      recomendacao,
+    }
+
+
+@mcp.tool()
+def get_status() -> dict[str, Any]:
+    """
+    Verifica o estado da API HANE (saúde, versão, modelo carregado) e
+    exibe a configuração ativa de privacidade (LGPD).
+
+    Returns:
+        Dicionário com status, versão, modo de operação e configuração LGPD.
+    """
+    result = _health()
+    result["api_url"] = HANE_MCP_URL if HANE_MODE == "mcp" else HANE_URL
+    result["mode"] = HANE_MODE
+    result["lgpd"] = {
+        "anonimizacao_ativa": _ANONYMIZE_ACTIVE,
+        "escopo": "CPF e e-mails pessoais (gmail/hotmail/outlook/yahoo/icloud/live)" if _ANONYMIZE_ACTIVE else "desativada",
+        "nao_mascarado": "CNPJ, razão social, valores fiscais (pessoa jurídica — fora do escopo LGPD Art. 5º I)",
+        "motivo_inativo": (
+            None if _ANONYMIZE_ACTIVE
+            else "HANE_MODE=rest — texto não transita por servidor externo, anonimização desnecessária"
+            if HANE_MODE == "rest" and HANE_ANONYMIZE
+            else "HANE_ANONYMIZE não definido — defina HANE_ANONYMIZE=true para ativar em modo remoto"
+        ),
+    }
+    return result
+
+
+@mcp.tool()
+def annotate_file_local(
+    path: str,
+    threshold: float = 0.45,
+    domain: str = "auto",
+) -> dict[str, Any]:
+    """
+    Lê um arquivo do disco local e envia o texto direto à API HANE — sem passar pelo contexto do Claude.
+
+    Este é o Fluxo 3 de máxima eficiência: o Claude nunca vê o conteúdo bruto do arquivo,
+    apenas as entidades comprimidas retornadas pelo HANE (~79 tokens em vez de ~1.000+).
+
+    Diferença em relação a extract_entities:
+    - extract_entities: Claude lê o arquivo → tokens entram no contexto → envia ao HANE → custo dobra
+    - annotate_file_local: cliente lê o arquivo → envia direto ao HANE → Claude recebe só entidades
+
+    Suporta: .txt, .py, .prw, .prx, .tlpp, .js, .ts, .java, .sql, .md, .pdf
+
+    Args:
+        path:      Caminho do arquivo no disco local.
+        threshold: Confiança mínima para incluir entidade (0.0–1.0). Padrão: 0.45.
+        domain:    Domínio de extração. Use "auto" para detecção automática.
+
+    Returns:
+        Dicionário com entidades, economia de tokens, latência e métricas de qualidade.
+    """
+    import pathlib
+
+    file_path = pathlib.Path(path)
+    if not file_path.exists():
+        return {"error": f"Arquivo não encontrado: {path}"}
+    if not file_path.is_file():
+        return {"error": f"Caminho não é um arquivo: {path}"}
+
+    ext = file_path.suffix.lower()
+    try:
+        if ext == ".pdf":
+            from pypdf import PdfReader
+            reader = PdfReader(str(file_path))
+            paginas = len(reader.pages)
+            text = "\n".join(p.extract_text() or "" for p in reader.pages)
+
+            # PDF escaneado: pypdf não extraiu texto suficiente.
+            # Fallback: envia o arquivo ao servidor, que aplica OCR via pytesseract.
+            if len(text.strip()) < 100 and HANE_MODE == "rest":
+                result = _rest_post_file(str(file_path), domain=domain, threshold=threshold)
+                if "error" not in result:
+                    result["arquivo"] = str(file_path.resolve())
+                    result["tamanho_bytes"] = file_path.stat().st_size
+                    result["paginas_pdf"] = paginas
+                    result["ocr_fallback"] = True
+                    return result
+        else:
+            paginas = None
+            text = file_path.read_text(encoding="utf-8", errors="ignore")
+    except Exception as exc:
+        return {"error": f"Erro ao ler arquivo: {exc}"}
+
+    if not text.strip():
+        return {"error": "Arquivo vazio ou sem conteúdo legível. Se for um PDF escaneado, verifique se o servidor tem pytesseract instalado."}
+
+    result = _annotate(text, threshold, domain)
+
+    by_label: dict[str, list[str]] = {}
+    for ent in result.get("entities", []):
+        lbl = ent.get("label", "?")
+        txt = ent.get("text", "")
+        if lbl not in by_label:
+            by_label[lbl] = []
+        if txt not in by_label[lbl]:
+            by_label[lbl].append(txt)
+
+    result["entities_by_label"] = by_label
+    result["arquivo"] = str(file_path.resolve())
+    result["tamanho_bytes"] = file_path.stat().st_size
+    if paginas:
+        result["paginas_pdf"] = paginas
+    return result
+
+
+# ----------------------------------------------
+# Entry point
+# ----------------------------------------------
+
+def main() -> None:
+    mcp.run()
+
+if __name__ == "__main__":
+    main()

hane_mcp_client-1.2.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+py-modules = ["hane_mcp_client"]
+
+[tool.setuptools.dynamic]
+readme = {file = "README.md", content-type = "text/markdown"}
+
+[project]
+name = "hane-mcp-client"
+version = "1.2.0"
+description = "Cliente MCP leve para o servidor HANE — extracao de entidades e analise semantica de documentos ERP/fiscal/juridico"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "Proprietary"}
+authors = [
+    {name = "HaneIA Tecnologia", email = "contato@haneia.com.br"},
+]
+keywords = ["mcp", "ner", "nlp", "hane", "advpl", "totvs", "fiscal", "juridico", "claude"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Text Processing :: Linguistic",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "fastmcp>=3.2.4",
+    "pypdf>=4.0",
+]
+
+[project.optional-dependencies]
+dev = ["build", "twine"]
+
+[project.scripts]
+hane-mcp-client = "hane_mcp_client:main"
+
+[project.urls]
+Homepage = "https://github.com/JacionSilva/hane"
+Repository = "https://github.com/JacionSilva/hane"

hane_mcp_client-1.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+