UI Journey MCP
This server lets agents inspect and compare mapped UI flows and their stored browser evidence without running a browser or modifying source.
List mapped flows and exact revisions per project (
list_flows)View a flow's declared states, transitions, and source dependencies (
get_flow)Retrieve stored execution evidence, screenshots, and failures for a flow (
get_flow_evidence)Compare two revisions' contracts and evidence structurally (
compare_flow)Trace the shortest declared path between states in a flow (
trace_journey)Find flows potentially affected by changed files (
get_ui_impact)Identify unverified or failed states/transitions (
get_coverage_gaps)Search stored runs by PR number (
get_change_evidence)Return stored PNG evidence inline by content hash (
get_evidence_image)All queries are read-only, idempotent, and require exact revision selection when multiple versions exist.
Provides source indexing for Flutter Modular navigation to discover routes and actions, supporting mapped UI flow queries and browser evidence.
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., "@UI Journey MCP Show checkout flow evidence and screenshot for shop at revision a1b2c3d"
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.
UI Journey MCP
Ask an agent what a UI flow does, which version was tested, and show the evidence.
Independent MIT-licensed MCP server and CLI for mapped UI flows and immutable browser evidence. No dependency on Codebase Memory, GitHub or any application. Runs locally; no model API, hosted account or telemetry.
Status: experimental v0.2. Incremental source indexing discovers Next App Router and Flutter Modular navigation. MCP queries refresh the configured checkout and separately retrieve saved execution evidence. The CLI can validate anonymous flows against a local test application. Authenticated fixtures and remote MCP hosting are not included.
Example queries
get_flow_evidence(project="shop", flow="checkout", revision="<40-character SHA>")
compare_flow(project="shop", flow="checkout", before="<SHA>", after="<SHA>")
get_evidence_image(project="shop", digest="<image hash from the result>")Flows are the primary entity. PR numbers are optional metadata. Query a mapped
flow without a PR, retrieve an exact historical run, or compare revisions.
get_evidence_image returns a PNG inline; resource URIs are also available.
Related MCP server: flowlens-mcp-server
Install from source
Requires Node.js 22+ and npm. This package has not been published to npm.
git clone https://github.com/thiagown1/ui-journey-mcp.git
cd ui-journey-mcp
npm ci
node bin/ui-journey.js helpConfigure your MCP client with absolute paths. On Windows, use forward slashes or escape backslashes in JSON. Restart/reconnect the client after adding a server.
{
"mcpServers": {
"ui-journey": {
"command": "node",
"args": ["/absolute/path/ui-journey-mcp/bin/ui-journey.js", "serve", "--store", "/private/path/ui-evidence"]
}
}
}The default store is ~/.ui-journey/store. Use a persistent directory or mounted
volume for long-term storage. Records never expire automatically; back up the store.
Codex setup
Register a stable checkout with absolute paths, outside a temporary worktree:
codex mcp add ui-journey-mcp -- /absolute/path/to/node /absolute/path/ui-journey-mcp/bin/ui-journey.js serve --store /private/path/ui-evidence
codex mcp get ui-journey-mcp --jsonThis adds a server to the host's global Codex configuration, shared by the local
desktop app, CLI and IDE extension. Restart/reconnect your client and inspect
/mcp to confirm the connection. An enabled configuration entry alone does not
prove that an existing session loaded the server. See the official
Codex MCP setup guide.
Once connected, ask for list_flows with your project ID, then
get_flow_evidence with a mapped flow and exact revision. Retrieve a returned
image digest with get_evidence_image to verify image delivery as well.
Availability does not mean invocation on every message. Agents select tools for
the task; this server does not intercept other calls or automatically collect
new screenshots. Codebase Memory can coexist as a separate server, but is not a
dependency. To encourage consistent use, add this guidance to the consuming
project's AGENTS.md, replacing the project ID:
For UI changes, consult UI Journey MCP using project="your-project":
- Use get_ui_impact for changed files and inspect relevant mapped flows.
- Use get_flow_evidence or compare_flow with exact commit revisions.
- Retrieve screenshots with get_evidence_image when reviewing visual evidence.
- Report missing, failed, stale or unverified evidence explicitly. Never treat
mapping alone as a successful browser validation.
- If the server is unavailable, state that limitation; do not invent evidence.These instructions guide tool selection; enforce required browser validation in CI if it must be a merge requirement. Import new collector output into the configured store to keep evidence up to date.
Try a local flow
To keep a source navigation map synchronized, configure .ui-journey.json in
your application and pass --repo /path/to/checkout to serve. Use
get_index_status, get_navigation_map and get_navigation_impact for inferred
routes/actions. Existing evidence queries remain about executed/declared flows.
See source synchronization and CI integration for
adapters, exact-revision comparison and before/after images in PR descriptions.
npx playwright install chromium
node examples/serve.jsThe demo prints an unused loopback URL. Keep it running and substitute that URL and the full SHA of the checkout serving the page in another terminal:
node bin/ui-journey.js validate --project demo --flow-file examples/help-flow.json --origin http://127.0.0.1:PORT --revision FULL_COMMIT_SHA --store .ui-journey
node bin/ui-journey.js query get_flow_evidence --args '{"project":"demo","flow":"help"}' --store .ui-journeyUse --channel chrome or --channel msedge for an installed browser.
--viewport mobile captures 390 × 844; desktop is 1440 × 1000. validate saves
failed evidence and exits nonzero on failed/incomplete validation. It does not
start the application: use your project's test-server setup.
The flow file describes a static route, accessible locators, observable states, click/fill transitions and fixture identity. Each edge is reached from a fresh browser context using a shortest path. States without outgoing transitions are captured too. Test fixtures must be deterministic.
Tools
Tool | Result |
| Refresh source index; report commit, content hash, dirty state and limits |
| Refresh and paginate inferred routes, actions, edges or diagnostics |
| Refresh and find potentially affected routes in the checkout |
| Mapped flows and available revisions; paginated |
| Declared map, executed contract and evidence summary |
| Outcomes, state screenshots, run, version and freshness |
| Added/removed/changed states and actions, evidence from both versions |
| Shortest declared path between states within one flow |
| Flows affected through recorded entry files/dependencies |
| Failed or unverified states/transitions in a mapped flow |
| Stored runs carrying a particular PR number |
| A referenced PNG as inline MCP image content |
Evidence CLI queries use the same names and JSON arguments. Source indexing uses
the index and compare-index CLI commands. All twelve MCP tools leave application
source unchanged; navigation queries update a derived private index cache.
Browser execution is an explicit CLI operation, not an MCP tool.
Selection and provenance
Mapping is
unverifieduntil observations cover every declared state and edge.Exact revision requests never fall back to another revision. With multiple revisions, the caller must select one; SHA ordering is not chronological.
Within a revision, the latest known observation time wins, including failures. Unknown/tied times require a
run; conflicting records are flagged.Without
currentRevision, freshness isunknown. A match means matching the caller's requested revision, not a live production check.Revision, PR, fixture and source identities are caller-supplied. The importer does not authenticate a CI run or prove the URL serves that commit. Your collector must check out the exact revision and provide truthful metadata. Local CLI validation likewise does not attest the identity of the running build.
The preserved executed base contract can differ from the new declared map. Both are stored: deleting an action cannot erase a failed attempt to execute it.
Comparison is structural/status-based, not an aesthetic or pixel correctness verdict. Missing environment metadata gives
environmentComparable: null.Execution coverage includes declared flows and recorded dependencies only. The separate source index discovers supported routing conventions. It does not crawl the UI, prove runtime reachability or automatically create browser tests.
Import CI evidence
Native records follow the snapshot schema, with PNGs named by SHA-256:
node bin/ui-journey.js import --file snapshot.json --images ./images --store /persistent/private/evidenceThe adapter also accepts ui-graph/v1: journeys, sha, observations and optional
executedContracts. Extra AST inventory fields are ignored. Import both sides separately:
node bin/ui-journey.js import-graph --graph graph-after.json --images ./captures --project shop --run ci-123-after --pr 42 --side after --store /persistent/private/evidenceSupply --observed-at only with the actual execution time. Otherwise time remains
unknown, not the import time. Original PNG names must be simple a-z0-9- basenames.
Observations must match the graph SHA and executed flow. PNG bytes are copied into
the store, so expiration of a CI artifact does not delete imported evidence.
Repeating the same import is idempotent.
On ephemeral runners the directory disappears unless you persist/export it. Use a private volume, authenticated transfer or an explicit evidence branch in your integration. This project does not push data or edit PRs automatically. Local MCP requires no GitHub token.
Storage and privacy
store/<project>/records/<sha256>.json
store/<project>/images/<sha256>.pngRecords/images are immutable. Images are written before records with atomic create-if-absent operations. Interrupted imports may leave unreferenced blobs; existing records are never overwritten. Graph imports are atomic per record, not across all flows/viewports. No automatic history deletion.
Limits: 20 states/40 transitions per flow, 1 MiB per PNG, 1600 × 1200 maximum dimensions, 4 MiB per JSON, 10,000 records/64 MiB metadata per project. Lists default to 20 and allow 50 results. Partition large stores. PNG signatures, chunk boundaries and dimensions are checked, not fully decoded. Hashes detect corruption, not authorship.
Keep screenshots/data in a separate private store, never this public repository. Use sanitized fixtures; images may contain secrets or personal data. The package allowlist includes source and synthetic examples only.
The stdio server reads every project in its configured store. Project IDs provide namespacing, not tenant authorization. Scope stores and filesystem access per client. No remote HTTP server/authentication is included. Symlinked store directories, nonregular files and traversal IDs are rejected; this is not a sandbox against a concurrent attacker controlling the same filesystem.
CLI validation permits loopback HTTP, fresh contexts, same-origin GET/HEAD, no
service workers/WebSockets and fixture 404s for /api/. Browser processes receive
a narrow environment without host tokens. The page's JavaScript still runs: use
a local test application and sandbox untrusted code. GET can have server-side
effects. This is not a general OS/network sandbox. No production credentials,
authenticated flows, arbitrary JavaScript tools, model API or telemetry.
Development
npm ci
npm test
npm run check
npx playwright install chromium
npm run test:browser
npm audit
npm pack --dry-runTests cover selection, stale/unknown evidence, removed contracts, corruption, traversal, concurrency and a real MCP stdio client. Browser integration uses synthetic pages for success, regression, mobile, blocked POST and MCP image delivery. See CONTRIBUTING.md.
Built on the official MCP SDK and Playwright.
Available Tools
9 toolscompare_flowBRead-onlyIdempotent
Compare contracts and evidence for two exact revisions. This is a structural/status comparison, not an aesthetic image verdict.
Inputs: flow (required), after (required), before (required), project (required), +2 more.
get_change_evidenceBRead-onlyIdempotent
Find stored runs associated with a PR number and optionally an exact revision. PR metadata is supplied by the importer, not authenticated by this server.
Inputs: pr (required), project (required), limit, offset, +1 more.
get_coverage_gapsCRead-onlyIdempotent
List unverified or failed mapped states/transitions for one flow. Does not claim exhaustive application coverage.
Inputs: flow (required), project (required), run, revision, +1 more.
get_evidence_imageARead-onlyIdempotent
Return a stored PNG inline for a project and content hash obtained from get_flow_evidence. Never fetches arbitrary URLs or paths.
Inputs: digest (required), project (required).
get_flowCRead-onlyIdempotent
Get the mapped states, transitions and source dependencies of a flow.
Inputs: flow (required), project (required), run, revision, +1 more.
get_flow_evidenceBRead-onlyIdempotent
Read stored flow evidence, screenshots and failures. Does not run a browser. Supply an exact revision when multiple versions exist.
Inputs: flow (required), project (required), run, revision, +1 more.
get_ui_impactBRead-onlyIdempotent
Find mapped flows whose declared entry files or recorded dependency closures intersect changed files. Unknown coverage remains possible.
Inputs: files (required), project (required), revision (required), limit, +1 more.
list_flowsBRead-onlyIdempotent
List mapped flows and available exact revisions. Mapping alone is not execution evidence.
Inputs: project (required), limit, offset, revision.
trace_journeyBRead-onlyIdempotent
Find a shortest declared interaction path within a mapped flow. A path is not proof it passed.
Inputs: to (required), flow (required), project (required), run, +3 more.
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 has a fairly distinct purpose: listing, fetching metadata, fetching evidence, comparing revisions, tracing paths, and finding impact/coverage gaps. Some overlap exists between get_flow_evidence and get_change_evidence, and between get_ui_impact and get_coverage_gaps, but descriptions clarify retrieval vs. discovery and revision vs. PR context.
All nine tools follow a consistent snake_case verb_noun pattern (list_flows, get_flow, compare_flow, trace_journey, get_evidence_image), with no mixed casing or verb styles.
Nine tools is a well-scoped set for a UI journey/evidence server, covering discovery, inspection, comparison, tracing, and impact analysis without bloat.
The surface covers the lifecycle of mapping, retrieving, comparing, tracing, and gap analysis, but lacks explicit create/update/delete operations for flows or mappings, so agents cannot mutate mappings through this server.
Maintenance
Related MCP Connectors
Synthetic UX reviews, findings, evidence images, and repair prompts. OAuth required.
Captured web interfaces, screenshots, flows and structured evidence for AI coding agents.
Query real user session replay data: tapes, transcripts, error/rage-click filters, alerts.
Session replay and product analytics. Read cases, sessions, verdicts and funnels.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables coding agents to access recorded browser flows (user actions, network, console, etc.) for debugging and regression testing without reproducing issues.109Apache 2.0
- FlicenseNot gradedqualityAmaintenanceEnables coding agents to inspect recorded browser flows with user actions, network activity, console logs, storage, DOM events, and screen recordings for debugging, regression testing, and sharing flows with teammates.-
- FlicenseNot gradedqualityAmaintenanceEnables coding agents to inspect recorded browser flows—including user actions, network activity, console logs, storage, DOM events, and screen recordings—for in-depth debugging and regression testing without reproducing the issue.-
- FlicenseNot gradedqualityAmaintenanceEnables coding agents to inspect recorded browser flows, including user actions, network activity, console logs, storage, DOM events, and screen recordings, so they can debug issues and perform regression testing without reproducing them.-