@theme-registry/refract-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Petyo Stoyanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# @theme-registry/refract-mcp
+
+> A [Model Context Protocol](https://modelcontextprotocol.io) server for refract. It
+> lets an AI agent (Claude Code, claude.ai, or any MCP client) **query and validate your project's
+> theme** while authoring — the "middleware" that keeps an agent bound to the theme's real vocabulary
+> instead of guessing.
+
+It is **project-scoped**: it loads your `theme.config.(ts|js|mjs)` once at startup and serves queries
+against it, so the agent asks about *your* theme without ever resending it. It reloads on change.
+
+## Tools
+
+| Tool | Answers |
+| --- | --- |
+| `resolveToken` | What does `colors.brand.dark` resolve to — its value, CSS `varName`, `unit`, and `derivedFrom`? |
+| `listTokens` | What token paths exist (the addressable vocabulary)? |
+| `findToken` | Which token paths start with a prefix? |
+| `searchTokens` | Which tokens match a query on their path OR resolved value? |
+| `listRecipes` | What recipes are defined? |
+| `getClass` | What real class (and composed class-list) does a recipe get — with the project's configured prefix? |
+| `renderRecipe` | What exact CSS does one recipe emit? |
+| `checkContrast` | Do the theme's colour pairings pass WCAG-2 (+ advisory APCA)? |
+| `validateTheme` | Is a candidate theme valid on every configured target? — returns **every** problem at once (collect-all), per target. |
+| `diffTheme` | What's the blast radius of a candidate edit — which tokens moved, classes changed, pairings crossed a threshold, targets stopped building? |
+
+`diffTheme` is the plan-then-apply guardrail: pass a **candidate edit** and it builds it against the
+project's real adapters and reports the blast radius *before* the agent writes — the claim a token file
+can't make. `validateTheme` surfaces refract's collect-all errors with their stable `code` per target, so
+an agent fixes all problems in one pass and catches adapter-level rules (unknown state, naming collision)
+a generic check would miss. `getClass` / `resolveToken` read the real emitted names, so the prefix matches
+what ships. The query tools take no
+`theme` argument — they read the loaded project theme.
+
+## Architecture
+
+Pure tools (`src/tools.ts`, unit-tested) operate on a built `Theme` the server holds; `callTool`
+(`src/server.ts`) is the transport-agnostic dispatch core; the transport is the official
+`@modelcontextprotocol/sdk` over stdio.
+
+```
+agent ⇄ (MCP stdio, SDK) ⇄ callTool ⇄ tools.ts ⇄ the project theme (loaded once from theme.config)
+```
+
+## Connect
+
+Register the server with your agent. Once published:
+
+```sh
+claude mcp add refract -- npx -y @theme-registry/refract-mcp
+```
+
+Or from a local build:
+
+```sh
+pnpm --filter @theme-registry/refract-mcp build      # → dist/server.js (a runnable bin)
+claude mcp add refract -- node ./packages/refract-mcp/dist/server.js
+```
+
+The server auto-discovers `theme.config.(ts|js|mjs)` in the working directory; pass `--config <path>`
+to point elsewhere. A `.ts` config needs the `typescript` optional peer (same as `refract build`).
+
+For project scope, commit a `.mcp.json`:
+
+```json
+{ "mcpServers": { "refract": { "command": "npx", "args": ["-y", "@theme-registry/refract-mcp", "--config", "theme.config.ts"] } } }
+```
+
+## Test
+
+```sh
+pnpm --filter @theme-registry/refract-mcp test
+```
+
+## Notes
+
+- **Stable** — published on the npm `latest` tag in lockstep with core and the adapters.
+- It's the **refract half** of a *Figma → refract → AI* loop: an agent reads a design, authors a theme,
+  and `validateTheme` is the guardrail that stops it drifting.

package/dist/server.js

@@ -0,0 +1,451 @@
+#!/usr/bin/env node
+import { readFileSync, watch } from 'node:fs';
+import { dirname } from 'node:path';
+import { parseArgs } from 'node:util';
+import { argv } from 'node:process';
+import { pathToFileURL } from 'node:url';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { audit, createTheme, createNoopAdapter } from '@theme-registry/refract';
+import { toDTCG } from '@theme-registry/refract/dtcg';
+import { loadConfig, buildGuide, diffThemes } from '@theme-registry/refract/build';
+
+/** Describe what a token derives from, read straight off the stored `Ref` graph (the `derivedFrom`). */
+const describeDerivation = (ref) => {
+    var _a;
+    if (!ref || ref.ref === undefined)
+        return undefined; // terminal literal / external → nothing to derive
+    const arg = (a) => (a === undefined ? "" : `(${JSON.stringify(a)})`);
+    if ((_a = ref.modifiers) === null || _a === void 0 ? void 0 : _a.length)
+        return `${ref.ref} ${ref.modifiers.map((m) => `${m.fn}${arg(m.arg)}`).join(" → ")}`;
+    if (ref.fn)
+        return `${ref.ref} ${ref.fn}${arg(ref.arg)}`;
+    return ref.ref; // a plain alias
+};
+/**
+ * Resolve one token path — enriched. Beyond the concrete `value`, returns the emitted CSS `varName`
+ * (from a class-emitting target, carrying its configured prefix — the most useful thing to hand an
+ * agent), the length `unit`, and `derivedFrom` (read off the stored `{ ref, fn/modifiers }` graph). A
+ * resolved literal is frozen; the varName is the live, re-themeable handle.
+ */
+const resolveToken = (base, path, targets = []) => {
+    var _a, _b;
+    const value = String(base.resolveToken(path));
+    const ref = base.tokens[path];
+    const varName = (_b = (_a = targets.map((t) => t.theme).find((t) => t.varName)) === null || _a === void 0 ? void 0 : _a.varName) === null || _b === void 0 ? void 0 : _b.call(_a, path);
+    const derivedFrom = describeDerivation(ref);
+    return {
+        path,
+        value,
+        ...(varName ? { varName } : {}),
+        ...((ref === null || ref === void 0 ? void 0 : ref.unit) ? { unit: ref.unit } : {}),
+        ...(derivedFrom ? { derivedFrom } : {}),
+    };
+};
+/** Every token path in the theme — the agent's addressable vocabulary. */
+const listTokens = (theme) => Object.keys(theme.tokens);
+/** Token paths starting with `prefix` — so an agent can discover names (`findToken("colors.brand")`). */
+const findToken = (theme, prefix) => Object.keys(theme.tokens).filter((p) => p.startsWith(prefix));
+/** Fuzzy token discovery: match `query` against a token's path OR its resolved value (case-insensitive). */
+const searchTokens = (theme, query) => {
+    const q = query.toLowerCase();
+    const out = [];
+    for (const path of Object.keys(theme.tokens)) {
+        let value = "";
+        try {
+            value = String(theme.resolveToken(path));
+        }
+        catch {
+            /* leave value empty */
+        }
+        if (path.toLowerCase().includes(q) || value.toLowerCase().includes(q))
+            out.push({ path, value });
+    }
+    return out;
+};
+/** Every recipe the theme defines, as `{ subsystem, group, variant }` identities. */
+const listRecipes = (theme) => {
+    var _a;
+    const out = [];
+    for (const [subsystem, sub] of Object.entries(theme.model.subsystems)) {
+        for (const [group, ruleSetGroup] of Object.entries((_a = sub.ruleSets) !== null && _a !== void 0 ? _a : {})) {
+            for (const variant of Object.keys(ruleSetGroup))
+                out.push({ subsystem, group, variant });
+        }
+    }
+    return out;
+};
+const classesOf = (theme) => theme.classes;
+/**
+ * The class (and full composed class-list) an agent should put on an element for a recipe — read from a
+ * target's **real** emitted classes, so the prefix/composition match what ships. Only class-emitting
+ * adapters (e.g. CSS) expose `.classes`; if the project configures none, this says so rather than
+ * inventing a canonical `dt-…` name that exists in no stylesheet.
+ */
+const getClass = (targets, id) => {
+    var _a, _b;
+    const named = targets.find((t) => classesOf(t.theme));
+    if (!named) {
+        const names = targets.map((t) => t.name).join(", ") || "(no targets configured)";
+        throw new Error(`getClass needs an adapter that emits class names (e.g. the CSS adapter) — none of [${names}] does`);
+    }
+    const leaf = (_b = (_a = classesOf(named.theme)[id.subsystem]) === null || _a === void 0 ? void 0 : _a[id.group]) === null || _b === void 0 ? void 0 : _b[id.variant];
+    if (leaf === undefined) {
+        throw new Error(`no recipe "${id.subsystem}.${id.group}.${id.variant}" — call listRecipes to see what exists`);
+    }
+    return typeof leaf === "string"
+        ? { className: leaf, classList: [leaf], target: named.name }
+        : { className: leaf.className, classList: leaf.classList, target: named.name };
+};
+/** The exact CSS one recipe emits — from a class-emitting target. Throws when nothing emits CSS. */
+const renderRecipe = (targets, id) => {
+    const named = targets.find((t) => typeof t.theme.renderRecipe === "function");
+    if (!named) {
+        const names = targets.map((t) => t.name).join(", ") || "(no targets configured)";
+        throw new Error(`renderRecipe needs an adapter that emits CSS (e.g. the CSS adapter) — none of [${names}] does`);
+    }
+    const render = named.theme.renderRecipe;
+    const css = render(id.subsystem, id.group, id.variant);
+    if (!css)
+        throw new Error(`no recipe "${id.subsystem}.${id.group}.${id.variant}" — call listRecipes to see what exists`);
+    return { css, target: named.name };
+};
+/** WCAG-2 contrast audit of the theme's colour pairings (+ advisory APCA) — `audit()` over MCP. */
+const checkContrast = (theme, minWcag) => {
+    const result = audit(theme, minWcag ? { minWcag: minWcag } : {});
+    return { ok: result.ok, summary: result.summary, pairings: result.pairings };
+};
+/**
+ * Validate a raw theme against every configured target, returning ALL problems per target (refract
+ * collects them) rather than the first. This is the anti-drift guardrail: an agent validates a
+ * candidate edit here — against the same adapters that will emit it — before it writes.
+ */
+const validateTheme = (raw, builders) => {
+    const perTarget = builders.map(({ name, build }) => {
+        var _a;
+        try {
+            build(raw);
+            return { target: name, ok: true, errors: [] };
+        }
+        catch (e) {
+            const err = e;
+            return {
+                target: name,
+                ok: false,
+                code: err.code,
+                errors: err.failures ? [...err.failures] : [(_a = err.message) !== null && _a !== void 0 ? _a : String(e)],
+            };
+        }
+    });
+    return { ok: perTarget.every((t) => t.ok), perTarget };
+};
+
+/**
+ * refract MCP server — a Model Context Protocol server over stdio, on the official
+ * `@modelcontextprotocol/sdk`. It is **project-scoped**: it loads the project's
+ * `theme.config.(ts|js|mjs)` once at startup (auto-discovered in the cwd, or via `--config <path>`),
+ * holds the built theme, and serves the query tools against it — so an agent asks about *this project's*
+ * theme without ever resending it. It watches the config and reloads on change.
+ *
+ * The tool logic lives in the pure `tools.ts`; `callTool` here is the transport-agnostic dispatch core
+ * (unit-testable) — the SDK handler is a thin wrapper over it.
+ */
+/** Read this package's version from its package.json (single source of truth for the handshake). */
+function serverVersion() {
+    var _a;
+    try {
+        return (_a = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version) !== null && _a !== void 0 ? _a : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+/** The manifest schema version this server speaks (matches `refract build --guide`). Echoed in the handshake. */
+const GUIDE_SCHEMA = 1;
+const RESOURCE_URIS = { llms: "refract://llms.txt", manifest: "refract://manifest.json" };
+// --- held state ---
+let held = null;
+let configPathArg;
+/** Load (or reload) the project's theme config and build it once per target. Throws if it can't be resolved/built. */
+async function loadTheme(configPath) {
+    var _a, _b;
+    const { config, path } = await loadConfig({ configPath });
+    // Match what `refract build` emits, so resolved values/classes are the project's real ones.
+    const buildOpts = { units: config.units, baseFontSize: config.baseFontSize, media: config.media };
+    const targets = config.targets.map((t, i) => {
+        var _a, _b;
+        return ({
+            name: (_b = (_a = t.name) !== null && _a !== void 0 ? _a : t.outDir) !== null && _b !== void 0 ? _b : `target-${i}`,
+            adapter: t.adapter,
+            theme: createTheme(config.raw, { adapter: t.adapter, ...buildOpts }),
+        });
+    });
+    // A config with no targets still answers token/model queries; build a noop base for them.
+    const base = (_b = (_a = targets[0]) === null || _a === void 0 ? void 0 : _a.theme) !== null && _b !== void 0 ? _b : createTheme(config.raw, { adapter: createNoopAdapter(), ...buildOpts });
+    return { targets, base, raw: config.raw, path, buildOpts };
+}
+/** The set of real-adapter themes `getClass` reads class names from. */
+const namedThemes = (state) => state.targets.map((t) => ({ name: t.name, theme: t.theme }));
+/**
+ * Builders that re-compile a candidate against each configured target's real adapter (with the project's
+ * build options), so `validateTheme` sees the same throws `refract build` would. When no targets are
+ * configured, fall back to a single `core` builder (noop adapter) — core-level checks only, honestly
+ * labelled — rather than claiming a target validated it.
+ */
+function buildersFor(state) {
+    var _a, _b;
+    const opts = (_a = state === null || state === void 0 ? void 0 : state.buildOpts) !== null && _a !== void 0 ? _a : {};
+    const list = ((_b = state === null || state === void 0 ? void 0 : state.targets) !== null && _b !== void 0 ? _b : []).map((t) => ({
+        name: t.name,
+        build: (raw) => void createTheme(raw, { adapter: t.adapter, ...opts }),
+    }));
+    if (list.length === 0) {
+        list.push({ name: "core", build: (raw) => void createTheme(raw, { adapter: createNoopAdapter(), ...opts }) });
+    }
+    return list;
+}
+const EMPTY_DIFF = { tokens: [], classes: [], contrast: [], summary: { tokensChanged: 0, classesChanged: 0, pairingsCrossed: 0 } };
+/**
+ * The `diffTheme` guardrail: build a candidate against the project's real adapters and report the blast
+ * radius vs the loaded theme — which tokens moved, which classes changed, which pairings crossed a
+ * threshold, and whether every target still builds. The diff runs through a class-emitting target (so
+ * `classes` is populated); if the candidate doesn't build there, the diff is empty and `targets` carries
+ * the failure. Plan-then-apply, before the agent writes.
+ */
+function diffHeld(state, candidateRaw) {
+    var _a, _b, _c;
+    const validation = validateTheme(candidateRaw, buildersFor(state));
+    const pick = (_a = state.targets.find((t) => typeof t.theme.renderRecipe === "function")) !== null && _a !== void 0 ? _a : state.targets[0];
+    const baseTheme = (_b = pick === null || pick === void 0 ? void 0 : pick.theme) !== null && _b !== void 0 ? _b : state.base;
+    let diff = EMPTY_DIFF;
+    try {
+        diff = diffThemes(baseTheme, createTheme(candidateRaw, { adapter: (_c = pick === null || pick === void 0 ? void 0 : pick.adapter) !== null && _c !== void 0 ? _c : createNoopAdapter(), ...state.buildOpts }));
+    }
+    catch {
+        /* candidate doesn't build — reported via `targets` */
+    }
+    return { ok: validation.ok, diff, targets: validation.perTarget };
+}
+// Dirs never worth reloading on (vendored deps, build output, VCS). Skipped under the recursive watch.
+const WATCH_IGNORE = /(^|[/\\])(node_modules|dist|out|\.git|coverage)([/\\]|$)/;
+// Source files a theme graph is authored in — a change to any of them may change the built theme.
+const WATCH_SOURCE = /\.(ts|mjs|cjs|js|json)$/;
+/**
+ * Watch the config's directory **recursively** and rebuild on any source-file change — so a theme split
+ * across `./tokens/*.ts` (imported transitively by the config) reloads, not just an edit to the config
+ * file itself (MCP-6). Debounced; keeps the previous theme on a failed reload. Recursive `fs.watch` is
+ * supported on macOS/Windows and modern Linux — falls back to a flat watch where it isn't.
+ */
+function watchConfig() {
+    if (!held)
+        return;
+    let timer;
+    const onChange = (_event, filename) => {
+        if (!filename)
+            return;
+        const f = filename.toString();
+        if (WATCH_IGNORE.test(f) || !WATCH_SOURCE.test(f))
+            return;
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+            loadTheme(configPathArg)
+                .then((next) => {
+                held = next;
+                process.stderr.write(`refract-mcp: reloaded theme from ${next.path}\n`);
+            })
+                .catch((e) => process.stderr.write(`refract-mcp: reload failed (kept previous theme): ${e.message}\n`));
+        }, 150);
+    };
+    try {
+        const dir = dirname(held.path);
+        let watcher;
+        try {
+            watcher = watch(dir, { recursive: true }, onChange);
+        }
+        catch {
+            // Platform without recursive support — fall back to a flat watch of the config dir.
+            watcher = watch(dir, onChange);
+        }
+        // Don't let the watcher keep the process alive: when the client closes stdin, the server should exit.
+        watcher.unref();
+    }
+    catch {
+        /* watching is best-effort — a missing dir or platform quirk shouldn't crash the server */
+    }
+}
+/**
+ * Render the project's self-documenting guide (`llms.txt` + `manifest.json`) IN MEMORY from the SAME
+ * real names the tools return (via `getClass`) + the DTCG token export — so the MCP's resources, the
+ * emitted `--guide` files, and the query tools are one source of truth (MCP-5 coherence). The manifest
+ * carries `schema: {@link GUIDE_SCHEMA}`.
+ */
+function guideFiles(state) {
+    const named = namedThemes(state);
+    const recipes = listRecipes(state.base).flatMap((id) => {
+        try {
+            return [{ ...id, name: getClass(named, id).className }];
+        }
+        catch {
+            return []; // a target that mints no class name for this recipe
+        }
+    });
+    const descriptor = {
+        format: "css",
+        summary: [
+            "Apply the recipe class names below to your elements (import the emitted stylesheet once).",
+            "Token values are CSS custom properties (var(--…)) — runtime theming = override the variables under a selector or [data-theme].",
+            "These names are the live compiled theme's — the same ones the MCP getClass / resolveToken tools return.",
+        ],
+        recipes,
+    };
+    return buildGuide(descriptor, toDTCG(state.base), { files: [] }).files;
+}
+// --- tool definitions (schemas carry NO `theme` — it's project-scoped) ---
+const TOOL_DEFS = [
+    { name: "resolveToken", description: "Resolve a token path (e.g. colors.brand.dark) to its value + its emitted CSS variable name (varName), unit, and derivedFrom (what it derives from) in the loaded theme.",
+        inputSchema: { type: "object", properties: { path: { type: "string" } }, required: ["path"] } },
+    { name: "listTokens", description: "List every token path in the loaded theme.",
+        inputSchema: { type: "object", properties: {}, required: [] } },
+    { name: "findToken", description: "List token paths that start with a prefix (discover names).",
+        inputSchema: { type: "object", properties: { prefix: { type: "string" } }, required: ["prefix"] } },
+    { name: "searchTokens", description: "Find token paths matching a query on the path OR the resolved value (fuzzy, case-insensitive).",
+        inputSchema: { type: "object", properties: { query: { type: "string" } }, required: ["query"] } },
+    { name: "listRecipes", description: "List every recipe as { subsystem, group, variant }.",
+        inputSchema: { type: "object", properties: {}, required: [] } },
+    { name: "getClass", description: "Get the real class + composed class-list for a recipe (from the project's class-emitting adapter, e.g. CSS — carries its configured prefix).",
+        inputSchema: { type: "object", properties: { subsystem: { type: "string" }, group: { type: "string" }, variant: { type: "string" } }, required: ["subsystem", "group", "variant"] } },
+    { name: "renderRecipe", description: "The exact CSS one recipe emits (base + its state/breakpoint rules), from the project's class-emitting adapter.",
+        inputSchema: { type: "object", properties: { subsystem: { type: "string" }, group: { type: "string" }, variant: { type: "string" } }, required: ["subsystem", "group", "variant"] } },
+    { name: "checkContrast", description: "WCAG-2 contrast audit of the loaded theme's colour pairings (+ advisory APCA). Optional minWcag pass bar (AA|AAA|AA-large).",
+        inputSchema: { type: "object", properties: { minWcag: { type: "string", description: "pass bar: AA (default) | AAA | AA-large" } }, required: [] } },
+    { name: "validateTheme", description: "Validate a candidate raw theme (or the loaded theme) against every configured target adapter — returns ALL problems per target at once.",
+        inputSchema: { type: "object", properties: { theme: { type: "object", description: "a candidate raw theme; omit to validate the loaded one" } }, required: [] } },
+    { name: "diffTheme", description: "Diff a candidate raw theme against the loaded one — which tokens moved, which classes changed, which contrast pairings crossed a threshold, and whether every target still builds. Plan-then-apply: see the blast radius before you write.",
+        inputSchema: { type: "object", properties: { theme: { type: "object", description: "the candidate raw theme to compare against the loaded one" } }, required: ["theme"] } },
+    { name: "reload", description: "Reload the project's theme config from disk.",
+        inputSchema: { type: "object", properties: {}, required: [] } },
+];
+/**
+ * Transport-agnostic tool dispatch — pure over the passed `state`. Query tools need a loaded theme;
+ * `validateTheme` works on a candidate even without one. `reload` is handled by the server (it mutates
+ * state + does I/O), not here.
+ */
+function callTool(name, args, state) {
+    var _a, _b;
+    const loaded = () => {
+        if (!state)
+            throw new Error("no theme loaded — launch refract-mcp in a project with a theme.config.(ts|js|mjs), or pass --config <path>");
+        return state;
+    };
+    switch (name) {
+        case "resolveToken":
+            return resolveToken(loaded().base, args.path, namedThemes(loaded()));
+        case "listTokens":
+            return listTokens(loaded().base);
+        case "findToken":
+            return findToken(loaded().base, args.prefix);
+        case "searchTokens":
+            return searchTokens(loaded().base, args.query);
+        case "listRecipes":
+            return listRecipes(loaded().base);
+        case "getClass":
+            return getClass(namedThemes(loaded()), { subsystem: args.subsystem, group: args.group, variant: args.variant });
+        case "renderRecipe":
+            return renderRecipe(namedThemes(loaded()), { subsystem: args.subsystem, group: args.group, variant: args.variant });
+        case "checkContrast":
+            return checkContrast(loaded().base, args.minWcag);
+        case "validateTheme": {
+            // A candidate wins; else the loaded theme. With neither, there is nothing to validate — say so
+            // rather than green-lighting `{}` (which builds cleanly and would teach the agent to trust it).
+            const candidate = (_a = args.theme) !== null && _a !== void 0 ? _a : state === null || state === void 0 ? void 0 : state.raw;
+            if (candidate === undefined) {
+                throw new Error("nothing to validate — pass a candidate `theme`, or launch refract-mcp in a project with a theme.config.(ts|js|mjs)");
+            }
+            return validateTheme(candidate, buildersFor(state));
+        }
+        case "diffTheme": {
+            // A diff needs a base to compare against — the loaded project theme.
+            const candidate = (_b = args.theme) !== null && _b !== void 0 ? _b : state === null || state === void 0 ? void 0 : state.raw;
+            if (candidate === undefined) {
+                throw new Error("nothing to diff — pass a candidate `theme`, or launch refract-mcp in a project with a theme.config.(ts|js|mjs)");
+            }
+            return diffHeld(loaded(), candidate);
+        }
+        default:
+            throw new Error(`unknown tool "${name}"`);
+    }
+}
+/** Run a tool call, handling the async `reload` at the server layer and delegating the rest to `callTool`. */
+async function runToolCall(name, args) {
+    if (name === "reload") {
+        held = await loadTheme(configPathArg);
+        return { reloaded: true, path: held.path };
+    }
+    return callTool(name, args, held);
+}
+/** Build the MCP server — tools + the self-documenting `llms.txt` / `manifest.json` resources. */
+function createServer() {
+    const server = new Server({ name: "refract-mcp", version: serverVersion() }, {
+        capabilities: { tools: {}, resources: { listChanged: true } },
+        // The handshake advertises the guide schema this server speaks, so an agent can reconcile the
+        // MCP resources, the emitted `--guide` files, and the installed skills against one version.
+        instructions: `refract-mcp serves the project's compiled theme as tools + resources (guide schema ${GUIDE_SCHEMA}). Read the "refract://manifest.json" resource for the machine index (schema ${GUIDE_SCHEMA}, real class names + token paths) and "refract://llms.txt" for prose. Use diffTheme to see a candidate edit's blast radius before writing.`,
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOL_DEFS }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        var _a;
+        const { name, arguments: args } = request.params;
+        try {
+            const result = await runToolCall(name, (_a = args) !== null && _a !== void 0 ? _a : {});
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: e.message }], isError: true };
+        }
+    });
+    // Resources: the same guide `refract build --guide` emits, rendered live from the loaded theme.
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: [
+            { uri: RESOURCE_URIS.llms, name: "llms.txt", description: "Prose guide to consuming this theme (real class names).", mimeType: "text/plain" },
+            { uri: RESOURCE_URIS.manifest, name: "manifest.json", description: `Machine index of the theme (schema ${GUIDE_SCHEMA}): class names + DTCG tokens.`, mimeType: "application/json" },
+        ],
+    }));
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        var _a, _b;
+        const { uri } = request.params;
+        if (!held)
+            throw new Error("no theme loaded — launch refract-mcp in a project with a theme.config.(ts|js|mjs), or pass --config <path>");
+        const files = guideFiles(held);
+        if (uri === RESOURCE_URIS.llms)
+            return { contents: [{ uri, mimeType: "text/plain", text: (_a = files["llms.txt"]) !== null && _a !== void 0 ? _a : "" }] };
+        if (uri === RESOURCE_URIS.manifest)
+            return { contents: [{ uri, mimeType: "application/json", text: (_b = files["manifest.json"]) !== null && _b !== void 0 ? _b : "" }] };
+        throw new Error(`unknown resource "${uri}"`);
+    });
+    return server;
+}
+/** Entry: resolve the config, load the theme (best-effort), start watching, then serve over stdio. */
+async function start(args) {
+    const { values } = parseArgs({ args, options: { config: { type: "string" } }, allowPositionals: true });
+    configPathArg = values.config;
+    try {
+        held = await loadTheme(configPathArg);
+        process.stderr.write(`refract-mcp: serving theme from ${held.path}\n`);
+        watchConfig();
+    }
+    catch (e) {
+        process.stderr.write(`refract-mcp: no theme loaded (${e.message}). Query tools will report it; validateTheme still works on a candidate.\n`);
+    }
+    const transport = new StdioServerTransport();
+    // When the client closes the pipe (session over), shut down — fs.watch would otherwise keep the
+    // event loop alive and orphan the process.
+    transport.onclose = () => process.exit(0);
+    await createServer().connect(transport);
+}
+// Run when invoked as the bin entry (ESM: compare our URL to the launched script), not when imported by tests.
+if (argv[1] && import.meta.url === pathToFileURL(argv[1]).href) {
+    void start(argv.slice(2));
+}
+
+export { callTool, createServer, guideFiles, loadTheme, serverVersion, start };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@theme-registry/refract-mcp",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for refract — query + validate a project's theme from an AI agent.",
+  "author": {
+    "name": "Petyo Stoyanov",
+    "email": "petyosv@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theme-registry/refract.git",
+    "directory": "packages/refract-mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/theme-registry/refract/issues"
+  },
+  "homepage": "https://github.com/theme-registry/refract#readme",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "refract-mcp": "./dist/server.js"
+  },
+  "files": [
+    "/dist"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@theme-registry/refract": "^0.1.0"
+  },
+  "peerDependencies": {
+    "typescript": "*"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^11.1.6",
+    "@types/node": "^24",
+    "rimraf": "^5.0.5",
+    "rollup": "^3.29.4",
+    "typescript": "^5.4.2",
+    "vitest": "^4.1.10",
+    "@theme-registry/refract-css": "^0.1.0"
+  },
+  "scripts": {
+    "build": "rollup -c",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "clean": "rimraf dist",
+    "test": "vitest run"
+  }
+}