storybook-addon-playwright-mcp 0.0.0

package/README.md

@@ -0,0 +1,111 @@
+# storybook-addon-playwright-mcp
+
+A local **stdio MCP server** that teaches AI coding assistants how to author
+visual/screenshot regression tests for the
+[`storybook-addon-playwright`](../README.md) addon.
+
+It is intentionally scoped: the server description tells the assistant to
+consult it **only** when the user asks to _add a story screenshot / visual test_
+or _generate Playwright screenshots_ — not on every Storybook or Playwright task.
+
+## What it knows
+
+- The `*.stories.playwright.json` action-file **format and naming convention**
+  (same base name, same folder as the story file).
+- How to build **action sets** and the full **action catalog** (searchable).
+- **Selector strategy** — prefer `data-slot` / `data-testid` / `id`.
+- **Screenshot sizing** — prefer focused `takeElementScreenshot` captures, and
+  the `options.offset` inset for trimming unwanted edges.
+- How screenshot **images are generated** (addon panel, tRPC endpoint, or the
+  visual test suite).
+
+## Tools
+
+| Tool                             | Purpose                                                             |
+| -------------------------------- | ------------------------------------------------------------------- |
+| `get_screenshot_authoring_guide` | Workflow + conventions. Start here. Optional `topic` for a section. |
+| `list_playwright_actions`        | List actions grouped by category.                                   |
+| `search_playwright_actions`      | Rank actions by relevance for a query.                              |
+| `get_playwright_action`          | Full detail + example for one action.                               |
+| `get_example_playwright_json`    | A complete example action file.                                     |
+
+## How it ships
+
+This folder is **source only**; it is not published as its own npm package.
+The addon's `tsup` build bundles [`src/cli.ts`](src/cli.ts) into
+`dist/mcp/cli.mjs`, which the root `storybook-addon-playwright` package exposes
+as a second bin:
+
+```jsonc
+// package.json (root)
+"bin": {
+  "storybook-addon-playwright": "./dist/cli.js",       // the addon's existing CLI (untouched)
+  "storybook-addon-playwright-mcp": "./dist/mcp/cli.mjs" // this MCP server
+}
+```
+
+So installing `storybook-addon-playwright` in a project makes the
+`storybook-addon-playwright-mcp` bin available — no separate install, published
+by the same release pipeline.
+
+## Usage (in a consuming project)
+
+Once `storybook-addon-playwright` is installed, register the server with your MCP
+client **in that project**. `npx` resolves the bin from the project's
+`node_modules/.bin` — there is no `storybook-addon-playwright-mcp` package on
+npm, so it must resolve locally:
+
+```jsonc
+{
+  "mcpServers": {
+    "storybook-playwright-screenshots": {
+      "command": "npx",
+      "args": ["storybook-addon-playwright-mcp"],
+    },
+  },
+}
+```
+
+For Claude Code (project scope, so the server starts in the project root):
+
+```bash
+claude mcp add -s project storybook-playwright-screenshots -- npx storybook-addon-playwright-mcp
+```
+
+### Troubleshooting
+
+`connection closed: initialize response` at startup means the bin was not
+resolved locally and `npx` fell back to the registry, where the name 404s.
+Causes and fixes:
+
+- **Registered in user/global scope** (or the client starts servers outside the
+  project) → re-register in project scope, or use an absolute path:
+  `node /abs/path/to/project/node_modules/storybook-addon-playwright/dist/mcp/cli.mjs`.
+- **Working inside this repo** (a package does not link its own bins under
+  pnpm) → point at the build output: `node <repo>/dist/mcp/cli.mjs`
+  (run `pnpm build` first).
+- **Really need it standalone** → name the owning package:
+  `npx -y -p storybook-addon-playwright storybook-addon-playwright-mcp`. Never
+  `npx -y storybook-addon-playwright-mcp` — that resolves to a nonexistent
+  package.
+
+## Development
+
+This folder's dependencies (`@modelcontextprotocol/sdk`, `zod`, `vitest`, `tsx`,
+`typescript`) are all present at the repo root, so **no separate install is
+needed** — run the checks from the repo root:
+
+```bash
+pnpm exec tsc --noEmit -p mcp/tsconfig.json          # typecheck
+pnpm exec vitest run --config mcp/vitest.config.ts   # tests (incl. schema-sync)
+pnpm exec tsx mcp/src/cli.ts                          # run the server over stdio
+```
+
+CI runs the typecheck + tests via the "MCP server checks" step. The
+[`schema-sync`](test/schema-sync.test.ts) test fails the build if
+[`src/data/actions.ts`](src/data/actions.ts) drifts from the addon's generated
+action schema (`src/api/server/data/action-schema.json`, produced from the
+`PlaywrightPage` interface).
+
+The production bin is produced by the root build (`pnpm build` at the repo
+root → `dist/mcp/cli.mjs`).

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "storybook-addon-playwright-mcp",
+  "version": "0.0.0",
+  "type": "module",
+  "description": "Source for the MCP server shipped as the `storybook-addon-playwright-mcp` bin of the storybook-addon-playwright package. Not published on its own — the addon's tsup build bundles mcp/src/cli.ts into dist/mcp/cli.mjs.",
+  "license": "MIT",
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --run --passWithNoTests",
+    "test:watch": "vitest --watch"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.7.0",
+    "tsx": "^4.21.0",
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.6"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { startServer } from './server.js';
+
+function readVersion(): string {
+  // Resolves to the storybook-addon-playwright package.json in both layouts:
+  //   dev  : mcp/src/cli.ts        -> ../../package.json (repo root)
+  //   built: dist/mcp/cli.mjs      -> ../../package.json (installed package root)
+  try {
+    const pkgUrl = new URL('../../package.json', import.meta.url);
+    const pkg = JSON.parse(readFileSync(pkgUrl, 'utf8')) as { version?: string };
+    return pkg.version ?? '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+await startServer(readVersion());

package/src/content.ts

@@ -0,0 +1,84 @@
+import type { ActionRegistry, Guide, PlaywrightAction } from './types.js';
+import { actions } from './data/actions.js';
+import { exampleExplanation, exampleFile, exampleFileName } from './data/example.js';
+import { guides } from './data/guides.js';
+
+const JSON_INDENT = 2;
+
+/** Action catalog keyed by action name. */
+export const actionRegistry: ActionRegistry = Object.fromEntries(
+  actions.map((action) => [action.name, action]),
+);
+
+/** Every guide keyed by its topic id. */
+const guideById: Record<string, Guide> = Object.fromEntries(
+  guides.map((guide) => [guide.id, guide]),
+);
+
+/** Valid `topic` values for the authoring-guide tool. */
+export const guideTopics: readonly string[] = guides.map((guide) => guide.id);
+
+/** Look up a single action by its exact name. */
+export function getAction(name: string): PlaywrightAction | undefined {
+  return Object.hasOwn(actionRegistry, name) ? actionRegistry[name] : undefined;
+}
+
+/** Group action names by category for the list tool. */
+export function listActionsByCategory(): Record<string, string[]> {
+  const grouped: Record<string, string[]> = {};
+
+  for (const action of actions) {
+    (grouped[action.category] ??= []).push(action.name);
+  }
+
+  for (const names of Object.values(grouped)) {
+    names.sort((a, b) => a.localeCompare(b));
+  }
+
+  return grouped;
+}
+
+const guideIndex = guides.map((guide) => `- \`${guide.id}\` — ${guide.title}`).join('\n');
+
+/**
+ * Build the markdown response for the authoring-guide tool.
+ *
+ * - no topic  → overview + workflow + an index of the remaining topics;
+ * - `all`     → every guide concatenated;
+ * - a topic   → that single guide;
+ * - unknown   → an error listing the valid topics.
+ */
+export function getGuideText(topic?: string): { text: string; isError?: boolean } {
+  if (!topic) {
+    const overview = guideById.overview?.body ?? '';
+    const workflow = guideById.workflow?.body ?? '';
+
+    return {
+      text: `${overview}\n\n---\n\n${workflow}\n\n---\n\n## More topics\n\nCall this tool again with a \`topic\` for detail:\n\n${guideIndex}`,
+    };
+  }
+
+  if (topic === 'all') {
+    return {
+      text: guides.map((guide) => guide.body).join('\n\n---\n\n'),
+    };
+  }
+
+  const guide = guideById[topic];
+
+  if (!guide) {
+    return {
+      isError: true,
+      text: `Unknown topic "${topic}". Valid topics: ${guideTopics.join(', ')}, all.`,
+    };
+  }
+
+  return { text: guide.body };
+}
+
+/** Build the markdown response for the example tool. */
+export function getExampleText(): string {
+  const json = JSON.stringify(exampleFile, null, JSON_INDENT);
+
+  return `# Example: \`${exampleFileName}\`\n\n\`\`\`json\n${json}\n\`\`\`\n\n${exampleExplanation}`;
+}