@1money/component-ui 0.0.22 → 0.0.24

package/scripts/mcp-server/index.mjs

@@ -1,45 +1,327 @@
 /* eslint-disable no-undef */
 /* eslint-env node */
+/**
+ * 1money-react-ui MCP stdio server.
+ *
+ * Loads the committed `index.generated.json`, `drift.json`, and `package.json`
+ * at startup (never on per-request basis) and serves 8 MCP tools over a
+ * stdio transport.
+ *
+ * Use `node scripts/mcp-server/index.mjs --selftest` to run each handler
+ * with a canned input — useful for smoke-testing without a real MCP client.
+ */
+
 import process from 'node:process';
-import { createServer } from 'node:http';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { registerComponentResources } from './resources.mjs';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema
+} from '@modelcontextprotocol/sdk/types.js';
 
-async function main() {
-  const host = process.env.MCP_HOST || '127.0.0.1';
-  const port = Number(process.env.MCP_PORT || 8686);
+import listSymbols from './tools/list-symbols.mjs';
+import searchSymbols from './tools/search-symbols.mjs';
+import getSymbol from './tools/get-symbol.mjs';
+import getExamples from './tools/get-examples.mjs';
+import listIcons from './tools/list-icons.mjs';
+import getToken from './tools/get-token.mjs';
+import resolveImport from './tools/resolve-import.mjs';
+import getLibraryInfo from './tools/get-library-info.mjs';
 
-  const server = new McpServer({
-    name: '1money-react-ui',
-    version: '0.1.0'
-  });
+const EXPECTED_SCHEMA_VERSION = '1';
+const SERVER_NAME = '1money-react-ui';
+const SERVER_VERSION = '0.1.0';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = path.resolve(__dirname, '..', '..');
+const indexPath = path.join(__dirname, 'index.generated.json');
+const driftPath = path.join(__dirname, 'drift.json');
+const examplesPath = path.join(__dirname, 'examples.generated.json');
+const pkgPath = path.join(repoRoot, 'package.json');
+
+/**
+ * Tool catalog — exposed to clients via tools/list. Input schemas are plain
+ * JSON Schema (not Zod) so we don't take a hard dep on zod here; the server
+ * routes to plain JS handlers below that do their own manual validation.
+ */
+const TOOL_CATALOG = [
+  {
+    name: 'list_symbols',
+    description:
+      'List top-level exported symbols (components, modules, hooks, types). Namespace roots (ProForm, Icons, Input) surface as kind=module.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        kind: {
+          type: 'string',
+          enum: ['component', 'module', 'hook', 'function', 'type', 'all'],
+          default: 'all',
+          description: 'Filter by symbol kind. Use "all" to include every kind.'
+        },
+        category: {
+          type: 'string',
+          description: 'Optional category filter (e.g., "input", "display").'
+        }
+      },
+      additionalProperties: false
+    },
+    handler: listSymbols
+  },
+  {
+    name: 'search_symbols',
+    description:
+      'Fuzzy search over the symbol index. Searches name, aliases (searchTags), summary, and prop names.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Search term.' },
+        limit: { type: 'integer', minimum: 1, default: 5 }
+      },
+      required: ['query'],
+      additionalProperties: false
+    },
+    handler: searchSymbols
+  },
+  {
+    name: 'get_symbol',
+    description:
+      'Fetch a detailed symbol record. Accepts both flat names (e.g., "ProFormItem") and dotted paths (e.g., "ProForm.Item"). Returns { kind: "not_exported", hint } when the name cannot be resolved.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Flat or dotted symbol name.' },
+        include: {
+          type: 'array',
+          items: { enum: ['props', 'examples', 'members', 'notes', 'related'] },
+          default: ['props', 'members']
+        }
+      },
+      required: ['name'],
+      additionalProperties: false
+    },
+    handler: getSymbol
+  },
+  {
+    name: 'get_examples',
+    description:
+      'Fetch curated usage examples for a symbol. Sources: README fenced blocks, Storybook `render` bodies, and canonical snippets. Each entry carries a compilable flag.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        limit: { type: 'integer', minimum: 1, default: 3 },
+        source: {
+          type: 'string',
+          enum: ['all', 'readme', 'stories', 'canonical'],
+          default: 'all'
+        }
+      },
+      required: ['name'],
+      additionalProperties: false
+    },
+    handler: getExamples
+  },
+  {
+    name: 'list_icons',
+    description:
+      'List icon names for the <Icons /> component. Optionally filter by case-insensitive substring.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string' },
+        limit: { type: 'integer', minimum: 1 }
+      },
+      additionalProperties: false
+    },
+    handler: listIcons
+  },
+  {
+    name: 'get_token',
+    description:
+      'Query design tokens by name, kind, or name prefix. Filters combine with AND semantics.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        kind: {
+          type: 'string',
+          enum: [
+            'color',
+            'spacing',
+            'radius',
+            'shadow',
+            'sizing',
+            'opacity',
+            'typography',
+            'breakpoint'
+          ]
+        },
+        prefix: { type: 'string' }
+      },
+      additionalProperties: false
+    },
+    handler: getToken
+  },
+  {
+    name: 'resolve_import',
+    description:
+      'Resolve how to import a symbol. Supports flat names and namespace-member paths (e.g., "ProForm.Item"). Rejects Icons.<Name> with a clear hint.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        symbol: { type: 'string' }
+      },
+      required: ['symbol'],
+      additionalProperties: false
+    },
+    handler: resolveImport
+  },
+  {
+    name: 'get_library_info',
+    description:
+      'Return package metadata: name, version, peer deps, available subpath exports, CSS entry, and schema version.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false
+    },
+    handler: getLibraryInfo
+  }
+];
+
+async function loadContext() {
+  const [indexRaw, driftRaw, examplesRaw, pkgRaw] = await Promise.all([
+    fs.readFile(indexPath, 'utf8'),
+    fs.readFile(driftPath, 'utf8'),
+    fs.readFile(examplesPath, 'utf8'),
+    fs.readFile(pkgPath, 'utf8')
+  ]);
+
+  const index = JSON.parse(indexRaw);
+  const drift = JSON.parse(driftRaw);
+  const examplesIndex = JSON.parse(examplesRaw);
+  const pkg = JSON.parse(pkgRaw);
+
+  if (index.schemaVersion !== EXPECTED_SCHEMA_VERSION) {
+    console.error(
+      `[mcp] schemaVersion mismatch: expected '${EXPECTED_SCHEMA_VERSION}', got '${index.schemaVersion}'. ` +
+        'Regenerate index.generated.json with `pnpm build:mcp-index` and ensure the indexer produces the expected schemaVersion.'
+    );
+    process.exit(1);
+  }
+
+  if (examplesIndex.schemaVersion !== EXPECTED_SCHEMA_VERSION) {
+    console.error(
+      `[mcp] schemaVersion mismatch in examples.generated.json: expected '${EXPECTED_SCHEMA_VERSION}', got '${examplesIndex.schemaVersion}'. ` +
+        'Regenerate with `pnpm build:mcp-index`.'
+    );
+    process.exit(1);
+  }
+
+  return { index, drift, examplesIndex, pkg };
+}
+
+function toToolResult(value) {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    structuredContent: value
+  };
+}
 
