@runsnative/mcp-server 0.1.0

package/dist/index.js

@@ -0,0 +1,72 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { GET_COMPONENT_TOOL, handleGetComponent } from './tools/get-component.js';
+import { LIST_COMPONENTS_TOOL, handleListComponents } from './tools/list-components.js';
+import { GET_FOUNDATION_TOOL, handleGetFoundation } from './tools/get-foundation.js';
+import { SEARCH_DOCS_TOOL, handleSearchDocs } from './tools/search-docs.js';
+import { INFER_THEME_TOOL, handleInferTheme } from './tools/infer-theme.js';
+import { INFER_BRAND_THEME_TOOL, handleInferBrandTheme } from './tools/infer-brand-theme.js';
+import { LIST_EXERCISES_TOOL, handleListExercises } from './tools/list-exercises.js';
+import { START_EXERCISE_TOOL, handleStartExercise } from './tools/start-exercise.js';
+import { GET_STEP_TOOL, handleGetStep } from './tools/get-step.js';
+import { SURFACE_PREVIEW_TOOL, handleSurfacePreview } from './tools/surface-preview.js';
+import { LIST_COMPOSITION_PATTERNS_TOOL, handleListCompositionPatterns } from './tools/list-composition-patterns.js';
+import { GET_COMPOSITION_PATTERN_TOOL, handleGetCompositionPattern } from './tools/get-composition-pattern.js';
+import { createProvider } from './provider.js';
+import { RemoteContentProvider } from './remote-provider.js';
+// Create the content provider — LocalContentProvider if content tree is present,
+// RemoteContentProvider otherwise. Initialize runs the manifest version check.
+const provider = await createProvider();
+if (provider instanceof RemoteContentProvider) {
+    await provider.initialize();
+}
+const server = new Server({ name: 'runsnative-mcp', version: '0.3.0' }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        GET_COMPONENT_TOOL,
+        LIST_COMPONENTS_TOOL,
+        GET_FOUNDATION_TOOL,
+        SEARCH_DOCS_TOOL,
+        INFER_THEME_TOOL,
+        INFER_BRAND_THEME_TOOL,
+        LIST_EXERCISES_TOOL,
+        START_EXERCISE_TOOL,
+        GET_STEP_TOOL,
+        SURFACE_PREVIEW_TOOL,
+        LIST_COMPOSITION_PATTERNS_TOOL,
+        GET_COMPOSITION_PATTERN_TOOL,
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    switch (request.params.name) {
+        case 'get_component':
+            return handleGetComponent(provider, request.params.arguments ?? {});
+        case 'list_components':
+            return handleListComponents(provider, request.params.arguments ?? {});
+        case 'get_foundation':
+            return handleGetFoundation(provider, request.params.arguments ?? {});
+        case 'search_docs':
+            return handleSearchDocs(provider, request.params.arguments ?? {});
+        case 'infer_theme':
+            return handleInferTheme(request.params.arguments ?? {});
+        case 'infer_brand_theme':
+            return handleInferBrandTheme(request.params.arguments ?? {});
+        case 'list_exercises':
+            return handleListExercises(provider, request.params.arguments ?? {});
+        case 'start_exercise':
+            return handleStartExercise(provider, request.params.arguments ?? {});
+        case 'get_step':
+            return handleGetStep(provider, request.params.arguments ?? {});
+        case 'surface_preview':
+            return handleSurfacePreview();
+        case 'list_composition_patterns':
+            return handleListCompositionPatterns(provider, request.params.arguments ?? {});
+        case 'get_composition_pattern':
+            return handleGetCompositionPattern(provider, request.params.arguments ?? {});
+        default:
+            throw new Error(`Unknown tool: ${request.params.name}`);
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/inferrer/image-extractor.js

@@ -0,0 +1,76 @@
+import sharp from 'sharp';
+const MAX_PIXELS = 10_000;
+const MAX_ITER = 20;
+function toHex(r, g, b) {
+    return '#' + [r, g, b]
+        .map(v => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0'))
+        .join('');
+}
+function sqDist(ar, ag, ab, br, bg, bb) {
+    return (ar - br) ** 2 + (ag - bg) ** 2 + (ab - bb) ** 2;
+}
+export async function extractImageColors(buffer, sourceType, k = 5) {
+    const extractedAt = new Date().toISOString();
+    const { data, info } = await sharp(buffer)
+        .flatten({ background: '#ffffff' })
+        .removeAlpha()
+        .raw()
+        .toBuffer({ resolveWithObject: true });
+    const totalPixels = info.width * info.height;
+    const stride = Math.max(1, Math.floor(totalPixels / MAX_PIXELS));
+    const pixels = [];
+    for (let i = 0; i < data.length; i += stride * 3) {
+        pixels.push([data[i], data[i + 1], data[i + 2]]);
+    }
+    // k-means++ initialisation
+    const centroids = [];
+    centroids.push([...pixels[Math.floor(Math.random() * pixels.length)]]);
+    for (let c = 1; c < k; c++) {
+        const dists = pixels.map(p => Math.min(...centroids.map(cen => sqDist(p[0], p[1], p[2], cen[0], cen[1], cen[2]))));
+        const total = dists.reduce((s, d) => s + d, 0);
+        let rnd = Math.random() * total;
+        let chosen = pixels.length - 1;
+        for (let i = 0; i < dists.length; i++) {
+            rnd -= dists[i];
+            if (rnd <= 0) {
+                chosen = i;
+                break;
+            }
+        }
+        centroids.push([...pixels[chosen]]);
+    }
+    // Lloyd's iterations
+    let assignments = new Array(pixels.length).fill(0);
+    for (let iter = 0; iter < MAX_ITER; iter++) {
+        const next = pixels.map(p => centroids.reduce((best, cen, ci) => {
+            const d = sqDist(p[0], p[1], p[2], cen[0], cen[1], cen[2]);
+            return d < best.d ? { ci, d } : best;
+        }, { ci: 0, d: Infinity }).ci);
+        const sums = centroids.map(() => [0, 0, 0]);
+        const counts = new Array(k).fill(0);
+        next.forEach((ci, pi) => {
+            sums[ci][0] += pixels[pi][0];
+            sums[ci][1] += pixels[pi][1];
+            sums[ci][2] += pixels[pi][2];
+            counts[ci]++;
+        });
+        centroids.forEach((cen, ci) => {
+            if (counts[ci] > 0) {
+                cen[0] = Math.round(sums[ci][0] / counts[ci]);
+                cen[1] = Math.round(sums[ci][1] / counts[ci]);
+                cen[2] = Math.round(sums[ci][2] / counts[ci]);
+            }
+        });
+        const converged = next.every((ci, i) => ci === assignments[i]);
+        assignments = next;
+        if (converged)
+            break;
+    }
+    const counts = new Array(k).fill(0);
+    assignments.forEach(ci => counts[ci]++);
+    const dominantColors = centroids
+        .map((cen, ci) => ({ hex: toHex(cen[0], cen[1], cen[2]), frequency: counts[ci] / pixels.length }))
+        .filter(dc => dc.frequency > 0)
+        .sort((a, b) => b.frequency - a.frequency);
+    return { dominantColors, sourceType, extractedAt };
+}

package/dist/inferrer/page-fetcher.js

@@ -0,0 +1,46 @@
+import { chromium } from 'playwright';
+const VIEWPORT = { width: 1280, height: 800 };
+export async function fetchAndRender(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { ok: false, error: { code: 'FETCH_ERROR', message: 'Invalid URL', url } };
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        return { ok: false, error: { code: 'FETCH_ERROR', message: `Unsupported scheme: ${parsed.protocol}`, url } };
+    }
+    const browser = await chromium.launch({ headless: true });
+    try {
+        const page = await browser.newPage();
+        await page.setViewportSize(VIEWPORT);
+        const response = await page.goto(url, { waitUntil: 'networkidle' });
+        if (!response) {
+            return { ok: false, error: { code: 'FETCH_ERROR', message: 'Navigation returned no response', url } };
+        }
+        const htmlSource = await response.text();
+        const renderedHtml = await page.content();
+        const screenshot = await page.screenshot({ fullPage: true });
+        const title = await page.title();
+        return {
+            ok: true,
+            snapshot: {
+                url: page.url(),
+                htmlSource,
+                renderedHtml,
+                screenshot,
+                viewport: VIEWPORT,
+                title,
+                fetchedAt: new Date().toISOString(),
+            },
+        };
+    }
+    catch (err) {
+        const cause = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: { code: 'FETCH_ERROR', message: 'Headless render failed', url, cause } };
+    }
+    finally {
+        await browser.close();
+    }
+}

package/dist/inferrer/pipeline.js

@@ -0,0 +1,27 @@
+import { fetchAndRender } from './page-fetcher.js';
+import { extractStyles } from './style-extractor.js';
+import { extractImageColors } from './image-extractor.js';
+import { inferTheme } from './theme-inferrer.js';
+export async function runInferencePipeline(url) {
+    const fetchResult = await fetchAndRender(url);
+    if (!fetchResult.ok)
+        return { ok: false, error: fetchResult.error };
+    const { snapshot } = fetchResult;
+    let imageEvidence = undefined;
+    try {
+        imageEvidence = await extractImageColors(snapshot.screenshot, 'screenshot');
+    }
+    catch {
+        // Image extraction is best-effort — proceed without it.
+    }
+    let evidence;
+    try {
+        evidence = await extractStyles(snapshot);
+    }
+    catch (err) {
+        const cause = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: { code: 'EXTRACTION_ERROR', message: 'Style extraction failed', url: snapshot.url, cause } };
+    }
+    const result = inferTheme(evidence, imageEvidence);
+    return { ok: true, result };
+}

