@react-spectrum/mcp 0.1.0 → 1.0.0

package/dist/s2/src/index.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/// <reference types="node" />
+import { errorToString } from '../../shared/src/utils.js';
+import { listIconNames, listIllustrationNames, loadIconAliases, loadIllustrationAliases, loadStyleMacroPropertyValues } from './s2-data.js';
+import { startServer } from '../../shared/src/server.js';
+import { z } from 'zod';
+// CLI entry for S2
+(async () => {
+    try {
+        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);
+        }
+        await startServer('s2', '0.1.0', (server) => {
+            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) }] };
+            });
+            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) }] };
+            });
+            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 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];
+                    }
+                }
+                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(', ')}`);
+                }
+                return { content: [{ type: 'text', text: JSON.stringify(def, null, 2) }] };
+            });
+        });
+    }
+    catch (err) {
+        console.error(errorToString(err));
+        process.exit(1);
+    }
+})();

package/dist/s2/src/s2-data.js

@@ -0,0 +1,62 @@
+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 = null;
+let illustrationIdCache = null;
+let iconAliasesCache = null;
+let illustrationAliasesCache = null;
+let styleMacroPropertyValuesCache = null;
+function readBundledJson(filename) {
+    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() {
+    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() {
+    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() {
+    if (iconAliasesCache) {
+        return iconAliasesCache;
+    }
+    const bundled = readBundledJson('iconAliases.json');
+    return (iconAliasesCache = (bundled && typeof bundled === 'object') ? bundled : {});
+}
+export async function loadIllustrationAliases() {
+    if (illustrationAliasesCache) {
+        return illustrationAliasesCache;
+    }
+    const bundled = readBundledJson('illustrationAliases.json');
+    return (illustrationAliasesCache = (bundled && typeof bundled === 'object') ? bundled : {});
+}
+export function loadStyleMacroPropertyValues() {
+    if (styleMacroPropertyValuesCache) {
+        return styleMacroPropertyValuesCache;
+    }
+    const bundled = readBundledJson('styleMacroPropertyValues.json');
+    if (!bundled || typeof bundled !== 'object' || Array.isArray(bundled)) {
+        return (styleMacroPropertyValuesCache = {});
+    }
+    return (styleMacroPropertyValuesCache = bundled);
+}

package/dist/shared/src/page-manager.js

@@ -0,0 +1,83 @@
+import { DEFAULT_CDN_BASE, fetchText } from './utils.js';
+import { extractNameAndDescription, parseSectionsFromMarkdown } from './parser.js';
+import path from 'path';
+// Cache of parsed pages
+const pageCache = new Map();
+// Whether we've loaded the page index for a library yet.
+const pageIndexLoaded = new Set();
+function libBaseUrl(library) {
+    return `${DEFAULT_CDN_BASE}/${library}`;
+}
+// Build an index of pages for the given library from the CDN's llms.txt.
+export async function buildPageIndex(library) {
+    if (pageIndexLoaded.has(library)) {
+        return Array.from(pageCache.values()).filter(p => p.key.startsWith(`${library}/`));
+    }
+    const pages = [];
+    // 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*:\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();
+        const description = (m[3] || '').trim() || undefined;
+        if (!href || !/\.md$/i.test(href)) {
+            continue;
+        }
+        const key = href.replace(/\.md$/i, '').replace(/\\/g, '/');
+        const name = display || path.basename(key);
+        const filePath = `${DEFAULT_CDN_BASE}/${key}.md`;
+        const info = { key, name, description, filePath, sections: [] };
+        pages.push(info);
+        pageCache.set(info.key, info);
+    }
+    pageIndexLoaded.add(library);
+    return pages.sort((a, b) => a.key.localeCompare(b.key));
+}
+export async function ensureParsedPage(info) {
+    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 { name, description } = extractNameAndDescription(lines);
+    const sections = parseSectionsFromMarkdown(lines);
+    const updated = { ...info, name: name || info.name, description, sections };
+    pageCache.set(updated.key, updated);
+    return updated;
+}
+export async function resolvePageRef(library, pageName) {
+    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 = { key: normalized, name: 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 = { key, name: pageName, description: undefined, filePath, sections: [] };
+    pageCache.set(stub.key, stub);
+    return stub;
+}

package/dist/shared/src/parser.js

@@ -0,0 +1,61 @@
+export function parseSectionsFromMarkdown(lines) {
+    const sections = [];
+    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;
+}
+export function extractNameAndDescription(lines) {
+    let name = '';
+    let description = undefined;
+    let i = 0;
+    for (; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.startsWith('# ')) {
+            name = line.replace(/^#\s+/, '').trim();
+            i++;
+            break;
+        }
+    }
+    let descLines = [];
+    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 { name, description };
+}

package/dist/shared/src/server.js

@@ -0,0 +1,76 @@
+import { buildPageIndex, ensureParsedPage, resolvePageRef } from './page-manager.js';
+import { errorToString, fetchText } from './utils.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { parseSectionsFromMarkdown } from './parser.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+export async function startServer(library, version, registerAdditionalTools) {
+    const server = new McpServer({
+        name: library === 's2' ? 's2-docs-server' : 'react-aria-docs-server',
+        version
+    });
+    // Build page index at startup.
+    try {
+        await buildPageIndex(library);
+    }
+    catch (e) {
+        console.warn(`Warning: failed to load ${library} docs index (${errorToString(e)}).`);
+    }
+    const toolPrefix = library === 's2' ? 's2' : 'react_aria';
+    server.registerTool(`list_${toolPrefix}_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 ? { name: p.name, description: p.description ?? '' } : { name: p.name });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(items, null, 2) }]
+        };
+    });
+    server.registerTool(`get_${toolPrefix}_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 = {
+            name: info.name,
+            description: info.description ?? '',
+            sections: info.sections.map(s => s.name)
+        };
+        return { content: [{ type: 'text', text: JSON.stringify(out, null, 2) }] };
+    });
+    server.registerTool(`get_${toolPrefix}_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;
+        text = await fetchText(ref.filePath);
+        if (!section_name) {
+            return { content: [{ type: 'text', text }] };
+        }
+        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 }] };
+    });
+    if (registerAdditionalTools) {
+        await registerAdditionalTools(server);
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/shared/src/types.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/src/utils.js

@@ -0,0 +1,30 @@
+export function errorToString(err) {
+    if (err && typeof err === 'object' && 'stack' in err && typeof err.stack === 'string') {
+        return err.stack;
+    }
+    if (err && typeof err === 'object' && 'message' in err && typeof err.message === 'string') {
+        return err.message;
+    }
+    try {
+        return JSON.stringify(err);
+    }
+    catch {
+        return String(err);
+    }
+}
+// CDN base for docs. Can be overridden via env variable.
+export const DEFAULT_CDN_BASE = process.env.DOCS_CDN_BASE ?? 'https://react-spectrum.adobe.com/beta';
+export async function fetchText(url, timeoutMs = 15000) {
+    const ctrl = new AbortController();
+    const id = setTimeout(() => ctrl.abort(), timeoutMs).unref?.();
+    try {
+        const res = await fetch(url, { signal: ctrl.signal, cache: 'no-store' });
+        if (!res.ok) {
+            throw new Error(`HTTP ${res.status} for ${url}`);
+        }
+        return await res.text();
+    }
+    finally {
+        clearTimeout(id);
+    }
+}

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@react-spectrum/mcp",
-  "version": "0.1.0",
-  "description": "MCP server for React Spectrum (S2) and React Aria documentation",
+  "version": "1.0.0",
+  "description": "MCP server for React Spectrum (S2) documentation",
   "type": "module",
-  "bin": "dist/index.js",
+  "bin": "dist/s2/src/index.js",
   "scripts": {
     "prepublishOnly": "yarn build",
     "build": "node ./scripts/build-data.mjs && tsc -p tsconfig.json",
-    "start": "node dist/index.js",
-    "dev": "node --enable-source-maps dist/index.js"
+    "start": "node dist/s2/src/index.js",
+    "dev": "node --enable-source-maps dist/s2/src/index.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.17.3",
@@ -30,10 +30,6 @@
     "type": "git",
     "url": "https://github.com/adobe/react-spectrum"
   },
-  "main": "dist/main.js",
-  "module": "dist/module.js",
-  "types": "dist/types.d.ts",
-  "source": "src/index.ts",
   "files": [
     "dist",
     "src"
@@ -41,5 +37,9 @@
   "sideEffects": [
     "*.css"
   ],
-  "gitHead": "0bda51183baa23306342af32a82012ea0fe0f2dc"
+  "main": "dist/main.js",
+  "module": "dist/module.js",
+  "types": "dist/types.d.ts",
+  "source": "src/index.ts",
+  "gitHead": "4d838da5bfe36abb35aed166995a9ef63825370f"
 }