@runsnative/mcp-server 0.1.0

package/dist/tools/get-component.js

@@ -0,0 +1,47 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+export const GET_COMPONENT_TOOL = {
+    name: 'get_component',
+    description: 'Returns RunsNative component documentation for a specific tab. ' +
+        'Tabs: usage (what it is and how to use it), style (tokens, CSS parts, theming), ' +
+        'code (API: properties, events, slots, framework integration), ' +
+        'accessibility (ARIA, keyboard, screen reader, WCAG). ' +
+        'Call usage first for orientation, code for generating correct markup.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            name: {
+                type: 'string',
+                description: 'Component slug — the element tag without the "run-" prefix. Examples: "button", "tabs", "text-field".',
+            },
+            tab: {
+                type: 'string',
+                enum: ['usage', 'style', 'code', 'accessibility'],
+                description: 'Which documentation tab to retrieve.',
+            },
+        },
+        required: ['name', 'tab'],
+    },
+};
+export async function handleGetComponent(provider, args) {
+    const name = args.name;
+    const tab = args.tab;
+    if (typeof name !== 'string' || !name.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, 'name must be a non-empty string');
+    }
+    if (typeof tab !== 'string') {
+        throw new McpError(ErrorCode.InvalidParams, 'tab must be a string');
+    }
+    let content;
+    try {
+        content = await provider.getComponent(name.trim(), tab.trim());
+    }
+    catch (err) {
+        if (err instanceof RangeError) {
+            throw new McpError(ErrorCode.InvalidParams, err.message);
+        }
+        throw err;
+    }
+    return {
+        content: [{ type: 'text', text: content }],
+    };
+}

package/dist/tools/get-composition-pattern.js

@@ -0,0 +1,43 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+export const GET_COMPOSITION_PATTERN_TOOL = {
+    name: 'get_composition_pattern',
+    description: 'Returns the full composition pattern for the named recipe. ' +
+        'Includes a live preview spec, code examples in HTML, React, Vue, Angular, and Svelte, ' +
+        'components used, accessibility notes, and customization guidance. ' +
+        'Use list_composition_patterns to discover available pattern names.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            name: {
+                type: 'string',
+                description: 'Pattern slug, e.g. "sign-in-form", "dashboard-shell", "multi-step-form". ' +
+                    'Use list_composition_patterns to see all available names.',
+            },
+        },
+        required: ['name'],
+    },
+};
+export async function handleGetCompositionPattern(provider, args) {
+    const name = args['name'];
+    if (typeof name !== 'string' || !name.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, 'name is required');
+    }
+    let content;
+    try {
+        content = await provider.getRecipe(name.trim());
+    }
+    catch (err) {
+        if (err instanceof RangeError) {
+            throw new McpError(ErrorCode.InvalidParams, err.message);
+        }
+        if (err instanceof McpError)
+            throw err;
+        if (err instanceof Error) {
+            throw new McpError(ErrorCode.InternalError, err.message);
+        }
+        throw err;
+    }
+    return {
+        content: [{ type: 'text', text: content }],
+    };
+}

package/dist/tools/get-foundation.js

@@ -0,0 +1,38 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+export const GET_FOUNDATION_TOOL = {
+    name: 'get_foundation',
+    description: 'Returns RunsNative design foundation documentation. ' +
+        'Foundations cover the token system: color, typography, spacing, grid, motion, elevation, icons. ' +
+        'Use this to answer questions about design tokens, CSS custom properties, and system-level decisions.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            name: {
+                type: 'string',
+                description: 'Foundation slug. One of: color, typography, spacing, grid, motion, elevation, icons.',
+            },
+        },
+        required: ['name'],
+    },
+};
+export async function handleGetFoundation(provider, args) {
+    const name = args.name;
+    if (typeof name !== 'string' || !name.trim()) {
+        const foundations = await provider.listFoundations();
+        const names = foundations.map((f) => f.foundation).join(', ');
+        throw new McpError(ErrorCode.InvalidParams, `name must be a non-empty string. Available foundations: ${names}.`);
+    }
+    let content;
+    try {
+        content = await provider.getFoundation(name.trim());
+    }
+    catch (err) {
+        if (err instanceof RangeError) {
+            const foundations = await provider.listFoundations();
+            const names = foundations.map((f) => f.foundation).join(', ');
+            throw new McpError(ErrorCode.InvalidParams, `${err.message} Available foundations: ${names}.`);
+        }
+        throw err;
+    }
+    return { content: [{ type: 'text', text: content }] };
+}

package/dist/tools/get-step.js