package/dist/inferrer/style-extractor.js

@@ -0,0 +1,75 @@
+import { chromium } from 'playwright';
+const SAMPLE_SELECTORS = 'body,h1,h2,h3,h4,h5,h6,p,a,button,input,select,textarea,' +
+    'div,span,header,footer,nav,main,section,article,aside,ul,ol,li';
+const MAX_ELEMENTS = 200;
+export async function extractStyles(snapshot) {
+    const browser = await chromium.launch({ headless: true });
+    try {
+        const page = await browser.newPage();
+        await page.setViewportSize({ width: 1280, height: 800 });
+        await page.setContent(snapshot.renderedHtml, { waitUntil: 'domcontentloaded' });
+        const raw = await page.evaluate(({ selectors, maxElements }) => {
+            const elements = Array.from(document.querySelectorAll(selectors)).slice(0, maxElements);
+            const colors = new Set();
+            const fontFamilies = new Set();
+            const fontSizes = new Set();
+            const borderRadii = new Set();
+            const shadows = new Set();
+            const spacings = new Set();
+            for (const el of elements) {
+                const cs = window.getComputedStyle(el);
+                for (const prop of [
+                    'color', 'background-color', 'border-top-color',
+                    'border-right-color', 'border-bottom-color', 'border-left-color', 'outline-color',
+                ]) {
+                    const v = cs.getPropertyValue(prop);
+                    if (v && v !== 'rgba(0, 0, 0, 0)')
+                        colors.add(v);
+                }
+                const ff = cs.getPropertyValue('font-family');
+                if (ff)
+                    fontFamilies.add(ff);
+                const fs = cs.getPropertyValue('font-size');
+                if (fs && fs !== '0px')
+                    fontSizes.add(fs);
+                for (const prop of [
+                    'border-top-left-radius', 'border-top-right-radius',
+                    'border-bottom-right-radius', 'border-bottom-left-radius',
+                ]) {
+                    const v = cs.getPropertyValue(prop);
+                    if (v && v !== '0px')
+                        borderRadii.add(v);
+                }
+                for (const prop of ['box-shadow', 'text-shadow']) {
+                    const v = cs.getPropertyValue(prop);
+                    if (v && v !== 'none')
+                        shadows.add(v);
+                }
+                for (const prop of [
+                    'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
+                    'padding-top', 'padding-right', 'padding-bottom', 'padding-left',
+                ]) {
+                    const v = cs.getPropertyValue(prop);
+                    if (v && v !== '0px')
+                        spacings.add(v);
+                }
+            }
+            return {
+                colors: [...colors],
+                fontFamilies: [...fontFamilies],
+                fontSizes: [...fontSizes],
+                borderRadii: [...borderRadii],
+                shadows: [...shadows],
+                spacings: [...spacings],
+            };
+        }, { selectors: SAMPLE_SELECTORS, maxElements: MAX_ELEMENTS });
+        return {
+            ...raw,
+            sourceUrl: snapshot.url,
+            extractedAt: new Date().toISOString(),
+        };
+    }
+    finally {
+        await browser.close();
+    }
+}

