@react-spectrum/mcp 0.1.0 → 1.0.0

package/src/index.ts

@@ -1,420 +1,126 @@
 #!/usr/bin/env node
 /// <reference types="node" />
-import {fileURLToPath} from 'url';
-import fs from 'fs';
-import {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js';
-import path from 'path';
-import {StdioServerTransport} from '@modelcontextprotocol/sdk/server/stdio.js';
+import {errorToString} from '../../shared/src/utils.js';
+import {listIconNames, listIllustrationNames, loadIconAliases, loadIllustrationAliases, loadStyleMacroPropertyValues} from './s2-data.js';
+import type {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js';
+import {startServer} from '../../shared/src/server.js';
 import {z} from 'zod';
 
-type SectionInfo = {
-  name: string,
-  startLine: number, // 0-based index where section heading starts
-  endLine: number   // exclusive end line index for section content
-};
-
-type PageInfo = {
-  key: string,          // e.g. "s2/Button"
-  title: string,        // from top-level heading
-  description?: string, // first paragraph after title
-  filePath: string,     // absolute path to markdown file
-  sections: SectionInfo[]
-};
-
-type Library = 's2' | 'react-aria';
-
-function errorToString(err: unknown): string {
-  if (err && typeof err === 'object' && 'stack' in err && typeof (err as any).stack === 'string') {
-    return (err as any).stack as string;
-  }
-  if (err && typeof err === 'object' && 'message' in err && typeof (err as any).message === 'string') {
-    return (err as any).message as string;
-  }
-  try {
-    return JSON.stringify(err);
-  } catch {
-    return String(err);
-  }
-}
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-// CDN base for docs. Can be overridden via env variable.
-const DEFAULT_CDN_BASE = process.env.DOCS_CDN_BASE
-  ?? 'https://reactspectrum.blob.core.windows.net/reactspectrum/7d2883a56fb1a0554864b21324d405f758deb3ce/s2-docs';
-
-function libBaseUrl(library: Library) {
-  return `${DEFAULT_CDN_BASE}/${library}`;
-}
-
-async function fetchText(url: string, timeoutMs = 15000): Promise<string> {
-  const ctrl = new AbortController();
-  const id = setTimeout(() => ctrl.abort(), timeoutMs).unref?.();
-  try {
-    const res = await fetch(url, {signal: ctrl.signal, cache: 'no-store'} as any);
-    if (!res.ok) {
-      throw new Error(`HTTP ${res.status} for ${url}`);
-    }
-    return await res.text();
-  } finally {
-    clearTimeout(id as any);
-  }
-}
-
-// Cache of parsed pages
-const pageCache = new Map<string, PageInfo>();
-
-let iconIdCache: string[] | null = null;
-let illustrationIdCache: string[] | null = null;
-let iconAliasesCache: Record<string, string[]> | null = null;
-let illustrationAliasesCache: Record<string, string[]> | null = null;
-
-function readBundledJson(filename: string): any | null {
-  try {
-    const p = path.resolve(__dirname, 'data', filename); // dist/data
-    if (!fs.existsSync(p)) {return null;}
-    const txt = fs.readFileSync(p, 'utf8');
-    return JSON.parse(txt);
-  } catch {
-    return null;
-  }
-}
-
-function listIconNames(): string[] {
-  if (iconIdCache) {return iconIdCache;}
-  const bundled = readBundledJson('icons.json');
-  return (iconIdCache = Array.isArray(bundled) ? bundled.slice().sort((a, b) => a.localeCompare(b)) : []);
-}
-
-function listIllustrationNames(): string[] {
-  if (illustrationIdCache) {return illustrationIdCache;}
-  const bundled = readBundledJson('illustrations.json');
-  return (illustrationIdCache = Array.isArray(bundled) ? bundled.slice().sort((a, b) => a.localeCompare(b)) : []);
-}
-
-async function loadIconAliases(): Promise<Record<string, string[]>> {
-  if (iconAliasesCache) {return iconAliasesCache;}
-  const bundled = readBundledJson('iconAliases.json');
-  return (iconAliasesCache = (bundled && typeof bundled === 'object') ? bundled : {});
-}
-
-async function loadIllustrationAliases(): Promise<Record<string, string[]>> {
-  if (illustrationAliasesCache) {return illustrationAliasesCache;}
-  const bundled = readBundledJson('illustrationAliases.json');
-  return (illustrationAliasesCache = (bundled && typeof bundled === 'object') ? bundled : {});
-}
-
-// Whether we've loaded the page index for a library yet.
-const pageIndexLoaded = new Set<Library>();
-
-// Build a lightweight index of pages for the given library from the CDN's llms.txt.
-// Populates pageCache with stubs (title from filename; description/sections omitted).
-async function buildPageIndex(library: Library): Promise<PageInfo[]> {
-  if (pageIndexLoaded.has(library)) {
-    return Array.from(pageCache.values()).filter(p => p.key.startsWith(`${library}/`));
-  }
-
-  const pages: PageInfo[] = [];
-
-  // Read llms.txt to enumerate available pages without downloading them all.
-  const llmsUrl = `${libBaseUrl(library)}/llms.txt`;
-  const txt = await fetchText(llmsUrl);
-  const re = /^\s*-\s*\[([^\]]+)\]\(([^)]+)\)\s*$/;
-  for (const line of txt.split(/\r?\n/)) {
-    const m = line.match(re);
-    if (!m) {continue;}
-    const display = (m[1] || '').trim();
-    const href = (m[2] || '').trim();
-    if (!href || !/\.md$/i.test(href)) {continue;}
-    const key = href.replace(/\.md$/i, '').replace(/\\/g, '/');
-    const title = display || path.basename(key);
-    const url = `${DEFAULT_CDN_BASE}/${key}.md`;
-    const info: PageInfo = {key, title, description: undefined, filePath: url, sections: []};
-    pages.push(info);
-    pageCache.set(info.key, info);
-  }
-
-  pageIndexLoaded.add(library);
-  return pages.sort((a, b) => a.key.localeCompare(b.key));
-}
-
-function parseSectionsFromMarkdown(lines: string[]): SectionInfo[] {
-  const sections: SectionInfo[] = [];
-  let inCode = false;
-  for (let idx = 0; idx < lines.length; idx++) {
-    const line = lines[idx];
-    if (/^```/.test(line.trim())) {inCode = !inCode;}
-    if (inCode) {continue;}
-    if (line.startsWith('## ')) {
-      const name = line.replace(/^##\s+/, '').trim();
-      sections.push({name, startLine: idx, endLine: lines.length});
-    }
-  }
-  for (let s = 0; s < sections.length - 1; s++) {
-    sections[s].endLine = sections[s + 1].startLine;
-  }
-  return sections;
-}
-
-function extractTitleAndDescription(lines: string[]): {title: string, description?: string} {
-  let title = '';
-  let description: string | undefined = undefined;
-
-  let i = 0;
-  for (; i < lines.length; i++) {
-    const line = lines[i];
-    if (line.startsWith('# ')) {
-      title = line.replace(/^#\s+/, '').trim();
-      i++;
-      break;
-    }
-  }
-
-  let descLines: string[] = [];
-  let inCode = false;
-  for (; i < lines.length; i++) {
-    const line = lines[i];
-    if (/^```/.test(line.trim())) {inCode = !inCode;}
-    if (inCode) {continue;}
-    if (line.trim() === '') {
-      if (descLines.length > 0) {break;} else {continue;}
-    }
-    if (/^#{1,6}\s/.test(line) || /^</.test(line.trim())) {continue;}
-    descLines.push(line);
-  }
-  if (descLines.length > 0) {
-    description = descLines.join('\n').trim();
-  }
-
-  return {title, description};
-}
-
-async function ensureParsedPage(info: PageInfo): Promise<PageInfo> {
-  if (info.sections && info.sections.length > 0 && info.description !== undefined) {
-    return info;
-  }
-
-  const text = await fetchText(info.filePath);
-  const lines = text.split(/\r?\n/);
-  const {title, description} = extractTitleAndDescription(lines);
-  const sections = parseSectionsFromMarkdown(lines);
-  const updated = {...info, title: title || info.title, description, sections};
-  pageCache.set(updated.key, updated);
-  return updated;
-}
-
-async function resolvePageRef(library: Library, pageName: string): Promise<PageInfo> {
-  // Ensure index is loaded
-  await buildPageIndex(library);
-
-  if (pageCache.has(pageName)) {
-    return pageCache.get(pageName)!;
-  }
-
-  if (pageName.includes('/')) {
-    const normalized = pageName.replace(/\\/g, '/');
-    const prefix = normalized.split('/', 1)[0];
-    if (prefix !== library) {
-      throw new Error(`Page '${pageName}' is not in the '${library}' library.`);
-    }
-    const maybe = pageCache.get(normalized);
-    if (maybe) {return maybe;}
-    const filePath = `${DEFAULT_CDN_BASE}/${normalized}.md`;
-    const stub: PageInfo = {key: normalized, title: path.basename(normalized), description: undefined, filePath, sections: []};
-    pageCache.set(stub.key, stub);
-    return stub;
-  }
-
-  const key = `${library}/${pageName}`;
-  const maybe = pageCache.get(key);
-  if (maybe) {return maybe;}
-  const filePath = `${DEFAULT_CDN_BASE}/${key}.md`;
-  const stub: PageInfo = {key, title: pageName, description: undefined, filePath, sections: []};
-  pageCache.set(stub.key, stub);
-  return stub;
-}
-
-async function startServer(library: Library) {
-  const server = new McpServer({
-    name: library === 's2' ? 's2-docs-server' : 'react-aria-docs-server',
-    version: '0.1.0'
-  });
-
-  // Build page index at startup.
+// CLI entry for S2
+(async () => {
   try {
-    await buildPageIndex(library);
-  } catch (e) {
-    console.warn(`Warning: failed to load ${library} docs index (${errorToString(e)}).`);
-  }
-
-  // list_pages tool
-  server.registerTool(
-    'list_pages',
-    {
-      title: library === 's2' ? 'List React Spectrum (@react-spectrum/s2) docs pages' : 'List React Aria docs pages',
-      description: `Returns a list of available pages in the ${library} docs.`,
-      inputSchema: {includeDescription: z.boolean().optional()}
-    },
-    async ({includeDescription}) => {
-      const pages = await buildPageIndex(library);
-      const items = pages
-        .sort((a, b) => a.key.localeCompare(b.key))
-        .map(p => includeDescription ? {key: p.key, title: p.title, description: p.description ?? ''} : {key: p.key, title: p.title});
-      return {
-        content: [{type: 'text', text: JSON.stringify(items, null, 2)}]
-      };
-    }
-  );
-
-  // get_page_info tool
-  server.registerTool(
-    'get_page_info',
-    {
-      title: 'Get page info',
-      description: 'Returns page description and list of sections for a given page.',
-      inputSchema: {page_name: z.string()}
-    },
-    async ({page_name}) => {
-      const ref = await resolvePageRef(library, page_name);
-      const info = await ensureParsedPage(ref);
-      const out = {
-        key: info.key,
-        title: info.title,
-        description: info.description ?? '',
-        sections: info.sections.map(s => s.name)
-      };
-      return {content: [{type: 'text', text: JSON.stringify(out, null, 2)}]};
-    }
-  );
-
-  // get_page tool
-  server.registerTool(
-    'get_page',
-    {
-      title: 'Get page markdown',
-      description: 'Returns the full markdown content for a page, or a specific section if provided.',
-      inputSchema: {page_name: z.string(), section_name: z.string().optional()}
-    },
-    async ({page_name, section_name}) => {
-      const ref = await resolvePageRef(library, page_name);
-      let text: string;
-      text = await fetchText(ref.filePath);
-
-      if (!section_name) {
-        return {content: [{type: 'text', text}]} as const;
-      }
-
-      const lines = text.split(/\r?\n/);
-      const sections = parseSectionsFromMarkdown(lines);
-      let section = sections.find(s => s.name === section_name);
-      if (!section) {
-        section = sections.find(s => s.name.toLowerCase() === section_name.toLowerCase());
-      }
-      if (!section) {
-        const available = sections.map(s => s.name).join(', ');
-        throw new Error(`Section '${section_name}' not found in ${ref.key}. Available: ${available}`);
-      }
-      const snippet = lines.slice(section.startLine, section.endLine).join('\n');
-      return {content: [{type: 'text', text: snippet}]} as const;
+    const arg = (process.argv[2] || '').trim();
+    if (arg === '--help' || arg === '-h' || arg === 'help') {
+      console.log('Usage: npx @react-spectrum/mcp@latest\n\nStarts the MCP server for React Spectrum (S2) documentation.');
+      process.exit(0);
     }
-  );
 
-  if (library === 's2') {
-    // search_icons tool
-    server.registerTool(
-      'search_icons',
-      {
-        title: 'Search S2 icons',
-        description: 'Searches the S2 workflow icon set by one or more terms; returns matching icon names.',
-        inputSchema: {terms: z.union([z.string(), z.array(z.string())])}
-      },
-      async ({terms}) => {
-        const allNames = listIconNames();
-        const nameSet = new Set(allNames);
-        const aliases = await loadIconAliases();
-        const rawTerms = Array.isArray(terms) ? terms : [terms];
-        const normalized = Array.from(new Set(rawTerms.map(t => String(t ?? '').trim().toLowerCase()).filter(Boolean)));
-        if (normalized.length === 0) {
-          throw new Error('Provide at least one non-empty search term.');
-        }
-        // direct name matches
-        const results = new Set(allNames.filter(name => {
-          const nameLower = name.toLowerCase();
-          return normalized.some(term => nameLower.includes(term));
-        }));
-        // alias matches
-        for (const [aliasKey, targets] of Object.entries(aliases)) {
-          if (!targets || targets.length === 0) {continue;}
-          const aliasLower = aliasKey.toLowerCase();
-          if (normalized.some(term => aliasLower.includes(term) || term.includes(aliasLower))) {
-            for (const t of targets) {
-              const n = String(t);
-              if (nameSet.has(n)) {results.add(n);}
+    await startServer('s2', '0.1.0', (server: McpServer) => {
+      server.registerTool(
+        'search_s2_icons',
+        {
+          title: 'Search S2 icons',
+          description: 'Searches the S2 workflow icon set by one or more terms; returns matching icon names.',
+          inputSchema: {terms: z.union([z.string(), z.array(z.string())])}
+        },
+        async ({terms}) => {
+          const allNames = listIconNames();
+          const nameSet = new Set(allNames);
+          const aliases = await loadIconAliases();
+          const rawTerms = Array.isArray(terms) ? terms : [terms];
+          const normalized = Array.from(new Set(rawTerms.map(t => String(t ?? '').trim().toLowerCase()).filter(Boolean)));
+          if (normalized.length === 0) {
+            throw new Error('Provide at least one non-empty search term.');
+          }
+          // direct name matches
+          const results = new Set(allNames.filter(name => {
+            const nameLower = name.toLowerCase();
+            return normalized.some(term => nameLower.includes(term));
+          }));
+          // alias matches
+          for (const [aliasKey, targets] of Object.entries(aliases)) {
+            if (!targets || targets.length === 0) {continue;}
+            const aliasLower = aliasKey.toLowerCase();
+            if (normalized.some(term => aliasLower.includes(term) || term.includes(aliasLower))) {
+              for (const t of targets) {
+                const n = String(t);
+                if (nameSet.has(n)) {results.add(n);}
+              }
             }
           }
+          return {content: [{type: 'text', text: JSON.stringify(Array.from(results).sort((a, b) => a.localeCompare(b)), null, 2)}]};
         }
-        return {content: [{type: 'text', text: JSON.stringify(Array.from(results).sort((a, b) => a.localeCompare(b)), null, 2)}]};
-      }
-    );
-
-    // search_illustrations tool
-    server.registerTool(
-      'search_illustrations',
-      {
-        title: 'Search S2 illustrations',
-        description: 'Searches the S2 illustrations set by one or more terms; returns matching illustration names.',
-        inputSchema: {terms: z.union([z.string(), z.array(z.string())])}
-      },
-      async ({terms}) => {
-        const allNames = listIllustrationNames();
-        const nameSet = new Set(allNames);
-        const aliases = await loadIllustrationAliases();
-        const rawTerms = Array.isArray(terms) ? terms : [terms];
-        const normalized = Array.from(new Set(rawTerms.map(t => String(t ?? '').trim().toLowerCase()).filter(Boolean)));
-        if (normalized.length === 0) {
-          throw new Error('Provide at least one non-empty search term.');
-        }
-        // direct name matches
-        const results = new Set(allNames.filter(name => {
-          const nameLower = name.toLowerCase();
-          return normalized.some(term => nameLower.includes(term));
-        }));
-        // alias matches
-        for (const [aliasKey, targets] of Object.entries(aliases)) {
-          if (!targets || targets.length === 0) {continue;}
-          const aliasLower = aliasKey.toLowerCase();
-          if (normalized.some(term => aliasLower.includes(term) || term.includes(aliasLower))) {
-            for (const t of targets) {
-              const n = String(t);
-              if (nameSet.has(n)) {results.add(n);}
+      );
+
+      server.registerTool(
+        'search_s2_illustrations',
+        {
+          title: 'Search S2 illustrations',
+          description: 'Searches the S2 illustrations set by one or more terms; returns matching illustration names.',
+          inputSchema: {terms: z.union([z.string(), z.array(z.string())])}
+        },
+        async ({terms}) => {
+          const allNames = listIllustrationNames();
+          const nameSet = new Set(allNames);
+          const aliases = await loadIllustrationAliases();
+          const rawTerms = Array.isArray(terms) ? terms : [terms];
+          const normalized = Array.from(new Set(rawTerms.map(t => String(t ?? '').trim().toLowerCase()).filter(Boolean)));
+          if (normalized.length === 0) {
+            throw new Error('Provide at least one non-empty search term.');
+          }
+          // direct name matches
+          const results = new Set(allNames.filter(name => {
+            const nameLower = name.toLowerCase();
+            return normalized.some(term => nameLower.includes(term));
+          }));
+          // alias matches
+          for (const [aliasKey, targets] of Object.entries(aliases)) {
+            if (!targets || targets.length === 0) {continue;}
+            const aliasLower = aliasKey.toLowerCase();
+            if (normalized.some(term => aliasLower.includes(term) || term.includes(aliasLower))) {
+              for (const t of targets) {
+                const n = String(t);
+                if (nameSet.has(n)) {results.add(n);}
+              }
             }
           }
+          return {content: [{type: 'text', text: JSON.stringify(Array.from(results).sort((a, b) => a.localeCompare(b)), null, 2)}]};
         }
-        return {content: [{type: 'text', text: JSON.stringify(Array.from(results).sort((a, b) => a.localeCompare(b)), null, 2)}]};
-      }
-    );
-  }
+      );
+
+      server.registerTool(
+        'get_style_macro_property_values',
+        {
+          title: 'Get style macro property values',
+          description: 'Returns the allowed values for a given S2 style macro property (including expanded color/spacing value lists where applicable).',
+          inputSchema: {propertyName: z.string()}
+        },
+        async ({propertyName}) => {
+          const name = String(propertyName ?? '').trim();
+          if (!name) {
+            throw new Error('Provide a non-empty propertyName.');
+          }
 
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-}
+          const all = loadStyleMacroPropertyValues();
+          let def = all[name];
+          if (!def) {
+            // fallback to case-insensitive lookup
+            const lower = name.toLowerCase();
+            const matchKey = Object.keys(all).find(k => k.toLowerCase() === lower);
+            if (matchKey) {
+              def = all[matchKey];
+            }
+          }
 
-function printUsage() {
-  const usage = 'Usage: mcp <subcommand>\n\nSubcommands:\n  s2           Start MCP server for React Spectrum S2 docs\n  react-aria   Start MCP server for React Aria docs\n\nEnvironment:\n\nExamples:\n  npx @react-spectrum/mcp s2\n  npx @react-spectrum/mcp react-aria';
-  console.log(usage);
-}
+          if (!def) {
+            const available = Object.keys(all).sort((a, b) => a.localeCompare(b));
+            throw new Error(`Unknown style macro property '${name}'. Available properties: ${available.join(', ')}`);
+          }
 
-// CLI entry
-(async () => {
-  try {
-    const arg = (process.argv[2] || '').trim();
-    if (arg === '--help' || arg === '-h' || arg === 'help') {
-      printUsage();
-      process.exit(0);
-    }
-    const library: Library = arg === 'react-aria' ? 'react-aria' : 's2';
-    await startServer(library);
+          return {content: [{type: 'text', text: JSON.stringify(def, null, 2)}]};
+        }
+      );
+    });
   } catch (err) {
     console.error(errorToString(err));
     process.exit(1);

package/src/s2-data.ts

@@ -0,0 +1,57 @@
+import {fileURLToPath} from 'url';
+import fs from 'fs';
+import path from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+let iconIdCache: string[] | null = null;
+let illustrationIdCache: string[] | null = null;
+let iconAliasesCache: Record<string, string[]> | null = null;
+let illustrationAliasesCache: Record<string, string[]> | null = null;
+let styleMacroPropertyValuesCache: Record<string, {values: string[], additionalTypes?: string[]}> | null = null;
+
+function readBundledJson(filename: string): any | null {
+  try {
+    // Go up from s2/src/ to dist/, then to data/
+    const p = path.resolve(__dirname, '..', '..', 'data', filename);
+    if (!fs.existsSync(p)) {return null;}
+    const txt = fs.readFileSync(p, 'utf8');
+    return JSON.parse(txt);
+  } catch {
+    return null;
+  }
+}
+
+export function listIconNames(): string[] {
+  if (iconIdCache) {return iconIdCache;}
+  const bundled = readBundledJson('icons.json');
+  return (iconIdCache = Array.isArray(bundled) ? bundled.slice().sort((a, b) => a.localeCompare(b)) : []);
+}
+
+export function listIllustrationNames(): string[] {
+  if (illustrationIdCache) {return illustrationIdCache;}
+  const bundled = readBundledJson('illustrations.json');
+  return (illustrationIdCache = Array.isArray(bundled) ? bundled.slice().sort((a, b) => a.localeCompare(b)) : []);
+}
+
+export async function loadIconAliases(): Promise<Record<string, string[]>> {
+  if (iconAliasesCache) {return iconAliasesCache;}
+  const bundled = readBundledJson('iconAliases.json');
+  return (iconAliasesCache = (bundled && typeof bundled === 'object') ? bundled : {});
+}
+
+export async function loadIllustrationAliases(): Promise<Record<string, string[]>> {
+  if (illustrationAliasesCache) {return illustrationAliasesCache;}
+  const bundled = readBundledJson('illustrationAliases.json');
+  return (illustrationAliasesCache = (bundled && typeof bundled === 'object') ? bundled : {});
+}
+
+export function loadStyleMacroPropertyValues(): Record<string, {values: string[], additionalTypes?: string[]}> {
+  if (styleMacroPropertyValuesCache) {return styleMacroPropertyValuesCache;}
+  const bundled = readBundledJson('styleMacroPropertyValues.json');
+  if (!bundled || typeof bundled !== 'object' || Array.isArray(bundled)) {
+    return (styleMacroPropertyValuesCache = {});
+  }
+  return (styleMacroPropertyValuesCache = bundled as any);
+}