Skip to main content
Glama

πŸ•ΈοΈ aspark-graph

A lean, local knowledge graph that joins a repo's code to its delivery artifacts β€” so agents and humans can trace a user story to the code that implements it, and see the story-level blast radius of a change.

aspark-graph reads one repository β€” its source code and its aSPARK .spark/ delivery trail (specs, plans, reviews, QA reports) β€” and builds a single queryable graph, served over a CLI and an MCP server. It is deterministic (tree-sitter + declared artifact links; no LLM, no network) and disposable (the graph is a rebuildable read model, never a source of truth).

β–Ά Watch the 60-second explainer β€” real output only: the graph on screen is this repository's own graph at v0.7.1.

Try it in 30 seconds

No aSPARK project of your own? This repository has a real delivery trail, so it works as the demo. You need uv and a full clone:

git clone https://github.com/a-lottes/aSPARK-graph && cd aSPARK-graph
uvx aspark-graph build .
uvx aspark-graph query impact src/aspark_graph/queries.py

That prints the user stories and acceptance criteria a change to queries.py touches, each tagged declared, extracted or inferred. Use a full clone: inferred links come from the git history, and a shallow clone (--depth 1) builds without them.


Related MCP server: kg-memory-mcp

The two questions it exists to answer

Everything else is in service of these:

Question

Tool

Plain meaning

"Which code implements this user story, and did its acceptance criteria pass QA?"

story_trace US-2

Follow story β†’ ACs β†’ plan tasks β†’ code β†’ QA results, with zero grepping.

"If I change these files, which stories and acceptance criteria are in the blast radius β€” what must QA re-verify?"

impact src/foo.py

Walk code β†’ tasks β†’ stories/ACs, tagging each hit with how trustworthy the link is.

Why this exists

When an AI agent (or the developer supervising it) works on an aSPARK-managed repo too large to hold in your head, those two questions are exactly the ones aSPARK's own review and QA gates depend on β€” and today the only way to answer them is Grep/Glob plus reading .spark/ files by hand.

The spec β†’ plan β†’ review β†’ QA trail is machine-parseable, and it is linked to code by intent. But nothing joins the two, so an agent re-derives the link every time it greps: slowly, incompletely, and non-reproducibly. aspark-graph computes that join once, deterministically, and lets you query it.

It does this by deliberately doing less on the code side than a general code graph, and adding the one thing general graphs don't have: the delivery artifacts. That artifact layer is what makes story tracing, gate-aware impact, and orphan detection possible at all.

When to use it β€” and when not

  • βœ… Use it on an aSPARK repo big enough that "read every relevant file" isn't viable, when you need a fast, reproducible answer before opening files.

  • ❌ Skip it on a repo small enough to hold in your head (just read the files), or a repo with no .spark/ artifacts (the artifact layer is the whole point; to see what it does, run the demo above on this repository).

  • 🀝 Want a broad semantic code graph too? Run Graphify alongside it β€” different scope, no conflict. aspark-graph is an accelerant for aSPARK, not a replacement for a code-search tool.

Using aspark-graph in aSPARK gates? See docs/aspark-integration.md for drop-in CLAUDE.md blocks that wire the /peer-review and /demo-day gates to the query tools.

Trust boundary, non-guarantees, and how to report a vulnerability: see SECURITY.md β€” read it before treating this server's output as anything other than data.


The graph model (read this to interpret any result)

The graph is a typed, directed multigraph. Every node id is stable and deterministic, derived only from content and location, so two builds of an unchanged repo produce byte-identical ids and a byte-identical graph.json.

Node types

Layer

Types

Source

Code

File, Class, Function

tree-sitter extraction

Artifact

Feature, Story, AcceptanceCriterion, Task, Finding, QACheck

.spark/ templates

Edge types

Edge

Direction

Meaning

contains

File β†’ Class/Function

code structure

imports

File β†’ File

resolved import

calls

Function β†’ Function

best-effort, may be absent

has_story

Feature β†’ Story

artifact structure

has_ac

Story β†’ AcceptanceCriterion

"

has_task

Feature β†’ Task

"

maps_to

Task β†’ Story

plan links a task to the story it serves

implements

Task β†’ File/Function

the code↔story bridge (best-effort; see below)

verifies

QACheck β†’ AcceptanceCriterion

QA result for an AC

found_in

Finding β†’ File

a review finding's location