package/dist/inferrer/theme-inferrer.js

@@ -0,0 +1,134 @@
+function parseCssColor(css) {
+    const m = /rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/.exec(css);
+    if (!m)
+        return null;
+    return [parseInt(m[1], 10), parseInt(m[2], 10), parseInt(m[3], 10)];
+}
+function rgbToHex(r, g, b) {
+    const ch = (v) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0');
+    return `#${ch(r)}${ch(g)}${ch(b)}`;
+}
+function rgbRange(r, g, b) {
+    return Math.max(r, g, b) - Math.min(r, g, b);
+}
+function parsePx(value) {
+    const m = /^([\d.]+)px$/.exec(value.trim());
+    return m ? parseFloat(m[1]) : null;
+}
+function median(values) {
+    if (values.length === 0)
+        return null;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0
+        ? (sorted[mid - 1] + sorted[mid]) / 2
+        : sorted[mid];
+}
+function inferPrimaryColor(evidence, imageEvidence) {
+    if (imageEvidence && imageEvidence.dominantColors.length > 0) {
+        return { value: imageEvidence.dominantColors[0].hex, confidence: 'high' };
+    }
+    let bestHex = '';
+    let bestRange = -1;
+    for (const css of evidence.colors) {
+        const rgb = parseCssColor(css);
+        if (!rgb)
+            continue;
+        const range = rgbRange(rgb[0], rgb[1], rgb[2]);
+        if (range > bestRange) {
+            bestRange = range;
+            bestHex = rgbToHex(rgb[0], rgb[1], rgb[2]);
+        }
+    }
+    if (bestHex) {
+        return { value: bestHex, confidence: bestRange >= 60 ? 'high' : 'medium' };
+    }
+    return { value: '#3b82f6', confidence: 'low' };
+}
+function inferTypography(fontFamilies) {
+    const haystack = fontFamilies.join(' ').toLowerCase();
+    if (!haystack.trim())
+        return { value: 'modern', confidence: 'low' };
+    const rules = [
+        [/mono|monospace|courier|consolas|source code|fira code|jetbrains|inconsolata/, 'technical'],
+        [/impact|black|ultra|extrabold|heavy|oswald|bebas|druk/, 'bold'],
+        [/playfair|freight|tiempos|canela|gt alpina|chronicle|le monde/, 'editorial'],
+        [/times|georgia|palatino|garamond|caslon|baskerville|bodoni|didot/, 'classic'],
+        [/rounded|nunito|quicksand|varela|comfortaa|dosis/, 'friendly'],
+        [/futura|circular|poppins|brandon|montserrat|raleway|proxima nova/, 'geometric'],
+        [/merriweather|lora|ibm plex|source serif|humanist|charter|utopia/, 'humanist'],
+        [/helvetica|avenir|gill sans|calibri|myriad|aktiv|graphik|haas/, 'minimal'],
+        [/corporate|arial|verdana|trebuchet/, 'corporate'],
+        [/inter|roboto|system-ui|segoe|sf pro|apple system|blinkmacsystem|-apple-system/, 'modern'],
+    ];
+    for (const [pattern, preset] of rules) {
+        if (pattern.test(haystack))
+            return { value: preset, confidence: 'medium' };
+    }
+    return { value: 'modern', confidence: 'low' };
+}
+function inferBorderRadius(borderRadii) {
+    const pxValues = borderRadii.map(parsePx).filter((v) => v !== null);
+    if (pxValues.length === 0)
+        return { value: 'sharp', confidence: 'low' };
+    const max = Math.max(...pxValues);
+    if (max <= 3)
+        return { value: 'sharp', confidence: 'high' };
+    if (max <= 8)
+        return { value: 'subtle', confidence: 'high' };
+    if (max <= 24)
+        return { value: 'rounded', confidence: 'high' };
+    return { value: 'pill', confidence: 'high' };
+}
+function inferElevation(shadows) {
+    const count = shadows.length;
+    if (count === 0)
+        return { value: 'flat', confidence: 'high' };
+    if (count <= 2)
+        return { value: 'subtle', confidence: 'high' };
+    if (count <= 5)
+        return { value: 'medium', confidence: 'medium' };
+    return { value: 'dramatic', confidence: 'medium' };
+}
+function inferDensity(spacings) {
+    const pxValues = spacings.map(parsePx).filter((v) => v !== null);
+    const med = median(pxValues);
+    if (med === null)
+        return { value: 'default', confidence: 'low' };
+    if (med < 8)
+        return { value: 'compact', confidence: 'medium' };
+    if (med < 16)
+        return { value: 'default', confidence: 'medium' };
+    if (med < 24)
+        return { value: 'comfortable', confidence: 'medium' };
+    return { value: 'spacious', confidence: 'medium' };
+}
+export function inferTheme(evidence, imageEvidence) {
+    const primary = inferPrimaryColor(evidence, imageEvidence);
+    const typography = inferTypography(evidence.fontFamilies);
+    const radius = inferBorderRadius(evidence.borderRadii);
+    const elevation = inferElevation(evidence.shadows);
+    const density = inferDensity(evidence.spacings);
+    return {
+        theme: {
+            primaryColor: primary.value,
+            secondaryColor: 'auto',
+            typography: typography.value,
+            density: density.value,
+            borderRadius: radius.value,
+            elevation: elevation.value,
+            motion: 'smooth',
+        },
+        confidence: {
+            primaryColor: primary.confidence,
+            secondaryColor: 'medium',
+            typography: typography.confidence,
+            density: density.confidence,
+            borderRadius: radius.confidence,
+            elevation: elevation.confidence,
+            motion: 'low',
+        },
+        sourceUrl: evidence.sourceUrl,
+        inferredAt: new Date().toISOString(),
+    };
+}

