codegraph-mcp

Part of the Accountable AI Engineering suite — provable governance for AI agents on infrastructure you own.

A no-train, on-prem code knowledge graph that you serve to AI agents over MCP — with a hash-chained audit row for every read.

Ask yourself:

• Do your AI coding agents need to understand a codebase that can't be uploaded to a vendor's cloud?

• Have you watched an agent miss that a one-line change breaks a caller in another language — because it only ever saw one file?

• When an agent reads your source, could you produce a record of exactly what it read — and prove it wasn't edited after the fact?

If that's your world, you're in the right place. codegraph-mcp gives agents real, structural understanding of your code, on hardware you control:

• No training, ever. The graph exists only to answer queries. Your code is never used to rank, sell, or train a model, and nothing leaves the machine.

• Overlay, not migration. Point it at any checkout or git URL. Keep hosting your code exactly where it already lives — GitHub, GitLab, an internal mirror, an air-gapped drive.

• Provable reads. Every query an agent makes lands in a tamper-evident, hash-chained audit log you can verify offline. "Which agent read what, and when" is a fact you can show a regulator, not a guess.

• Sees what one-file context can't. Six languages, with cross-language edges — the dependency a giant context window misses. (Independent research keeps finding graph-structured understanding beats stuffing raw files into a prompt.)

Watch the walkthrough

A full tour — browsing the repo, the setup, the live code graph, and all five demo scenarios running for real (narrated, ~12 min):

▶ Watch the walkthrough (MP4) — click the thumbnail or the link to play.

Related MCP server: NOMIK

What it does

On every push or re-index, codegraph-mcp parses your source and builds a queryable graph of:

• Symbols — functions, methods, classes, and types, with signatures and exact locations.

• Call edges — who calls whom, within and across files.

• Cross-language edges — the edge nobody else resolves: a TypeScript fetch('/api/users/:id') linked to the Go and Python handlers that serve that route. These files share no symbol name, so only a structural join finds the dependency.

• References — every call site / use of a name.

Then it answers the questions an agent (or a human) actually asks: find this symbol, who calls it, what's the blast radius if I change it, what crosses a language boundary here.

Quick start

git clone https://github.com/cognis-digital/codegraph-mcp
cd codegraph-mcp
pip install -e .          # or just run via `python -m codegraph`

# 1. Index any repo (a local path, or a git URL it clones read-only)
codegraph index ./examples/sample_repo --db graph.db
codegraph index https://github.com/your-org/your-service.git --db graph.db
codegraph index . --since HEAD~1 --db graph.db   # incremental: only what changed

# 2. Query the graph
codegraph query search loadUser --db graph.db
codegraph query impact 7 --db graph.db          # transitive callers ("blast radius")
codegraph query xlang --db graph.db             # cross-language HTTP edges

# 2b. Visualize the graph — Mermaid (renders inline on GitHub) or Graphviz DOT
codegraph viz --db graph.db --view project --format mermaid
codegraph viz --db graph.db --view impact --symbol 7 --format mermaid
codegraph viz --db graph.db --format dot | dot -Tsvg > graph.svg

# 3. Serve it to an agent over MCP — stdio or HTTP
codegraph token issue ci-agent --scopes read --db graph.db   # prints a bearer token
codegraph serve --db graph.db --token cg_XXXX                 # stdio
codegraph serve --db graph.db --http --port 8765 --require-token   # HTTP (POST /mcp)

# Diff the graph between two git refs — what changed in the *shape* of the code
codegraph diff main feature/x --repo .

# 4. Prove what happened
codegraph audit --db graph.db -n 20
codegraph audit --db graph.db --verify          # replays the hash chain

Run python demo.py to watch it index the sample repo, resolve cross-language edges, trace a blast radius, and verify the audit chain end to end.

See the graph

codegraph viz renders the module-level architecture as Mermaid — drawn inline by GitHub, GitLab, and Obsidian. This is the actual graph of the bundled polyglot sample repo: solid edges are calls, dashed gold edges are the cross-language HTTP boundaries a single-file context window can never see.

