Athena-MCP

Português · English

Servidor MCP (stdio, JSON-RPC) para execução governada de CLIs de agentes de IA na sua máquina: combos ordenados com fallback controlado, lease de workspace, deadlines com cancelamento confiável e verificação determinística + advisory do resultado.

Status: Athena v1 tecnicamente fechado e verificado para uso local e single-user. POSIX (macOS/Linux). Windows não é suportado nesta versão.

Estado da distribuição v1

• O runtime público expõe sete tools MCP e preserva as autoridades separadas de Zeus, Nike, Aegis, Chronos e Evidence Gate.

• O checkout Athena-beta já contém o runtime funcional do v1. Em 2026-08-31, a diferença restante para o checkout principal era somente documentação e testes adicionais de instalação/CAS, sem mudança no código de runtime.

• A validação corrente protegida registra 716 passed, 3 deselected; o baseline histórico de evidência do runtime permanece 5319763, com 715 passed, 3 deselected.

Related MCP server: consult-mcp

O que faz

1. Roteamento com failover governado — run_combo executa tentativas ordenadas; o fallback só ocorre após término confirmado da tentativa anterior e aprovação da política de risco.

2. Verificação de alegações — verification opcional re-executa comandos permitidos e confere arquivos citados (determinístico), com camada advisory não bloqueante.

3. Ciclo de vida observável — toda execução tem execution_id, estados explícitos (completed, failed, cancelled, timed_out…), consulta (get_execution, list_executions) e cancelamento idempotente (cancel_execution).

4. Falha sanitizada — timeouts e falhas voltam como resultado da tool com isError: true e payload sanitizado (estado, exit code, stdout/stderr parciais, duração, deadline expirado) — nunca como erro de protocolo opaco.

Tools MCP (7)

Instalação

Requisitos: Python ≥ 3.11, pip, Git.

# 1. Checkouts irmãos
git clone git@github.com:JoaoPauloNA/aegis.git ../aegis
git clone git@github.com:JoaoPauloNA/athena.git
cd athena

# 2. Um único ambiente virtual para Athena + Aegis
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ../aegis
python -m pip install -e ".[dev]"

# 3. Verificação protegida
python harness/p0_gate.py
python -m pytest tests -m "not regression" -q --ignore=tests/test_api_mode.py

Registro no cliente MCP (exemplo Claude Desktop):

{
  "mcpServers": {
    "athena": { "command": "/caminho/para/athena/.venv/bin/athena-mcp" }
  }
}

Limitações conhecidas

• POSIX-only: o bridge usa grupos de processo e PTY POSIX; encerramento em Windows não é garantido (TERMINATION_UNCONFIRMED).

• Single-user: processo stdio local por usuário; sem rede, sem autenticação, sem multiusuário.

• Sem dashboard de produção: as tools MCP são a interface operacional. Olimpo OLIMPO-0 é uma biblioteca HTTP local opt-in em loopback para observação e publicação de configuração validada por preview + CAS; não executa, cancela ou autoriza tarefas e não é o produto Olimpo completo.

• Sem sandbox forte: as CLIs executadas rodam com as permissões do seu usuário no workspace informado — use diretórios de trabalho dedicados.

• Fallback automático: perfis authenticated_external e unknown nunca fazem fallback automático (política fail-closed do Aegis).

• Aprovação humana inline (REQUIRES_HUMAN_APPROVAL) está reservada no contrato do Aegis e ainda não é emitida.

Publicação curada e segurança

O Athena adota um monorepo público modular. Zeus, Nike, Chronos, Evidence Gate, Clio, Harmonia, Capsule e Iris possuem fronteiras próprias, mas permanecem no núcleo enquanto não houver necessidade comprovada de ciclo de release ou consumidor externo independente.

O material público pode conter código, contratos, schemas, testes, documentação e templates sanitizados. Prompts proprietários completos pertencem a um repositório privado separado; prompts preenchidos com dados reais, conversas, respostas privadas, caminhos pessoais, tokens, chaves, cookies e sessões OAuth não pertencem a nenhum repositório Git, mesmo privado.

Português é a documentação canônica e inglês é a primeira tradução mantida. Outros idiomas entram somente quando houver demanda e revisão editorial capaz de impedir divergência entre versões.

Arquitetura (resumo)

cliente MCP → mcp_stdio (JSON-RPC) → mcp_server (camada fina das tools)
    → router (combos/fallback via aegis.decision.evaluate)
        → bridge (subprocess/PTY POSIX, sob lease de workspace)
        → verifier (determinístico → advisory)
    → registry (execuções sanitizadas: get/list/cancel)

Fronteiras de import entre módulos são verificadas por máquina (import-linter; ver pyproject.toml). O núcleo não importa código de legado/.

Documentação

• CHANGELOG.md — histórico de mudanças.

• docs/backlog.md — pendências registradas.

• contexto/gerencia_athena-mcp.md — handoff técnico corrente.

Licença

Ver LICENSE.

Ecossistema: repositórios independentes

Módulos internos (não são repositórios)

Zeus (elegibilidade) · Nike (resolução de runtime/provider) · Chronos (ciclo governado) · Evidence Gate (EG-1 motor + EG-3A sink opt-in) · Clio (logging 4 níveis) · Harmonia (paralelismo/write-sets) · Capsule (ambiente mínimo com seal) · Iris (preflight) · Olimpo (biblioteca HTTP loopback opt-in; observação + configuração CAS) · Flow/Tasks (durabilidade) · Lease · config loader · bridge · SSH transport (dormente, D-SSH).

Testes (comando exato e contagem fresh)

.venv/bin/python harness/p0_gate.py           # lint/boundaries/p0 — PASS
.venv/bin/python -m pytest tests -m "not regression" -q --ignore=tests/test_api_mode.py
# 716 passed, 3 deselected — current protected-aware suite after install-smoke hardening;
# runtime evidence baseline remains 5319763 (715 passed, 3 deselected).

tests/test_api_mode.py e athena/api_mode.py são arquivos protegidos do usuário (hash-verificados; não executados nesta suíte).

Classificações terminais v1 (ADR-0001)

Nenhum item opcional bloqueia o fechamento técnico do v1. Detalhes: docs/adr/ADR-0001-v1-scope-and-deferrals.md.

Olimpo OLIMPO-0

OLIMPO-0 é uma biblioteca, não um daemon instalado nem parte do startup MCP. A composição autorizada instancia athena.olimpo.OlimpoHttpServer com dependências explícitas e chama start(); o servidor recusa bind fora de 127.0.0.1, gera/exige CSRF e deve ser encerrado com shutdown(). O smoke HTTP real e o CAS de configuração são cobertos por tests/test_olimpo_e2e.py.