The aspark-graph server lets you build and query a local knowledge graph connecting a repository's source code to its aSPARK delivery artifacts (specs, plans, reviews, QA reports), enabling deterministic traceability between user stories and the code that implements them.
Build the graph (build_graph): Scan a repo's source code and .spark/ artifacts to construct and persist a queryable knowledge graph — no LLM or network required.
Trace a user story (story_trace): Follow the full thread of a story — acceptance criteria with latest QA verdicts, mapped plan tasks, and code links.
Assess change impact (impact): Determine the blast radius of a code change by identifying which stories and ACs depend on specified files or a git diff range, tagged with confidence tiers (declared, extracted, or inferred).
Check gate health (gate_health): Inspect aSPARK gate invariants for a feature — orphan tasks, unverified ACs, and open review findings.
Check staleness (staleness): Verify whether the built graph still reflects the current state of the repository on disk.
Look up a node (get_node): Retrieve a single graph node by its deterministic ID (e.g. file:src/foo.py, story:my-feature:US-1).
Search for nodes (find_nodes): Find nodes whose ID or name contains a substring, optionally filtered by type (e.g. File, Story, Function).
Explore neighbors (get_neighbors): Discover nodes within a given number of hops from a target node, optionally filtered by edge type.
Find shortest path (shortest_path): Get the ordered connecting path between any two nodes in the graph.
Click on "Install 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.
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).
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. |
Related MCP server: Knowledge Master
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.
✅ 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).
🤝 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 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#0Requires 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.
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.
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.
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.
# 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
# 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"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.
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.
Code extraction covers TypeScript/JavaScript, Python and Java (tree-sitter).
Files in other languages are recorded as unparsed File nodes — the build never
fails on an unknown language.
Deterministic. Byte-identical rebuild on an unchanged repo; parse-affecting
dependencies are pinned exactly; a double-build test enforces it. The five
tree-sitter grammars (Python, TypeScript, Java, Go, Rust) 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.
Languages beyond the six 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, and Rust.
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.
MIT © Andreas Lottes. Part of the aSPARK product family. Code-graph prior art: Graphify — different scope.
Find nodes whose id or name contains a substring, optionally by type.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | . | |
| type | No | ||
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must disclose behavioral traits. It fails to mention case sensitivity, whether the substring match is exact or fuzzy, pagination, or potential performance impact. For a read-only search, it does not confirm immutability.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words, but it omits essential details that would benefit the agent. It is not verbose but is under-specified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and sparse description, the tool lacks critical context such as return format, error handling, or result limits. For a search operation, this is insufficient for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the tool description does not explain any parameters. The meaning of 'repo' (likely repository path) and 'type' (scope of nodes) is left ambiguous, forcing the agent to guess or assume defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (find) and resource (nodes), and specifies matching on id or name substring with optional type filter. This distinguishes it from sibling tools like get_node (single node) or get_neighbors (adjacent nodes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_node or search. The description only states what it does without context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The aSPARK gate invariants as data: orphan tasks, unverified acceptance criteria, and open findings for a feature.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | . | |
| feature | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for disclosing behavioral traits. It does not state if the tool is read-only, destructive, requires authentication, or has side effects. 'As data' implies read-only, but this is not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it front-loads jargon ('aSPARK gate invariants') without explanation. While not verbose, the structure could be improved by clarifying the tool's action earlier.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema, annotations, and parameter explanations, the description is incomplete. It does not explain the return format, how to interpret the data (orphan tasks, etc.), or how the tool fits into the broader set of sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain parameters, but it only mentions 'feature' generically. It does not clarify what 'feature' means, what 'repo' (default '.') refers to, or how they affect the output. The parameter semantics are almost entirely absent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description vaguely indicates that the tool retrieves data about gate invariants (orphan tasks, unverified acceptance criteria, open findings) for a feature, but lacks a clear verb like 'get' or 'list', making its purpose ambiguous. Compared to sibling tools, it's not immediately obvious what specific action it performs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'impact', 'staleness', or 'story_trace'. There is no mention of prerequisites, context, or scenarios where gate_health is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Nodes within depth hops of a node (both directions); 'what touches this?'.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| repo | No | . | |
| depth | No | ||
| edge_types | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is minimal and does not disclose important behavioral details such as performance characteristics, ordering of results, pagination, or treatment of edge types. Annotations are absent, so the description carries full burden but fails to provide sufficient transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one line), which is efficient but comes at the cost of completeness. It front-loads the purpose but omits essential details, making it borderline under-specified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, four parameters with zero descriptions, and sibling tools that suggest complex graph operations, the description is severely incomplete. It fails to explain the return format, the meaning of 'edge_types' and 'repo', or how depth works, leaving the agent with significant ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain any of the four parameters beyond the mention of 'depth'. With 0% schema description coverage, the description should compensate, but it offers no meaning for 'id', 'repo', or 'edge_types'. The agent cannot infer parameter semantics from this description alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns nodes within 'depth' hops in both directions, using the intuitive phrase 'what touches this?'. This effectively conveys the core functionality and distinguishes it from siblings like 'shortest_path' (which finds paths) or 'build_graph' (which constructs full graph).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'shortest_path' or 'find_nodes'. There is no mention of when not to use it, prerequisites, or context where it might be inappropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| diff | No | ||
| repo | No | . | |
| files | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the mutual exclusivity of input parameters and the output format (stories with confidence), but does not cover error handling, performance, or other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first defines purpose and output, second gives usage constraint. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema or annotations, the description adequately defines input, output, and a key usage rule. It lacks details on error conditions or return structure confidence interpretation, but is likely sufficient for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds meaning for 'files' (list of files) and 'diff' (git diff range) and the 'not both' constraint. However, the 'repo' parameter is not explained, which is a minor gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it computes the blast radius of a change, listing stories and acceptance criteria depending on files or a diff range, each tagged with confidence. It is specific and distinguishes from sibling graph tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies the input constraint (pass either files or diff, not both) but does not explicitly compare to alternative tools like build_graph or find_nodes, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
An ordered path connecting two nodes, or an explicit 'no path' result.
| Name | Required | Description | Default |
|---|---|---|---|
| a | Yes | ||
| b | Yes | ||
| repo | No | . |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description only describes the output format but does not disclose behavior like read-only nature, algorithm, or requirements (e.g., graph must already be built).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The one-sentence description is too short and vague, lacking substantive content. It does not balance brevity with informativeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a shortest path tool, with no output schema and no annotations, the description is insufficient. It fails to explain return format, error cases, or integration with sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should add meaning to parameters. It hints at 'two nodes' but does not explain a, b, or repo, leaving their semantics unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description mentions 'ordered path' and 'no path' result, vaguely indicating graph path finding, but does not specify 'shortest' or the context (e.g., code repository graph). It fails to differentiate from sibling tools like get_neighbors or story_trace.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as build_graph or get_neighbors. No prerequisites or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report whether the built graph still matches the repo on disk (US-4).
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | . |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It only states the function but does not disclose side effects, auth needs, or any behavioral traits beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is very short but includes irrelevant 'US-4' in parentheses. It is efficient but could be cleaner without the extra noise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one optional parameter and no output schema, the description should at least hint at the return type (e.g., boolean). It does not, leaving the agent guessing about output format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% for the 'repo' parameter. Description adds no explanation about the parameter's meaning or usage, leaving the agent without clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool reports whether the built graph matches the repo on disk. Verb 'report' and resource 'staleness' are specific, and it distinguishes from sibling tools like build_graph and find_nodes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full thread of a user story: acceptance criteria (with their latest QA verdict), mapped plan tasks, and any best-effort code links.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | . | |
| story | Yes | ||
| feature | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, so description must convey behavior. It discloses the output structure (acceptance criteria, tasks, code links) but does not mention read-only nature, side effects, or performance characteristics. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the main action. Efficient but could benefit from breaking out the components for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description partially describes the return value (QA verdict, tasks, code links). However, it omits how parameters like 'repo' and 'feature' influence results, and whether multiple stories are returned. Adequate but has gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fails to clarify the roles of 'repo', 'story', and 'feature'. It only mentions 'user story' implicitly. This leaves the agent without understanding how each parameter affects the result.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves a 'full thread of a user story' including acceptance criteria with QA verdict, plan tasks, and code links. It provides a specific verb ('trace' implied) and resource, and is distinct from sibling tools like build_graph or find_nodes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool or when to prefer alternatives. The description only lists output contents, not context or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.4.0build_graphget_nodev0.3.0build_graphfind_nodesgate_healthget_neighborsget_nodeimpactshortest_pathstalenessstory_traceEach tool targets a distinct operation: building the graph, querying nodes by various criteria (single node, substring, neighbors, path), impact analysis, health reporting, and staleness check. No two tools serve the same purpose.
All tool names follow a consistent verb_noun pattern with lowercase and underscores (e.g., build_graph, find_nodes, gate_health). The naming is predictable and uniform.
With 9 tools, the server is well-scoped for a graph-based repository analysis tool. Each tool provides a clear and necessary function without overloading or underproviding capabilities.
The set covers core graph operations (build, query, traverse) and domain-specific features (impact, story trace, health). Minor gaps exist, such as lacking a tool to list all graph nodes or delete the graph, but these do not hinder primary workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
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.
Repository evidence for agents before they adopt dependencies, enter codebases, compare, or merge.
Project memory for coding agents: requirements, decisions, code graph and delivery telemetry.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/a-lottes/aSPARK-graph'
If you have feedback or need assistance with the MCP directory API, please join our Discord server