Agent surface

The design system, as tools on the page

WebMCP lets a page register tools with the browser (document.modelContext.registerTool), so an agent working in that browser can call them. BlockSmith registers its governance engine that way: on a design system's page the agent gets the rules of the system the human is looking at, bound to that document — not a copy in a prompt, not a guess.

Discovery: the whole surface is published at /.well-known/webmcp.json — every tool, its schema, where it is registered, and how to invoke it — generated from the registry, so it cannot list a tool that does not exist.

1 · On a design system page

16 tools on every /wiki page. Switching design systems re-registers them and fires toolchange: check_component's schema carries an enum of the open system's components, so the agent cannot name one the system does not have. Open the panel at the top of any wiki page to see the live list.

Only in the page — these need the reader's screen, which no remote server has:

propose_component
acts on the page
Put a component or full page in front of the user on the page they are reading, rendered in this design system's own tokens, and get back the governance verdict. Use this instead of only printing code in chat — the user should see the thing, not the markup. Earlier proposals are kept: each new one becomes a version the user can revisit, view as code, or download from the full-page view, so propose freely rather than editing one blob in place.
propose_design_change
acts on the page
Propose a change to the design system itself — add or edit a colour token, add a do/don't rule, revise a component's guidance. The change is staged for the human to approve; you cannot apply it. Use this when the user wants the system changed, not code written against it.
get_current_context
read-only
See what the user is looking at right now: which design system is open in their browser and which page of it. Call this first so your answer applies to their actual screen rather than a guess.

Dispatched to the server — registered in the page, answered by POST /api/webmcp/invoke:

get_governance_rules
read-only
Get the active design system's rules: token palette, do's, don'ts, and component count. Call this before writing or changing any UI code so the result matches the system instead of guessing at values.
list_components
read-only
List what this design system offers, what is deprecated, and what it has deliberately ruled out. Call this before proposing any component so you build with what exists instead of inventing something the system does not have.
check_capability
read-only
Ask whether this design system allows a given UI pattern before you build it. Answers available, preferred, deprecated, or ruled out — with what to use instead. Call this whenever you are about to reach for a pattern you have not confirmed exists, rather than inventing one.
list_presets
read-only
List the design systems available to build against. Use this when the user has no system of their own, or wants to switch which one governs their work.
capture_site_design
read-only
Read a public website's design decisions — colours, typefaces, radii, spacing, type sizes — and save them as a design system you can then build against. Use this when the user has no design system of their own and wants to start from a site they like. The result is a draft: it has no components and its roles are inferred.
export_skill
read-only
Turn the active design system into a skill file a coding agent can load, so it writes compliant UI in an editor where these tools are not reachable. Returns a summary and a URL to fetch the file. Use when the user wants their agent to follow this system outside this page.
check_governance
read-only
Check UI code against the active design system: off-token colors, off-scale spacing, font sizes and radii, banned patterns like gradients or shadows, and Tailwind classes that resolve to non-token values. Returns each violation with its line and the value to use instead. Call before showing generated UI to the user, and again after fixing.
fix_violations
read-only
Apply every mechanical fix the design system can make to a piece of code — off-token colours with a near match, off-scale spacing, type sizes, radii, and Tailwind classes. Returns the corrected code plus anything that still needs a human decision. Use after check_governance rejects something.
explain_violation
read-only
Explain why a specific color value violates the design system and which token to use instead. Use this when the user asks why a change was rejected.
check_component
read-only
Check proposed colors against one named component's governance, returning its do's, don'ts, and any deviations. Use this when changing a specific component rather than checking a whole file.
figma_token_drift
read-only
Figma says X, code says Y. Pass Figma's variables (the output of get_variable_defs, as an object or JSON string) and get back which tokens agree with this design system, which differ in value, which were renamed, and which exist on one side only. Use it before building from a Figma frame, and to answer whether a file and its code have drifted apart.
audit_page_styles
read-only
The page says X, the system says Y. Pass what a live page actually paints — its colours with usage counts, typefaces and radii, as collected by the BlockSmith in-page script — and get back how much of it is on-system: exact token matches, near misses with the token to use instead, and values the system has no answer for.
audit_site
read-only
Judge any public website against this design system, from its address alone. Reads what the page actually paints and reports how much is on-system, which values are near misses with the token to use instead, and which have no token at all. Use when the user asks whether a site or a page of their own is on-brand.

