EKOS

Compile um repositório do GitHub em um servidor MCP.

Não é um wrapper da API do GitHub. É uma passada de compilação — issues, PRs, arquivos e suas relações reais tornam-se conhecimento anexado-apenas, com respaldo de evidências, que qualquer agente que fale MCP pode consultar diretamente.

§ 01 / problema

Agentes leem seu repositório. Eles não o entendem.

Um agente de codificação pode buscar em suas issues e fazer diff de seus PRs, mas ele re-deriva os mesmos fatos a cada sessão: quais arquivos um PR realmente tocou, qual issue um merge fechou, o que depende do quê. Nada disso persiste, e nada disso é rastreável até uma fonte.

• HojeIssues/PRs em texto livre, relidos e re-adivinhados a cada prompt.
• AusenteUma relação estruturada "referencia X" que agentes possam consultar em vez de inferir.
• EKOSCompila essa relação uma vez, armazena com evidências, serve via MCP.

§ 02 / arquitetura

Um compilador, quatro primitivas semânticas.

Objeto · Relação · Evento · Evidência — tudo o que o GitHub emite é mapeado para esses antes de chegar a qualquer agente.

Fonte

Repositório GitHub

→

Observação

GitHubObserver

→

Passada de compilação

GitHubAnalyzerPass

→

Armazenamento

Ledger Semântico

→

Runtime

somente leitura

→

Interface

ekos mcp serve

Cada issue e PR torna-se um artefato.

GitHubObserver percorre GET /issues?state=all e GET /pulls/{n}/files, distinguindo issues de PRs da mesma forma que a própria API do GitHub faz. Um MockGitHubClient exercita a lógica real de mapeamento com zero dependência de rede — a mesma disciplina usada para todos os outros conectores no código.

• EmiteUm ObservationArtifact por issue/PR, alvo "{owner}/{repo}#{number}"
• Config [connectors.github] — dono, repositório, variável de ambiente do token

pub struct GitHubItem {
    pub number: u64,
    pub title: String,
    pub body: String,
    pub state: String,          // "open" | "closed"
    pub is_pull_request: bool,
    pub files_changed: Vec<String>,
}

pub trait GitHubClient: Send + Sync {
    async fn list_items(
        &self, owner: &str, repo: &str
    ) -> Result<Vec<GitHubItem>, GitHubClientError>;
}

Texto torna-se relações rastreáveis.

// PR → changed file
References(pr_id, file_id)
  evidence: "the PR's file-change entry"

// body text: "Fixes #12"
References(issue_47, issue_12)
  evidence: "body sentence containing keyword"

// deterministic id — stable across re-runs
Uuid::new_v5(NAMESPACE, "github:{owner}/{repo}#{n}")

O files_changed de cada PR torna-se uma aresta References para o objeto daquele arquivo. Cada palavra-chave de fechamento reconhecida — closes, fixes, resolves — torna-se uma aresta References entre itens. Nenhum LLM adivinha a relação; o GitHub já nos disse o que fechou o quê.

• IdempotenteMesmo item, mesma execução, mesmo id de objeto — cada re- ekos recover converge.
• Com evidênciasCada aresta cita a entrada exata do arquivo ou a frase do corpo que a produziu.

§ 05 / armazenamento

Anexado-apenas. Endereçável por conteúdo. Nunca reescrito.

• ObjetoUma Issue ou PullRequest — nomeada, tipada, com número/estado/excerto do corpo como propriedades.
• RelaçãoUma aresta de Referência — PR → arquivo, ou item → item via palavra-chave de fechamento.
• EvidênciaO texto-fonte literal ao qual toda conclusão remonta — nunca opcional.
• EventoUm fato com timestamp no fluxo anexado-apenas, reproduzível em qualquer ponto no tempo.

O ledger nunca edita o histórico — ele apenas anexa. Esse único invariante é o que torna ekos_diff possível downstream: "o que mudou desde T" é uma consulta sobre o log, não um palpite a partir de dois snapshots.

§ 06 / servir