Confidence tiers β€” every artifact/code link carries a tier, and impact reports the weakest link on the strongest path so you can trust a result appropriately:

Tier

Rank

Where it comes from

declared

strongest

an explicit files: note in a plan task

extracted

middle

tree-sitter (contains/imports) β€” deterministic structure

inferred

weakest

self-derived from git history β€” treat as a hint, confirm before acting

Reading a result: an impact hit tagged inferred reached the story only through a git-history guess; a declared hit rests on an author-written link. The tier never raises confidence β€” it reports the weakest step, so an inferred edge can only ever lower a path's trust, never mask a real one.

Node id schemes (useful when constructing get_node/shortest_path queries):

file:<relpath>                     e.g. file:src/aspark_graph/queries.py
def:<relpath>::<qualname>          e.g. def:src/foo.py::Widget.render
feature:<name>                     e.g. feature:aspark-graph
story:<feature>:<id>               e.g. story:aspark-graph:US-1
ac:<feature>:<id>                  e.g. ac:aspark-graph:AC-1.2
task:<feature>:<id>                e.g. task:aspark-graph:T3
finding:<feature>:<id>             e.g. finding:aspark-graph:F1
qa:<feature>:<ac>#<index>          e.g. qa:aspark-graph:AC-1.1#0

Install

Requires Python β‰₯ 3.11. aspark-graph is published on PyPI:

pip install aspark-graph
# or, with uv:
uvx aspark-graph build .   # build the graph for the current repo, no install step

Add it to Claude Code as an MCP server:

claude mcp add aspark-graph -- uvx aspark-graph serve

Building from source (for contributors) is documented under Development below.

Update

pip install --upgrade aspark-graph
# or, with uvx, the latest published version always runs β€” no separate update step

The graph is not forwards-compatible across versions: always rebuild after updating (aspark-graph build .). Incremental builds (v0.4.0+) make this fast β€” only changed files are re-parsed, so a routine update rebuild takes seconds on most repos.

Build the graph

aspark-graph build [path]     # scans code + .spark/, writes .aspark-graph/graph.json

