@reposkein/mcp

RepoSkein gives your AI coding agent a map of your codebase — so it navigates structure instead of grepping and guessing.

This is the Model Context Protocol server for RepoSkein — a deterministic code graph (functions, classes, imports, call edges) built from your repo with Tree-sitter and served to any MCP-capable agent (Claude Code, Cursor, Codex, …). Your agent navigates structure instead of guessing, and writes short summaries onto the graph as it learns — versioned in git as shared team memory.

• ⚡ Zero-infra — no database, no Docker. The graph lives in committed .reposkein/*.jsonl files.
• 🔒 Deterministic — same code → byte-identical graph. No LLM in the construction path.
• 🌐 7 languages — Python, TypeScript, JavaScript, Rust, Go, Java, C#.

Contents: Get started · Tools · How your agent uses it · Configuration · Embeddings · Learn more

Get started (≈30 seconds)

In the repo you want your agent to understand:

npx @reposkein/mcp init

That downloads the indexer, sets up git hooks, installs the agent skill, and prints an MCP config block. Paste that block into your agent (e.g. Claude Code's .mcp.json):

{
  "mcpServers": {
    "reposkein": {
      "command": "reposkein-mcp",
      "env": { "REPOSKEIN_REPO_PATH": "/path/to/your/repo" }
    }
  }
}

init already built the graph — verify and commit it:

reposkein-mcp doctor .        # ✓ binary  ✓ indexed (N nodes)  ✓ ready
git add .reposkein && git commit -m "add RepoSkein code graph"
# re-index after big changes:  reposkein-mcp index .

Then ask your agent "what calls this function?" or "what breaks if I change X?" — it answers from the graph.

Tools

| Tool | What it does | | --- | --- | | list_repos | enumerate the repos discovered by resolution — path, name, cheap node/edge counts. One entry in single-repo mode; workspace mode lists every sibling repo found | | select_repo | set the session-active repo (by path or name from list_repos) for every repo-scoped tool below — how workspace mode resolves ambiguity, and how you switch repos without restarting the server | | get_context_profile | resolve a function/class → its caller/callee neighborhood as ready-to-read prose | | semantic_find | find where to start — rank functions/classes by meaning (lexical BM25F; optional pluggable embeddings), seeding get_context_profile | | impact | transitive callers of a function/class — split into impacted code vs covering tests — with counts and truncated flag | | read_cypher | read-only graph queries (writes rejected, results capped) | | write_semantic_summary | attach a hash-stamped summary to a node | | init_cpg_skeleton | build/rebuild the graph | | reindex_file | refresh after editing a file | | get_temporal_context | git-derived signals for a file: change frequency, top authors, and co-change — which files historically change together (advisory, not committed) |

CLI:

• reposkein-mcp init — set up a repo (downloads the indexer, installs git hooks + the skill, builds the graph, prints an MCP config block).
• reposkein-mcp doctor — health check (binary → index → MCP reachability).
• reposkein-mcp index — rebuild the committed graph after big changes.
• reposkein-mcp migrate [path] [--dry-run] — untrack a still-committed derived graph (pre-0.2.7 repos), refresh hooks + .gitignore/.gitattributes.
• reposkein-mcp stats [--last | --session <id> | --all] [--json] — session usage report: calls by tool, top queried nodes/files, ADRs/summaries written, session duration, and an estimated context-tokens-saved-vs-grep number. See Session usage stats below.
• reposkein-mcp view [path] — open the constellation viewer: a local, read-only, zero-infra web app (bound to 127.0.0.1) that renders the committed .reposkein graph as an interactive 3D astronomy-style map. --export <dir> instead writes a self-contained static site (works from file:// or any static host). See the viewer section in the main README, or try the live demo (RepoSkein viewing its own graph).
• reposkein-mcp serve --http [path] — advanced, optional: one shared server for agents that have no clone. Speaks MCP over Streamable HTTP and serves the viewer + /api/* from the same process, behind bearer-token auth, read-only by default, re-indexing when the served checkout's HEAD moves. Nothing binds a socket unless you run it; stdio remains the default transport. See docs/REMOTE.md.

How your agent uses it

You ask in plain language; the bundled skill drives the tools:

1. semantic_find — find where to start by meaning ("where's the rate limiter?").
2. get_context_profile — callers + callees of a function/class as ready-to-read prose.
3. impact — before editing: transitive callers (what breaks) + the tests that cover it.
4. get_temporal_context — files that historically change together, plus churn/ownership.
5. write_semantic_summary — record understanding onto the node (committed to git).
6. reindex_file — refresh after an edit.

Install the cross-agent skills so your agent knows when to use each:

npx skills add reposkein/reposkein --all

(reposkein-mcp init already installs the navigation skill for Claude Code; this adds it to Cursor, Codex, and 70+ other agents.)

Session usage stats

Every tool call is logged, server-side, as one JSONL line to .reposkein/local/sessions/<session-id>.jsonl under the repo the call touched — {ts, tool, argsShape, resultBytes, nodeIds}, never argument or result values (only argument key names — no code/user text ever lands on disk). Because logging happens in the server, this works for any MCP-capable agent (Claude Code, Cursor, Codex, …), not just one. It's zero-infra like everything else here: local-only, git-ignored (local/), never blocks or fails a tool call — a logging failure is always swallowed. Old sessions are pruned automatically (newest 50, or 30 days, whichever is stricter).

reposkein-mcp stats                 # last session, human-readable
reposkein-mcp stats --all           # every retained session, combined
reposkein-mcp stats --session <id>  # one specific session
reposkein-mcp stats --json          # machine-readable

The report includes calls by tool, the top queried nodes/files, ADRs and semantic summaries written, session duration, and an estimated context-tokens-saved-vs-grep figure (using the ~8.4× mean token ratio measured in mcp/bench — always labeled an estimate, never claimed as measured).

Claude Code Stop-hook recipe — print a session's stats the moment it ends, by adding to .claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "reposkein-mcp stats --last" }
        ]
      }
    ]
  }
}

Configuration

Repo resolution (zero-config)

REPOSKEIN_REPO_PATH is optional — the server resolves the target repo from the process's working directory. Full precedence:

1. select_repo — an MCP tool call that sets the session-active repo (by path or name from list_repos) for every repo-scoped tool call made afterward, for the rest of the connection. The only one of these that's mutable at runtime — everything below it is fixed at server start.
2. REPOSKEIN_REPO_PATH, if set.
3. Walk up: the nearest ancestor of the cwd containing .reposkein/.
4. Walk down (workspace mode, only tried when no ancestor has one): scans the cwd's children and grandchildren (skipping node_modules, .git, target, dist, .worktrees, .claude) for .reposkein/ dirs. One hit is used automatically; two or more leave the repo unresolved until a select_repo call picks one — list_repos always enumerates every repo the walk finds (plus a REPOSKEIN_REPO_PATH pin, if one is set and not already among them), regardless of which one is currently active.

If nothing resolves — or step 4 finds more than one repo and none has been select_repo'd — repo-scoped tools don't fail silently at startup: each call returns a structured error telling you what to run (reposkein-mcp init, list_repos/select_repo, or which REPOSKEIN_REPO_PATH to set — naming the candidates when ambiguous). reposkein-mcp doctor and --help never require a resolved repo. See mcp/src/store/resolveRepoPath.ts and mcp/src/store/repoSession.ts.

| Env var | Purpose | | --- | --- | | REPOSKEIN_REPO_PATH | pins the repository the server operates on — optional, see repo resolution above | | REPOSKEIN_SESSION_ID | override the session id used for reposkein-mcp stats logging (default: start-timestamp + pid) | | REPOSKEIN_STORE | auto (default) · jsonl (zero-infra) · neo4j | | REPOSKEIN_AGENT | names the writer in summary_by / decided_by and picks its local/summaries-<agent>.jsonl sidecar (default agent) | | REPOSKEIN_SERVE_TOKENS | serve --http only — name:secret[:write] entries, comma- or whitespace-separated. Required for that mode; see docs/REMOTE.md | | REPOSKEIN_INDEXER_BIN | override the reposkein-indexer binary path (unsupported platforms) | | NEO4J_URI / NEO4J_USER / NEO4J_PASSWORD | optional Neo4j backend (large graphs / Cypher at scale) | | REPOSKEIN_EMBED_PROVIDER | none (default) · voyage · http — see below | | REPOSKEIN_EMBED_MODEL | embedding model id (provider default when absent) | | REPOSKEIN_EMBED_DIMS | output dimension (model default when absent) | | VOYAGE_API_KEY | API key for the voyage provider | | REPOSKEIN_EMBED_URL | base URL for the http (local model) provider |

Optional: semantic embeddings

By default, semantic_find is deterministic and lexical (BM25F over qualified names, signatures, and summaries) — zero-infra, no API keys, byte-identical results. You can optionally enable a hybrid embedding tier that fuses lexical + cosine similarity via Reciprocal Rank Fusion (RRF):

Voyage API (cloud):

REPOSKEIN_EMBED_PROVIDER=voyage
VOYAGE_API_KEY=<your-key>
# Optional: REPOSKEIN_EMBED_MODEL=voyage-code-3 (default)
# Optional: REPOSKEIN_EMBED_DIMS=1024  (default; Matryoshka: 256/512/1024/2048)

Privacy note: with REPOSKEIN_EMBED_PROVIDER=voyage, the document strings (qualified names, signatures, agent-written summaries) are sent to Voyage AI's servers for embedding. Teams with code-egress restrictions should use the local/http provider or leave embeddings disabled.

Local/offline model (no egress):

REPOSKEIN_EMBED_PROVIDER=http
REPOSKEIN_EMBED_URL=http://127.0.0.1:8080/v1/embeddings
REPOSKEIN_EMBED_MODEL=voyage-4-nano   # or any model your local server serves
REPOSKEIN_EMBED_DIMS=1024

Point this at any OpenAI-compatible local embedding server. Two easy options: Ollama (ollama pull nomic-embed-text, URL http://127.0.0.1:11434/v1/embeddings, dims 768), or RepoSkein's one-command voyage-4-nano server — embed-server/ (docker compose up -d). All text stays on your machine.

How it works: vectors are cached in .reposkein/local/embeddings/ (gitignored — never committed, never required). The cache is invalidated per-node when the document content changes. On any embedding error, semantic_find silently falls back to the lexical result. Enabling embeddings never changes the committed graph.

Platforms: prebuilt indexer binaries for macOS (Apple Silicon), Linux (x64/arm64), and Windows (x64).

Learn more

Full documentation, architecture, supported-language details, benchmarks, and the cross-agent skills live in the main repository:

👉 https://github.com/reposkein/reposkein

Support: Ko-fi — funds hosted-constellation infra + indexer maintenance.

License

Apache-2.0.