[WIP] docs: create .mcpb bundles for the MCP servers

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

@@ -109,6 +109,10 @@ Follow Windsurf MCP [documentation](https://docs.windsurf.com/windsurf/cascade/m
 | `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. |
 
+## Privacy Policy
+
+See [Adobe's privacy policy](https://www.adobe.com/privacy/policy.html).
+
 ## Development
 
 ### Testing locally
@@ -135,4 +139,12 @@ Update your MCP client configuration to use the local MCP server:
     }
   }
 }
+```
+
+## Bundling
+
+To build an [MCP Bundle (MCPB)](https://github.com/modelcontextprotocol/mcpb), run:
+
+```bash
+yarn workspace @react-spectrum/s2-docs generate:mcpb
 ```

packages/dev/mcp/react-aria/src/index.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /// <reference types="node" />
-import {errorToString} from '../../shared/src/utils.js';
+import {errorToString, readPackageVersion} from '../../shared/src/utils.js';
 import {startServer} from '../../shared/src/server.js';
 
 // CLI entry for React Aria
@@ -11,7 +11,7 @@ import {startServer} from '../../shared/src/server.js';
       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');
+    await startServer('react-aria', readPackageVersion(import.meta.url));
   } catch (err) {
     console.error(errorToString(err));
     process.exit(1);

packages/dev/mcp/s2/README.md

@@ -111,6 +111,10 @@ Follow Windsurf MCP [documentation](https://docs.windsurf.com/windsurf/cascade/m
 | `search_s2_icons` | `{ terms: string \| string[] }` | Search S2 workflow icon names. |
 | `search_s2_illustrations` | `{ terms: string \| string[] }` | Search S2 illustration names. |
 
+## Privacy Policy
+
+See [Adobe's privacy policy](https://www.adobe.com/privacy/policy.html).
+
 ## Development
 
 ### Testing locally
@@ -137,4 +141,12 @@ Update your MCP client configuration to use the local MCP server:
     }
   }
 }
+```
+
+## Bundling
+
+To build an [MCP Bundle (MCPB)](https://github.com/modelcontextprotocol/mcpb), run:
+
+```bash
+yarn workspace @react-spectrum/s2-docs generate:mcpb
 ```

packages/dev/mcp/s2/src/index.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /// <reference types="node" />
-import {errorToString} from '../../shared/src/utils.js';
+import {errorToString, readPackageVersion} 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';
@@ -15,13 +15,14 @@ import {z} from 'zod';
       process.exit(0);
     }
 
-    await startServer('s2', '0.1.0', (server: McpServer) => {
+    await startServer('s2', readPackageVersion(import.meta.url), (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())])}
+          inputSchema: {terms: z.union([z.string(), z.array(z.string())])},
+          annotations: {readOnlyHint: true}
         },
         async ({terms}) => {
           const allNames = listIconNames();
@@ -57,7 +58,8 @@ import {z} from 'zod';
         {
           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())])}
+          inputSchema: {terms: z.union([z.string(), z.array(z.string())])},
+          annotations: {readOnlyHint: true}
         },
         async ({terms}) => {
           const allNames = listIllustrationNames();
@@ -93,7 +95,8 @@ import {z} from 'zod';
         {
           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()}
+          inputSchema: {propertyName: z.string()},
+          annotations: {readOnlyHint: true}
         },
         async ({propertyName}) => {
           const name = String(propertyName ?? '').trim();

packages/dev/mcp/shared/src/server.ts

@@ -30,7 +30,8 @@ export async function startServer(
     {
       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()}
+      inputSchema: {includeDescription: z.boolean().optional()},
+      annotations: {readOnlyHint: true}
     },
     async ({includeDescription}) => {
       const pages = await buildPageIndex(library);
@@ -48,7 +49,8 @@ export async function startServer(
     {
       title: 'Get page info',
       description: 'Returns page description and list of sections for a given page.',
-      inputSchema: {page_name: z.string()}
+      inputSchema: {page_name: z.string()},
+      annotations: {readOnlyHint: true}
     },
     async ({page_name}) => {
       const ref = await resolvePageRef(library, page_name);
@@ -67,7 +69,8 @@ export async function startServer(
     {
       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()}
+      inputSchema: {page_name: z.string(), section_name: z.string().optional()},
+      annotations: {readOnlyHint: true}
     },
     async ({page_name, section_name}) => {
       const ref = await resolvePageRef(library, page_name);

packages/dev/mcp/shared/src/utils.ts

@@ -1,3 +1,24 @@
+import {dirname, join} from 'path';
+import {fileURLToPath} from 'url';
+import {readFileSync} from 'fs';
+
+// Resolves the version from the nearest package.json above the CLI entry point.
+// Both the npm-published layout (dist/<lib>/src/index.js) and the .mcpb bundle
+// layout (server/<lib>/src/index.js) place package.json three levels up.
+export function readPackageVersion(entryUrl: string): string {
+  const entryDir = dirname(fileURLToPath(entryUrl));
+  const pkgPath = join(entryDir, '..', '..', '..', 'package.json');
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    if (typeof pkg.version === 'string' && pkg.version.length > 0) {
+      return pkg.version;
+    }
+  } catch {
+    // fall through
+  }
+  return '0.0.0';
+}
+
 export 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;

packages/dev/s2-docs/package.json

@@ -10,7 +10,8 @@
     "build:s2": "LIBRARY=s2 parcel build 'pages/s2/**/*.mdx' --config .parcelrc-s2-docs --dist-dir dist/s2 --cache-dir ../../../.parcel-cache/s2",
     "build:react-aria": "LIBRARY=react-aria parcel build 'pages/react-aria/**/*.mdx' --config .parcelrc-s2-docs --dist-dir dist/react-aria --cache-dir ../../../.parcel-cache/react-aria",
     "generate:og": "node scripts/generateOGImages.mjs",
-    "generate:md": "node scripts/generateMarkdownDocs.mjs"
+    "generate:md": "node scripts/generateMarkdownDocs.mjs",
+    "generate:mcpb": "node scripts/generateMcpb.mjs"
   },
   "targets": {
     "react-static": {
@@ -71,6 +72,7 @@
     "vanilla-starter": "../../../starters/docs/src"
   },
   "devDependencies": {
+    "@anthropic-ai/mcpb": "^2.1.2",
     "axe-playwright": "^2.2.2",
     "playwright": "^1.57.0"
   },

packages/dev/s2-docs/pages/s2/ai.mdx

@@ -121,4 +121,4 @@ Add the `.md` extension to the URL to get the markdown version of a page. Additi
 
 ## llms.txt
 
-The <Link href="llms.txt" target="_blank">llms.txt</Link> file contains a list of all the markdown pages available in the React Spectrum documentation.
+The <Link href="llms.txt" target="_blank">llms.txt</Link> file contains a list of all the markdown pages available in the React Spectrum documentation.