package/dist/local-provider.js

@@ -0,0 +1,38 @@
+import { getComponent, listComponentMeta, getFoundation, listFoundations, searchDocs, listExerciseMeta, getExerciseDetail, getExerciseStep, listRecipeMeta, getRecipe, } from './content.js';
+// ---------------------------------------------------------------------------
+// LocalContentProvider — reads directly from the filesystem content tree.
+// Used when running inside the runsnative repo (dev path) or when
+// RUNSNATIVE_CONTENT_ROOT is set explicitly.
+// ---------------------------------------------------------------------------
+export class LocalContentProvider {
+    getComponent(name, tab) {
+        return getComponent(name, tab);
+    }
+    listComponents(includeDrafts = false) {
+        return listComponentMeta(includeDrafts);
+    }
+    getFoundation(name) {
+        return getFoundation(name);
+    }
+    listFoundations() {
+        return listFoundations();
+    }
+    searchDocs(query, limit = 5) {
+        return searchDocs(query, limit);
+    }
+    listExercises(includeDrafts = false) {
+        return listExerciseMeta(includeDrafts);
+    }
+    getExerciseDetail(name) {
+        return getExerciseDetail(name);
+    }
+    getExerciseStep(name, step) {
+        return getExerciseStep(name, step);
+    }
+    listRecipes() {
+        return listRecipeMeta();
+    }
+    getRecipe(name) {
+        return getRecipe(name);
+    }
+}

package/dist/provider.js

@@ -0,0 +1,27 @@
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// ---------------------------------------------------------------------------
+// Factory — selects provider based on environment / filesystem presence.
+//
+// Selection order:
+//   1. RUNSNATIVE_CONTENT_ROOT env var set → LocalContentProvider
+//   2. ../../../content exists relative to dist/ → LocalContentProvider
+//   3. Otherwise → RemoteContentProvider
+// ---------------------------------------------------------------------------
+export async function createProvider() {
+    if (process.env['RUNSNATIVE_CONTENT_ROOT']) {
+        const { LocalContentProvider } = await import('./local-provider.js');
+        return new LocalContentProvider();
+    }
+    // Probe for the local content tree relative to this module's location.
+    // In the compiled dist/ layout: dist/provider.js → ../../../content
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const localContent = join(__dirname, '../../../content');
+    if (existsSync(localContent)) {
+        const { LocalContentProvider } = await import('./local-provider.js');
+        return new LocalContentProvider();
+    }
+    const { RemoteContentProvider } = await import('./remote-provider.js');
+    return new RemoteContentProvider();
+}