@react-spectrum/mcp 1.1.0 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @react-spectrum/mcp
 
-The `@react-spectrum/mcp` package provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) server for React Spectrum (S2) documentation. It exposes a set of tools that MCP clients can discover and call to browse the docs, search for icons and illustrations, and more.
+The `@react-spectrum/mcp` package provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) server for React Spectrum (S2) documentation. It exposes a set of tools that MCP clients can discover and call to browse the docs, search for icons and illustrations, and more. It also bundles the React Aria docs tools, so you can browse React Aria documentation from the same server.
 
 ## Installation
 
@@ -110,6 +110,14 @@ Follow Windsurf MCP [documentation](https://docs.windsurf.com/windsurf/cascade/m
 | `get_s2_page` | `{ page_name: string, section_name?: string }` | Return full page markdown, or only the specified section. |
 | `search_s2_icons` | `{ terms: string \| string[] }` | Search S2 workflow icon names. |
 | `search_s2_illustrations` | `{ terms: string \| string[] }` | Search S2 illustration names. |
+| `get_style_macro_property_values` | `{ propertyName: string }` | Return allowed values for an S2 style macro property. |
+| `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. |
+
+## Privacy Policy
+
+See [Adobe's privacy policy](https://www.adobe.com/privacy/policy.html).
 
 ## Development
 
@@ -137,4 +145,19 @@ Update your MCP client configuration to use the local MCP server:
     }
   }
 }
+```
+
+## Bundling
+
+To build an [MCP Bundle (MCPB)](https://github.com/modelcontextprotocol/mcpb), first prepare the staging directory:
+
+```bash
+yarn workspace @react-spectrum/s2-docs generate:mcpb
+```
+
+Then validate and pack using the [`@anthropic-ai/mcpb`](https://www.npmjs.com/package/@anthropic-ai/mcpb) CLI (paths are printed by the script above):
+
+```bash
+npx @anthropic-ai/mcpb validate <staging-dir>
+npx @anthropic-ai/mcpb pack <staging-dir> <output-path>
 ```

package/dist/data/styleMacroPropertyValues.json

@@ -3926,7 +3926,7 @@
       "auto",
       "square",
       "video",
-      "number / number"
+      "${number}/${number}"
     ],
     "additionalTypes": []
   },

package/dist/data/styleProperties.json

@@ -870,7 +870,7 @@
       "auto",
       "square",
       "video",
-      "number / number"
+      "${number}/${number}"
     ],
     "additionalTypes": [],
     "links": {

package/dist/s2/src/index.js

@@ -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 { startServer } from '../../shared/src/server.js';
 import { z } from 'zod';
@@ -12,102 +12,130 @@ import { z } from 'zod';
             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;
+        await startServer('s2', readPackageVersion(import.meta.url), {
+            additionalLibraries: ['react-aria'],
+            registerAdditionalTools: (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())]) },
+                    annotations: { readOnlyHint: true, openWorldHint: true }
+                }, 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.');
                     }
-                    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);
+                    // 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;
+                    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())]) },
+                    annotations: { readOnlyHint: true, openWorldHint: true }
+                }, 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.');
                     }
