Skip to main content
Glama
sdd-graph-mcp

sdd-graph-mcp

by VitaliyT96

sdd-graph-mcp

A local MCP server that keeps a two-layer, copy-on-write code-contract graph for TypeScript/React repositories and uses it to catch contracts broken by multi-step agentic edits.

The graph lives in the built-in node:sqlite. It has an immutable baseline layer (CURRENT) and a task-scoped delta layer (WIP), the same idea as React Fiber's current / workInProgress trees. A deterministic SQL reconciliation pass diffs the two layers and returns every dependent symbol that still targets an old contract (STALE_CONTRACT). For each one you get the call-site line and the old/new signatures. On bulletproof-react this pass runs in under a millisecond.

Status: v0.1, research prototype. TS/TSX only, purely syntactic (no type checker). See Architectural Trade-offs & Known Limitations before you depend on it.

Design background, SQL derivations, and the survey of prior work behind this engine are in docs/RESEARCH_REPORT_2026.md (covering LocAgent ACL'25, RepoGraph ICLR'25, CodexGraph NAACL'25, InlineCoder FSE'26, ARISE'26, SeeRepo ASE'26, Rivet'26, and the 2026 MCP code-graph servers).


Table of Contents

  1. Motivation: The Baseline Amnesia Problem

  2. Core Architecture

  3. MCP Tool Surface

  4. Comparison with the 2026 Code-Graph Ecosystem

  5. Real-World Benchmarks (bulletproof-react)

  6. Architectural Trade-offs & Known Limitations

  7. Roadmap (v0.2)

  8. Quickstart & Reproducing Benchmarks


Related MCP server: Tently MCP

Motivation: The Baseline Amnesia Problem

Current MCP code-graph servers keep one graph and update it in place. A file watcher re-parses a saved file and overwrites that file's nodes and edges. That works for "chat with your codebase". It breaks for Spec-Driven Development (SDD), where an agent carries out a multi-file change against a written spec:

Failure mode

What happens with a single in-place graph

Baseline amnesia

When the agent changes verifyToken(token) to verifyToken(token, opts), the old signature is overwritten. The graph can no longer tell which of the 12 callers were written against sig_v1 and which were already adapted to sig_v2.

Torn reads

Halfway through a 5-file refactor, the graph is a mix of new and old code. Broken edges look the same as the original topology.

No rollback

An abandoned hypothesis can only be undone by a full re-index.

No commit gate

Nothing stops the agent from declaring the task done while dependents still target the old contract.

You can reconstruct the old signatures from git show HEAD:file. But the SDD task boundary is not the git commit boundary: an agent may edit for dozens of steps without committing, or commit midway. sdd-graph-mcp makes the task baseline an explicit, queryable layer. It does not rely on version control to provide it.


Core Architecture

flowchart LR
    subgraph Parse["Two-pass extractor"]
        TS["web-tree-sitter TS/TSX (WASM)"] --> P1["Pass 1: symbols, imports, re-exports, references"]
        OXC["oxc-resolver (tsconfig paths, index files)"] --> P1
        P1 --> P2["Pass 2: transitive barrel unwrapping + edge linking"]
    end
    P2 -->|init_current| CUR[("CURRENT layer")]
    P2 -->|sync WIP via git status or file list| WIP[("WIP layer (delta + tombstones)")]
    CUR --> V["Virtual merged graph: WIP over CURRENT"]
    WIP --> V
    V --> Q["sdd_query_subgraph (signatures only)"]
    CUR --> R["Reconciliation (STALE_CONTRACT)"]
    WIP --> R
    R -->|0 stale| C["commit: WIP -> CURRENT"]
    R -->|stale > 0| A["agent fixes dependents"]

1. Two-layer copy-on-write store on node:sqlite

  • Three tables: nodes, edges, specs. All are WITHOUT ROWID and clustered on a composite primary key ending in layer IN ('CURRENT','WIP'), for example PRIMARY KEY (node_id, layer).

  • CURRENT is read-only for the duration of a task. All mutations go to WIP. A deletion is written as a WIP row with is_tombstone = 1, and CURRENT is left untouched.

  • Every read resolves through a single overlay rule. For each LEFT JOIN pair w (WIP) and c (CURRENT):

    WHERE COALESCE(w.is_tombstone, c.is_tombstone, 1) = 0

    The rule returns the WIP row if one exists and is live. It hides the symbol if WIP tombstoned it. It falls back to CURRENT otherwise, and treats IDs that exist in neither layer as absent.

  • Commit runs in one BEGIN IMMEDIATE transaction. It applies tombstones, promotes live WIP rows, removes orphaned edges and clears WIP. Abort is three DELETE ... WHERE layer = 'WIP' statements.

  • There are no native build steps: storage is node:sqlite (DatabaseSync, WAL), the parser is WASM, and the resolver ships as a prebuilt Rust N-API binary (oxc-resolver).

2. signature_hash (contract) vs body_hash (implementation)

Each callable is stored with two hashes. Both are computed over source with comments stripped by AST byte range and whitespace collapsed:

Hash

Covers

Effect when changed

signature_hash

Everything up to the body: modifiers, generics, parameters, return annotation. For interface and type declarations, the full declaration.

Triggers reconciliation for dependents

body_hash

The function body / JSX

Ignored by reconciliation; 0 false STALE_CONTRACT

Each dependency edge stores expected_target_hash: the target's signature_hash at the time the edge was extracted. Node IDs are canonical: src/components/ui/button/button.tsx::Button#component.

For callables, signature_hash is a contract hash, not a hash of the raw signature text. Parameter binding patterns and default values are cut out by AST range before hashing, because TypeScript parameters are positional. Whitespace around punctuation and Prettier trailing commas are normalized away. As a result, the following do not change the contract:

  • parameter renames;

  • destructuring changes (({ a }: Props) → ({ a, b, ...rest }: Props));

  • default values;

  • reformatting.

Parameter types, arity, optionality, return type, async, and wrapper generics (forwardRef<HTMLButtonElement, ButtonProps>) still do. The human-readable signature column keeps the original text.

3. Two-pass AST extraction with barrel unwrapping

  • Pass 1 (per file, web-tree-sitter): top-level function, arrow/function-expression consts (including memo(...) / forwardRef(...) wrappers around inline functions), interface, and type. For each it records:

    • imports and re-exports;

    • references inside each declaration: CALLS (call_expression), RENDERS_JSX (jsx_opening_element / jsx_self_closing_element), and USES_TYPE (type_identifier).

  • Pass 2 (project): each import is resolved through oxc-resolver (tsconfig paths/baseUrl, index files, extension aliases). It is then followed through any chain of export * / export { a as b } from re-exports to the defining symbol. A visited set keyed on (file, exportedName) makes cyclic barrels (A -> B -> A) terminate. Edges that were resolved through at least one barrel are tagged resolution_mode = 'BARREL_UNWRAPPED'.

  • Incremental sync re-parses only changed files into WIP. Unchanged files are resolved against the effective (WIP over CURRENT) node map loaded from SQLite.

    • Changed files are discovered with git status --porcelain -- . and re-based from the git top-level (git rev-parse --show-toplevel) onto projectRoot. A monorepo sub-package such as apps/web therefore works as a project root, and changes in sibling packages are ignored.

  • WASM memory: each Tree-sitter tree is freed with tree.delete() in a finally block. The WASM heap is not managed by the JS garbage collector.

4. Hub damping

Utilities such as cn() have dozens to hundreds of callers. A naive bidirectional k-hop query from Button reaches cn at hop 1 (outbound). At hop 2 it then pulls in every unrelated component that also calls cn.

querySubgraph blocks inbound expansion from a node that was reached via an outbound edge at hop ≥ 1 when that node's distinct in-degree exceeds maxHubInDegree (default 20). The hub is still returned. Its co-dependents are not. Direct callers of the seed (hop 1 inbound) are never damped.

The hub test is a correlated subquery that runs once per candidate edge. Its distinct count is therefore bounded with LIMIT maxHubInDegree + 1, so each check costs O(min(in-degree, threshold)) instead of O(in-degree). This avoids O(in-degree²) behaviour on large hubs: a 5,000-caller hub is damped in about 13 ms, versus 2.4 s with an unbounded COUNT(DISTINCT).

5. Reconciliation: deterministic STALE_CONTRACT detection

A recursive CTE starts from the (small) WIP layer:

  • d = 1 (DIRECT_SIGNATURE_MUTATION / TOMBSTONED_TARGET): U is stale when all of the following hold:

    • target T changed its signature_hash in WIP or was tombstoned;

    • the CALLS | USES_TYPE | RENDERS_JSX edge U -> T is still live;

    • U has not been adapted. That means one of:

      • U is not in WIP at all;

      • U is in WIP only because its file was re-parsed, with unchanged body_hash and signature_hash;

      • U's edge still carries the old expected_target_hash.

  • d = 2 (TRANSITIVE_TYPE_CONTRACT_DRIFT): drift propagates in two cases:

    • from a stale interface/type to its USES_TYPE dependents;

    • from a component that is stale through its props type (USES_TYPE at d = 1) to every parent that renders it (RENDERS_JSX): ButtonProps -> Button (d=1) -> <Button/> call sites (d=2).

    Depth is capped at 3. Cycles are cut by a visit path.

Each report row contains: the stale node, file, broken line, dependency type, mutated target, old/new signature and old/new hash. Output order is deterministic (propagation_depth, file, line), which keeps the agent's prompt-cache prefix stable.

stateDiagram-v2
    [*] --> CURRENT: init_current
    CURRENT --> WIP: agent edits .ts/.tsx
    WIP --> Reconcile: sdd_reconcile_wip
    Reconcile --> WIP: STALE_CONTRACT > 0
    Reconcile --> Commit: STALE_CONTRACT == 0
    Commit --> CURRENT: atomic WIP -> CURRENT
    WIP --> CURRENT: abort (DELETE WIP)

MCP Tool Surface

There are four tools. The tool schema never changes at runtime: no dynamic enums or counters, so the tool list stays prompt-cache friendly. All output is sorted deterministically (hop_distance, node_id).

Tool

Purpose

sdd_query_subgraph

k-hop (1..5) merged subgraph around a symbol. Returns signatures + JSDoc + edge traces with call-site lines only, never bodies.

sdd_read_implementation

Reads exact start_line..end_line source for selected nodes from disk, right before editing them.

sdd_reconcile_wip

Syncs changed files into WIP (explicit list or git status), runs reconciliation, and returns commit_gate: PASSED | BLOCKED_BY_STALE_CONTRACTS.

sdd_lifecycle

init_current | status | commit (gated; force bypasses the gate) | abort.


Comparison with the 2026 Code-Graph Ecosystem

These tools are broader and more mature than this project. The table only compares the axis this project is built around: state over the lifetime of an editing task. Descriptions of other tools are based on their public documentation as of November 2026.

Parsing & resolution

Storage

Update model

Pre-task baseline kept?

Contract-drift output

@colbymchenry/codegraph

Tree-sitter, many languages

SQLite + FTS5

File watcher, incremental in-place sync

No (single layer)

Callers / impact of the current state

Repowise

Tree-sitter, multi-tier call resolution; PageRank, Leiden communities; git churn/co-change

SQLite + LanceDB (hybrid FTS/vector)

Re-index / incremental

No (single snapshot + git history analytics)

Change-risk / blast-radius scoring

codebase-memory-mcp

Native binary, 150+ Tree-sitter grammars + hybrid LSP-style type resolution for ~10 languages incl. TS

SQLite

Incremental; maps git diff onto graph

No (single layer)

Impact of a git diff

Aider RepoMap

Tree-sitter tags; file graph + personalized PageRank under a token budget

mtime-keyed tag cache

Recomputed per request

N/A (context selection, not a contract graph)

None

sdd-graph-mcp

Tree-sitter TS/TSX + oxc-resolver + barrel unwrapping; no type checker

node:sqlite, CURRENT/WIP CoW

Explicit sync into WIP, atomic commit/abort

Yes

STALE_CONTRACT with old/new signature, call-site line, d=1/d=2, commit gate

Where the others are stronger:

  • language coverage (one language vs 100+);

  • type-aware resolution (hybrid LSP resolves member calls on inferred types, which this project does not);

  • community detection and centrality ranking;

  • semantic/vector search;

  • git-history analytics;

  • maturity and tooling.

What this project adds: the baseline is an explicit, queryable layer. It provides three things that a single in-place graph cannot express without re-parsing history:

  • the "which dependents have not been adapted yet" relation;

  • consistent reads of the work-in-progress state;

  • O(1) rollback.

Why not just use an existing graph, or tsc?

  • Why not run tsc --noEmit? Keep running it. It is the ground truth and remains the final gate. Reconciliation is a cheap per-step pre-filter:

    • it returns a structured worklist (node, line, old/new signature) instead of compiler diagnostics;

    • it costs less than a millisecond instead of a type-check of the whole project;

    • it also flags dependents whose code still compiles against a changed contract (for example, a newly added optional parameter), which tsc cannot report.

  • Why not add a WIP layer to an existing tool? Their schemas key nodes by a single id, and every query assumes one layer. Adding layer, tombstones and hash-pinned edges touches every query. The CoW store here is about 1,000 lines. The reusable part (Tree-sitter extraction) is the commodity part.


Real-World Benchmarks (bulletproof-react)

Target: alan2207/bulletproof-react @ 9506629, all three apps, 415 .ts/.tsx files. Measured on an Apple Silicon laptop with Node.js 24.8.0 and an in-memory database; three runs.

Metric

Result

Cold baseline index (CURRENT)

300–400 ms (≈1,000–1,370 files/s), parse + resolve + SQLite insert

Extracted graph

830 nodes (component 324, type_alias 267, function 191, hook 48); 2,224 edges

Edges recovered through barrels (BARREL_UNWRAPPED)

513 / 2,224 (23.1 %): IMPORTS 262, RENDERS_JSX 248, USES_TYPE 3. A resolver that stops at index.ts loses these edges.

2-hop subgraph of Button (react-vite), no damping

121 nodes / 65 files / 11.57 KB of signatures, ≈6 ms

Same, hub damping (maxHubInDegree = 20)

98 nodes / 63 files / 8.75 KB, ≈3.5–5 ms; 23 unrelated cn() co-callers removed

Context size vs. reading the same files raw

8.75 KB vs 107.99 KB → −91.9 % (bytes, not tokens)

Reconciliation after mutating ButtonProps in WIP

0.5–0.7 ms (includes the WIP upsert); 27 STALE_CONTRACT: 2 at d=1 (Button, PaginationLinkProps), 25 at d=2 (<Button/> render sites such as LandingRoute, DashboardLayout, ConfirmationDialog)

Query plans

SEARCH ... USING PRIMARY KEY / covering index for every nodes/edges access (SCAN only over CTE rows)

How to read these numbers:

  • The d=2 result over-approximates. It flags every <Button/> site for any ButtonProps change, including additive optional props (see limitations).

  • The context-reduction figure compares against the raw files that contain the subgraph's nodes, not against a whole-repo dump.


Architectural Trade-offs & Known Limitations

Each limitation below is either an explicit design choice or a known gap. Items marked (planned) have a scoped fix in the roadmap.

Precision and recall of contracts (no type checker)

  • Inferred contracts are invisible. A hook with no return annotation changes its real contract through its body, but only body_hash changes. The same applies to z.infer<typeof schema>, ReturnType<...>, and generic inference. All of these need a TypeChecker. (planned: on-demand checker for WIP nodes)

  • Hash equality, not compatibility. Adding an optional prop is reported exactly like adding a required one. There is no variance or structural diff.

  • Acknowledgement is node-level, not call-site-level. A caller counts as adapted when its own body_hash or signature_hash changed in WIP. Re-parsing an untouched caller does not clear it; a regression test covers this. Editing an unrelated line inside the same function does clear it. (planned: per-edge call_site_hash)

  • commit with force: true makes drift invisible. After promotion, reconciliation only diffs WIP against CURRENT. The mismatch survives in CURRENT.expected_target_hash, but nothing checks it yet. (planned: latent-drift integrity query)

Extractor coverage (TS/TSX)

Not extracted as nodes:

  • class and enum declarations;

  • non-function consts: zod schemas, cva variants, config objects. In bulletproof-react this is roughly 134 of 432 exported consts;

  • memo(Identifier) / forwardRef(Identifier) wrapping a named function;

  • anonymous export default;

  • overload signatures (only the implementation signature is hashed).

Not resolved as edges:

  • export * as NS from;

  • compound components assigned via Object.assign (<Form.Item /> through a named import; import * as F works);

  • 3-level JSX namespaces;

  • lazy(() => import(...));

  • member calls on values (api.get()).

Other gaps:

  • Unresolved references are dropped silently. There is no UNRESOLVED diagnostic, so a missing edge is indistinguishable from no dependency.

  • The schema reserves EXTENDS, PASSES_PROPS, IMPLEMENTS_SPEC, VERIFIED_BY_TEST and the class / method / variable / module kinds. v0.1 emits only IMPORTS, CALLS, RENDERS_JSX, USES_TYPE and five node kinds. extends clauses are captured as USES_TYPE.

  • Only .ts / .tsx; .d.ts is skipped.

Performance and operations

  • WIP discovery is relative to git HEAD, not to CURRENT. Files committed into CURRENT but not into git are re-synced on every call. This is idempotent but wasteful.

  • No staleness check between a persisted CURRENT and the files on disk after a restart. Run init_current if in doubt.

  • Commit-time orphan cleanup is a full scan of CURRENT edges (O(E)).

  • web-tree-sitter is pinned to 0.20.x.


Roadmap (v0.2)

  1. SPEC_DRIFT. Parse .md specs into specs (heading anchors → spec_id, content_hash). Link code via @spec path.md#anchor JSDoc tags (IMPLEMENTS_SPEC). Report nodes whose spec section changed in WIP while the code did not, using the same CTE pattern as STALE_CONTRACT.

  2. Per-edge call_site_hash (normalized call expression / JSX opening element) for call-site-level acknowledgement.

  3. Latent-drift integrity check on CURRENT (expected_target_hash != target.signature_hash), surfaced in status and after force commits.

  4. UNRESOLVED_REFERENCE diagnostics for references that resolve to no symbol.

  5. On-demand TypeScript checker (LSP_TYPECHECKER resolution mode), limited to unresolved member calls and unannotated return types of WIP nodes.

  6. Extractor coverage: enum, class/method, schema consts, memo(Ident), export * as NS, compound components.


Quickstart & Reproducing Benchmarks

Requirements: Node.js with built-in node:sqlite and native TypeScript type stripping. Tested on Node 24.8.0; Node ≥ 22.18 should work. No build step: sources run as .ts directly.

npm install
npm test                      # node:test, 21 tests (store, extractor, indexer, MCP e2e)

Benchmarks:

# Synthetic TS/React repo (offline)
npm run bench -- --synthetic 200

# bulletproof-react (shallow clone into a temp dir, removed afterwards)
npm run bench -- --clone https://github.com/alan2207/bulletproof-react.git

# Any local checkout
npm run bench -- --repo /path/to/project

The benchmark prints the following, in order:

  1. cold-index statistics with the edge breakdown by resolution_mode;

  2. the damped vs. undamped 2-hop subgraph around Button, with EXPLAIN QUERY PLAN;

  3. the d=1 / d=2 reconciliation report after mutating ButtonProps in WIP.

MCP client configuration (Claude Code / Cursor / Antigravity):

{
  "mcpServers": {
    "sdd-graph": {
      "command": "node",
      "args": [
        "--no-warnings",
        "/abs/path/to/sdd-graph-mcp/src/index.ts",
        "--project-root", "/abs/path/to/your/repo",
        "--init-current"
      ]
    }
  }
}

Options:

Flag

Default

--db-path <file>

.sdd-graph/sdd-graph.db

--memory

in-memory database

--init-current

index CURRENT on startup

The same settings are available as env vars: SDD_PROJECT_ROOT, SDD_DB_PATH, SDD_AUTO_INIT=1.

Typical agent loop:

  1. sdd_lifecycle(init_current).

  2. sdd_query_subgraph → sdd_read_implementation → edit.

  3. sdd_reconcile_wip, then fix each reported STALE_CONTRACT.

  4. Repeat steps 2–3 until commit_gate = PASSED.

  5. Run tsc --noEmit and the tests.

  6. sdd_lifecycle(commit).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI coding agents to query a live, type-aware, intent-aware cross-repo index of an organization's TypeScript services, answering semantic questions about functions, endpoints, types, and behavior across repositories. It also supports validation of cross-repo API mismatches and same-repo checks.
      7
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables coding agents such as Claude Code and Cursor to check a team's learned decisions from pull requests, reviews, and docs before writing code, showing whether breaking them is blocking or advisory. It also provides locally computed symbol impact/blast-radius analysis so source code never leaves the machine.
      67 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables coding agents to navigate and verify a contract-backed semantic graph of TypeScript backends, inspect change impact, run checks, explain failures, and draft human-reviewable contracts through bounded MCP tools and matching JSON CLI output.
      Apache 2.0
    • F
      license
      B
      quality
      B
      maintenance
      Enables AI coding agents to maintain an architecture board, retrieve focused code slices with contracts and exact line ranges, and run fast pre-commit verification that tracks downstream impact. It helps keep architecture rules, code, and Git history synchronized without manual spec bookkeeping.
      8
      -