fix: refactor mcp servers into separate packages (#9061)

* refactor mcp server to be two separate servers

* update README and docs

* fix data loading

* cleanup

* improve structure

* yarn.lock

* update npx commands to use @latest

Author: reidbarber

eslint.config.mjs

@@ -59,7 +59,8 @@ export default [{
         "packages/dev/parcel-transformer-storybook/*",
         "packages/dev/storybook-builder-parcel/*",
         "packages/dev/storybook-react-parcel/*",
-        "packages/dev/s2-docs/pages/**"
+        "packages/dev/s2-docs/pages/**",
+        "packages/dev/mcp/*/dist"
     ],
 }, ...compat.extends("eslint:recommended"), {
     plugins: {

package.json

@@ -27,8 +27,8 @@
     "build:docs": "DOCS_ENV=staging parcel build 'packages/@react-{spectrum,aria,stately}/*/docs/*.mdx' 'packages/react-aria-components/docs/**/*.mdx' 'packages/@internationalized/*/docs/*.mdx' 'packages/dev/docs/pages/**/*.mdx'",
     "start:s2-docs": "yarn workspace @react-spectrum/s2-docs start",
     "build:s2-docs": "yarn workspace @react-spectrum/s2-docs build",
-    "build:mcp": "yarn workspace @react-spectrum/mcp build",
-    "start:mcp": "yarn workspace @react-spectrum/s2-docs generate:md && yarn workspace @react-spectrum/mcp build && node packages/dev/mcp/dist/index.js",
+    "build:mcp": "yarn workspace @react-spectrum/mcp build && yarn workspace @react-aria/mcp build",
+    "start:mcp": "yarn workspace @react-spectrum/s2-docs generate:md && yarn build:mcp && node packages/dev/mcp/s2/dist/index.js && node packages/dev/mcp/react-aria/dist/index.js",
     "test:mcp": "yarn build:s2-docs && yarn build:mcp && node packages/dev/mcp/scripts/smoke-list-pages.mjs",
     "test": "cross-env STRICT_MODE=1 VIRT_ON=1 yarn jest",
     "test:lint": "node packages/**/*.test-lint.js",
@@ -66,6 +66,8 @@
     "packages/react-aria",
     "packages/react-aria-components",
     "packages/tailwindcss-react-aria-components",
+    "packages/dev/mcp/s2",
+    "packages/dev/mcp/react-aria",
     "packages/*/*"
   ],
   "devDependencies": {

packages/dev/mcp/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"
+      }
+    }
+  }
+}
+```

packages/dev/mcp/react-aria/README.md

@@ -0,0 +1,41 @@
+{
+  "name": "@react-aria/mcp",
+  "version": "0.1.0",
+  "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"
+}