Merge pull request #11 from storybookjs/improve-instructions

Improve UI Building instructions

Author: JReinhold

.changeset/loose-cobras-cheat.md

@@ -0,0 +1,6 @@
+---
+"@storybook/addon-mcp": patch
+---
+
+- Improved UI Building Instructions
+- Improved output format of Get Story URLs tool

.mcp.json

@@ -5,4 +5,4 @@
       "url": "http://localhost:6006/mcp"
     }
   }
-}
+}

.storybook/main.ts

@@ -13,6 +13,9 @@ const config = defineMain({
   addons: ["@storybook/addon-docs", import.meta.resolve("../dist/preset.js")],
   framework: "@storybook/react-vite",
   logLevel: "debug",
+  core: {
+    disableTelemetry: true,
+  },
 });
 
 export default config;

package.json

@@ -30,7 +30,7 @@
     "build-storybook": "storybook build",
     "build:watch": "pnpm run build -- --watch",
     "changeset": "changeset",
-    "inspect": "mcp-inspector --config .mcp.json",
+    "inspect": "mcp-inspector --transport streamable-http --server-url http://localhost:6006/mcp",
     "release": "pnpm run build && pnpm changeset publish",
     "start": "run-p build:watch \"storybook --quiet\"",
     "storybook": "storybook dev --port 6006 --loglevel debug",

src/mcp-handler.ts

@@ -52,7 +52,7 @@ async function createMcpServer(options: Options, client: string) {
   });
 
   registerStoryUrlsTool({ server, options });
-  registerUIBuildingTool(server);
+  registerUIBuildingTool({ server, options });
 
   server.connect(transport);
   return transport;

src/tools/get-story-urls.ts

@@ -96,12 +96,10 @@ export function registerStoryUrlsTool({
       });
 
       return {
-        content: [
-          {
-            type: "text",
-            text: result.length > 1 ? `- ${result.join("\n- ")}` : result[0]!,
-          },
-        ],
+        content: result.map((text) => ({
+          type: "text",
+          text,
+        })),
         // Note: Claude Code seems to ignore structuredContent at the moment https://github.com/anthropics/claude-code/issues/4427
         structuredContent: { urls: result },
       };

src/tools/get-ui-building-instructions.ts

@@ -1,47 +1,17 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { GET_STORY_URLS_TOOL_NAME } from "./get-story-urls";
 import { collectTelemetry } from "../telemetry";
+import uiInstructionsTemplate from "../ui-building-instructions.md";
+import type { Options } from "storybook/internal/types";
+import { logger } from "storybook/internal/node-logger";
 
-const INSTRUCTIONS = `
-  # Writing User Interfaces Components
-
-  When writing UI components, 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.
-
-  When writing stories, use CSF3 importing types from '@storybook/nextjs-vite'. Here is a simple example:
-
-  \`\`\`ts
-  import { Meta, StoryObj } from '@storybook/nextjs-vite';
-
-  import { Break } from './Break';
-
-  type Story = StoryObj<typeof Break>;
-
-  const meta: Meta<typeof Break> = {
-    component: Break,
-    args: {},
-  };
-
-  export default meta;
-
-  export const Horizontal: Story = {
-    args: {
-      orientation: 'horizontal',
-    },
-  };
-  \`\`\`
-
-  ALWAYS provide story links after any changes to stories files, including changes to existing stories.
-  After changing any UI components, ALWAYS search for related stories that might cover the changes you've made.
-  If you find any, provide the story links to the user. THIS IS VERY IMPORTANT, as it allows the user
-  to visually inspect the modifications you've made.
-  Even later in a session when changing UI components or stories that have already been linked to previously, YOU MUST PROVIDE THE LINKS AGAIN.
-  Use the ${GET_STORY_URLS_TOOL_NAME} tool /and provide links in the format \`[Story Name](<story_url_from_tool>)\`
-  whenever you create, modify, or update any story file.
-`;
-
-export function registerUIBuildingTool(server: McpServer) {
+export function registerUIBuildingTool({
+  server,
+  options,
+}: {
+  server: McpServer;
+  options: Options;
+}) {
   server.registerTool(
     "get_ui_building_instructions",
     {
@@ -57,9 +27,53 @@ export function registerUIBuildingTool(server: McpServer) {
         event: "tool:getUIBuildingInstructions",
         mcpSessionId: sessionId!,
       });
+
+      const frameworkPreset = await options.presets.apply("framework");
+      const framework =
+        typeof frameworkPreset === "string"
+          ? frameworkPreset
+          : frameworkPreset?.name;
+      const renderer = frameworkToRendererMap[framework!];
+
+      if (!framework || !renderer) {
+        logger.debug("Unable to determine framework or renderer", {
+          frameworkPreset,
+          framework,
+          renderer,
+        });
+      }
+
+      const uiInstructions = uiInstructionsTemplate
+        .replace("{{FRAMEWORK}}", framework)
+        .replace("{{RENDERER}}", renderer ?? framework)
+        .replace("{{GET_STORY_URLS_TOOL_NAME}}", GET_STORY_URLS_TOOL_NAME);
+
       return {
-        content: [{ type: "text", text: INSTRUCTIONS }],
+        content: [{ type: "text", text: uiInstructions }],
       };
     },
   );
 }