-  console.info('[mcp] Starting 1money-react-ui MCP server...');
+function toToolError(message) {
+  return {
+    content: [{ type: 'text', text: message }],
+    isError: true
+  };
+}
+
+function findTool(name) {
+  return TOOL_CATALOG.find(t => t.name === name);
+}
 
-  const registeredCount = await registerComponentResources(server);
-  console.info(`[mcp] Registered ${registeredCount} component resources from src/components`);
+async function runTool(name, rawInput, ctx) {
+  const tool = findTool(name);
+  if (!tool) {
+    throw new Error(`Unknown tool: ${name}`);
+  }
+  return Promise.resolve(tool.handler(rawInput ?? {}, ctx));
+}
 
-  const transport = new StreamableHTTPServerTransport();
-  console.info(`[mcp] Binding HTTP transport on http://${host}:${port}/mcp`);
+async function runSelfTest(ctx) {
+  const cannedInputs = {
+    list_symbols: { kind: 'component' },
+    search_symbols: { query: 'button', limit: 3 },
+    get_symbol: { name: 'ProForm.Item' },
+    get_examples: { name: 'Button' },
+    list_icons: { query: 'chevron', limit: 5 },
+    get_token: { kind: 'breakpoint' },
+    resolve_import: { symbol: 'ProForm.Item' },
+    get_library_info: {}
+  };
 
-  const httpServer = createServer(async (req, res) => {
+  const results = [];
+  for (const tool of TOOL_CATALOG) {
+    const input = cannedInputs[tool.name] ?? {};
     try {
-      await transport.handleRequest(req, res);
-    } catch (error) {
-      console.error('[mcp] HTTP handler error:', error);
-      res.statusCode = 500;
-      res.end('Internal MCP server error');
+      const output = await runTool(tool.name, input, ctx);
+      results.push({ name: tool.name, ok: true, output });
+    } catch (err) {
+      results.push({ name: tool.name, ok: false, error: err.message });
+    }
+  }
+
+  process.stdout.write(JSON.stringify({ selftest: true, toolCount: results.length, results }, null, 2) + '\n');
+  const anyFailed = results.some(r => !r.ok);
+  process.exit(anyFailed ? 1 : 0);
+}
+
+async function startStdioServer(ctx) {
+  const server = new Server(
+    { name: SERVER_NAME, version: SERVER_VERSION },
+    { capabilities: { tools: {} } }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, () => ({
+    tools: TOOL_CATALOG.map(({ name, description, inputSchema }) => ({
+      name,
+      description,
+      inputSchema
+    }))
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async request => {
+    const { name, arguments: args } = request.params;
+    try {
+      const output = await runTool(name, args ?? {}, ctx);
+      return toToolResult(output);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return toToolError(message);
     }
   });
 
+  const transport = new StdioServerTransport();
   await server.connect(transport);
+  console.error(
+    `[mcp] ${SERVER_NAME} v${SERVER_VERSION} listening on stdio (tools: ${TOOL_CATALOG.length})`
+  );
+}
 
-  await new Promise(resolve => httpServer.listen(port, host, resolve));
-  console.info('[mcp] Server ready at http://%s:%d/mcp', host, port);
+async function main() {
+  const argv = process.argv.slice(2);
+  const ctx = await loadContext();
+  if (argv.includes('--selftest')) {
+    await runSelfTest(ctx);
+    return;
+  }
+  await startStdioServer(ctx);
 }
 
-main().catch(error => {
-  console.error('[mcp] Fatal error:', error);
+main().catch(err => {
+  console.error('[mcp] Fatal error:', err);
   process.exit(1);
 });

package/scripts/mcp-server/tools/get-examples.mjs

@@ -0,0 +1,125 @@
+/* eslint-disable no-undef */
+/* eslint-env node */
+/**
+ * Tool: get_examples
+ *
+ * Returns curated usage examples for a symbol.
+ *
+ * Input:  { name, limit = 3, source = 'all' }
+ * Output: { examples: [{ title, code, source, compilable }] }
+ *
+ * Name resolution mirrors `get_symbol`:
+ *   - dotted paths (`ProForm.Item`) resolve through a module's memberMap
+ *   - flat names (`Button`) resolve directly
+ *   - unknown names return `{ examples: [], note, hint }`
+ *
+ * The example bodies live in `examples.generated.json` (content-hashed). The
+ * per-symbol references (in `symbol.examples`) are hydrated against that
+ * payload at request time.
+ */
+
+const VALID_SOURCES = ['all', 'readme', 'stories', 'canonical'];
+const DEFAULT_LIMIT = 3;
+const LOCAL_PREFIX = '$local:';
+
+function validateInput(input) {
+  const args = input && typeof input === 'object' ? input : {};
+  if (typeof args.name !== 'string' || args.name.trim().length === 0) {
+    throw new Error('get_examples: `name` must be a non-empty string');
+  }
+  const source = args.source ?? 'all';
+  if (!VALID_SOURCES.includes(source)) {
+    throw new Error(
+      `get_examples: invalid source '${source}', expected one of ${VALID_SOURCES.join(', ')}`,
+    );
+  }
+  const limit =
+    typeof args.limit === 'number' && Number.isFinite(args.limit) && args.limit > 0
+      ? Math.floor(args.limit)
+      : DEFAULT_LIMIT;
+  return { name: args.name.trim(), source, limit };
+}
+
+function buildByName(index) {
+  const byName = new Map();
+  for (const sym of index.symbols) {
+    byName.set(sym.name, sym);
+  }
+  return byName;
+}
+
+/** Resolve a dotted-path lookup against a module's memberMap. */
+function resolveDotted(inputName, byName) {
+  const dotIdx = inputName.indexOf('.');
+  const ownerName = inputName.slice(0, dotIdx);
+  const memberKey = inputName.slice(dotIdx + 1);
+  const owner = byName.get(ownerName);
+  if (!owner || owner.kind !== 'module' || !owner.memberMap) return null;
+  const target = owner.memberMap[memberKey];
+  if (typeof target !== 'string') return null;
+  if (target.startsWith(LOCAL_PREFIX)) {
+    return { internal: true, ownerName };
+  }
+  return byName.get(target) ?? null;
+}
+
+function hintForMissing(name) {
+  if (/^Icons\.[A-Z]/.test(name)) {
+    return 'Icon names are string keys, not exported symbols. Use `<Icons name="chevronDown" />` (camelCase) and call `list_icons` for names.';
+  }
+  if (/^use[A-Z]/.test(name)) {
+    return 'This hook may live in `@1money/hooks`, not `@1money/component-ui`. Check that package.';
+  }
+  return `No exported symbol named '${name}'. Use search_symbols to discover candidates.`;
+}
+
+export default function getExamples(input, ctx) {
+  const { name, source, limit } = validateInput(input);
+  const { index, examplesIndex } = ctx ?? {};
+  if (!index || !Array.isArray(index.symbols)) {
+    throw new Error('get_examples: context missing `index`');
+  }
+  if (!examplesIndex || typeof examplesIndex.examples !== 'object') {
+    throw new Error('get_examples: context missing `examplesIndex`');
+  }
+
+  const byName = buildByName(index);
+
+  let sym = null;
+  if (name.includes('.')) {
+    const resolved = resolveDotted(name, byName);
+    if (resolved && resolved.internal) {
+      return {
+        examples: [],
+        note: `'${name}' is an internal member of '${resolved.ownerName}'; not separately exported.`,
+      };
+    }
+    sym = resolved ?? null;
+  } else {
+    sym = byName.get(name) ?? null;
+  }
+
+  if (!sym) {
+    return { examples: [], note: hintForMissing(name) };
+  }
+
+  const refs = Array.isArray(sym.examples) ? sym.examples : [];
+  const filtered =
+    source === 'all' ? refs : refs.filter(r => r && r.source === source);
+
+  const hydrated = [];
+  for (const ref of filtered) {
+    if (!ref || typeof ref.hash !== 'string') continue;
+    const body = examplesIndex.examples[ref.hash];
+    if (!body) continue;
+    hydrated.push({
+      title: body.title,
+      code: body.code,
+      source: body.source,
+      compilable: body.compilable,
+    });
+    if (hydrated.length >= limit) break;
+  }
+
+  return { examples: hydrated };
+}

package/scripts/mcp-server/tools/get-library-info.mjs

@@ -0,0 +1,25 @@
+/* eslint-disable no-undef */
+/* eslint-env node */
+/**
+ * Tool: get_library_info
+ *
+ * Returns package metadata loaded at server startup (never per-request).
+ */
+
+export default function getLibraryInfo(_input, ctx) {
+  const { index, pkg } = ctx;
+
+  const exportsMap = (pkg && typeof pkg.exports === 'object' && pkg.exports) || {};
+  const subpathExports = Object.keys(exportsMap)
+    .filter(key => key !== '.' && key !== './index.css')
+    .sort();
+
+  return {
+    name: pkg?.name ?? null,
+    version: pkg?.version ?? null,
+    peerDependencies: pkg?.peerDependencies ?? {},
+    subpathExports,
+    cssEntry: '@1money/component-ui/index.css',
+    schemaVersion: index?.schemaVersion ?? null
+  };
+}