Onze ferramentas. Um runtime somente leitura.

stdio, JSON-RPC 2.0 delimitado por nova linha — o transporte que todo cliente MCP já fala. Sem superfície de rede, sem história de autenticação, sem nova dependência.

Ferramenta MCP	Responde
ekos_search	Encontra um objeto por nome ou tipo
ekos_neighborhood	O que está conectado a isto, N saltos de distância
ekos_dependents	O que quebra se isto mudar — arestas de entrada vs. de saída
ekos_impact	Raio de explosão multi-salto em todo o grafo
ekos_state	Reconstrói o estado a partir de qualquer timestamp RFC 3339
ekos_diff	Que conhecimento mudou desde T
ekos_ekl	Executa uma expressão estruturada de consulta de conhecimento
ekos_status	Contagens de entradas / objetos / relações do ledger
ekos_transformation_explain	O que uma transformação ETL/SQL legada realmente faz, evidência por etapa
ekos_transformation_diff	Uma migração mudou o significado de uma transformação
ekos_identity_review	Confirma/rejeita uma correspondência de identidade entre sistemas — a única ferramenta com capacidade de escrita

§ 07 / invariantes

Quatro garantias que nenhum índice vetorial oferece.

Runtime somente leitura

O handler não possui caminho de escrita — um agente pode consultar o ledger, mas nunca mutá-lo.

Rastreável por evidências

Cada Objeto e Relação cita a linha-fonte exata que o produziu — sem afirmações sem fonte.

Anexado-apenas

Nada é editado no lugar, então "o que mudou desde T" é uma consulta real e reproduzível.

Ids determinísticos

A mesma issue ou PR resolve para o mesmo objeto em cada reconstrução — sem deriva, sem duplicatas.

§ 08 / instalação e execução

Clone, construa, compile, sirva.

terminal — macOS / Linux / WSL2

# 1. clone — the Cargo workspace root is ekos/, not the repo root
$ git clone https://github.com/alexeyban/EKOS.git
$ cd EKOS/ekos

# 2. build (needs Rust stable via rustup.rs + a C toolchain)
$ cargo build --release --workspace
$ cargo install --path crates/cli

# 3. compile a workspace's knowledge, once
$ cd /path/to/your/repo
$ ekos init
$ ekos build && ekos recover && ekos resolve && ekos compile && ekos commit

# 4. serve it over MCP, stdio
$ ekos mcp serve --workspace .

Pré-requisitos: Rust estável (edição 2024 precisa de rustc 1.85+) e um toolchain C/C++ — o SQLite embutido do rusqlite e o crate zstd ambos compilam C nativo no momento da construção, embora o projeto em si seja Rust puro. Windows também tem um caminho nativo (winget + ferramentas de build MSVC); WSL2 é o caminho de menor fricção se você preferir seguir os passos do Linux sem modificações.

• Verifique ekos --help · cargo test --workspace — 500+ testes
• Config do conector GitHub [connectors.github] em ekos.toml — dono, repositório, variável de ambiente do token
• Passos completos por SOREADME.md → Instalação (macOS, Windows nativo, WSL2)

Aponte um agente para seu repositório. Não para a API — para o conhecimento compilado.

terminal — conecte-o ao Claude Code

# register the server — path-based
$ claude mcp add ekos -- ekos --config ekos.toml \
    mcp serve --workspace /path/to/workspace

# or path-free, via env vars
$ claude mcp add ekos --env EKOS_WORKSPACE=/path/to/workspace \
    -- ekos mcp serve

"What does PR #47 actually close,
 and which files does it touch?"

→ ekos_neighborhood(pr_47_id)
{ "relationships": [
  { "kind": "References", "to": "issue_12",
    "evidence": "body: closes #12" },
  { "kind": "References", "to": "file:src/auth.rs",
    "evidence": "PR file-change entry" }
] }

EKOS · RFC 0013 (Servidor MCP) + RFC 0020 (Conector GitHub) · github.com/alexeyban/EKOS (branch main)