+
+// TODO: this is a stupid map to maintain and it's not complete, but we can't easily get the current renderer name
+const frameworkToRendererMap: Record<string, string> = {
+  "@storybook/react-vite": "@storybook/react",
+  "@storybook/react-webpack5": "@storybook/react",
+  "@storybook/nextjs": "@storybook/react",
+  "@storybook/nextjs-vite": "@storybook/react",
+  "@storybook/react-native-web-vite": "@storybook/react",
+
+  "@storybook/vue3-vite": "@storybook/vue3",
+  "@nuxtjs/storybook": "@storybook/vue3",
+
+  "@storybook/angular": "@storybook/angular",
+
+  "@storybook/svelte-vite": "@storybook/svelte",
+  "@storybook/sveltekit": "@storybook/svelte",
+
+  "@storybook/preact-vite": "@storybook/preact",
+
+  "@storybook/web-components-vite": "@storybook/web-components",
+
+  "@storybook/html-vite": "@storybook/html",
+};

src/types.d.ts

@@ -0,0 +1,4 @@
+declare module "*.md" {
+  const content: string;
+  export default content;
+}

src/ui-building-instructions.md

@@ -0,0 +1,93 @@
+# Storybook 9 Essential Changes for Story Writing
+
+## Package Consolidation
+
+### `Meta` and `StoryObj` imports
+
+Update story imports to use the framework package:
+
+```diff
+- import { Meta, StoryObj } from '{{RENDERER}}';
++ import { Meta, StoryObj } from '{{FRAMEWORK}}';
+```
+
+### Test utility imports
+
+Update test imports to use `storybook/test` instead of `@storybook/test`
+
+```diff
+- import { fn } from '@storybook/test';
++ import { fn } from 'storybook/test';
+```
+
+## Global State Changes
+
+The `globals` annotation has be renamed to `initialGlobals`:
+
+```diff
+// .storybook/preview.js
+export default {
+- globals: { theme: 'light' }
++ initialGlobals: { theme: 'light' }
+};
+```
+
+## Autodocs Configuration
+
+Instead of `parameters.docs.autodocs` in main.js, use tags:
+
+```js
+// .storybook/preview.js or in individual stories
+export default {
+  tags: ["autodocs"], // generates autodocs for all stories
+};
+```
+
+## Mocking imports in Storybook
+
+To mock imports in Storybook, use Storybook's mocking features. ALWAYS mock external dependencies to ensure stories render consistently.
+
+1. **Register in the mock in Storybook's preview file**:
+   To mock dependendencies, you MUST register a module mock in `.storybook/preview.ts` (or equivalent):
+
+```js
+import { sb } from "storybook/test";
+
+// Full mock (replaces with empty fn functions)
+sb.mock(import("some-library"));
+```
+
+2. **Specify mock values in stories**:
+   You can override the behaviour of the mocks per-story using `beforeEach` and the `mocked()` type function:
+
+```js
+import { expect, mocked, fn } from 'storybook/test';
+import { library } from 'some-library';
+
+const meta = {
+  component: AuthButton,
+  beforeEach: async () => {
+    mocked(library).mockResolvedValue({  user: 'data' });
+  },
+};
+
+export const LoggedIn: Story = {
+  play: async ({ canvas }) => {
+    await expect(library).toHaveBeenCalled();
+  },
+};
+```
+
+Before doing this ensure you have mocked the import in the preview file.
+
+## Key Requirements
+
+- **Node.js 20+**, **TypeScript 4.9+**, **Vite 5+**
+- React Native uses `.rnstorybook` directory
+- `afterEach` hook is now stable (was `experimental_afterEach`)
+
+# Story Linking Agent Behavior
+
+- ALWAYS provide story links after any changes to stories files, including changes to existing stories.
+- After changing any UI components, ALWAYS search for related stories that might cover the changes you've made. If you find any, provide the story links to the user. THIS IS VERY IMPORTANT, as it allows the user to visually inspect the changes you've made. Even later in a session when changing UI components or stories that have already been linked to previously, YOU MUST PROVIDE THE LINKS AGAIN.
+- Use the {{GET_STORY_URLS_TOOL_NAME}} tool to get the correct URLs for links to stories.

tsconfig.json

@@ -17,7 +17,8 @@
     "noImplicitAny": true,
     "lib": ["esnext", "dom", "dom.iterable"],
     "baseUrl": ".",
-    "rootDir": "./src"
+    "rootDir": "./src",
+    "types": ["./src/types.d.ts"]
   },
   "include": ["src/**/*", "tsup.config.ts"]
 }