aspark-graph
This server builds and queries a deterministic knowledge graph linking a repo's code to its aSPARK delivery artifacts (.spark/).
Build the graph (
build_graph): scan a repository and its.spark/artifacts, writing.aspark-graph/(the only writing tool).Trace stories (
story_trace): follow a user story through its acceptance criteria, QA verdicts, plan tasks, and best-effort code links.Assess change impact (
impact): find the stories and acceptance criteria in a file's or git diff's blast radius, tagged by confidence (declared,extracted,inferred); supportsbriefmode and feature prioritization.Check gate health (
gate_health): surface orphan tasks, unverified acceptance criteria, and open findings for a feature.Check freshness (
staleness): verify whether the built graph still matches the repo on disk.Navigate the graph: look up nodes by id (
get_node), search by name/type (find_nodes), explore nearby nodes (get_neighbors), and find paths between nodes (shortest_path).
Integrates with local Git repositories to infer code-to-artifact links from commit history and to compute the blast radius of changes from a Git diff range (e.g., impact --diff HEAD~1..HEAD).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@aspark-graph what code implements user story US-2?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
πΈοΈ 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.pyThat 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?" |
| 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?" |
| 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 |
| tree-sitter extraction |
Artifact |
|
|
Edge types
Edge | Direction | Meaning |
| File β Class/Function | code structure |
| File β File | resolved import |
| Function β Function | best-effort, may be absent |
| Feature β Story | artifact structure |
| Story β AcceptanceCriterion | " |
| Feature β Task | " |
| Task β Story | plan links a task to the story it serves |
| Task β File/Function | the codeβstory bridge (best-effort; see below) |
| QACheck β AcceptanceCriterion | QA result for an AC |
| 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 |
| strongest | an explicit |
| middle | tree-sitter ( |
| weakest | self-derived from git history β treat as a hint, confirm before acting |
Reading a result: an
impacthit taggedinferredreached the story only through a git-history guess; adeclaredhit 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#0Install
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 stepAdd it to Claude Code as an MCP server:
claude mcp add aspark-graph -- uvx aspark-graph serveBuilding 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 stepThe 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.jsonThe 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 |
| An explicit | In |
| Git commit history | Reference the task id and its story id in the commit message β subject |
| tree-sitter ( | 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 |
|
|
QA |
|
|
Release |
|
|
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 committeduv.lockis 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 pytestAdd a checkout to Claude Code as an MCP server:
claude mcp add aspark-graph -- uv run --directory /path/to/aspark-graph aspark-graph serveTo 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 toolsbuild_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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
Repository knowledge graph MCP server for codebase understanding and debugging.
Shared context for your codebase: a hosted code knowledge graph over MCP. Free plan, OAuth sign-up.
Knowledge coverage map and health score. Ingest docs into a governed knowledge graph via MCP.
Hosted code graph over MCP: exact callers, dependencies, and cross-repo blast radius for AI agents.
Related MCP Servers
- AlicenseAqualityCmaintenanceA local knowledge graph MCP server that provides AI agents with permanent, structured memory about codebases, enabling semantic search, blast radius analysis, and convention enforcement.83MIT
- FlicenseNot gradedqualityDmaintenanceAn 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.-
- AlicenseNot gradedqualityDmaintenanceExposes code graphs across multi-program repositories via MCP, enabling humans and agents to query the fleet with evidence.MIT
- AlicenseNot gradedqualityBmaintenanceLets 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.9Apache 2.0