The graph is written to .aspark-graph/graph.json at the repo root (gitignore it β€” it's rebuildable). Re-running build on an unchanged repo produces a byte-identical graph. Parsing fails loudly on .spark/ template drift (it names the file and the mismatch) rather than silently guessing.

Query

Every query is available on both the CLI and MCP, and they return identical answers by construction (all query logic lives in one shared module; the CLI and server are thin adapters over it, and a parity test enforces it). Output is JSON.

CLI

# The two headline queries
aspark-graph query story_trace US-2 --feature my-feature
aspark-graph query impact src/foo.py src/bar.py
aspark-graph query impact --diff HEAD~1..HEAD      # blast radius of a change range
aspark-graph query impact --diff HEAD~1..HEAD --brief --feature my-feature   # bounded answer for an agent

# Gate & freshness
aspark-graph query gate_health my-feature          # are this feature's ACs covered / passing?
aspark-graph query staleness                        # does the graph still match the repo on disk?

# Graph navigation
aspark-graph query get_node "file:src/foo.py"
aspark-graph query find_nodes Widget --type Class
aspark-graph query get_neighbors "story:my-feature:US-1" --edge-type has_ac
aspark-graph query shortest_path "task:my-feature:T1" "ac:my-feature:AC-1.1"

--brief β€” the answer an agent can read in one go. The full impact answer lists every code entity, story and AC per file; on a grown repo that is tens of kilobytes, past what an agent's tool result holds. --brief (MCP: brief=true) returns the same hits regrouped: one entry per story, grouped by feature, with the story's confidence, its ACs by confidence tier and the changed files that reach it (via). Files carry counts, not lists. With --feature <name> the stories of other features come first under other_features and the named feature's own under this_feature β€” the first list is what a change breaks unnoticed. The answer is bounded (30 stories, 20 ACs and 5 via paths per story); when a bound cuts, truncated is true, acs_total/via_total name the full counts, totals always counts everything, and the own feature is cut before the others. Without --brief the answer is unchanged.

MCP

The same operations are exposed as MCP tools: story_trace, impact, gate_health, staleness, get_node, find_nodes, get_neighbors, shortest_path β€” all eight read-only, plus build_graph, the one tool that writes (<target>/.aspark-graph/graph.json and parse-cache.json). Querying before a build (or any domain error) returns a clean {"found": false, ...}-shaped result β€” never a raw traceback. See SECURITY.md for the full trust boundary.

Linking code to stories

impact and story_trace are only as useful as the implements (task→code) links they can find. aspark-graph establishes those links three ways, strongest to weakest confidence:

Confidence

Source

How to opt in

declared

An explicit files: note on a plan task

In plan.md, add files: <path> to a task's Definition of Done cell, e.g. … ; files: src/foo.py. The link is created only if the file exists β€” a dangling path is ignored, never fabricated.

inferred

Git commit history

Reference the task id and its story id in the commit message β€” subject T3: add parser (US-1) or a Refs: T3, US-1 trailer. Any file that commit touched is linked to the task at inferred confidence.

extracted

tree-sitter (contains/imports)

Automatic β€” no action needed.

Recommendation for aSPARK repos: make one commit per task whose message names the task and story ids (the convention aSPARK's own workflow already encourages). That alone lets impact answer on a repo that was never hand-annotated.

Inference is deterministic (it reads only committed state — file paths and message ids, never timestamps) and offline; if git is unavailable it is simply skipped. When multiple .spark/ features reuse the same T<n>/US-<n> numbering, a commit is resolved to a single feature before linking (by the .spark/<feature>/ tree it touched, or by a unique task→story pairing in its message); a genuinely ambiguous commit contributes no edge — an honest absence over a wrong cross-feature link.

Shallow clones and ZIP downloads

inferred links need commit history. A shallow clone (git clone --depth 1, the default in many CI setups) has only part of it, and a ZIP download has none. When the graph has at least one plan task, build says so on stderr:

Shallow git history: inferred links may be missing (run 'git fetch --unshallow', then rebuild).
No git history: inferred links are missing (build from a full git clone to get them).

At most one of the two lines appears. MCP build_graph reports the same as two booleans, shallow_history and no_git_history. In a shallow clone, git shows the oldest kept (boundary) commits as adding every file, so the build skips their inferred links: impact can show fewer links than on a full clone, never extra ones. The exit code and the stdout format are unchanged, and on a full clone graph.json is byte-identical to earlier versions. To get the missing links, run git fetch --unshallow (or build from a full clone) and rebuild.

Supported languages

Code extraction covers Python, TypeScript/JavaScript, Java, Go, Rust and C# (tree-sitter; C# using directives resolve to in-repo namespaces, best-effort). Files in other languages are recorded as unparsed File nodes β€” the build never fails on an unknown language.

Artifacts read

Per feature folder in .spark/, the graph parses spec.md and plan.md, plus review, QA and release files under either name aSPARK has used:

Artifact

Current name

Legacy name

Review

review.md

review-report.md

QA

qa.md

qa-report.md

Release

release.md

release-notes.md

When both names exist in one folder, the current name wins. The build names the ignored file (Ignored … (qa.md takes precedence) on stderr, ignored_legacy_files over MCP), and the ignored file leaves no trace in the graph. A QA result cell is read by its marker first β€” ❌ fail, ⚠ unverified, βœ… pass β€” and by its words only when it has none.

Design guarantees (why you can trust the output)

  • Deterministic. Byte-identical rebuild on an unchanged repo; parse-affecting dependencies are pinned exactly; a double-build test enforces it. The tree-sitter grammars (Python, TypeScript, Java, Go, Rust, C#) and tree-sitter core are pinned with ==, and the committed uv.lock is part of the determinism contract for the rest β€” a grammar version can change the node types it extracts, so an unpinned grammar would silently break byte-identity. The guarantee's boundary: byte-identical rebuild holds for an unchanged repo on a fixed grammar set. A grammar bump is a deliberate, changelog-documented, version-bumped event β€” never a silent change to what a past build promised.

  • Offline & LLM-free. No network, no model calls β€” just AST parsing and artifact-template parsing.

  • Fails loudly, never silently. Template drift raises a named error; it never skips or guesses.

  • Clean errors. Domain errors (drift, graph-not-built) surface as one-line messages with a non-zero exit / a structured dict β€” never a stack trace.

  • Disposable. The graph is a read model. Delete .aspark-graph/ and rebuild; the source of truth is always the code and the .spark/ files.

Out of scope

Languages beyond those currently supported, an LLM/natural-language layer, precise call-graph resolution, a visualization UI, exports (Neo4j/GraphML/Obsidian), HTTP/team mode, and authenticated or remote MCP transport are out of scope. The current language support is Python, TypeScript/JavaScript, Java, Go, Rust, and C#.

Development

Requires uv. Build and run from a checkout:

git clone https://github.com/a-lottes/aSPARK-graph.git aspark-graph
cd aspark-graph
uv sync --extra dev
uv run aspark-graph build .   # build the graph for the current repo
uv run pytest

Add a checkout to Claude Code as an MCP server:

claude mcp add aspark-graph -- uv run --directory /path/to/aspark-graph aspark-graph serve

To pick up upstream changes: git pull && uv sync --extra dev.

The project dogfoods itself: its own .spark/aspark-graph/ trail is the primary test fixture, so touching the parser or a query is checked against a real aSPARK trail.

License

MIT Β© Andreas Lottes. Part of the aSPARK product family. Code-graph prior art: Graphify β€” different scope.

Available Tools

9 tools
build_graphA

(Re)scan a repository and its .spark/ artifacts and persist the graph. Writes /.aspark-graph/ β€” this is the one MCP tool that writes.

Inputs: path.

find_nodesC

Find nodes whose id or name contains a substring, optionally by type.

Inputs: query (required), repo, type.

gate_healthC

The aSPARK gate invariants as data: orphan tasks, unverified acceptance criteria, and open findings for a feature.

Inputs: feature (required), repo.

get_neighborsC

Nodes within depth hops of a node (both directions); 'what touches this?'.

Inputs: id (required), repo, depth, edge_types.

get_nodeB

Look up a single node by its id (e.g. 'file:src/foo.py').

Inputs: id (required), repo.

impactA

Blast radius of a change: the stories and acceptance criteria that depend on the given files (or the files in a git diff range), each tagged with its weakest-edge confidence. Pass either files or diff, not both.

Prefer brief=true: a bounded answer with the stories grouped by feature, their acceptance criteria and the files that reach them, without entity lists. With feature set to the feature you are working on, the stories of other features come first (other_features) β€” the ones a change breaks unnoticed.

Inputs: diff, repo, brief, files, +1 more.

shortest_pathC

An ordered path connecting two nodes, or an explicit 'no path' result.

Inputs: a (required), b (required), repo.

stalenessC

Report whether the built graph still matches the repo on disk (US-4).

Inputs: repo.

story_traceB

Full thread of a user story: acceptance criteria (with their latest QA verdict), mapped plan tasks, and any best-effort code links.

Inputs: story (required), repo, feature.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 9 tools

    Disambiguation4/5

    Each tool maps to a distinct query shape: substring search (find_nodes), id lookup (get_node), traversal (get_neighbors), pathfinding (shortest_path), freshness (staleness), invariants (gate_health), and aggregation (impact, story_trace). The main soft spot is the family of impact/story_trace/get_neighbors, which all answer variations of 'what is affected by X' at different abstraction levels; descriptions differentiate them, but an agent must read carefully to pick the right one.

    Naming Consistency4/5

    Six of nine tools follow a clear verb_noun or verb pattern (build_graph, find_nodes, get_node, get_neighbors, shortest_path, story_trace) in consistent snake_case. The remaining three (impact, gate_health, staleness) are bare nouns, a minor deviation that is still readable and semantically sensible given they are report-style queries.

    Tool Count5/5

    Nine tools is well within the ideal range and each covers a distinct graph operation: build, lookup, search, traverse, path, and four analytical reports. Nothing feels redundant or padded.

    Completeness4/5

    The lifecycle is well covered: the graph is built (build_graph), validated (staleness), queried at node/neighbor/path levels, and analyzed via impact, gate_health, and story_trace. Minor gaps exist β€” there is no explicit way to enumerate features, edge types, or the full node set without a substring, and no direct query for a story's raw acceptance-criteria records outside story_trace.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      An in-memory knowledge graph MCP server that gives coding agents structural and semantic recall over codebases by indexing Python source, ADR documents, and project configuration, exposing 7 tools for search, traversal, context retrieval, and natural-language Q&A.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Lets coding agents query a hosted knowledge graph of a git repository over MCP or the shell to retrieve recorded commit intent, co-change coupling, ranked blast radius, and computed architecture. Answers are drawn from the graph rather than file reads, reporting measured per-answer token savings.
      9
      Apache 2.0