@@ -0,0 +1,44 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+export const GET_STEP_TOOL = {
+    name: 'get_step',
+    description: 'Returns one step from a RunsNative exercise. ' +
+        'The goal field is a one-sentence summary; content is the full step body (instructions, what to expect, troubleshooting). ' +
+        'Call start_exercise(name) first to get the step list and total step count.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            exercise: {
+                type: 'string',
+                description: 'Exercise slug. Examples: "vibe-with-runsnative", "migrate-to-runsnative".',
+            },
+            step: {
+                type: 'number',
+                description: 'Step number (1-indexed).',
+            },
+        },
+        required: ['exercise', 'step'],
+    },
+};
+export async function handleGetStep(provider, args) {
+    const exercise = args.exercise;
+    const step = args.step;
+    if (typeof exercise !== 'string' || !exercise.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, 'exercise must be a non-empty string');
+    }
+    if (typeof step !== 'number' || !Number.isInteger(step) || step < 1) {
+        throw new McpError(ErrorCode.InvalidParams, 'step must be a positive integer');
+    }
+    let result;
+    try {
+        result = await provider.getExerciseStep(exercise.trim(), step);
+    }
+    catch (err) {
+        if (err instanceof RangeError) {
+            throw new McpError(ErrorCode.InvalidParams, err.message);
+        }
+        throw err;
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+}

package/dist/tools/infer-brand-theme.js

@@ -0,0 +1,29 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { runInferencePipeline } from '../inferrer/pipeline.js';
+export const INFER_BRAND_THEME_TOOL = {
+    name: 'infer_brand_theme',
+    description: 'Fetches a URL via headless browser, extracts CSS and image signals, and returns an ' +
+        'InferenceResult with a resolved InferredTheme and per-field confidence metadata. ' +
+        'Requires playwright to be installed. Use infer_theme for HTML-only analysis.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            url: {
+                type: 'string',
+                description: 'The page URL to fetch and analyse (http or https).',
+            },
+        },
+        required: ['url'],
+    },
+};
+export async function handleInferBrandTheme(args) {
+    const url = args.url;
+    if (typeof url !== 'string' || !url.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, 'url must be a non-empty string');
+    }
+    const pipelineResult = await runInferencePipeline(url);
+    if (!pipelineResult.ok) {
+        throw new McpError(ErrorCode.InternalError, `Inference pipeline failed: ${pipelineResult.error.message}`);
+    }
+    return { content: [{ type: 'text', text: JSON.stringify(pipelineResult.result, null, 2) }] };
+}

package/dist/tools/infer-theme.js

@@ -0,0 +1,95 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+export const INFER_THEME_TOOL = {
+    name: 'infer_theme',
+    description: 'Infers the RunsNative skin/theme in use from HTML markup or a page URL. ' +
+        'Analyses CSS custom property overrides and class-based skin selectors to identify ' +
+        'which skin is active. Returns skin name, confidence, detected token overrides, and reasoning. ' +
+        'Returns low-confidence stub when skin token data is unavailable.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            html: {
+                type: 'string',
+                description: 'HTML snippet or full document to analyse.',
+            },
+            url: {
+                type: 'string',
+                description: 'Optional page URL for additional context.',
+            },
+        },
+        required: ['html'],
+    },
+};
+// Skin selector patterns — maps skin name to CSS class / data-attribute markers.
+const SKIN_PATTERNS = [
+    {
+        skin: 'default',
+        patterns: [/data-skin="default"/, /class="[^"]*run-skin-default[^"]*"/],
+    },
+    {
+        skin: 'dark',
+        patterns: [/data-theme="dark"/, /data-skin="dark"/, /class="[^"]*run-skin-dark[^"]*"/, /class="[^"]*dark-mode[^"]*"/],
+    },
+    {
+        skin: 'high-contrast',
+        patterns: [/data-skin="high-contrast"/, /class="[^"]*run-skin-high-contrast[^"]*"/, /data-theme="high-contrast"/],
+    },
+];
+// CSS custom property token pattern — matches --run-* overrides in style attributes or <style> blocks.
+const TOKEN_OVERRIDE_RE = /--run-([\w-]+)\s*:\s*([^;}"]+)/g;
+function analyseHtml(html) {
+    // Extract token overrides from inline styles and <style> blocks.
+    const token_overrides = {};
+    let match;
+    TOKEN_OVERRIDE_RE.lastIndex = 0;
+    while ((match = TOKEN_OVERRIDE_RE.exec(html)) !== null) {
+        token_overrides[`--run-${match[1]}`] = match[2].trim();
+    }
+    // Match skin by selector patterns.
+    for (const { skin, patterns } of SKIN_PATTERNS) {
+        const matched = patterns.filter((p) => p.test(html));
+        if (matched.length > 0) {
+            const overrideCount = Object.keys(token_overrides).length;
+            const confidence = overrideCount > 0 ? 'high' : 'medium';
+            return {
+                skin,
+                confidence,
+                token_overrides,
+                reasoning: `Matched skin selector pattern for "${skin}". ` +
+                    (overrideCount > 0
+                        ? `Found ${overrideCount} CSS custom property override(s).`
+                        : 'No CSS custom property overrides detected.'),
+            };
+        }
+    }
+    // Check for any --run-color-* overrides that might hint at theming without a named skin.
+    const overrideCount = Object.keys(token_overrides).length;
+    if (overrideCount > 0) {
+        return {
+            skin: null,
+            confidence: 'medium',
+            token_overrides,
+            reasoning: `No named skin selector found, but detected ${overrideCount} CSS custom property override(s) using RunsNative tokens.`,
+        };
+    }
+    // Fallback stub — skin token data not yet loaded or markup has no skin signals.
+    return {
+        skin: null,
+        confidence: 'low',
+        token_overrides: {},
+        reasoning: 'No skin selector or RunsNative token overrides detected in the provided markup. ' +
+            'Skin token data may not yet be available for this build, or the page uses the default skin implicitly.',
+    };
+}
+export async function handleInferTheme(args) {
+    const html = args.html;
+    if (typeof html !== 'string') {
+        throw new McpError(ErrorCode.InvalidParams, 'html must be a string');
+    }
+    if (!html.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, 'html must not be empty');
+    }
+    const result = analyseHtml(html);
+    const text = JSON.stringify(result, null, 2);
+    return { content: [{ type: 'text', text }] };
+}

