@react-spectrum/mcp 3.0.0-nightly-df85b152a-250928 → 3.0.0-nightly-5ede892f6-250929

package/README.md

@@ -0,0 +1,127 @@
+# @react-spectrum/mcp
+
+The `@react-spectrum/mcp` package allows you to run [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) servers for React Spectrum (S2) and React Aria locally. It exposes a set of tools that MCP clients can discover and call to browse the docs.
+
+## Using with an MCP client
+
+Add one or both servers to your MCP client configuration (the exact file and schema may depend on your client).
+
+```json
+{
+  "mcpServers": {
+    "s2-docs": {
+      "command": "npx",
+      "args": ["@react-spectrum/mcp", "s2"]
+    },
+    "react-aria-docs": {
+      "command": "npx",
+      "args": ["@react-spectrum/mcp", "react-aria"]
+    }
+  }
+}
+```
+
+<details>
+<summary>Cursor</summary>
+
+#### Click the button to install:
+
+React Spectrum (S2):
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=s2-docs&config=eyJjb21tYW5kIjoibnB4IEByZWFjdC1zcGVjdHJ1bS9tY3AgczIifQ%3D%3D)
+
+React Aria:
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=react-aria-docs&config=eyJjb21tYW5kIjoibnB4IEByZWFjdC1zcGVjdHJ1bS9tY3AgcmVhY3QtYXJpYSJ9)
+
+Or follow the MCP install [guide](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) and use the standard config above.
+
+</details>
+
+<details>
+<summary>VS Code</summary>
+
+#### Click the button to install:
+
+React Spectrum (S2):
+
+[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](vscode:mcp/install?%7B%22name%22%3A%22s2-docs%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22%40react-spectrum%2Fmcp%22%2C%22s2%22%5D%7D)
+
+React Aria:
+
+[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](vscode:mcp/install?%7B%22name%22%3A%22react-aria-docs%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22%40react-spectrum%2Fmcp%22%2C%22react-aria%22%5D%7D)
+
+
+#### Or install manually:
+
+Follow the MCP install [guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server) and use the standard config above. You can also add servers using the VS Code CLI:
+
+```bash
+# For VS Code
+code --add-mcp '{"name":"s2-docs","command":"npx","args":["@react-spectrum/mcp","s2"]}'
+code --add-mcp '{"name":"react-aria-docs","command":"npx","args":["@react-spectrum/mcp","react-aria"]}'
+```
+
+</details>
+
+<details>
+<summary>Claude Code</summary>
+
+Use the Claude Code CLI to add the servers:
+
+```bash
+claude mcp add s2-docs npx @react-spectrum/mcp s2
+claude mcp add react-aria-docs npx @react-spectrum/mcp react-aria
+```
+For more information, see the [Claude Code MCP documentation](https://docs.claude.com/en/docs/claude-code/mcp).
+</details>
+
+<details>
+<summary>Codex</summary>
+
+Create or edit the configuration file `~/.codex/config.toml` and add:
+
+```toml
+[mcp_servers.s2-docs]
+command = "npx"
+args = ["@react-spectrum/mcp", "s2"]
+
+[mcp_servers.react-aria-docs]
+command = "npx"
+args = ["@react-spectrum/mcp", "react-aria"]
+```
+
+For more information, see the [Codex MCP documentation](https://github.com/openai/codex/blob/main/docs/config.md#mcp_servers).
+
+</details>
+
+<details>
+<summary>Gemini CLI</summary>
+
+Use the Gemini CLI to add the servers:
+
+```bash
+gemini mcp add s2-docs npx @react-spectrum/mcp s2
+gemini mcp add react-aria-docs npx @react-spectrum/mcp react-aria
+```
+
+For more information, see the [Gemini CLI MCP documentation](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#how-to-set-up-your-mcp-server).
+
+</details>
+
+<details>
+<summary>Windsurf</summary>
+
+Follow Windsurf MCP [documentation](https://docs.windsurf.com/windsurf/cascade/mcp) and use the standard config above.
+
+</details>
+
+## Tools
+
+| Tool | Input | Description |
+| --- | --- | --- |
+| `list_pages` | `{ includeDescription?: boolean }` | List available pages in the selected docs library. |
+| `get_page_info` | `{ page_name: string }` | Return page description and list of section titles. |
+| `get_page` | `{ page_name: string, section_name?: string }` | Return full page markdown, or only the specified section. |
+| `search_icons` (S2 only) | `{ terms: string or string[] }` | Search S2 workflow icon names. |
+| `search_illustrations` (S2 only) | `{ terms: string or string[] }` | Search S2 illustration names. |

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@react-spectrum/mcp",
-  "version": "3.0.0-nightly-df85b152a-250928",
+  "version": "3.0.0-nightly-5ede892f6-250929",
   "description": "MCP server for React Spectrum (S2) and React Aria documentation",
   "type": "module",
   "bin": "dist/index.js",
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "node ./scripts/build-data.mjs && tsc -p tsconfig.json",
     "start": "node dist/index.js",
     "dev": "node --enable-source-maps dist/index.js"
   },

package/src/index.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import fg from 'fast-glob';
-import {fileURLToPath, pathToFileURL} from 'url';
+/// <reference types="node" />
+import {fileURLToPath} from 'url';
 import fs from 'fs';
 import {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js';
 import path from 'path';
@@ -37,110 +37,131 @@ function errorToString(err: unknown): string {
   }
 }
 
-// Resolve docs dist root based on this file location
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-const DOCS_DIST_ROOT = path.resolve(__dirname, '../../s2-docs/dist');
 
-function assertDocsExist() {
-  if (!fs.existsSync(DOCS_DIST_ROOT)) {
-    const hint = path.resolve(__dirname, '../../s2-docs/scripts/generateMarkdownDocs.mjs');
-    throw new Error(`S2 docs dist not found at ${DOCS_DIST_ROOT}. Build them first via: yarn workspace @react-spectrum/s2-docs generate:md (script: ${hint})`);
+// 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>();
 
-const ICONS_DIR = path.resolve(__dirname, '../../../@react-spectrum/s2/s2wf-icons');
 let iconIdCache: string[] | null = null;
-const ILLUSTRATIONS_DIR = path.resolve(__dirname, '../../../@react-spectrum/s2/spectrum-illustrations/linear');
 let illustrationIdCache: string[] | null = null;
 let iconAliasesCache: Record<string, string[]> | null = null;
 let illustrationAliasesCache: Record<string, string[]> | null = null;
 
-function ensureIconsExist() {
-  if (!fs.existsSync(ICONS_DIR)) {
-    throw new Error(`S2 icons directory not found at ${ICONS_DIR}`);
+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;}
-  ensureIconsExist();
-  const files = fg.sync('*.svg', {cwd: ICONS_DIR, absolute: false, suppressErrors: true});
-  const ids = Array.from(new Set(
-    files.map(f => f.replace(/\.svg$/i, '')
-      // Mirror IconPicker.tsx regex to derive the id from the filename
-      .replace(/^S2_Icon_(.*?)(Size\d+)?_2.*/, '$1'))
-  )).sort((a, b) => a.localeCompare(b));
-  iconIdCache = ids;
-  return ids;
-}
-
-function ensureIllustrationsExist() {
-  if (!fs.existsSync(ILLUSTRATIONS_DIR)) {
-    throw new Error(`S2 illustrations directory not found at ${ILLUSTRATIONS_DIR}`);
-  }
+  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;}
-  ensureIllustrationsExist();
-  // linear directory may contain multiple sizes per illustration name
-  const files = fg.sync('**/*.svg', {cwd: ILLUSTRATIONS_DIR, absolute: false, suppressErrors: true});
-  const ids = Array.from(new Set(
-    files.map(f => {
-      const base = f.replace(/\.svg$/i, '')
-        // Pattern: S2_lin_<name>_<size>
-        .replace(/^S2_lin_(.*)_\d+$/, '$1');
-      return base ? (base.charAt(0).toUpperCase() + base.slice(1)) : base;
-    })
-  )).sort((a, b) => a.localeCompare(b));
-  illustrationIdCache = ids;
-  return ids;
+  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 aliasesPath = path.resolve(__dirname, '../../s2-docs/src/iconAliases.js');
-  if (!fs.existsSync(aliasesPath)) {return iconAliasesCache = {};}
-  const mod = await import(pathToFileURL(aliasesPath).href);
-  return (iconAliasesCache = (mod.iconAliases ?? {}));
+  const bundled = readBundledJson('iconAliases.json');
+  return (iconAliasesCache = (bundled && typeof bundled === 'object') ? bundled : {});
 }
 
 async function loadIllustrationAliases(): Promise<Record<string, string[]>> {
   if (illustrationAliasesCache) {return illustrationAliasesCache;}
-  const aliasesPath = path.resolve(__dirname, '../../s2-docs/src/illustrationAliases.js');
-  if (!fs.existsSync(aliasesPath)) {return illustrationAliasesCache = {};}
-  const mod = await import(pathToFileURL(aliasesPath).href);
-  return (illustrationAliasesCache = (mod.illustrationAliases ?? {}));
+  const bundled = readBundledJson('illustrationAliases.json');
+  return (illustrationAliasesCache = (bundled && typeof bundled === 'object') ? bundled : {});
 }
 
-function readAllPagesFor(library: Library): PageInfo[] {
-  assertDocsExist();
-  const pattern = `${library}/**/*.md`;
-  const absFiles = fg.sync([pattern], {cwd: DOCS_DIST_ROOT, absolute: true, suppressErrors: true});
+// 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[] = [];
-  for (const absPath of absFiles) {
-    if (path.basename(absPath).toLowerCase() === 'llms.txt') {continue;}
-    const rel = path.relative(DOCS_DIST_ROOT, absPath);
-    const key = rel.replace(/\\/g, '/').replace(/\.md$/i, '');
-    const info = parsePage(absPath, key);
+
+  // 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);
   }
-  return pages;
+
+  pageIndexLoaded.add(library);
+  return pages.sort((a, b) => a.key.localeCompare(b.key));
 }
 
-function parsePage(absPath: string, keyFromPath?: string): PageInfo {
-  const raw = fs.readFileSync(absPath, 'utf8');
-  const lines = raw.split(/\r?\n/);
+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;
-  // Find first H1 (title)
   for (; i < lines.length; i++) {
     const line = lines[i];
     if (line.startsWith('# ')) {
@@ -150,7 +171,6 @@ function parsePage(absPath: string, keyFromPath?: string): PageInfo {
     }
   }
 
-  // Collect first paragraph as description (non-empty text until blank line)
   let descLines: string[] = [];
   let inCode = false;
   for (; i < lines.length; i++) {
@@ -160,7 +180,6 @@ function parsePage(absPath: string, keyFromPath?: string): PageInfo {
     if (line.trim() === '') {
       if (descLines.length > 0) {break;} else {continue;}
     }
-    // ignore headings and HTML-like tags if they appear before paragraph
     if (/^#{1,6}\s/.test(line) || /^</.test(line.trim())) {continue;}
     descLines.push(line);
   }
@@ -168,31 +187,26 @@ function parsePage(absPath: string, keyFromPath?: string): PageInfo {
     description = descLines.join('\n').trim();
   }
 
-  // Parse sections (## ...)
-  const sections: SectionInfo[] = [];
-  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});
-    }
-  }
-  // Compute endLine for each section as start of next section
-  for (let s = 0; s < sections.length - 1; s++) {
-    sections[s].endLine = sections[s + 1].startLine;
+  return {title, description};
+}
+
+async function ensureParsedPage(info: PageInfo): Promise<PageInfo> {
+  if (info.sections && info.sections.length > 0 && info.description !== undefined) {
+    return info;
   }
 
-  const rel = path.relative(DOCS_DIST_ROOT, absPath).replace(/\\/g, '/');
-  const key = keyFromPath ?? rel.replace(/\.md$/i, '');
-  return {key, title, description, filePath: absPath, sections};
+  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;
 }
 
-function resolvePagePathFor(library: Library, pageName: string): PageInfo {
-  // Accept keys like "s2/Button" or plain "Button" but restrict to the selected library
-  assertDocsExist();
+async function resolvePageRef(library: Library, pageName: string): Promise<PageInfo> {
+  // Ensure index is loaded
+  await buildPageIndex(library);
 
   if (pageCache.has(pageName)) {
     return pageCache.get(pageName)!;
@@ -204,27 +218,21 @@ function resolvePagePathFor(library: Library, pageName: string): PageInfo {
     if (prefix !== library) {
       throw new Error(`Page '${pageName}' is not in the '${library}' library.`);
     }
-    const abs = path.join(DOCS_DIST_ROOT, `${normalized}.md`);
-    if (!fs.existsSync(abs)) {
-      throw new Error(`Page not found: ${pageName}`);
-    }
-    const info = parsePage(abs, normalized);
-    pageCache.set(normalized, info);
-    return info;
+    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 abs = path.join(DOCS_DIST_ROOT, library, `${pageName}.md`);
-  if (!fs.existsSync(abs)) {
-    throw new Error(`Page not found in '${library}': ${pageName}`);
-  }
   const key = `${library}/${pageName}`;
-  const info = parsePage(abs, key);
-  pageCache.set(info.key, info);
-  return info;
-}
-
-function readPageContent(filePath: string): string {
-  return fs.readFileSync(filePath, 'utf8');
+  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) {
@@ -233,6 +241,13 @@ async function startServer(library: Library) {
     version: '0.1.0'
   });
 
+  // Build page index at startup.
+  try {
+    await buildPageIndex(library);
+  } catch (e) {
+    console.warn(`Warning: failed to load ${library} docs index (${errorToString(e)}).`);
+  }
+
   // list_pages tool
   server.registerTool(
     'list_pages',
@@ -242,7 +257,7 @@ async function startServer(library: Library) {
       inputSchema: {includeDescription: z.boolean().optional()}
     },
     async ({includeDescription}) => {
-      const pages = readAllPagesFor(library);
+      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});
@@ -261,7 +276,8 @@ async function startServer(library: Library) {
       inputSchema: {page_name: z.string()}
     },
     async ({page_name}) => {
-      const info = resolvePagePathFor(library, page_name);
+      const ref = await resolvePageRef(library, page_name);
+      const info = await ensureParsedPage(ref);
       const out = {
         key: info.key,
         title: info.title,
@@ -281,24 +297,26 @@ async function startServer(library: Library) {
       inputSchema: {page_name: z.string(), section_name: z.string().optional()}
     },
     async ({page_name, section_name}) => {
-      const info = resolvePagePathFor(library, page_name);
+      const ref = await resolvePageRef(library, page_name);
       let text: string;
+      text = await fetchText(ref.filePath);
+
       if (!section_name) {
-        text = readPageContent(info.filePath);
-      } else {
-        // Find section by exact title match (case-sensitive first, then case-insensitive)
-        let section = info.sections.find(s => s.name === section_name);
-        if (!section) {
-          section = info.sections.find(s => s.name.toLowerCase() === section_name.toLowerCase());
-        }
-        if (!section) {
-          const available = info.sections.map(s => s.name).join(', ');
-          throw new Error(`Section '${section_name}' not found in ${info.key}. Available: ${available}`);
-        }
-        const lines = fs.readFileSync(info.filePath, 'utf8').split(/\r?\n/);
-        text = lines.slice(section.startLine, section.endLine).join('\n');
+        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}`);
       }
-      return {content: [{type: 'text', text}]} as const;
+      const snippet = lines.slice(section.startLine, section.endLine).join('\n');
+      return {content: [{type: 'text', text: snippet}]} as const;
     }
   );
 
@@ -383,7 +401,7 @@ async function startServer(library: Library) {
 }
 
 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\nExamples:\n  npx @react-spectrum/mcp s2\n  npx @react-spectrum/mcp react-aria';
+  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);
 }