flowchart LR
    m_api["api<br/>1f · 4s · python"]
    m_dotnet["dotnet<br/>1f · 4s · csharp"]
    m_jvm["jvm<br/>1f · 4s · java"]
    m_server["server<br/>1f · 5s · go"]
    m_svc["svc<br/>1f · 5s · rust"]
    m_web["web<br/>1f · 4s · typescript"]
    m_web -. "HTTP ×2" .-> m_api
    m_web -. "HTTP ×2" .-> m_dotnet
    m_web -. "HTTP ×2" .-> m_jvm
    m_web -. "HTTP ×2" .-> m_server
    m_web -. "HTTP ×2" .-> m_svc
    m_api -- "calls ×2" --> m_svc
    m_jvm -- "calls ×4" --> m_server
    m_svc -- "calls ×2" --> m_api
    classDef xlang stroke:#f4b400,stroke-width:3px;
    class m_api,m_dotnet,m_jvm,m_server,m_svc,m_web xlang;

Demos

Five runnable scenarios, each targeting a different audience, in demos/ — run them all with python demos/run_all.py:

See docs/ARCHITECTURE.md for how indexing, the graph store, cross-language resolution, the audit chain, and the MCP server fit together.

MCP tools

When you run codegraph serve, the following tools are advertised to the agent host over MCP (initialize → tools/list → tools/call). Every call is scope-checked and audited.

The server speaks plain JSON-RPC 2.0 — no proprietary transport, no SDK to audit — over either stdio or HTTP. Point a subprocess-style host at codegraph serve, or an HTTP host at codegraph serve --http (bearer token via Authorization: Bearer …, GET /health for readiness). Both transports share the exact same dispatch, scope checks, and audit logging.

Graph diff

codegraph diff <refA> <refB> compares the knowledge graph between two git refs and reports what changed in the shape of the code — not the text:

codegraph diff main feature/x --repo .

{ "summary": { "symbols_added": 3, "symbols_removed": 1, "signatures_changed": 2,
               "endpoints_added": 1, "cross_language_edges_added": 1, ... },
  "cross_language_edges": { "added": [ { "from": "load (typescript)", "to": "get_item (python)" } ] } }

That last line is the one a text diff can never give you: a front-end change and a back-end change in the same PR were newly wired together across a language boundary. Reviewers see the contract that just formed.

Security model

• Scoped, revocable tokens. Agents authenticate with a bearer token mapped to scopes (read, audit, admin). Only a salted BLAKE2b hash of each token is stored, so a database leak doesn't leak usable credentials. Revocation is immediate.

• Tamper-evident audit log. Each record's hash commits to the previous record's hash (BLAKE2b over a canonical JSON encoding). Altering, inserting, or deleting any historical record breaks the chain, and audit --verify reports the first broken sequence number. The scheme is simple enough to re-implement in any language for independent verification.

• Local by construction. SQLite file, standard library only, no outbound network calls except an explicit, read-only git clone when you index a remote.

Language support

Six languages, with cross-language edges resolved between any of them — a single TypeScript fetch('/api/users/:id') resolves to the Python, Go, Rust, Java, and C# handlers serving that route. The extractor interface is language-agnostic; adding a language (or swapping in a tree-sitter backend for one) doesn't touch the indexer or the graph.

Benchmark

The graph earns its keep on the dependency no text search can see: a front-end caller and the back-end handler it depends on share no symbol name, only a route. bench/benchmark.py generates a multi-language repo and measures how often each strategy finds that cross-language dependency:

python bench/benchmark.py --services 120

## cross-language dependency recall
  (find the front-end caller that breaks if a back-end handler changes)
  codegraph (graph impact):   120/120
  grep by symbol name:        0/120
  grep by route substring:    120/120 (files only, not symbols)

100% vs 0%. A symbol-name search can't cross the language boundary at all; a route-substring search finds files but not the symbol-level, transitive impact you actually need. The graph gives you both. (This is the "Navigation Paradox" — independent research finds graph-structured navigation beats retrieval/long-context on exactly these hidden-dependency tasks.)

How it compares

Cloud code assistants give you great comprehension but require sending your code to their infrastructure, where it may be retained or used to improve a model. Self-hosted forges give you control but make you migrate your hosting to get the indexed graph. codegraph-mcp deliberately splits the difference: the comprehension layer is the product, the graph never trains anything, and it overlays the repos you already have.

The overlay model is the wedge: you get the indexed graph and the audit trail without leaving GitHub/GitLab, and the audit is tamper-evident today, not on a roadmap.

Testing

pip install -e ".[dev]"
pytest -q          # 50 tests

License

COCL (Cognis Open Collaboration License). © Cognis Digital.

Status: v0.1 — runnable and tested. HTTP transport, KG diff, project-graph, and incremental (--since) indexing are shipped. Roadmap: more languages (Ruby, Kotlin, PHP) and a watch mode.