package/dist/tools/list-components.js

@@ -0,0 +1,35 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+export const LIST_COMPONENTS_TOOL = {
+    name: 'list_components',
+    description: 'Lists RunsNative components available in the knowledge base. ' +
+        'Returns name, title, element tag, surface area, status, and purpose for each component. ' +
+        'By default returns only ready components. Pass include_drafts: true to include draft stubs.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            include_drafts: {
+                type: 'boolean',
+                description: 'When true, includes draft/stub components in addition to ready ones. Default: false.',
+            },
+        },
+        required: [],
+    },
+};
+export async function handleListComponents(provider, args) {
+    const includeDrafts = args.include_drafts === true;
+    let components;
+    try {
+        components = await provider.listComponents(includeDrafts);
+    }
+    catch (err) {
+        if (err instanceof Error) {
+            throw new McpError(ErrorCode.InternalError, err.message);
+        }
+        throw err;
+    }
+    const payload = { components };
+    if (provider.bootstrapUrl)
+        payload['bootstrap_url'] = provider.bootstrapUrl;
+    const text = JSON.stringify(payload, null, 2);
+    return { content: [{ type: 'text', text }] };
+}

package/dist/tools/list-composition-patterns.js

@@ -0,0 +1,29 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+export const LIST_COMPOSITION_PATTERNS_TOOL = {
+    name: 'list_composition_patterns',
+    description: 'Lists available RunsNative composition patterns (recipes). ' +
+        'Each pattern shows how to compose a complete UI surface — sign-in form, dashboard shell, ' +
+        'multi-step form, chat room, etc. — using RunsNative components, with live preview specs, ' +
+        'framework code examples, accessibility notes, and customization guidance. ' +
+        'Call get_composition_pattern(name) to retrieve the full pattern.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        required: [],
+    },
+};
+export async function handleListCompositionPatterns(provider, _args) {
+    let patterns;
+    try {
+        patterns = await provider.listRecipes();
+    }
+    catch (err) {
+        if (err instanceof Error) {
+            throw new McpError(ErrorCode.InternalError, err.message);
+        }
+        throw err;
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify({ patterns }, null, 2) }],
+    };
+}

package/dist/tools/list-exercises.js

@@ -0,0 +1,23 @@
+export const LIST_EXERCISES_TOOL = {
+    name: 'list_exercises',
+    description: 'Returns the available RunsNative guided exercises. ' +
+        'Each exercise is activity-shaped (vibe, migrate, compose, explore) with a difficulty level and estimated time. ' +
+        'Call start_exercise(name) to begin an exercise and get its step list.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            include_drafts: {
+                type: 'boolean',
+                description: 'Include exercises with status: draft. Defaults to false (ready exercises only).',
+            },
+        },
+        required: [],
+    },
+};
+export async function handleListExercises(provider, args) {
+    const includeDrafts = args.include_drafts === true;
+    const exercises = await provider.listExercises(includeDrafts);
+    return {
+        content: [{ type: 'text', text: JSON.stringify({ exercises }, null, 2) }],
+    };
+}