-                    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);
+                    // 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];
+                    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() },
+                    annotations: { readOnlyHint: true, openWorldHint: true }
+                }, 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(', ')}`);
                     }
-                }
-                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) }] };
-            });
+                    return { content: [{ type: 'text', text: JSON.stringify(def, null, 2) }] };
+                });
+            }
         });
     }
     catch (err) {

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

@@ -27,28 +27,32 @@ export function listIconNames() {
         return iconIdCache;
     }
     const bundled = readBundledJson('icons.json');
-    return (iconIdCache = Array.isArray(bundled) ? bundled.slice().sort((a, b) => a.localeCompare(b)) : []);
+    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)) : []);
+    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 : {});
+    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 : {});
+    return (illustrationAliasesCache = bundled && typeof bundled === 'object' ? bundled : {});
 }
 export function loadStyleMacroPropertyValues() {
     if (styleMacroPropertyValuesCache) {

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

@@ -67,7 +67,13 @@ export async function resolvePageRef(library, pageName) {
             return maybe;
         }
         const filePath = `${baseUrl}/${normalized}.md`;
-        const stub = { key: normalized, name: path.basename(normalized), description: undefined, filePath, sections: [] };
+        const stub = {
+            key: normalized,
+            name: path.basename(normalized),
+            description: undefined,
+            filePath,
+            sections: []
+        };
         pageCache.set(stub.key, stub);
         return stub;
     }

package/dist/shared/src/server.js

@@ -4,11 +4,22 @@ 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) {
+export async function startServer(library, version, options = {}) {
     const server = new McpServer({
         name: library === 's2' ? 's2-docs-server' : 'react-aria-docs-server',
         version
     });
+    const libraries = [library, ...(options.additionalLibraries ?? [])];
+    for (const lib of libraries) {
+        await registerLibraryDocsTools(server, lib);
+    }
+    if (options.registerAdditionalTools) {
+        await options.registerAdditionalTools(server);
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+async function registerLibraryDocsTools(server, library) {
     // Build page index at startup.
     try {
         await buildPageIndex(library);
@@ -18,9 +29,12 @@ export async function startServer(library, version, registerAdditionalTools) {
     }
     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',
+        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, openWorldHint: true }
     }, async ({ includeDescription }) => {
         const pages = await buildPageIndex(library);
         const items = pages
@@ -33,7 +47,8 @@ export async function startServer(library, version, registerAdditionalTools) {
     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() }
+        inputSchema: { page_name: z.string() },
+        annotations: { readOnlyHint: true, openWorldHint: true }
     }, async ({ page_name }) => {
         const ref = await resolvePageRef(library, page_name);
         const info = await ensureParsedPage(ref);
@@ -47,7 +62,8 @@ export async function startServer(library, version, registerAdditionalTools) {
     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() }
+        inputSchema: { page_name: z.string(), section_name: z.string().optional() },
+        annotations: { readOnlyHint: true, openWorldHint: true }
     }, async ({ page_name, section_name }) => {
         const ref = await resolvePageRef(library, page_name);
         let text;
@@ -68,9 +84,4 @@ export async function startServer(library, version, registerAdditionalTools) {
         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/utils.js

@@ -1,8 +1,31 @@
+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) {
+    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) {
     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') {
+    if (err &&
+        typeof err === 'object' &&
+        'message' in err &&
+        typeof err.message === 'string') {
         return err.message;
     }
     try {

package/package.json

@@ -1,9 +1,28 @@
 {
   "name": "@react-spectrum/mcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "MCP server for React Spectrum (S2) documentation",
-  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/adobe/react-spectrum"
+  },
   "bin": "dist/s2/src/index.js",
+  "source": "src/index.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "main": "dist/main.js",
+  "module": "dist/module.js",
+  "types": "dist/types.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "prepublishOnly": "yarn build",
     "build": "node ./scripts/build-data.mjs && tsc -p tsconfig.json",
@@ -22,24 +41,5 @@
   "engines": {
     "node": ">=18"
   },
-  "license": "Apache-2.0",
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/adobe/react-spectrum"
-  },
-  "files": [
-    "dist",
-    "src"
-  ],
-  "sideEffects": [
-    "*.css"
-  ],
-  "main": "dist/main.js",
-  "module": "dist/module.js",
-  "types": "dist/types.d.ts",
-  "source": "src/index.ts",
-  "gitHead": "a6999bdf494a2e9c0381a5881908328bdd22ddae"
+  "gitHead": "3577a20859b9585a000010c720f6ee39c1c588cc"
 }

package/src/index.ts

@@ -1,7 +1,13 @@
 #!/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 {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';
 import {z} from 'zod';
@@ -11,115 +17,182 @@ import {z} from 'zod';
   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.');
+      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: 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())])}
-        },
-        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);}
+    await startServer('s2', readPackageVersion(import.meta.url), {
+      additionalLibraries: ['react-aria'],
+      registerAdditionalTools: (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())])},
+            annotations: {readOnlyHint: true, openWorldHint: true}
+          },
+          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
+                  )
+                }
+              ]
+            };
           }
-          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);}
+        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())])},
+            annotations: {readOnlyHint: true, openWorldHint: true}
+          },
+          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
+                  )
+                }
+              ]
+            };
           }
-          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.');
-          }
+        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()},
+            annotations: {readOnlyHint: true, openWorldHint: true}
+          },
+          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];
+            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(', ')}`);
-          }
+            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)}]};
-        }
-      );
+            return {content: [{type: 'text', text: JSON.stringify(def, null, 2)}]};
+          }
+        );
+      }
     });
   } catch (err) {
     console.error(errorToString(err));

package/src/s2-data.ts

@@ -9,13 +9,18 @@ let iconIdCache: string[] | null = null;
 let illustrationIdCache: string[] | null = null;
 let iconAliasesCache: Record<string, string[]> | null = null;
 let illustrationAliasesCache: Record<string, string[]> | null = null;
-let styleMacroPropertyValuesCache: Record<string, {values: string[], additionalTypes?: string[]}> | null = null;
+let styleMacroPropertyValuesCache: Record<
+  string,
+  {values: string[]; additionalTypes?: string[]}
+> | null = null;
 
 function readBundledJson(filename: string): any | null {
   try {
     // Go up from s2/src/ to dist/, then to data/
     const p = path.resolve(__dirname, '..', '..', 'data', filename);
-    if (!fs.existsSync(p)) {return null;}
+    if (!fs.existsSync(p)) {
+      return null;
+    }
     const txt = fs.readFileSync(p, 'utf8');
     return JSON.parse(txt);
   } catch {
@@ -24,31 +29,48 @@ function readBundledJson(filename: string): any | null {
 }
 
 export function listIconNames(): string[] {
-  if (iconIdCache) {return iconIdCache;}
+  if (iconIdCache) {
+    return iconIdCache;
+  }
   const bundled = readBundledJson('icons.json');
-  return (iconIdCache = Array.isArray(bundled) ? bundled.slice().sort((a, b) => a.localeCompare(b)) : []);
+  return (iconIdCache = Array.isArray(bundled)
+    ? bundled.slice().sort((a, b) => a.localeCompare(b))
+    : []);
 }
 
 export function listIllustrationNames(): string[] {
-  if (illustrationIdCache) {return illustrationIdCache;}
+  if (illustrationIdCache) {
+    return illustrationIdCache;
+  }
   const bundled = readBundledJson('illustrations.json');
-  return (illustrationIdCache = Array.isArray(bundled) ? bundled.slice().sort((a, b) => a.localeCompare(b)) : []);
+  return (illustrationIdCache = Array.isArray(bundled)
+    ? bundled.slice().sort((a, b) => a.localeCompare(b))
+    : []);
 }
 
 export async function loadIconAliases(): Promise<Record<string, string[]>> {
-  if (iconAliasesCache) {return iconAliasesCache;}
+  if (iconAliasesCache) {
+    return iconAliasesCache;
+  }
   const bundled = readBundledJson('iconAliases.json');
-  return (iconAliasesCache = (bundled && typeof bundled === 'object') ? bundled : {});
+  return (iconAliasesCache = bundled && typeof bundled === 'object' ? bundled : {});
 }
 
 export async function loadIllustrationAliases(): Promise<Record<string, string[]>> {
-  if (illustrationAliasesCache) {return illustrationAliasesCache;}
+  if (illustrationAliasesCache) {
+    return illustrationAliasesCache;
+  }
   const bundled = readBundledJson('illustrationAliases.json');
-  return (illustrationAliasesCache = (bundled && typeof bundled === 'object') ? bundled : {});
+  return (illustrationAliasesCache = bundled && typeof bundled === 'object' ? bundled : {});
 }
 
-export function loadStyleMacroPropertyValues(): Record<string, {values: string[], additionalTypes?: string[]}> {
-  if (styleMacroPropertyValuesCache) {return styleMacroPropertyValuesCache;}
+export function loadStyleMacroPropertyValues(): Record<
+  string,
+  {values: string[]; additionalTypes?: string[]}
+> {
+  if (styleMacroPropertyValuesCache) {
+    return styleMacroPropertyValuesCache;
+  }
   const bundled = readBundledJson('styleMacroPropertyValues.json');
   if (!bundled || typeof bundled !== 'object' || Array.isArray(bundled)) {
     return (styleMacroPropertyValuesCache = {});