ads-mcp

Local MCP adapter for Agentic Design System. It turns ADS rendering, deterministic gates,
evaluation receipts, and decision provenance into a stable three-tool surface for coding agents.
Run from npm
Point the server at the project whose UI you want ADS to inspect:
npx --yes ads-mcp@0.3.0 --root /absolute/path/to/project
The MCP server connects without downloading a browser, so cold clients can discover its tools
inside their startup budget. Before the first web render, verify or install Chromium once:
npx --yes ads-mcp@0.3.0 doctor
npx --yes ads-mcp@0.3.0 setup
If Chromium is missing, ads_render preserves a blocked run with the same setup command instead of
timing out or fabricating evidence. Operators may also set
PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH to an existing compatible Chromium executable.
Build from source
From the ADS repository:
npm --prefix packages/ads-mcp install
npm --prefix packages/ads-mcp run build
node packages/ads-mcp/dist/cli.js --root /absolute/path/to/project
Optional server flags:
--runs-dir <relative-path> changes the run directory under the project root. The default is
.ads/runs.
--allow-origin <origin> allows one non-local HTTP(S) origin. Repeat the flag for additional
origins.
--timeout-ms <number> changes the per-tool timeout. The default is 30 seconds.
--judge-command, --judge-provider, and --judge-model configure an explicit visual-judge
adapter. --judge-arg is repeatable.
--swiftui-command configures a SwiftUI snapshot adapter. --swiftui-arg and
--swiftui-detector are repeatable; --swiftui-renderer labels the renderer in run manifests.
Client configuration
Use the published package as a local stdio server. Replace the project path:
{
"mcpServers": {
"ads": {
"command": "npx",
"args": [
"--yes",
"ads-mcp@0.3.0",
"--root",
"/absolute/path/to/project"
]
}
}
}
The server initialization instructions tell clients to render and evaluate first:
ads_render -> ads_evaluate
ads_trace is conditional. Call it only after reading the run manifest and confirming it contains
at least one observed skill file, source file, and artifact file. Use the exact root-relative paths
and excerpts captured in that manifest. Never invent provenance paths or substitute prompt labels
or URLs.
Registry name: io.github.aa-on-ai/agentic-design-system.
For URL targets, the default state uses the original URL. Every requested non-default state is
loaded as #state=<name>, so the application should read the state parameter from
location.hash.
Protocol and extension posture
The server is built on the split MCP TypeScript SDK v2 packages and starts through
serveStdio. One binary accepts both legacy initialize clients and modern clients that
negotiate the 2026-07-28 protocol through server/discover.
Run identifiers are durable handles backed by <root>/.ads/runs, not MCP session identifiers.
Render, evaluate, trace, and resource reads therefore recover across fresh client, server, and
service instances on the same project filesystem.
The server advertises the stable MCP Apps extension as io.modelcontextprotocol/ui. Each ADS tool
links to ui://ads/review, a self-contained
text/html;profile=mcp-app resource that can display evidence, gates, findings, blockers, and
decision traces inline. The app uses the 2026-01-26 Apps protocol and only requests server-tool
and server-resource access from a compatible host. Hosts without Apps support retain the same
three-tool and resource surface.
Current extension decisions are deliberate:
- ADS does not advertise the
io.modelcontextprotocol/tasks extension. Render and evaluation
remain bounded synchronous calls because they do not yet need an asynchronous lifecycle; ADS
will adopt the extension only with a concrete long-running operation and a verified TypeScript
SDK and host path. It does not use the deprecated core task vocabulary.
- Local stdio does not add an authentication layer. Any future remote transport must implement the
current MCP OAuth/OIDC authorization model before it is enabled.
- The filesystem run store is suitable for one local project root and is independent of an MCP
session. Hosted or replicated operation requires a shared durable store and concurrency controls
before it can claim the same recovery guarantee.
ads_render
Render an allowed URL, root-confined TSX component, or startup-configured SwiftUI target. The tool
captures requested states and viewports, runs the applicable platform gates, and returns
ads://runs/... resources.
{
"target": { "type": "url", "url": "http://127.0.0.1:3000/orders" },
"states": ["default", "loading", "empty", "error"],
"viewports": [{ "width": 390, "height": 844 }, { "width": 1280, "height": 800 }],
"waitFor": "main",
"provenance": {
"observedSkillFiles": ["skills/design-review/SKILL.md"],
"sourceFiles": ["brief.md"],
"artifactFiles": ["src/Orders.tsx"]
}
}
A render is complete only when axe, overflow, landmarks and live regions, requested states, CLS,
and touch-target gates have usable passing evidence. Missing browser dependencies, timeouts, and
gate failures return a preserved blocked run instead of a false success.
SwiftUI uses the same public tool through an external snapshot adapter:
{
"target": {
"type": "swiftui",
"projectPath": "Orders.xcodeproj",
"scheme": "Orders",
"sourcePath": "Orders/ContentView.swift",
"configuration": "Debug",
"device": "iPhone 16 Pro"
},
"states": ["default", "loading", "empty", "error"],
"viewports": [{ "width": 393, "height": 852 }]
}
ads_evaluate
Normalize a rendered run and optionally compare it with another run. The default
judge.mode: "none" remains model-free and returns needs_human when deterministic gates pass.
judge.mode: "configured" invokes the visual-judge adapter selected at server startup and returns
a typed verdict, rubric scores, findings, and next revision prompt.
{
"runId": "run_...",
"compareToRunId": "run_optional_baseline",
"rubric": {
"task": "Make the orders workflow understandable on mobile and desktop",
"criteria": [
{ "name": "Design Quality", "weight": 35 },
{ "name": "Originality", "weight": 30 },
{ "name": "Craft", "weight": 20 },
{ "name": "Functionality", "weight": 15 }
]
},
"judge": { "mode": "configured" }
}
The server validates exact rubric score keys, ADS finding categories, severities, evidence links,
normalized screenshot regions, and verdict consistency before accepting the result. Missing,
timed-out, or inconsistent judge output returns blocked, never a pass.
Command judges may add an optional usage object to their JSON response:
{"provider":"actual-provider","model":"returned-model","modelCalls":0}
Place that object under the usage key alongside the existing verdict/scores/findings fields.
It is adapter-reported, not independent provider verification. Operator-configured identity
remains unchanged even when the reported model differs. Old adapters remain compatible; when
usage is absent, modelCalls is null (unknown), not one inferred call.
Receipts record adapterAttempts separately. A thrown, timed-out or malformed result records
one attempted adapter invocation and unknown provider usage; zero means no attempt, or an
explicit adapter-reported zero. Valid usage metadata survives later semantic verdict rejection.
Judge context
When context is requested, candidate screenshots retain their existing screenshots field with
role: "candidate". Without context or comparison, the adapter request retains its previous shape.
When compareToRunId is supplied, judges also receive that run's screenshots labelled baseline
in context.images. Add context.referenceRunIds (up to four existing completed runs) to send
explicit visual references. These are comparison material, not instructions or another candidate.
A baseline must differ from the candidate, including in model-free (judge.mode: "none") evaluations;
self-comparison returns a blocked receipt. Findings still target candidate screenshots; supporting evidence may cite a supplied context image.
Source text is opt-in via context.sourceFiles: exact relative paths previously hashed under
provenance.sourceFiles in this candidate's render manifest. Files must still match those hashes,
remain inside the project root, be UTF-8 text, and fit 16 KiB each / 64 KiB total. Unrecorded,
changed, missing or oversized context blocks evaluation before the judge runs; it is never silently
omitted. The receipt records roles and source hashes, not duplicated source text, and marks whether context
was submitted to the adapter (not whether a provider received it). Partial context is cleared on
validation failure. Treat supplied
content as untrusted source data, not executable instructions. Adapter authors must preserve this
boundary when constructing model messages; ADS does not attest to downstream prompt handling.
Comparison-enabled callers now send baseline screenshots in addition to comparison metrics.
Strict command-adapter validators must accept the additive context and role fields before
enabling context/comparison on this version; the request schema version remains 1.
No source text is included by default. Selecting files or reference runs opts them into the
already-authorized judge request, so include only material authorized for that reviewer.
ads_trace
Verify final decisions against files hashed during render. Rule files must have been recorded as
observed, source and artifact files must be present and unchanged, excerpts must be exact, and all
evidence URIs must resolve inside the same run.
For URL-only inspection without captured provenance, stop after ads_evaluate. If a client calls
ads_trace anyway, the server returns one actionable trace not applicable error without
resolving caller-invented paths.
{
"runId": "run_...",
"context": "Orders responsive repair",
"decisions": [
{
"id": "mobile-primary-action",
"decision": "Keep the primary action reachable on mobile.",
"artifact": { "path": "src/Orders.tsx", "location": "Primary action row" },
"rule": {
"path": "skills/design-review/SKILL.md",
"excerpt": "All consequential controls need a visible, reachable interaction target."
},
"sourceConstraint": {
"path": "brief.md",
"excerpt": "The primary action must remain reachable on mobile."
},
"evidence": ["ads://runs/run_.../evidence"]
}
]
}
Artifacts and security
Run artifacts live under <root>/.ads/runs/<runId>/. Tools return short structured results and
read-only resource links for manifests, rendered evidence, screenshots, evaluation receipts,
reports, traces, and trace validation.
resources/list enumerates recent run artifacts so a client can recover them after losing a tool
response. Resource URIs are stable logical identifiers rather than disk paths. For example,
ads://runs/<runId>/screenshots/default-390x844.png maps to
<root>/.ads/runs/<runId>/evidence/default-390x844.png; clients should use resources/read.
- No arbitrary command tool or caller-selected output path.
- Project file reads and run writes stay under
--root, including symlink checks.
- URL inputs must use HTTP(S). Localhost is allowed by default; other origins need startup
allow-listing.
- URL credentials are rejected and common secret query parameters are redacted from receipts.
- External adapters run as fixed argv processes without a shell. Executables must be absolute
paths and stdout is bounded.
- A model call requires both startup configuration and per-evaluation
judge.mode: "configured"; configured identity, adapter attempts, and explicitly reported usage are written separately to the receipt.
Verify
The suite covers legacy initialization and modern server/discover, the MCP App handshake and
inline review action, a complete MCP client sequence, cross-server run recovery, Chromium URL and
TSX component capture, command-adapter JSON exchange, configured visual verdicts, SwiftUI snapshot
evidence, rendered comparisons, resource reads, repeated stage receipts, timeout and
incomplete-evidence behavior, path traversal, symlink escape, origin denial, and trace failures.
Current limits
- Local stdio only. No remote HTTP, OAuth, or hosted service.
- The MCP App is an optional progressive enhancement; host-native rendering still depends on the
host implementing the stable Apps extension.
- Tasks are intentionally not advertised.
- Browser acquisition is explicit through
ads-mcp setup; MCP startup never downloads Chromium.
- The core package does not bundle provider SDKs, select a model, or ship a universal Xcode
snapshot harness. Operators supply explicit command adapters for their environment.
- SwiftUI evidence depends on the configured adapter's build, state injection, and detector
capabilities.
- The default path remains deterministic and returns
needs_human; automated judgment is
deliberately opt-in.
See the canonical API contract
and command adapter protocol
for the complete interfaces.