package/dist/tools/search-docs.js

@@ -0,0 +1,43 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+export const SEARCH_DOCS_TOOL = {
+    name: 'search_docs',
+    description: 'Lexical search across all RunsNative component documentation, foundations, and exercises. ' +
+        'Useful when you do not know the exact component name — for example, searching "focus ring token" ' +
+        'or "which component handles multi-select". Returns scored results with excerpts.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'Search terms, e.g. "focus ring token" or "accessible checkbox".',
+            },
+            limit: {
+                type: 'number',
+                description: 'Maximum number of results to return. Default: 5.',
+            },
+        },
+        required: ['query'],
+    },
+};
+export async function handleSearchDocs(provider, args) {
+    const query = args.query;
+    const limit = args.limit;
+    if (typeof query !== 'string') {
+        throw new McpError(ErrorCode.InvalidParams, 'query must be a string');
+    }
+    if (limit !== undefined && (typeof limit !== 'number' || limit < 1)) {
+        throw new McpError(ErrorCode.InvalidParams, 'limit must be a positive number');
+    }
+    let results;
+    try {
+        results = await provider.searchDocs(query.trim(), typeof limit === 'number' ? Math.floor(limit) : 5);
+    }
+    catch (err) {
+        if (err instanceof Error) {
+            throw new McpError(ErrorCode.InternalError, err.message);
+        }
+        throw err;
+    }
+    const text = JSON.stringify({ query, results }, null, 2);
+    return { content: [{ type: 'text', text }] };
+}

package/dist/tools/start-exercise.js

@@ -0,0 +1,36 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+export const START_EXERCISE_TOOL = {
+    name: 'start_exercise',
+    description: 'Returns the overview and step list for a RunsNative exercise. ' +
+        'Does not return step content — call get_step(exercise, n) for each step individually. ' +
+        'Use list_exercises() first to see available exercise names.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            name: {
+                type: 'string',
+                description: 'Exercise slug. Examples: "vibe-with-runsnative", "migrate-to-runsnative", "compose-with-compounds".',
+            },
+        },
+        required: ['name'],
+    },
+};
+export async function handleStartExercise(provider, args) {
+    const name = args.name;
+    if (typeof name !== 'string' || !name.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, 'name must be a non-empty string');
+    }
+    let detail;
+    try {
+        detail = await provider.getExerciseDetail(name.trim());
+    }
+    catch (err) {
+        if (err instanceof RangeError) {
+            throw new McpError(ErrorCode.InvalidParams, err.message);
+        }
+        throw err;
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(detail, null, 2) }],
+    };
+}

package/dist/tools/surface-preview.js

@@ -0,0 +1,36 @@
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+export const SURFACE_PREVIEW_TOOL = {
+    name: 'surface_preview',
+    description: 'Renders a RunsNative component fixture (run-table + run-button) inside an MCP App ' +
+        'iframe. Used to verify that RunsNative web components hydrate correctly in the claude.ai ' +
+        'MCP Apps sandbox. Returns HTML content. This tool exists for RUN-477 verification — ' +
+        'it is not a production surface.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        required: [],
+    },
+};
+export function handleSurfacePreview() {
+    // Read fixture from the fixtures/ sibling dir at call time, not compile time,
+    // so hot-reloading the fixture doesn't require rebuilding the server.
+    // In dist/, __dirname resolves to dist/tools/; fixture is at ../../fixtures/.
+    const fixturePath = resolve(__dirname, '../../fixtures/surface-preview.html');
+    const html = readFileSync(fixturePath, 'utf8');
+    return {
+        content: [
+            {
+                type: 'resource',
+                resource: {
+                    uri: 'data:text/html;charset=utf-8,surface-preview',
+                    mimeType: 'text/html',
+                    text: html,
+                },
+            },
+        ],
+    };
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@runsnative/mcp-server",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "dist/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "runsnative-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "http-server": "node dist/http-server.js",
+    "validate": "node dist/test/validate.js",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "playwright": "^1.58.2",
+    "sharp": "^0.33.0",
+    "typescript": "^5.5.3",
+    "vitest": "^4.1.2",
+    "zod": "*"
+  }
+}