EKOS

Compila un repositorio de GitHub en un servidor MCP.

No es un envoltorio alrededor de la API de GitHub. Es una pasada de compilación: issues, PRs, archivos y sus relaciones reales se convierten en conocimiento inmutable respaldado por evidencia que cualquier agente que hable MCP puede consultar directamente.

§ 01 / problema

Los agentes leen tu repositorio. No lo entienden.

Un agente de codificación puede buscar en tus issues y revisar tus PRs, pero vuelve a derivar los mismos hechos en cada sesión: qué archivos tocó realmente un PR, qué issue cerró un merge, qué depende de qué. Nada de eso persiste, y nada de eso es rastreable hasta una fuente.

• HoyTextos libres de issues/PRs, releídos y re-inferidos en cada prompt.
• FaltaUna relación estructurada "referencia a X" que los agentes puedan consultar en lugar de inferir.
• EKOSCompila esa relación una vez, la almacena con evidencia y la sirve a través de MCP.

§ 02 / arquitectura

Un compilador, cuatro primitivas semánticas.

Objeto · Relación · Evento · Evidencia — todo lo que GitHub emite se mapea a estos antes de llegar a un agente.

Fuente

Repositorio de GitHub

→

Observación

GitHubObserver

→

Pasada de compilación

GitHubAnalyzerPass

→

Almacenamiento

Registro Semántico

→

Ejecución

solo lectura

→

Interfaz

ekos mcp serve

Cada issue y PR se convierte en un artefacto.

GitHubObserver recorre GET /issues?state=all y GET /pulls/{n}/files, distinguiendo issues de PRs de la misma manera que la propia API de GitHub. Un MockGitHubClient ejercita la lógica real de mapeo con cero dependencia de red — la misma disciplina utilizada para cada otro conector en el código base.

• EmiteUn ObservationArtifact por issue/PR, dirigido a "{owner}/{repo}#{number}"
• Config [connectors.github] — propietario, repositorio, variable de entorno del 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>;
}

El texto se convierte en relaciones rastreables.

// 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}")

El files_changed de cada PR se convierte en un borde References hacia el objeto de ese archivo. Cada palabra clave de cierre reconocida — closes, fixes, resolves — se convierte en un borde References entre elementos. Ningún LLM adivina la relación; GitHub ya nos dijo qué cerró qué.

• IdempotenteMismo elemento, misma ejecución, mismo id de objeto — cada re- ekos recover converge.
• Con evidenciaCada borde cita la entrada exacta del archivo o la frase del cuerpo que lo produjo.

§ 05 / almacenamiento

Solo anexión. Direccionable por contenido. Nunca reescrito.

• ObjetoUn Issue o PullRequest — nombrado, tipado, con su número/estado/extracto del cuerpo como propiedades.
• RelaciónUn borde de Referencia — PR → archivo, o elemento → elemento mediante una palabra clave de cierre.
• EvidenciaEl texto fuente literal al que cada conclusión se remonta — nunca opcional.
• EventoUn hecho con marca de tiempo en el flujo de solo anexión, reproducible en cualquier momento.

El registro nunca edita el historial — solo anexa. Ese único invariante es lo que hace posible ekos_diff aguas abajo: "qué ha cambiado desde T" es una consulta sobre el registro, no una suposición a partir de dos instantáneas.

§ 06 / servicio

Once herramientas. Un runtime de solo lectura.

stdio, JSON-RPC 2.0 delimitado por nuevas líneas — el transporte que todo cliente MCP ya habla. Sin superficie de red, sin historia de autenticación, sin nueva dependencia.

Herramienta MCP	Responde
ekos_search	Encuentra un objeto por nombre o tipo
ekos_neighborhood	Qué está conectado a esto, N saltos de distancia
ekos_dependents	Qué se rompe si esto cambia — bordes entrantes vs. salientes
ekos_impact	Radio de explosión multi-salto en todo el grafo
ekos_state	Reconstruye el estado en cualquier marca de tiempo RFC 3339
ekos_diff	Qué conocimiento cambió desde T
ekos_ekl	Ejecuta una expresión estructurada de consulta de conocimiento
ekos_status	Conteos de entradas de registro / objetos / relaciones
ekos_transformation_explain	Qué hace realmente una transformación ETL/SQL heredada, evidencia por paso
ekos_transformation_diff	¿Una migración cambió el significado de una transformación?
ekos_identity_review	Confirmar/rechazar una coincidencia de identidad entre sistemas — la única herramienta con capacidad de escritura

§ 07 / invariantes

Cuatro garantías que ningún índice vectorial te da.

Runtime de solo lectura

El manejador no tiene ruta de escritura — un agente puede consultar el registro pero nunca mutarlo.

Rastreable por evidencia

Cada Objeto y Relación cita la línea fuente exacta que lo produjo — sin afirmaciones sin fuente.

Solo anexión

Nada se edita en su lugar, por lo que "qué cambió desde T" es una consulta real y reproducible.

Ids deterministas

El mismo issue o PR se resuelve al mismo objeto en cada reconstrucción — sin deriva, sin duplicados.

§ 08 / instalación y ejecución

Clona, compila, compila, sirve.

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 .

Requisitos previos: Rust estable (la edición 2024 necesita rustc 1.85+) y un toolchain de C/C++ — el SQLite incluido de rusqlite y el crate zstd ambos compilan C nativo en tiempo de compilación aunque el proyecto en sí sea Rust puro. Windows también tiene una ruta nativa (winget + herramientas de compilación MSVC); WSL2 es la ruta de menor fricción si prefieres seguir los pasos de Linux sin modificaciones.

• Verifica ekos --help · cargo test --workspace — más de 500 pruebas
• Config del conector de GitHub [connectors.github] en ekos.toml — propietario, repositorio, variable de entorno del token
• Pasos completos por sistema operativoREADME.md → Instalación (macOS, Windows nativo, WSL2)

Apunta un agente a tu repositorio. No a la API — al conocimiento compilado.

terminal — conéctalo a 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 de GitHub) · github.com/alexeyban/EKOS (rama main)