@react-aria/mcp 3.0.0-nightly-46eb0efb5-251114

package/README.md

@@ -0,0 +1,138 @@
+# @react-aria/mcp
+
+The `@react-aria/mcp` package provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) server for React Aria documentation. It exposes a set of tools that MCP clients can discover and call to browse the docs.
+
+## Installation
+
+### Quick Start
+
+Simply run the server using npx:
+
+```bash
+npx @react-aria/mcp@latest
+```
+
+### Using with an MCP client
+
+Add the server to your MCP client configuration (the exact file and schema may depend on your client).
+
+```json
+{
+  "mcpServers": {
+    "React Aria": {
+      "command": "npx",
+      "args": ["@react-aria/mcp@latest"]
+    }
+  }
+}
+```
+
+<details>
+<summary>Cursor</summary>
+
+#### Click the button to install:
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=React%20Aria&config=eyJjb21tYW5kIjoibnB4IEByZWFjdC1hcmlhL21jcEBsYXRlc3QifQ%3D%3D)
+
+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:
+
+[<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%20Aria%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22%40react-aria%2Fmcp%40latest%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 the server using the VS Code CLI:
+
+```bash
+code --add-mcp '{"name":"React Aria","command":"npx","args":["@react-aria/mcp@latest"]}'
+```
+
+</details>
+
+<details>
+<summary>Claude Code</summary>
+
+Use the Claude Code CLI to add the server:
+
+```bash
+claude mcp add react-aria npx @react-aria/mcp@latest
+```
+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.react-aria]
+command = "npx"
+args = ["@react-aria/mcp@latest"]
+```
+
+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 server:
+
+```bash
+gemini mcp add react-aria npx @react-aria/mcp@latest
+```
+
+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_react_aria_pages` | `{ includeDescription?: boolean }` | List available pages in the React Aria docs. |
+| `get_react_aria_page_info` | `{ page_name: string }` | Return page description and list of section titles. |
+| `get_react_aria_page` | `{ page_name: string, section_name?: string }` | Return full page markdown, or only the specified section. |
+
+## Development
+
+### Testing locally
+
+Build the docs and MCP server locally, then start the docs server.
+
+```bash
+yarn workspace @react-spectrum/s2-docs generate:md
+yarn workspace @react-aria/mcp build
+yarn start:s2-docs
+```
+
+Update your MCP client configuration to use the local MCP server:
+
+```json
+{
+  "mcpServers": {
+    "React Aria": {
+      "command": "node",
+      "args": ["{your path here}/react-spectrum/packages/dev/mcp/react-aria/dist/index.js"],
+      "env": {
+        "DOCS_CDN_BASE": "http://localhost:1234"
+      }
+    }
+  }
+}
+```

package/dist/react-aria/src/index.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/// <reference types="node" />
+import { errorToString } from '../../shared/src/utils.js';
+import { startServer } from '../../shared/src/server.js';
+// CLI entry for React Aria
+(async () => {
+    try {
+        const arg = (process.argv[2] || '').trim();
+        if (arg === '--help' || arg === '-h' || arg === 'help') {
+            console.log('Usage: npx @react-aria/mcp@latest\n\nStarts the MCP server for React Aria documentation.');
+            process.exit(0);
+        }
+        await startServer('react-aria', '0.1.0');
+    }
+    catch (err) {
+        console.error(errorToString(err));
+        process.exit(1);
+    }
+})();

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

@@ -0,0 +1,41 @@
+{
+  "name": "@react-aria/mcp",
+  "version": "3.0.0-nightly-46eb0efb5-251114",
+  "description": "MCP server for React Aria documentation",
+  "type": "module",
+  "bin": "dist/react-aria/src/index.js",
+  "scripts": {
+    "prepublishOnly": "yarn build",
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/react-aria/src/index.js",
+    "dev": "node --enable-source-maps dist/react-aria/src/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.3",
+    "@swc/helpers": "^0.5.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.2"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/adobe/react-spectrum"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "main": "dist/main.js",
+  "module": "dist/module.js",
+  "types": "dist/types.d.ts",
+  "source": "src/index.ts"
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/// <reference types="node" />
+import {errorToString} from '../../shared/src/utils.js';
+import {startServer} from '../../shared/src/server.js';
+
+// CLI entry for React Aria
+(async () => {
+  try {
+    const arg = (process.argv[2] || '').trim();
+    if (arg === '--help' || arg === '-h' || arg === 'help') {
+      console.log('Usage: npx @react-aria/mcp@latest\n\nStarts the MCP server for React Aria documentation.');
+      process.exit(0);
+    }
+    await startServer('react-aria', '0.1.0');
+  } catch (err) {
+    console.error(errorToString(err));
+    process.exit(1);
+  }
+})();