uigraph MCP server
Commit Nov 11, 2026Generates and verifies application UI transition graphs to provide AI agents with deterministic, proof-gated navigation maps.
Also known as kanetran29/uigraph
- Stars
- 5
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 11, 2026
- License
- MIT
What is uigraph MCP?
uigraph generates and verifies application UI transition graphs to provide AI agents with deterministic, proof-gated navigation maps.
Summary generated from the project's README
About uigraph MCP server
Providing AI agents with deterministic navigation maps for web applications is what uigraph accomplishes. It generates and verifies application UI transition graphs by treating screens as nodes and transitions as edges. This allows developers to give coding agents like Claude Code, Cursor, or Copilot a reliable map of how an application actually behaves, rather than relying on guesses. The system works by performing static analysis on frameworks such as React, Vue, Angular, and Next.js to extract routes with file and line number witnesses.
Users connect their preferred AI client via a model-free MCP server that runs over stdio. Because it is model-free, it requires no API keys and works offline or in restricted environments. The server uses a proof-gated verification system where transitions must be confirmed by a Playwright runner with evidence like URL changes or screenshots to earn a high trust tier. All data is stored in a local SQLite database, allowing teams to commit the verified graph to version control so every developer and CI process uses the same source of truth.
What you can do with it
- 1Map application navigation from source codeAn agent can automatically derive the structure of a React or Next.js app using static analysis.
- 2Monitor graph freshness and coverageTeams can identify stale navigation data or unverified paths through a dedicated dashboard.
- 3Provide agents with high-trust navigation mapsCoding agents can use the 27 provided MCP tools to navigate complex UI flows with confidence.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablekanetran29/uigraph is public and reachablegithub.com/kanetran29/uigraph ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-11github.com/kanetran29/uigraph ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubYour agent re-derives your app's navigation from source on every session — and a graph it guesses today can disagree with the one it guesses tomorrow. UI-graph computes the map once per commit, deterministically, then makes the LLM's additions earn their way in with runtime proof. The moat is not the word "map". It's the word verified.
Features
[!NOTE] The core is model-free: no API key, no bundled LLM. Your coding agent (Claude Code, Cursor, Copilot) connects over MCP and brings its own model — the graph works offline and in LLM-restricted CI.
| Deterministic extraction | ts-morph static analysis of react-router v5/v6/data-router, vue-router, Angular Routes, and Next.js file routes — every edge carries a file:line witness |
| Proof-gated verification | report_observation(confirmed) requires evidence (URL change, asserted dialog, screenshot on disk) + provenance, or it is rejected. A hallucinated confirmation cannot enter the graph |
| Trust tiers on every edge | witnessed > proven > asserted > llm-verified > proposed > unknown — projected on read, so an agent always knows how far to lean |
| The Tier-2/3 loop | The LLM proposes greedily (propose, quarantined), the runner drives a real browser (uigraph verify), and only the observation — never the guess — mints an edge |
| Honest coverage | runtime-verified ⊆ verified ⊆ accounted are never conflated; undrivable edges are parked with a written reason, and a re-map demotes stale witnesses for re-confirmation |
| Agent-native | 27 MCP tools + an installable agent kit (uigraph kit install), a one-command dashboard, Playwright spec generation, and structural + temporal graph diffs |
Quick start
-
Install the CLI and map your app (adapter auto-detected from
package.json):npm i -g @ui-graph/cli # or: pnpm add -g @ui-graph/cli uigraph map ~/work/your-app --controls -
Open the dashboard — one command, serves UI + API and opens your browser:
uigraph dash # all registered projects, switchable in the topbar -
Verify against the running app — drive uncertain transitions in a real browser; confirmations need proof:
uigraph login http://localhost:3000 --out auth.json # log in manually once (any auth scheme) uigraph verify ~/work/your-app --app-url http://localhost:3000 \ --storage-state auth.json --until-done uigraph verify ~/work/your-app --app-url http://localhost:3000 --all # sweep static proofs too -
Connect your agent over MCP:
uigraph mcp ~/work/your-app # stdio server for Claude Code / Cursor / Copilot uigraph kit install --claude # rules + guides + the reconciliation-loop playbookIn your MCP client config (e.g. Claude Code / Cursor):
{ "mcpServers": { "uigraph": { "command": "uigraph", "args": ["mcp", "/abs/path/to/your-app"] } } }
Every workspace is a single
uigraph.db(SQLite, no native deps) you can commit — teammates and CI read the same verified graph without re-deriving it.Building from source? Clone the repo, then
pnpm install && pnpm check; run the CLI in-tree withpnpm --filter @ui-graph/cli run uigraph -- <command>.
Multiple projects
map auto-registers each project in ~/.uigraph/; dash/serve without a dir serve them all, switchable in the topbar. The switcher uses opaque ids — absolute paths never leave the server.
Under the hood
Three tiers, one invariant — no edge enters the base graph without a deterministic witness:
| Tier | Who | What enters the graph |
|---|---|---|
| 1 — static | ts-morph extractors | route nodes + edges with file:line witnesses; anything unresolvable degrades honestly (may fan-out, unknown sink, soundiness note) — never a silent miss, never a guessed must |
| 2 — propose | your agent's LLM | nothing. Proposals are quarantined hypotheses that land on the verify worklist — a wrong proposal costs nothing |
| 3 — verify | Playwright runner / agent | the observation, with evidence attached. Guarded edges keep their guard (one run proves existence, not unconditionality); refuting a static must raises the loudest alarm the system has |
Extraction quality is enforced by an adversarial gauntlet: a data-router React app packing 25 common-website patterns (examples/sample-gauntlet-react), graded against 35 golden expectations on every pnpm check — a silent miss fails the suite.
| Package | Role |
|---|---|
@ui-graph/core |
framework-agnostic IR + pure ops (validate, overlay/merge, diff, plan_path, codegen, coverage, trust tiers) |
@ui-graph/adapter-react |
react-router v5 + v6 + data-router extraction |
@ui-graph/adapter-vue · -angular · -next |
vue-router, Angular Routes, Next.js App+Pages router |
@ui-graph/mcp |
model-free stdio MCP server, 27 tools |
@ui-graph/cli |
map / verify / login / dash / gen / diff / serve / workspace / mcp |
apps/dashboard |
React Flow viewer: graph, coverage, freshness, verify worklist |
Open core
This repository is the complete, MIT-licensed trust engine — nothing epistemic is paywalled. The commercial layer, UI-graph studio (separate private repo), adds the interactive workflow on top: scenario/feature drafting, overlay editing and proposals triage in the UI, and Playwright e2e suite generation from the verified graph. The single-path uigraph gen primitive stays here.
Contributing
- Fork and branch.
pnpm install && pnpm check— typecheck + tests + lint must stay green.- Extraction changes must keep the gauntlet at 35/35 (
pnpm exec tsx scripts/gauntlet-report.ts); new patterns welcome — add the case and its golden expectation. - Follow the dev cycle in docs/20-development-cycle.md.
Star history
License
MIT © Kane Tran — see LICENSE. The research dossier behind the design lives in docs/ui-graph-dossier-final-en.md.
uigraph MCP questions
How does the verification process work?
Verification requires evidence such as URL changes, asserted dialogs, or screenshots on disk to ensure that only proven observations enter the graph.
Which frameworks are supported for route extraction?
It supports React Router (v5, v6, and data-router), Vue Router, Angular Routes, and Next.js file routes.
Where is the graph data stored?
Each workspace uses a single SQLite database named uigraph.db which can be committed to version control.