convez.ai
MCP ServerIntegração & APIsAvançado
szl-holdings

Hatun-MCP — Servidor MCP com Governança PURIQ

szl-holdings/hatun-mcp

MCP server governado que integra backends SZL com segurança criptográfica e auditoria append-only

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor Model Context Protocol assinado que agrega serviços backend SZL (plataforma a11oy e killinchu) sob governança PURIQ, expondo 49 ferramentas MCP. Implementa autenticação, validação Yuyay-13, reputação, aprovação 2-pessoas, recibos Khipu e assinatura DSSE para cada chamada.

Instalação

$npx convez-ai szl-holdings/hatun-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
87%
Último commit
há 3 dias
Versão
v1.0.4
Issues abertas
1
Contribuidores
6

Casos de uso

  • Integração segura de múltiplos serviços backend sob protocolo MCP
  • Auditoria e rastreamento de operações com recibos criptográficos
  • Governança de acesso com reputação e aprovação multi-assinante

Veredito

Projeto maduro e operacional que implementa o MCP com rigor criptográfico e governança apropriada para sistemas críticos. A documentação é transparente sobre status live/paused dos serviços, refletindo honestidade sobre estado real — válido para arquiteturas que exigem auditoria e conformidade.

README

A tradução para o português deste README ainda está na fila.

License Doctrine v11 LOCKED CI SLSA

🪢 hatun-mcp

The great context protocol — hatun (Quechua) = "big / great".

The one signed MCP endpoint that aggregates the SZL backend services — the a11oy command platform (and its policy, memory and operator capability services) plus killinchu (drones & vessels) — under PURIQ governance and re-exposes their tools to any MCP client.

Hugging Face Space · GitHub Org

receipts.in ≡ receipts.out


What this is

A real, operational Model Context Protocol server built on the official mcp Python SDK (mcp.server.fastmcp.FastMCP). Every tool call is governed by the PURIQ formula:

  1. Authenticate the client (SZL API key → client_id); anonymous calls are declined.
  2. Yuyay-13 gate on the input (input-as-data; OWASP MCP06 injection defense).
  3. Reputation factor Hatun_MCP(client) ∈ [0,1].
  4. 2-person Yuyay gate for state-changing tools (e.g. killinchu_cue, halt_drone).
  5. Call the real organ backend within a latency budget.
  6. Mint a Khipu receipt on success and failure (append-only sha256 DAG).
  7. Return a DSSE-signed response — the client receives the receipt hash.

Tools exposed

  • 17 core szl_* tools (hand-wired): yuyay scoring, PURIQ evaluation, Khipu verification, Lean verification, formula evaluation, doctrine/thesis lookup, service shortcuts, and szl_lambda_quorum (Byzantine Λ verdict).
  • Service-derived tools registered dynamically at startup from each backend service's live catalog at /api/<service>/v1/mcp/tools, named <service>_<tool>.

Live count (probed 2026-06-03): 49 MCP tools total — 17 core + 32 service-derived across the a11oy capability services (memory 4, policy/gates 11, operator 12, status 1) and killinchu (4).

Naming note. The live API route segments /api/amaru/..., /api/rosie/..., /api/sentra/... are immutable infra coordinates kept verbatim (renaming breaks the live routes). In user-facing terms these are the YACHAY reasoning cortex, the operator console, and the CHAPAQ egress immune-inspector respectively.

Honest reachability (HONESTY OVER CHECKLIST)

Backend serviceCatalog routeStatus 2026-06-03
a11oy — YACHAY read-only reasoning cortex / memory/api/amaru/v1/mcp/toolsLIVE — 4 tools
killinchu/api/killinchu/v1/mcp/toolsLIVE — 4 tools (cue/halt_drone are 2-person)
a11oy — operator console/api/rosie/v1/mcp/toolsLIVE — 12 tools
a11oy — CHAPAQ egress immune-inspector (policy/gates)/api/sentra/v1/gatesLIVE (gates-derived) — 8 gates + 3 actions; this service does not expose a JSON /v1/mcp/tools catalog (SPA shell), so tools are derived from /gates
a11oy — command/api/a11oy/v1/mcp/toolsPAUSED (503) — "ask a maintainer to restart it". Registers zero tools + one honest a11oy_status tool. Requires a founder-flipped restart of the Space before its ≤49 policy gates surface. Self-heals to a full live catalog on the next server restart once a11oy returns 200 — no code change, no fabricated stubs.

Byzantine quorum + BLS aggregate

szl_lambda_quorum fans a governance-critical Λ verdict out to the five backend services and decides under a Byzantine n ≥ 3f+1 quorum (n=5, f=1): ≥ 4 services must be reachable and ≥ 3 must agree. Participating receipts are BLS12-381 aggregated (py_ecc; honest sha256 Merkle-root fallback if the BLS backend is absent). With a11oy paused, quorum degrades gracefully to the 4 live services (n=4 still satisfies n ≥ 3f+1) and discloses the degradation in governance.quorum.


Run locally (stdio)

pip install -r requirements.txt
python -m hatun_mcp.server          # stdio mode for Claude Desktop / Codex

Run hosted (Streamable HTTP)

uvicorn hatun_mcp.server_http:app --host 0.0.0.0 --port 7860
# MCP endpoint:  http://127.0.0.1:7860/mcp   (legacy SSE at /sse)

The DSSE signing key is injected at runtime via the HATUN_MCP_SIGNING_KEY (PEM) Space secret; without it the signer runs in honest PLACEHOLDER mode (clearly labeled, never a fake signature).


MCP client setup

Claude Desktop

Drop examples/claude-desktop-config.json into ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows), replacing szl_YOUR_KEY:

{
  "mcpServers": {
    "hatun-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote",
        "https://szlholdings-hatun-mcp.hf.space/mcp",
        "--header", "Authorization: Bearer szl_YOUR_KEY"]
    }
  }
}

Codex (~/.codex/config.toml)

[mcp_servers.hatun-mcp]
command = "npx"
args = ["-y", "mcp-remote", "https://szlholdings-hatun-mcp.hf.space/mcp",
        "--header", "Authorization: Bearer szl_YOUR_KEY"]

Continue (~/.continue/config.json)

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "mcp-remote",
            "https://szlholdings-hatun-mcp.hf.space/mcp",
            "--header", "Authorization: Bearer szl_YOUR_KEY"]
        }
      }
    ]
  }
}

Tests

HATUN_MCP_DISABLE_DYNAMIC=true python -m pytest tests/ -q
# tests/test_server.py    — list tools, call a tool, assert response shape
# tests/test_quorum.py    — quorum math + threshold edge cases + BLS aggregate
# tests/test_adapters.py  — mocked organ endpoints, adapter wiring + honest gaps
# tests/test_governance.py— Khipu chain, Yuyay gate, PURIQ factor (pre-existing)

Doctrine v11 LOCKED — 749 / 14 / 163 · Λ = Conjecture 1 (NOT a theorem) · SLSA L1 honest · L2 verified-provenance on roadmap (L3 not claimed) receipts.in ≡ receipts.out

Signed-off-by: Yachay <yachay@szlholdings.ai> Co-Authored-By: Perplexity Computer Agent <agent@perplexity.ai>

Ver o original no GitHub

Bom para

Relacionados