Case Study · Architecture
Service-Graph MCP Tool — Giving AI Agents a Map of a Microservice Estate
An MCP server that turns a wiki-style documentation repo into a queryable dependency graph AI agents traverse natively — so coding sessions are grounded in real service topology instead of hallucinated architecture.
- Status
- ARCHITECT
- Year
- 2026
- Role
- Solo build
- Stack
- Node.jsTypeScriptMCP
Problem
Large microservice estates have a knowledge problem: no single engineer — and no AI coding assistant — holds the full picture of service dependencies. When asked "what breaks if we change this API?", the answer lives in scattered wikis and tribal knowledge.
The cost is paid on every change. Engineers reconstruct the dependency picture by hand, cross-referencing docs that drifted from reality months ago and pinging the few people who still remember how the pieces fit together. The blast radius of a change is rarely visible before the change ships.
AI assistants make this worse. Without structured context, they suggest changes with hidden blast radius — confidently editing an endpoint without knowing which downstream services consume it, or proposing a refactor that silently breaks a contract three hops away.
The missing piece is not more documentation. It is documentation an agent can traverse — a machine-readable map of the estate that answers dependency questions structurally rather than by reading prose.
Solution
A service-graph MCP server that turns a wiki-style documentation repo into a queryable dependency graph AI agents traverse natively.
Each service doc declares its dependencies, consumers, owned data, and contracts in typed YAML frontmatter — a validated schema that acts as the source of truth. The documentation is not a description of the graph; the documentation is the graph. A build step assembles the frontmatter across every doc into a single connected dependency graph.
That graph is exposed to AI agents over the Model Context Protocol. During a coding or planning session, an agent calls graph tools — get_service, trace_dependencies, impact_analysis — to answer topology questions the way it would call any other tool. Retrieval is structural: the agent walks edges rather than reading paragraphs.
A CI validation gate keeps the graph honest. A validator in the pipeline fails builds on malformed frontmatter, unknown service references, or broken edges, so the map cannot silently drift from the estate it describes.
The graph isn't locked to one tool — the same server plugs into Claude Code, IDE agents, or any MCP client.
Architecture Diagram
The pipeline runs from documentation to a grounded agent answer. Service docs carry typed frontmatter; a parser lifts that frontmatter into nodes and edges; a graph builder assembles the estate-wide dependency graph; the MCP server exposes traversal tools over it; and AI agents call those tools during their sessions.
A CI validator gates the whole pipeline — nothing enters the graph until its frontmatter is well-formed and every referenced service resolves.
The Frontmatter Parser is the entry point into the graph. It reads each service doc, extracts the typed frontmatter block — dependencies, consumers, owned data, contracts — and emits nodes and edges. It interprets schema, not prose: the body of the doc is for humans; the frontmatter is for the graph.
The Graph Builder assembles the parsed frontmatter across every doc into one connected estate. A dependency declared in one service resolves to the node for another; consumers are the inverse edges. The result is a single graph where every service knows both what it depends on and what depends on it.
The MCP Server sits between the graph and the agents. It exposes get_service, trace_dependencies, and impact_analysis as Model Context Protocol tools, so any MCP client can query the estate without embedding a copy of the topology in its prompt.
Service Graph Model
The Service acts as the root entity within the graph.
Every service doc declares, in typed frontmatter, the facts that connect it to the rest of the estate.
The graph currently models:
- Dependencies
- Consumers
- Owned Data
- Contracts
- APIs
- Owner Team
- Runtime
- Documentation
These facts are declared in the doc's frontmatter and validated against a schema, so the graph is only ever as stale as the last merged pull request.
Relationships provide the real value. Instead of simply knowing that a service exists, the graph captures what it depends on, who consumes it, what data it owns, and which contracts it must honor.
Because dependencies and consumers are inverse edges of the same relationship, the graph answers questions in both directions — upstream ("what does this call?") and downstream ("what calls this?") — from a single declaration.
Impact Analysis Flow
The signature query the tool answers is "what breaks if we change this?".
A change target enters as a service or contract. The server looks it up, then walks the graph breadth-first along consumer edges to collect every service that transitively depends on it.
Breadth-first traversal orders the result by distance, so the immediate blast radius is distinguishable from the second- and third-order effects.
The traversal expands outward one hop at a time. From the change target, it follows consumer edges to the services that call it directly, then follows their consumer edges in turn, until the frontier is exhausted.
For example, a change to a payments contract may surface the checkout service that consumes it directly, the order-history service that consumes checkout, and the analytics pipeline that reads both — each tagged with its distance from the change.
The result is a ranked blast radius rather than a flat list: the services one hop away need coordinated changes now; the services three hops away need a heads-up. What used to take a cross-team Slack thread answers in seconds.
MCP Tool Workflow
The agent layer is any MCP client. Rather than embedding topology in a prompt, the agent calls graph tools during its session and reasons over the structured results.
The MCP server exposes three tools, each backed by the same dependency graph.
get_service returns a single service's declared facts — its dependencies, consumers, owned data, and contracts — as the agent's entry point into the estate.
trace_dependencies walks the upstream chain, returning everything a service transitively relies on, so an agent planning a change can see the full set of systems it must reason about.
impact_analysis walks the downstream chain, returning the blast radius. Because all three tools share one graph, an agent can chain them in a single session — look up a service, trace what it needs, then assess what a change would break — and produce recommendations grounded in real topology.
Technology Decisions
The platform makes a small number of decisions that together keep the graph trustworthy and portable. Each has a real alternative and a real tradeoff.
| Decision | Choice | Rationale |
|---|---|---|
| Source of truth | Typed YAML frontmatter in service docs | A separate graph database drifts from the docs engineers actually read. Putting the schema in the doc's frontmatter makes documentation and graph the same artifact — updated in the same pull request. |
| Agent interface | Model Context Protocol (MCP) | A bespoke API locks the graph to one tool. MCP exposes traversal as standard tools, so the same server plugs into Claude Code, IDE agents, or any MCP client without re-integration. |
| Impact traversal | Breadth-first search over consumer edges | BFS orders the blast radius by distance from the change, distinguishing immediate consumers from second- and third-order effects — the information an engineer needs to sequence a change. |
| Freshness enforcement | CI validation gate | Documentation rots without enforcement. Failing builds on malformed frontmatter, unknown references, or broken edges makes the graph impossible to silently break. |
| Runtime | Node.js + TypeScript | First-class MCP tooling, a typed schema for the frontmatter contract, and a low-friction fit with the CI and editor environments where agents already run. |
These decisions share one purpose: keep the map close to the territory. The graph lives with the docs, is enforced by CI, and is reachable by any agent — so the topology an assistant reasons over is the topology the estate actually has.
Capabilities
The tool is built around four capabilities that together turn a documentation repo into a live map of the estate.
Typed YAML frontmatter as source of truth
Each service doc declares dependencies, consumers, owned data, and contracts in a validated schema. Documentation is the graph — there is no second system to keep in sync.
Graph traversal tools over MCP
Agents call get_service, trace_dependencies, and impact_analysis during coding and planning sessions, querying topology as native tool calls rather than parsing prose.
BFS impact tracing
The server walks the graph breadth-first to answer "what is the downstream blast radius of this change?", ordering affected services by distance from the change target.
CI validation gate
A validator in the pipeline fails builds on malformed frontmatter, unknown service references, or broken edges. The graph can't silently rot.
Outcomes
The tool changes how both engineers and agents reason about the estate.
AI sessions grounded in real topology
Coding assistants reason over the estate's actual dependency graph instead of hallucinated architecture. Change suggestions account for real consumers and contracts rather than guessing at them.
Impact analysis in seconds
Impact analysis that took cross-team Slack threads now answers in seconds. An engineer — or an agent — asks what breaks, and the blast radius comes back ranked by distance.
Documentation freshness enforced by CI
Because the graph is validated in the pipeline, documentation freshness is enforced by CI rather than by goodwill. The map stays aligned with the estate it describes.
Have a product that needs AI features?
Work with me →