@storybook/react-native 10.3.0-next.0 → 10.3.0-next.2

package/dist/metro/withStorybook.d.ts

@@ -42,6 +42,13 @@ interface WithStorybookOptions {
      * This will mock out the default storybook ui so you don't need to install all its dependencies like reanimated etc.
      */
     liteMode?: boolean;
+    /**
+     * Whether to enable MCP (Model Context Protocol) server support. Defaults to false.
+     * When enabled, adds an /mcp endpoint to the channel server,
+     * allowing AI agents (Claude Code, Cursor, etc.) to query component documentation.
+     * If websockets are disabled, MCP documentation tools still work but story selection is unavailable.
+     */
+    experimental_mcp?: boolean;
 }
 /**
  * Configures Metro bundler to work with Storybook in React Native.

package/dist/metro/withStorybook.js

@@ -4,6 +4,9 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
 var __commonJS = (cb, mod) => function __require() {
   return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
 };
@@ -220,7 +223,6 @@ var require_generate = __commonJS({
     directory: "${specifier.directory}",
     files: "${specifier.files}",
     importPathMatcher: /${reg.source}/,
-    ${useJs ? "" : "// @ts-ignore"}
     req: require.context(
       '${pathToStory}',
       ${r},
@@ -291,7 +293,7 @@ declare global {
 }
 `;
       const fileContent = `/* do not change this file, it is auto generated by storybook. */
-import { start, updateView${useJs ? "" : ", View, type Features"} } from '@storybook/react-native';
+${useJs ? "" : '/// <reference types="@storybook/react-native/metro-env" />\n'}import { start, updateView${useJs ? "" : ", View, type Features"} } from '@storybook/react-native';
 
 ${registeredAddons.join("\n")}
 
@@ -306,7 +308,6 @@ const annotations = ${annotations};
 globalThis.STORIES = normalizedStories;
 ${channelHost ? `globalThis.STORYBOOK_WEBSOCKET = { host: '${channelHost}', port: ${port ?? 7007} };` : ""}
 
