@starklab/stark-mcp 0.1.0

package/src/data.test.js

@@ -0,0 +1,231 @@
+import { mkdtempSync, rmSync, readdirSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { describe, it, expect, afterEach } from 'vitest';
+
+import {
+  toSlug,
+  listComponents,
+  getComponentUsage,
+  getComponentProps,
+  getComponentTokens,
+  buildManifest,
+  getLayoutCatalog,
+  getLayoutSchema,
+  validateLayout,
+  getGenerationProtocol,
+  ejectComponent,
+} from './data.js';
+
+describe('toSlug', () => {
+  it('converts PascalCase to kebab-case', () => {
+    expect(toSlug('TextInput')).toBe('text-input');
+    expect(toSlug('BadgeStatus')).toBe('badge-status');
+  });
+
+  it('is idempotent on already-kebab input', () => {
+    expect(toSlug('text-input')).toBe('text-input');
+  });
+
+  it('is case-insensitive for plain names', () => {
+    expect(toSlug('button')).toBe('button');
+    expect(toSlug('Button')).toBe('button');
+  });
+});
+
+describe('listComponents', () => {
+  it('includes Button with a resolved usage status', () => {
+    const components = listComponents();
+    const button = components.find(c => c.slug === 'button');
+    expect(button).toBeTruthy();
+    expect(button.name).toBe('Button');
+    expect(button.status).toBe('stable');
+    expect(button.description).toContain('action');
+  });
+
+  it('is sorted by name', () => {
+    const names = listComponents().map(c => c.name);
+    const sorted = [...names].sort((a, b) => a.localeCompare(b));
+    expect(names).toEqual(sorted);
+  });
+});
+
+describe('getComponentUsage', () => {
+  it('returns dos/donts for a known component, case-insensitively', () => {
+    const usage = getComponentUsage('button');
+    expect(Array.isArray(usage.dos)).toBe(true);
+    expect(Array.isArray(usage.donts)).toBe(true);
+    expect(usage.dos.length).toBeGreaterThan(0);
+
+    const same = getComponentUsage('Button');
+    expect(same.dos).toEqual(usage.dos);
+  });
+
+  it('throws a helpful error for an unknown component', () => {
+    expect(() => getComponentUsage('NotAComponent')).toThrow(/list_components/);
+  });
+});
+
+describe('getComponentProps', () => {
+  it('returns the propMap for Button on web', () => {
+    const props = getComponentProps('Button', 'web');
+    expect(props.component).toBe('Button');
+    const variant = props.propMap.find(p => p.react === 'variant');
+    expect(variant).toBeTruthy();
+    expect(variant.values).toMatchObject({ primary: 'primary' });
+  });
+
+  it('throws for an unsupported platform', () => {
+    expect(() => getComponentProps('Button', 'not-a-platform')).toThrow(/does not support platform/);
+  });
+
+  it('omits tokens by default', () => {
+    const props = getComponentProps('Button', 'web');
+    expect(props.tokens).toBeUndefined();
+  });
+
+  it('includes token JSON when includeTokens is true', () => {
+    const props = getComponentProps('Button', 'web', true);
+    expect(props.tokens).toBeTruthy();
+    expect(props.tokens.button).toBeTruthy();
+  });
+
+  it('returns null tokens for a component with no token file', () => {
+    const props = getComponentProps('Container', 'web', true);
+    expect(props.tokens).toBeNull();
+  });
+});
+
+describe('getComponentTokens', () => {
+  it('returns the DTCG token tree for a component that has one', () => {
+    const tokens = getComponentTokens('Button');
+    expect(tokens.button).toBeTruthy();
+  });
+
+  it('returns null for a component with no token file', () => {
+    expect(getComponentTokens('Grid')).toBeNull();
+    expect(getComponentTokens('Stack')).toBeNull();
+    expect(getComponentTokens('RadioGroup')).toBeNull();
+  });
+});
+
+describe('buildManifest', () => {
+  it('includes every listed component, with usage, props, and tokens rolled in', () => {
+    const manifest = buildManifest();
+    expect(manifest.componentCount).toBe(listComponents().length);
+    expect(manifest.components.length).toBe(manifest.componentCount);
+
+    const button = manifest.components.find(c => c.name === 'Button');
+    expect(button.usage.dos.length).toBeGreaterThan(0);
+    expect(button.props.web.propMap.length).toBeGreaterThan(0);
+    expect(button.tokens.button).toBeTruthy();
+  });
+
+  it('handles a component with no token file without throwing', () => {
+    const manifest = buildManifest();
+    const container = manifest.components.find(c => c.name === 'Container');
+    expect(container).toBeTruthy();
+    expect(container.tokens).toBeNull();
+  });
+
+  it('only includes platforms the component actually supports', () => {
+    const manifest = buildManifest();
+    const button = manifest.components.find(c => c.name === 'Button');
+    expect(Object.keys(button.props)).toContain('web');
+  });
+});
+
+describe('layout catalog / schema', () => {
+  it('lists Button in the web layout catalog with nodeType', () => {
+    const catalog = getLayoutCatalog('web');
+    const entry = catalog.find(c => c.name === 'Button');
+    expect(entry).toBeTruthy();
+    expect(entry.schema.nodeType).toBe('Button');
+  });
+
+  it('get_layout_schema returns the same entry as filtering the catalog', () => {
+    const schema = getLayoutSchema('Button', 'web');
+    expect(schema.schema.nodeType).toBe('Button');
+  });
+
+  it('throws for a component with no standalone layout node', () => {
+    expect(() => getLayoutSchema('DefinitelyNotReal', 'web')).toThrow(/get_layout_catalog/);
+  });
+});
+
+describe('validateLayout', () => {
+  it('returns a findings array for an empty layout', () => {
+    const result = validateLayout({ layout: { page: { sections: [] } } });
+    expect(Array.isArray(result.findings)).toBe(true);
+    expect(typeof result.hasBlocking).toBe('boolean');
+  });
+});
+
+describe('ejectComponent', () => {
+  let tmpDir;
+
+  afterEach(() => {
+    if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('copies a component\'s jsx and css into the target directory', () => {
+    tmpDir = mkdtempSync(path.join(os.tmpdir(), 'stark-eject-test-'));
+    const target = path.join(tmpDir, 'Button');
+    const result = ejectComponent('button', { outDir: target });
+
+    expect(result.component).toBe('Button');
+    expect(result.files.sort()).toEqual(['Button.css', 'Button.jsx']);
+    expect(readdirSync(target).sort()).toEqual(['Button.css', 'Button.jsx']);
+  });
+
+  it('excludes .figma.tsx code-connect metadata', () => {
+    tmpDir = mkdtempSync(path.join(os.tmpdir(), 'stark-eject-test-'));
+    const target = path.join(tmpDir, 'DataTable');
+    const result = ejectComponent('DataTable', { outDir: target });
+
+    expect(result.files.some(f => f.endsWith('.figma.tsx'))).toBe(false);
+  });
+
+  it('throws for an unknown component', () => {
+    expect(() => ejectComponent('NotAComponent')).toThrow(/Unknown component/);
+  });
+
+  it('copies from stk-react-native when platform is native', () => {
+    tmpDir = mkdtempSync(path.join(os.tmpdir(), 'stark-eject-test-'));
+    const target = path.join(tmpDir, 'Button');
+    const result = ejectComponent('Button', { outDir: target, platform: 'native' });
+
+    expect(result.platform).toBe('native');
+    expect(result.files).toEqual(['Button.jsx']);
+    expect(readdirSync(target)).toEqual(['Button.jsx']);
+  });
+
+  it('throws for an unsupported eject platform', () => {
+    expect(() => ejectComponent('Button', { platform: 'not-a-platform' })).toThrow(/Unsupported platform/);
+  });
+
+  it('refuses to overwrite a non-empty target without force', () => {
+    tmpDir = mkdtempSync(path.join(os.tmpdir(), 'stark-eject-test-'));
+    const target = path.join(tmpDir, 'Button');
+    ejectComponent('Button', { outDir: target });
+
+    expect(() => ejectComponent('Button', { outDir: target })).toThrow(/already exists/);
+  });
+
+  it('overwrites a non-empty target when force is set', () => {
+    tmpDir = mkdtempSync(path.join(os.tmpdir(), 'stark-eject-test-'));
+    const target = path.join(tmpDir, 'Button');
+    ejectComponent('Button', { outDir: target });
+
+    expect(() => ejectComponent('Button', { outDir: target, force: true })).not.toThrow();
+  });
+});
+
+describe('getGenerationProtocol', () => {
+  it('returns the versioned step checklist', () => {
+    const protocol = getGenerationProtocol();
+    expect(protocol.version).toBeGreaterThanOrEqual(1);
+    expect(protocol.steps.length).toBeGreaterThan(0);
+  });
+});

package/src/index.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+import { createServer } from './server.js';
+
+const server = createServer();
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/server.js

@@ -0,0 +1,149 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+import {
+  listComponents,
+  getComponentUsage,
+  getComponentProps,
+  buildManifest,
+  getLayoutCatalog,
+  getLayoutSchema,
+  validateLayout,
+  getGenerationProtocol,
+} from './data.js';
+
+const json = value => ({ content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] });
+const error = message => ({ content: [{ type: 'text', text: message }], isError: true });
+
+const wrap = fn => async args => {
+  try {
+    return json(await fn(args));
+  } catch (err) {
+    return error(err instanceof Error ? err.message : String(err));
+  }
+};
+
+export function createServer() {
+  const server = new McpServer({ name: 'stark-design-system', version: '0.1.0' });
+
+  server.registerTool(
+    'list_components',
+    {
+      title: 'List Stark components',
+      description:
+        'List every component in the Stark design system catalog with its status ' +
+        '(stable/beta/experimental/deprecated), one-line description, and supported platforms.',
+      inputSchema: {},
+    },
+    wrap(() => listComponents())
+  );
+
+  server.registerTool(
+    'get_component_usage',
+    {
+      title: 'Get component usage rules',
+      description:
+        'Get the dos/donts, prop table, and Figma link for one Stark component. ' +
+        'Read this before placing the component in a layout.',
+      inputSchema: {
+        component: z.string().describe('Component name, e.g. "Button" or "TextInput" (case-insensitive)'),
+      },
+    },
+    wrap(({ component }) => getComponentUsage(component))
+  );
+
+  server.registerTool(
+    'get_component_props',
+    {
+      title: 'Get component prop mapping',
+      description:
+        'Get the React<->Figma prop translation table for one component: prop names, ' +
+        'types, enum values, and defaults.',
+      inputSchema: {
+        component: z.string().describe('Component name, e.g. "Button"'),
+        platform: z.enum(['web', 'native']).default('web').describe('Target platform'),
+        includeTokens: z
+          .boolean()
+          .default(false)
+          .describe(
+            'Also return the component-level design token JSON (spacing, radius, color aliases…) in a ' +
+              '"tokens" field. null if the component has no component-layer tokens of its own (e.g. layout primitives).'
+          ),
+      },
+    },
+    wrap(({ component, platform, includeTokens }) => getComponentProps(component, platform, includeTokens))
+  );
+
+  server.registerTool(
+    'get_manifest',
+    {
+      title: 'Get the full design system manifest',
+      description:
+        'Get every component in one call — usage rules, prop mappings for every supported platform, ' +
+        'and token JSON — instead of making list_components + get_component_usage + get_component_props ' +
+        'per component. Useful for a one-shot snapshot of the whole system.',
+      inputSchema: {},
+    },
+    wrap(() => buildManifest())
+  );
+
+  server.registerTool(
+    'get_layout_catalog',
+    {
+      title: 'Get the full layout catalog',
+      description:
+        'Get every component that can be used as a standalone layout node, with its props ' +
+        'and slots. This is the same catalog Stark\'s own layout generator (Vecna) is restricted to.',
+      inputSchema: {
+        platform: z.enum(['web', 'native']).default('web').describe('Target platform'),
+      },
+    },
+    wrap(({ platform }) => getLayoutCatalog(platform))
+  );
+
+  server.registerTool(
+    'get_layout_schema',
+    {
+      title: 'Get one component\'s layout schema',
+      description: 'Get the props/slots schema for a single layout-capable component.',
+      inputSchema: {
+        component: z.string().describe('Component name, e.g. "Card"'),
+        platform: z.enum(['web', 'native']).default('web').describe('Target platform'),
+      },
+    },
+    wrap(({ component, platform }) => getLayoutSchema(component, platform))
+  );
+
+  server.registerTool(
+    'validate_layout',
+    {
+      title: 'Validate a generated layout',
+      description:
+        'Run Stark\'s deterministic conformance checks (no LLM) against a LayoutConfig JSON: ' +
+        'catalog membership, component do/dont rules, guardrails, and prop shape. Returns findings ' +
+        'ranked Critical/Warning/Info. Pass `canvasCases` (your renderer\'s supported node-type list) ' +
+        'if you have one — without it, the catalog<->renderer parity check is skipped.',
+      inputSchema: {
+        layout: z.record(z.string(), z.any()).describe('The LayoutConfig JSON, shaped { page: { sections: [...] } }'),
+        intent: z.record(z.string(), z.any()).optional().describe('Intent/guardrails object the layout was generated from'),
+        platform: z.enum(['web', 'native']).default('web'),
+        canvasCases: z.array(z.string()).optional().describe('Node types your renderer actually supports'),
+      },
+    },
+    wrap(({ layout, intent, platform, canvasCases }) => validateLayout({ layout, intent, platform, canvasCases }))
+  );
+
+  server.registerTool(
+    'get_generation_protocol',
+    {
+      title: 'Get the layout generation protocol',
+      description:
+        'Get the enforced step-by-step checklist an agent must follow before a generated layout ' +
+        'is considered done — the same checklist the Vecna orchestrator runs.',
+      inputSchema: {},
+    },
+    wrap(() => getGenerationProtocol())
+  );
+
+  return server;
+}