2 · On the dashboard

The signed-in home registers the read-only tools against the default system, so an agent can read rules, check a snippet or capture a site before any page is chosen.

3 · On any website

The same tools, on a page BlockSmith did not build. Drag the button to your bookmarks bar, open any site, click it: the script registers 4 tools with that page's document.modelContext. An agent browsing the site can then capture its design system, or audit what the page paints against a system you govern — “the page says #4c70e8, the system says #4c6ee6”.

⚒ BlockSmith on this page← drag to your bookmarks bar

blocksmith_capture_this_site
read-only
Read the design system of the page the user is on — colours, type, spacing, radii and repeated components, measured from the rendered page — and save it as a governed design system with a link to open.
blocksmith_audit_this_page
read-only
Collect what the current page actually paints and judge it against a design system: how much is on-system, near misses with the token to use, values with no token.
blocksmith_get_rules
read-only
The governance rules of a design system — palette, do's and don'ts — without leaving the current page.
blocksmith_page_context
read-only
Where the user is: the page's address and title, and a first count of the distinct colours, typefaces and radii it paints. Runs entirely in the page.

Sites with a strict Content-Security-Policy block bookmarklet scripts. The extension in extension/ injects the same script as a content script in the page's main world, which CSP does not govern: chrome://extensions → Developer mode → Load unpacked → the extension folder. Both need Chrome with chrome://flags/#enable-webmcp-testing.

// what the script registers, in outline
document.modelContext.registerTool({
  name: "blocksmith_audit_this_page",
  inputSchema: { type: "object", properties: { doc: { type: "string" } } },
  annotations: { readOnlyHint: true, untrustedContentHint: true },
  execute: async ({ doc }) => {
    const styles = collect();               // colours, fonts, radii the page paints
    const res = await fetch("https://blocksmithv1.vercel.app/api/webmcp/invoke", {
      method: "POST",
      body: JSON.stringify({ tool: "audit_page_styles", args: { styles }, doc }),
    });
    return { content: [{ type: "text", text: (await res.json()).text }] };
  },
});

4 · Figma says X, code says Y

figma_token_drift takes what an agent's Figma MCP returns from get_variable_defs and compares it with the open design system: tokens that agree, tokens that differ in value, tokens that were renamed (same value, different name), near misses (a colour a few levels off), and tokens that exist on one side only. Renames and near misses are told apart from real drift, because an agent told “these differ” will change one of them.

// in a wiki page, from any WebMCP-capable agent
figma_token_drift({
  variables: { "Color/Brand": "#4c70e8", "Radius/Medium": "8" },
  fileKey: "AbC123"
})
// → # Figma vs Cohere
//   3 agree · 1 differ · 0 renamed · 1 near misses · 0 Figma only · 12 code only
//   ## Near misses
//   - `--color-brand`: Figma #4c70e8, nearest in code #4c6ee6 (Accent) — a near miss, likely drift

5 · Outside a browser

The same engine is a remote MCP server at /api/mcp (Streamable HTTP, Bearer API key) with 16 tools for Cursor, Claude Code and CI. The in-page surface is deliberately narrower: each tool costs the agent context and completion time, and a page has one job.

What is enforced, not assumed

Chrome's budgets — 30 characters per tool name, 500 per description, 1,500 per result — are asserted by npm run verify:webmcp, which also checks that every count in the README and submission matches the registry, that the page tools declared here match the ones the wiki registers, and that the tools this script advertises are the ones it registers.