-${useJs ? "" : "// @ts-ignore"}
 module?.hot?.accept?.();
 ${featuresAssignment ? `
 ${featuresAssignment}
@@ -336,42 +337,11 @@ export const view${useJs ? "" : ": View"} = globalThis.view;
   }
 });
 
-// src/metro/withStorybook.ts
-var withStorybook_exports = {};
-__export(withStorybook_exports, {
-  withStorybook: () => withStorybook
-});
-module.exports = __toCommonJS(withStorybook_exports);
-var path2 = __toESM(require("path"));
-var import_generate = __toESM(require_generate());
-var import_common3 = require("storybook/internal/common");
-var import_telemetry = require("storybook/internal/telemetry");
-
-// src/metro/channelServer.ts
-var import_ws = require("ws");
-var import_node_http = require("http");
-
 // src/metro/buildIndex.ts
-var import_common = require("storybook/internal/common");
-var import_node_fs = require("fs");
-var import_glob = require("glob");
-var import_path = __toESM(require("path"));
-var import_csf_tools = require("storybook/internal/csf-tools");
-var import_csf = require("storybook/internal/csf");
-var import_preview_api = require("storybook/internal/preview-api");
-var import_common2 = __toESM(require_common());
-var cwd = process.cwd();
-var makeTitle = (fileName, specifier, userTitle) => {
-  const title = (0, import_preview_api.userOrAutoTitleFromSpecifier)(fileName, specifier, userTitle);
-  if (title) {
-    return title.replace("./", "");
-  } else if (userTitle) {
-    return userTitle.replace("./", "");
-  } else {
-    console.error("Could not generate title!!");
-    process.exit(1);
-  }
-};
+var buildIndex_exports = {};
+__export(buildIndex_exports, {
+  buildIndex: () => buildIndex
+});
 function ensureRelativePathHasDot(relativePath) {
   return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
 }
@@ -459,14 +429,369 @@ async function buildIndex({ configPath }) {
     return index;
   }
 }
+var import_common, import_node_fs, import_glob, import_path, import_csf_tools, import_csf, import_preview_api, import_common2, cwd, makeTitle;
+var init_buildIndex = __esm({
+  "src/metro/buildIndex.ts"() {
+    import_common = require("storybook/internal/common");
+    import_node_fs = require("fs");
+    import_glob = require("glob");
+    import_path = __toESM(require("path"));
+    import_csf_tools = require("storybook/internal/csf-tools");
+    import_csf = require("storybook/internal/csf");
+    import_preview_api = require("storybook/internal/preview-api");
+    import_common2 = __toESM(require_common());
+    cwd = process.cwd();
+    makeTitle = (fileName, specifier, userTitle) => {
+      const title = (0, import_preview_api.userOrAutoTitleFromSpecifier)(fileName, specifier, userTitle);
+      if (title) {
+        return title.replace("./", "");
+      } else if (userTitle) {
+        return userTitle.replace("./", "");
+      } else {
+        console.error("Could not generate title!!");
+        process.exit(1);
+      }
+    };
+  }
+});
+
+// src/metro/manifest/storyInstructions.ts
+var storyInstructions_exports = {};
+__export(storyInstructions_exports, {
+  storyInstructions: () => storyInstructions
+});
+var storyInstructions;
+var init_storyInstructions = __esm({
+  "src/metro/manifest/storyInstructions.ts"() {
+    storyInstructions = `# Writing React Native UI Components
+
+When writing UI, prefer breaking larger components up into smaller parts.
+
+ALWAYS write a Storybook story for any component written. If editing a component, ensure appropriate changes have been made to stories for that component.
+
+## How to write good stories
+
+Goal: Cover every distinct piece of business logic and state the component can reach (happy paths, error/edge states, loading, permissions/roles, empty states, variations from props/context). Avoid redundant stories that show the same logic.
+
+Interactivity: For interactive components, create separate stories that demonstrate each interaction state. Use \`fn()\` from \`storybook/test\` to mock callback props so you can verify they are wired up correctly.
+
+Data/setup: Provide realistic props, state, and mocked data. Include meaningful labels/text to make behaviors observable. Stub network/services with deterministic fixtures; keep stories reliable.
+
+Variants to consider (pick only those that change behavior): default vs. alternate themes; loading vs. loaded vs. empty vs. error; validated vs. invalid input; permissions/roles/capabilities; feature flags; size/density/layout variants that alter logic.
+
+Accessibility: Use semantic roles/labels where applicable.
+
+Naming/structure: Use clear story names that describe the scenario ("Error state after failed submit"). Group related variants logically; don't duplicate.
+
+Imports/format: Import Meta/StoryObj from the framework package. Keep stories minimal\u2014only what's needed to demonstrate behavior.
+
+## React Native Storybook Essentials
+
+### Framework and Renderer
+
+React Native Storybook uses \`@storybook/react-native\` as the framework. Stories use the same CSF (Component Story Format) as web Storybook.
+
+### Meta and StoryObj imports
+
+\`\`\`ts
+import type { Meta, StoryObj } from '@storybook/react-native';
+\`\`\`
+
+### Story file structure
+
+\`\`\`tsx
+import type { Meta, StoryObj } from '@storybook/react-native';
+import { MyComponent } from './MyComponent';
+
+const meta: Meta<typeof MyComponent> = {
+  title: 'Components/MyComponent',
+  component: MyComponent,
+  args: {
+    // default args
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const WithCustomProps: Story = {
+  args: {
+    label: 'Custom Label',
+    variant: 'secondary',
+  },
+};
+\`\`\`
+
+### Global State Changes
+
+The \`globals\` annotation has been renamed to \`initialGlobals\`:
+
+\`\`\`diff
+// .rnstorybook/preview.js
+export default {
+- globals: { theme: 'light' }
++ initialGlobals: { theme: 'light' }
+};
+\`\`\`
+
+### React Native Specific Considerations
+
+- The config directory is \`.rnstorybook\` (not \`.storybook\`)
+- Stories run on-device (iOS/Android), not in a browser
+- Use React Native components (\`View\`, \`Text\`, \`Pressable\`, etc.), not HTML elements
+- \`StyleSheet\` or inline styles instead of CSS
+- No DOM APIs \u2014 use React Native's layout system (Flexbox)
+- For navigation-dependent components, mock the navigation context
+- For platform-specific stories, use \`Platform.OS\` checks or separate story files
+- Test on both iOS and Android when possible
+
+### Key Requirements
+
+- **Node.js 20+**, **TypeScript 4.9+**
+- React Native 0.72+
+- Storybook 10+
+`;
+  }
+});
+
+// src/metro/withStorybook.ts
+var withStorybook_exports = {};
+__export(withStorybook_exports, {
+  withStorybook: () => withStorybook
+});
+module.exports = __toCommonJS(withStorybook_exports);
+var path2 = __toESM(require("path"));
+var import_generate = __toESM(require_generate());
+var import_common3 = require("storybook/internal/common");
+var import_telemetry = require("storybook/internal/telemetry");
+
+// src/metro/channelServer.ts
+var import_ws = require("ws");
+var import_node_http = require("http");
+init_buildIndex();
+
+// src/metro/mcpServer.ts
+var import_consumers = require("stream/consumers");
+function toHeaderEntries(nodeHeaders) {
+  const entries = [];
+  for (const [key, value] of Object.entries(nodeHeaders)) {
+    if (value === void 0) continue;
+    entries.push([key, Array.isArray(value) ? value.join(", ") : value]);
+  }
+  return entries;
+}
+async function incomingMessageToWebRequest(req) {
+  const host = req.headers.host || "localhost";
+  const isTLS = "encrypted" in req.socket && req.socket.encrypted;
+  const protocol = isTLS ? "https" : "http";
+  const url = new URL(req.url || "/", `${protocol}://${host}`);
+  const bodyBuffer = await (0, import_consumers.buffer)(req);
+  return new Request(url, {
+    method: req.method,
+    headers: toHeaderEntries(req.headers),
+    body: bodyBuffer.length > 0 ? new Uint8Array(bodyBuffer) : void 0
+  });
+}
+async function webResponseToServerResponse(webResponse, nodeResponse) {
+  nodeResponse.statusCode = webResponse.status;
+  webResponse.headers.forEach((value, key) => {
+    nodeResponse.setHeader(key, value);
+  });
+  if (webResponse.body) {
+    const reader = webResponse.body.getReader();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        nodeResponse.write(value);
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  nodeResponse.end();
+}
+function createMcpHandler(configPath, wss) {
+  let handler = null;
+  let initPromise = null;
+  async function init() {
+    if (handler) return;
+    if (initPromise) {
+      await initPromise;
+      return;
+    }
+    initPromise = (async () => {
+      try {
+        const [
+          { McpServer },
+          { ValibotJsonSchemaAdapter },
+          { HttpTransport },
+          {
+            addListAllDocumentationTool,
+            addGetDocumentationTool,
+            addGetComponentStoryDocumentationTool
+          },
+          { storyInstructions: storyInstructions2 },
+          { buildIndex: buildIndex2 },
+          valibot,
+          { experimental_manifests }
+        ] = await Promise.all([
+          import("tmcp"),
+          import("@tmcp/adapter-valibot"),
+          import("@tmcp/transport-http"),
+          import("@storybook/mcp"),
+          Promise.resolve().then(() => (init_storyInstructions(), storyInstructions_exports)),
+          Promise.resolve().then(() => (init_buildIndex(), buildIndex_exports)),
+          import("valibot"),
+          import("@storybook/react/preset")
+        ]);
+        const manifestProvider = async (_request, manifestPath) => {
+          if (manifestPath.includes("docs.json")) {
+            throw new Error("Docs manifest not available in React Native Storybook");
+          }
+          const index = await buildIndex2({ configPath });
+          const entries = Object.values(index.entries);
+          const manifest = await experimental_manifests({}, { manifestEntries: entries });
+          return JSON.stringify(manifest.components);
+        };
+        const server = new McpServer(
+          {
+            name: "@storybook/react-native",
+            version: "1.0.0",
+            description: "Storybook React Native MCP server"
+          },
+          {
+            adapter: new ValibotJsonSchemaAdapter(),
+            capabilities: {
+              tools: { listChanged: true }
+            }
+          }
+        ).withContext();
+        addListAllDocumentationTool(server);
+        addGetDocumentationTool(server);
+        addGetComponentStoryDocumentationTool(server);
+        server.tool(
+          {
+            name: "get-storybook-story-instructions",
+            title: "React Native Storybook Story Instructions",
+            description: "Get instructions for writing React Native Storybook stories. Call this before creating or modifying story files (.stories.tsx, .stories.ts)."
+          },
+          async () => ({
+            content: [{ type: "text", text: storyInstructions2 }]
+          })
+        );
+        if (wss) {
+          const broadcastEvent = (event) => {
+            const message = JSON.stringify(event);
+            wss.clients.forEach((client) => {
+              if (client.readyState === 1) {
+                client.send(message);
+              }
+            });
+          };
+          server.tool(
+            {
+              name: "select-story",
+              title: "Select Story",
+              description: 'Select and display a story on the connected device. Use the story ID in the format "title--name" (e.g. "button--primary"). Use the list-all-documentation tool to discover available components and stories.',
+              schema: valibot.object({ storyId: valibot.string() })
+            },
+            async ({ storyId }) => {
+              try {
+                const index = await buildIndex2({ configPath });
+                if (!index.entries[storyId]) {
+                  const availableIds = Object.keys(index.entries).slice(0, 10);
+                  return {
+                    content: [
+                      {
+                        type: "text",
+                        text: `Story "${storyId}" not found. Available stories include: ${availableIds.join(", ")}` + (Object.keys(index.entries).length > 10 ? ", ..." : "")
+                      }
+                    ],
+                    isError: true
+                  };
+                }
+                broadcastEvent({
+                  type: "setCurrentStory",
+                  args: [{ storyId, viewMode: "story" }]
+                });
+                const entry = index.entries[storyId];
+                return {
+                  content: [
+                    {
+                      type: "text",
+                      text: `Selected story "${entry.name}" (${entry.title}) on connected devices.`
+                    }
+                  ]
+                };
+              } catch (error) {
+                return {
+                  content: [
+                    {
+                      type: "text",
+                      text: `Failed to select story: ${error instanceof Error ? error.message : String(error)}`
+                    }
+                  ],
+                  isError: true
+                };
+              }
+            }
+          );
+        }
+        const transport = new HttpTransport(server, { path: null });
+        handler = (req) => transport.respond(req, {
+          request: req,
+          manifestProvider
+        });
+        console.log("[Storybook] MCP server initialized");
+      } catch (error) {
+        initPromise = null;
+        console.error("[Storybook] Failed to initialize MCP server:", error);
+        throw error;
+      }
+    })();
+    await initPromise;
+  }
+  async function handleMcpRequest(req, res) {
+    try {
+      await init();
+      if (!handler) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "MCP handler not initialized" }));
+        return;
+      }
+      const webRequest = await incomingMessageToWebRequest(req);
+      const webResponse = await handler(webRequest);
+      await webResponseToServerResponse(webResponse, res);
+    } catch (error) {
+      console.error("[Storybook] MCP request failed:", error);
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "MCP request failed" }));
+    }
+  }
+  function preInit() {
+    init().catch(
+      (e) => console.warn("[Storybook] MCP pre-initialization failed (will retry on first request):", e)
+    );
+  }
+  return { handleMcpRequest, preInit };
+}
 
 // src/metro/channelServer.ts
 function createChannelServer({
   port = 7007,
   host = void 0,
-  configPath
+  configPath,
+  experimental_mcp = false,
+  websockets = true
 }) {
-  const httpServer = (0, import_node_http.createServer)(async (req, res) => {
+  const httpServer = (0, import_node_http.createServer)();
+  const wss = websockets ? new import_ws.WebSocketServer({ server: httpServer }) : null;
+  const mcpServer = experimental_mcp ? createMcpHandler(configPath, wss ?? void 0) : null;
+  httpServer.on("request", async (req, res) => {
     if (req.method === "OPTIONS") {
       res.writeHead(204);
       res.end();
@@ -485,6 +810,11 @@ function createChannelServer({
       return;
     }
     if (req.method === "POST" && req.url === "/send-event") {
+      if (!wss) {
+        res.writeHead(503, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ success: false, error: "WebSockets are disabled" }));
+        return;
+      }
       let body = "";
       req.on("data", (chunk) => {
         body += chunk.toString();
@@ -503,31 +833,36 @@ function createChannelServer({
       });
       return;
     }
+    if (mcpServer && req.url === "/mcp" && (req.method === "POST" || req.method === "GET")) {
+      await mcpServer.handleMcpRequest(req, res);
+      return;
+    }
     res.writeHead(404, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ error: "Not found" }));
   });
-  const wss = new import_ws.WebSocketServer({ server: httpServer });
-  wss.on("error", () => {
-  });
-  setInterval(function ping() {
-    wss.clients.forEach(function each(client) {
-      if (client.readyState === import_ws.WebSocket.OPEN) {
-        client.send(JSON.stringify({ type: "ping", args: [] }));
-      }
+  if (wss) {
+    wss.on("error", () => {
     });
-  }, 1e4);
-  wss.on("connection", function connection(ws) {
-    console.log("WebSocket connection established");
-    ws.on("error", console.error);
-    ws.on("message", function message(data) {
-      try {
-        const json = JSON.parse(data.toString());
-        wss.clients.forEach((wsClient) => wsClient.send(JSON.stringify(json)));
-      } catch (error) {
-        console.error(error);
-      }
+    setInterval(function ping() {
+      wss.clients.forEach(function each(client) {
+        if (client.readyState === import_ws.WebSocket.OPEN) {
+          client.send(JSON.stringify({ type: "ping", args: [] }));
+        }
+      });
+    }, 1e4);
+    wss.on("connection", function connection(ws) {
+      console.log("WebSocket connection established");
+      ws.on("error", console.error);
+      ws.on("message", function message(data) {
+        try {
+          const json = JSON.parse(data.toString());
+          wss.clients.forEach((wsClient) => wsClient.send(JSON.stringify(json)));
+        } catch (error) {
+          console.error(error);
+        }
+      });
     });
-  });
+  }
   httpServer.on("error", (error) => {
     if (error.code === "EADDRINUSE") {
       console.warn(
@@ -538,8 +873,10 @@ function createChannelServer({
     }
   });
   httpServer.listen(port, host, () => {
-    console.log(`WebSocket server listening on ${host ?? "localhost"}:${port}`);
+    const protocol = wss ? "WebSocket" : "HTTP";
+    console.log(`${protocol} server listening on ${host ?? "localhost"}:${port}`);
   });
+  mcpServer?.preInit();
   return wss;
 }
 
@@ -557,7 +894,8 @@ function withStorybook(config, options = {
     useJs = false,
     enabled = true,
     docTools = true,
-    liteMode = false
+    liteMode = false,
+    experimental_mcp = false
   } = options;
   const disableTelemetry = (0, import_common3.optionalEnvToBoolean)(process.env.STORYBOOK_DISABLE_TELEMETRY);
   if (!disableTelemetry && enabled) {
@@ -598,17 +936,31 @@ function withStorybook(config, options = {
       }
     };
   }
-  if (websockets) {
-    const port = websockets === "auto" ? 7007 : websockets.port ?? 7007;
-    const host = websockets === "auto" ? "auto" : websockets.host;
-    createChannelServer({ port, host: host === "auto" ? void 0 : host, configPath });
-    (0, import_generate.generate)({
+  if (websockets || experimental_mcp) {
+    const port = websockets === "auto" ? 7007 : websockets?.port ?? 7007;
+    const host = websockets === "auto" ? "auto" : websockets?.host;
+    createChannelServer({
+      port,
+      host: host === "auto" ? void 0 : host,
       configPath,
-      useJs,
-      docTools,
-      host,
-      port
+      experimental_mcp,
+      websockets: Boolean(websockets)
     });
+    if (websockets) {
+      (0, import_generate.generate)({
+        configPath,
+        useJs,
+        docTools,
+        host,
+        port
+      });
+    } else {
+      (0, import_generate.generate)({
+        configPath,
+        useJs,
+        docTools
+      });
+    }
   } else {
     (0, import_generate.generate)({
       configPath,

package/dist/node.d.ts

@@ -17,6 +17,16 @@ interface ChannelServerOptions {
      * The path to the Storybook config folder.
      */
     configPath: string;
+    /**
+     * Whether to enable MCP (Model Context Protocol) server support.
+     * When enabled, adds an /mcp endpoint.
+     */
+    experimental_mcp?: boolean;
+    /**
+     * Whether to enable WebSocket support.
+     * When false, starts only the HTTP server endpoints.
+     */
+    websockets?: boolean;
 }
 /**
  * Creates a channel server for syncing storybook instances and sending events.
@@ -24,14 +34,17 @@ interface ChannelServerOptions {
  * - WebSocket: broadcasts all received messages to all connected clients
  * - POST /send-event: sends an event to all WebSocket clients
  * - GET /index.json: returns the story index built from story files
+ * - POST /mcp: MCP endpoint for AI agent integration (when experimental_mcp option is enabled)
  *
  * @param options - Configuration options for the channel server.
  * @param options.port - The port to listen on.
  * @param options.host - The host to bind to.
  * @param options.configPath - The path to the Storybook config folder.
- * @returns The created WebSocketServer instance.
+ * @param options.experimental_mcp - Whether to enable MCP server support.
+ * @param options.websockets - Whether to enable WebSocket server support.
+ * @returns The created WebSocketServer instance, or null when websockets are disabled.
  */
-declare function createChannelServer({ port, host, configPath, }: ChannelServerOptions): WebSocketServer;
+declare function createChannelServer({ port, host, configPath, experimental_mcp, websockets, }: ChannelServerOptions): WebSocketServer | null;
 
 declare function buildIndex({ configPath }: {
     configPath: string;