EKOS

Compile a GitHub repositoryinto an MCP server.

Not a wrapper around the GitHub API. A compiler pass — issues, PRs, files, and their real relationships become append-only, evidence-backed knowledge that any MCP-speaking agent can query directly.

Agents read your repo. They don't understand it.

A coding agent can grep your issues and diff your PRs, but it re-derives the same facts every session: which files a PR actually touched, which issue a merge closed, what depends on what. None of it persists, and none of it is traceable back to a source.

- TodayFree-text issues/PRs, re-read and re-guessed on every prompt.
- MissingA structured "references X" relationship agents can query instead of infer.
- EKOSCompiles that relationship once, stores it with evidence, serves it over MCP.

Object · Relationship · Event · Evidence — everything GitHub emits gets mapped onto these before it ever reaches an agent.

Every issue and PR becomes one artifact.

GitHubObserverwalksGET /issues?state=allandGET /pulls/{n}/files, distinguishing issues from PRs the same way GitHub's own API does. AMockGitHubClientexercises the real mapping logic with zero network dependency — the same discipline used for every other connector in the codebase.

- EmitsOne ObservationArtifact per issue/PR, target"{owner}/{repo}#{number}"
- Config[connectors.github]— owner, repo, token env var

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>; }

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

Every PR'sfiles_changedbecomes aReferencesedge to that file's object. Every recognized closing keyword —closes, fixes, resolves— becomes aReferencesedge between items. No LLM guesses at the relationship; GitHub already told us what closed what.

- IdempotentSame item, same run, same object id — every re-ekos recoverconverges.
- EvidencedEvery edge cites the exact file entry or body sentence that produced it.

Append-only. Content-addressable. Never rewritten.

- ObjectAn Issue or PullRequest — named, typed, with its number/state/body excerpt as properties.
- RelationshipA References edge — PR → file, or item → item via a closing keyword.
- EvidenceThe literal source text every conclusion traces back to — never optional.
- EventA timestamped fact in the append-only stream, replayable at any point in time.

The ledger never edits history — it only appends. That single invariant is what makesekos_diffpossible downstream: "what has changed since T" is a query over the log, not a guess from two snapshots.

stdio, newline-delimited JSON-RPC 2.0 — the transport every MCP client already speaks. No network surface, no auth story, no new dependency.

Four guarantees no vector index gives you.

The handler holds no write path — an agent can query the ledger but never mutate it.

Every Object and Relationship cites the exact source line that produced it — no unsourced claims.

Nothing is edited in place, so "what changed since T" is a real, replayable query.

The same issue or PR resolves to the same object across every rebuild — no drift, no duplicates.

# 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 .

Prerequisites: Rust stable (2024 edition needs rustc 1.85+) and a C/C++ toolchain —rusqlite's bundled SQLite and thezstdcrate both compile native C at build time even though the project itself is pure Rust. Windows has a native path too (winget+ MSVC build tools); WSL2 is the path of least friction if you'd rather follow the Linux steps unmodified.

- Verifyekos --help·cargo test --workspace— 500+ tests
- GitHub connector config[connectors.github]inekos.toml— owner, repo, token env var
- Full OS-by-OS stepsREADME.md → Installation (macOS, Windows native, WSL2)

Point an agent at your repo. Not the API — the compiled knowledge.

# 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 (MCP Server) + RFC 0020 (GitHub Connector) ·github.com/alexeyban/EKOS(main branch)

Sync Calendars, Scheduling Links, AI Executive Scheduling Assistant, Unified Calendar