@storyshelf/mcp 0.0.0-stage → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Siddhant Gupta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# @storyshelf/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP server for [StoryShelf](https://github.com/GuptaSiddhant/StoryShelf): let AI agents (Claude Code, Cursor, …) read builds, snapshot diffs, capture logs and AI triage, and comment on reviews. Read-only plus comments; approving stays a human decision.
+
+## Usage
+
+```sh
+STORYSHELF_URL=https://shelf.example.com STORYSHELF_TOKEN=... STORYSHELF_SLUG=web npx @storyshelf/mcp   # stdio
+STORYSHELF_URL=https://shelf.example.com npx @storyshelf/mcp --http --port 3333                           # HTTP at /mcp
+```
+
+The tools that read snapshots, capture logs or AI insights are advertised only when the instance has `testing` (read from `GET /api/v1/health`).
+
+Over HTTP each client sends its own `Authorization: Bearer <token>`, which is forwarded to the StoryShelf API. Or scaffold with `storyshelf mcp init`.
+
+## Tools
+
+Read tools cover projects, builds, snapshots and AI insights. The write tools are the review comments, which are `review` routes of the API:
+
+| Tool              | What it does                                                                                                                                             |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list_comments`   | Build comments, story comments and per-snapshot threads of a build.                                                                                      |
+| `add_comment`     | Adds a comment to a build, optionally anchored to a story (`storyId`) or a snapshot (`snapshotId`), or a reply. Needs a token with `developer` or above. |
+| `resolve_comment` | Marks a comment resolved.                                                                                                                                |
+
+A project with [review](https://storyshelf.js.org/guides/review/#review-without-screenshots) off has no comments: these tools fail with 404 for it. Build verdicts (`POST …/reviews`) are deliberately not exposed.
+
+Docs: https://storyshelf.js.org/ai/mcp/ · Design: `docs/adr/0017-mcp-server.md`

package/dist/capabilities.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/capabilities.ts
+/**
+* Read the instance's capabilities. An instance that does not say (an older one) or cannot be
+* reached counts as having `testing`, so no tool is hidden on a guess.
+*/
+async function probeCapabilities(client) {
+	try {
+		return { testing: (await client.get("/health")).testing !== false };
+	} catch {
+		return { testing: true };
+	}
+}
+/** The tools an instance with these capabilities serves: `testing` tools only when it has `testing`. */
+function toolsFor(tools, capabilities) {
+	return tools.filter((tool) => tool.routeClass !== "testing" || capabilities.testing);
+}
+//#endregion
+export { probeCapabilities, toolsFor };

package/dist/client.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import "node:path";
+import "node:url";
+import.meta.url;
+import { HttpError, httpJson } from "@storyshelf/core/utils";
+//#region src/client.ts
+/** Error whose message is safe to show an agent (no secrets, actionable). */
+var ToolError = class extends Error {
+	name = "ToolError";
+};
+/** Build an {@link ApiClient} that sends the configured Bearer token on every call. */
+function createApiClient(config) {
+	const headers = config.token ? { authorization: `Bearer ${config.token}` } : {};
+	const request = async (method, path, json, query) => {
+		try {
+			return await httpJson(`${config.url}/api/v1${path}${toQueryString(query)}`, {
+				method,
+				headers,
+				...json === void 0 ? {} : { json }
+			});
+		} catch (error) {
+			throw toToolError(error);
+		}
+	};
+	return {
+		defaultSlug: config.slug,
+		get: async (path, query) => await request("GET", path, void 0, query),
+		post: async (path, json) => await request("POST", path, json ?? {})
+	};
+}
+function toQueryString(query) {
+	const params = new URLSearchParams();
+	for (const [key, value] of Object.entries(query ?? {})) if (value !== void 0) params.set(key, String(value));
+	const text = params.toString();
+	return text ? `?${text}` : "";
+}
+const STATUS_HINTS = {
+	401: "authentication failed: check STORYSHELF_TOKEN",
+	403: "forbidden: this token's role does not allow that (comments need developer or above)",
+	404: "not found: check the project slug and build id",
+	409: "conflict: AI insights are disabled for this project",
+	501: "AI is not configured on this StoryShelf server"
+};
+/** Map transport/HTTP failures to an agent-readable {@link ToolError}. */
+function toToolError(error) {
+	if (error instanceof ToolError) return error;
+	if (error instanceof HttpError) return new ToolError(`StoryShelf API: ${STATUS_HINTS[error.status] ?? `request failed (${error.status})`}`);
+	return new ToolError(`StoryShelf API unreachable: ${error instanceof Error ? error.message : String(error)}`);
+}
+//#endregion
+export { ToolError, createApiClient, toToolError };

package/dist/config.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/config.ts
+/**
+* Read the connection from the environment (same variables as the CLI:
+* `STORYSHELF_URL`, `STORYSHELF_TOKEN`/`SHELF_TOKEN`, `STORYSHELF_SLUG`).
+*
+* @throws When no server URL is configured.
+*/
+function resolveConfig(env = process.env, overrides = {}) {
+	const url = overrides.url ?? env["STORYSHELF_URL"];
+	if (!url) throw new Error("STORYSHELF_URL is required (or pass --url)");
+	const token = overrides.token ?? env["STORYSHELF_TOKEN"] ?? env["SHELF_TOKEN"];
+	const slug = overrides.slug ?? env["STORYSHELF_SLUG"];
+	return {
+		url: url.replace(/\/+$/u, ""),
+		...token ? { token } : {},
+		...slug ? { slug } : {}
+	};
+}
+//#endregion
+export { resolveConfig };

package/dist/http.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+import "node:path";
+import "node:url";
+import.meta.url;
+import { probeCapabilities } from "./capabilities.js";
+import { createApiClient } from "./client.js";
+import { createStoryShelfMcpServer } from "./server.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { createServer } from "node:http";
+import { Readable } from "node:stream";
+//#region src/http.ts
+/**
+* Create a stateless Streamable HTTP MCP handler. Each request carries its own
+* `Authorization: Bearer` token, which is forwarded to `/api/v1`, so StoryShelf's
+* project scoping and roles apply per caller and no token is stored here.
+*/
+function createMcpHttpHandler(options) {
+	const capabilities = cachedCapabilities(options);
+	return async (request) => {
+		const rejected = rejectRequest(request, options);
+		if (rejected) return rejected;
+		const token = bearerToken(request);
+		const client = createApiClient({
+			url: options.url,
+			token,
+			...options.slug ? { slug: options.slug } : {}
+		});
+		const server = createStoryShelfMcpServer(client, await capabilities());
+		const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true });
+		await server.connect(transport);
+		try {
+			return await transport.handleRequest(request);
+		} finally {
+			await server.close();
+		}
+	};
+}
+/** How long the instance's capabilities are reused (they only change when it restarts). */
+const CAPABILITIES_TTL_MS = 6e4;
+/** The instance's capabilities, probed without credentials (liveness is open) at most once a minute. */
+function cachedCapabilities(options) {
+	let cached;
+	let inflight;
+	return async () => {
+		if (cached && Date.now() - cached.at < CAPABILITIES_TTL_MS) return cached.value;
+		inflight ??= probeCapabilities(createApiClient({
+			url: options.url,
+			token: ""
+		})).then((value) => {
+			cached = {
+				at: Date.now(),
+				value
+			};
+			inflight = void 0;
+			return value;
+		}, (error) => {
+			inflight = void 0;
+			throw error;
+		});
+		return await inflight;
+	};
+}
+/** Start a Node HTTP server exposing the handler at `/mcp`. */
+async function serveHttp(options) {
+	const handler = createMcpHttpHandler(options);
+	const server = createServer((incoming, outgoing) => {
+		handleNode(handler, incoming, outgoing).catch(() => outgoing.writeHead(500).end());
+	});
+	await new Promise((resolve) => {
+		server.listen(options.port, options.host ?? "127.0.0.1", resolve);
+	});
+	return server;
+}
+function rejectRequest(request, options) {
+	const origin = request.headers.get("origin");
+	if (origin && !options.allowedOrigins?.includes(origin)) return jsonError(403, "Origin not allowed");
+	if (!bearerToken(request)) return Response.json({ error: "Missing Bearer token" }, {
+		status: 401,
+		headers: {
+			"content-type": "application/json",
+			"www-authenticate": "Bearer realm=\"storyshelf\""
+		}
+	});
+}
+function bearerToken(request) {
+	return /^Bearer\s+(?<token>.+)$/iu.exec(request.headers.get("authorization") ?? "")?.groups?.["token"] ?? "";
+}
+function jsonError(status, error) {
+	return Response.json({ error }, { status });
+}
+async function handleNode(handler, incoming, outgoing) {
+	const url = new URL(incoming.url ?? "/", `http://${incoming.headers.host ?? "localhost"}`);
+	if (url.pathname !== "/mcp") {
+		outgoing.writeHead(404).end();
+		return;
+	}
+	const response = await handler(toRequest(incoming, url));
+	outgoing.writeHead(response.status, Object.fromEntries(response.headers));
+	outgoing.end(Buffer.from(await response.arrayBuffer()));
+}
+function toRequest(incoming, url) {
+	const hasBody = incoming.method !== "GET" && incoming.method !== "HEAD";
+	return new Request(url, {
+		method: incoming.method ?? "GET",
+		headers: incoming.headers,
+		...hasBody ? {
+			body: Readable.toWeb(incoming),
+			duplex: "half"
+		} : {}
+	});
+}
+//#endregion
+export { createMcpHttpHandler, serveHttp };

package/dist/index.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import "node:path";
+import "node:url";
+import.meta.url;
+import { resolveConfig } from "./config.js";
+import { parseArgs } from "node:util";
+//#region src/index.ts
+const HELP = `storyshelf-mcp: StoryShelf MCP server
+
+Usage: storyshelf-mcp [--http] [--port 3333] [--host 127.0.0.1] [--url URL] [--slug SLUG] [--token TOKEN] [--origin ORIGIN]
+
+Env: STORYSHELF_URL, STORYSHELF_TOKEN (or SHELF_TOKEN), STORYSHELF_SLUG
+Default transport is stdio. With --http, a Streamable HTTP endpoint is served at /mcp
+and each client sends its own "Authorization: Bearer <token>".`;
+function parseCli() {
+	return parseArgs({ options: {
+		http: { type: "boolean" },
+		port: { type: "string" },
+		host: { type: "string" },
+		url: { type: "string" },
+		slug: { type: "string" },
+		token: { type: "string" },
+		origin: {
+			type: "string",
+			multiple: true
+		},
+		help: {
+			type: "boolean",
+			short: "h"
+		}
+	} }).values;
+}
+function configFrom(values) {
+	return resolveConfig(process.env, {
+		...values.url ? { url: values.url } : {},
+		...values.slug ? { slug: values.slug } : {},
+		...values.token ? { token: values.token } : {}
+	});
+}
+async function runHttp(values, config) {
+	const { serveHttp } = await import("./http.js");
+	const port = Number(values.port ?? process.env["PORT"] ?? 3333);
+	const host = values.host ?? "127.0.0.1";
+	await serveHttp({
+		url: config.url,
+		...config.slug ? { slug: config.slug } : {},
+		...values.origin ? { allowedOrigins: values.origin } : {},
+		port,
+		host
+	});
+	process.stderr.write(`storyshelf-mcp listening on http://${host}:${port}/mcp\n`);
+}
+async function main() {
+	const values = parseCli();
+	if (values.help) {
+		process.stdout.write(`${HELP}\n`);
+		return;
+	}
+	const config = configFrom(values);
+	if (values.http) {
+		await runHttp(values, config);
+		return;
+	}
+	const { runStdio } = await import("./stdio.js");
+	await runStdio(config);
+}
+try {
+	await main();
+} catch (error) {
+	process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+	process.exitCode = 1;
+}
+//#endregion
+export {};

package/dist/server.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import "node:path";
+import "node:url";
+import.meta.url;
+import { toolsFor } from "./capabilities.js";
+import { toToolError } from "./client.js";
+import { ALL_TOOLS } from "./tools/index.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+//#region src/server.ts
+/** What a server assumes of an instance that was not asked: nothing is hidden. */
+const ALL_CAPABILITIES = { testing: true };
+/**
+* Create the StoryShelf MCP server over an {@link ApiClient}. Transport-agnostic:
+* connect it to stdio or Streamable HTTP.
+*/
+function createStoryShelfMcpServer(client, capabilities = ALL_CAPABILITIES) {
+	const server = new McpServer({
+		name: "storyshelf",
+		version: "0.7.0"
+	}, { instructions: "StoryShelf visual testing for Storybook. Inspect builds, snapshot diffs, capture logs and advisory AI triage; add review comments. Approving or rejecting snapshots is not available: leave that to a human in the StoryShelf UI." });
+	registerTools(server, client, capabilities);
+	registerPrompts(server, capabilities);
+	return server;
+}
+function registerTools(server, client, capabilities) {
+	for (const tool of toolsFor(ALL_TOOLS, capabilities)) server.registerTool(tool.name, {
+		title: tool.title,
+		description: tool.description,
+		inputSchema: tool.input,
+		annotations: {
+			readOnlyHint: tool.readOnly,
+			destructiveHint: false,
+			openWorldHint: false
+		}
+	}, async (args) => {
+		try {
+			const data = await tool.run(client, args);
+			return { content: [{
+				type: "text",
+				text: JSON.stringify(data, null, 2)
+			}] };
+		} catch (error) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: toToolError(error).message
+				}]
+			};
+		}
+	});
+}
+/** The steps of the review prompt: the capture tools are named only when the instance serves them. */
+function reviewSteps(testing) {
+	return testing ? "Call get_build, then list_snapshots, then get_build_insight (if AI is enabled) and get_capture_logs if the build failed. Summarise: what changed, which snapshots look like regressions vs intended changes, and what a human reviewer should check first." : "Call get_build (this instance has no capture, so there are no snapshots, insight or capture logs). Summarise: what the build contains and what a human reviewer should check first.";
+}
+function registerPrompts(server, capabilities) {
+	server.registerPrompt("review-build", {
+		title: "Review a build",
+		description: "Summarise a build's visual changes and recommend what a human should look at.",
+		argsSchema: {
+			buildId: z.string(),
+			project: z.string().optional()
+		}
+	}, ({ buildId, project }) => ({ messages: [{
+		role: "user",
+		content: {
+			type: "text",
+			text: `Review StoryShelf build ${buildId}${project ? ` in project ${project}` : ""}. ${reviewSteps(capabilities.testing)} Do not approve anything; you may add_comment with findings if asked.`
+		}
+	}] }));
+}
+//#endregion
+export { createStoryShelfMcpServer };

package/dist/stdio.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import "node:path";
+import "node:url";
+import.meta.url;
+import { probeCapabilities } from "./capabilities.js";
+import { createApiClient } from "./client.js";
+import { createStoryShelfMcpServer } from "./server.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+//#region src/stdio.ts
+/** Serve MCP over stdio (local agents: Claude Code, Cursor). Logs go to stderr only. */
+async function runStdio(config) {
+	const client = createApiClient(config);
+	await createStoryShelfMcpServer(client, await probeCapabilities(client)).connect(new StdioServerTransport());
+}
+//#endregion
+export { runStdio };

package/dist/tools/builds.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+import "node:path";
+import "node:url";
+import.meta.url;
+import { buildPath, projectSlug } from "./types.js";
+import { z } from "zod";
+//#region src/tools/builds.ts
+const project = z.string().optional().describe("Project slug (defaults to STORYSHELF_SLUG)");
+const buildId = z.string().describe("Build id (ULID)");
+const BUILD_FIELDS = [
+	"id",
+	"gitSha",
+	"gitBranch",
+	"isDefault",
+	"message",
+	"authorName",
+	"status",
+	"snapshotCount",
+	"changedCount",
+	"approvedCount",
+	"rejectedCount",
+	"createdAt"
+];
+const listBuilds = {
+	name: "list_builds",
+	title: "List builds",
+	description: "List recent builds of a project, newest first, with change counts. Filter by branch or status.",
+	readOnly: true,
+	input: {
+		project,
+		branch: z.string().optional().describe("Only builds on this git branch"),
+		status: z.enum([
+			"pending",
+			"capturing",
+			"comparing",
+			"reviewing",
+			"approved",
+			"rejected",
+			"failed",
+			"cancelled"
+		]).optional(),
+		limit: z.number().int().min(1).max(100).default(20).describe("Max builds to return")
+	},
+	run: async (client, args) => {
+		const builds = await client.get(`/projects/${projectSlug(client, args["project"])}/builds`, {
+			branch: args["branch"],
+			status: args["status"]
+		});
+		const limit = Number(args["limit"] ?? 20);
+		return builds.slice(0, limit).map((b) => pickFields(b, BUILD_FIELDS));
+	}
+};
+const getBuild = {
+	name: "get_build",
+	title: "Get build",
+	description: "Get one build: status, git info, snapshot/changed/approved/rejected counts, baseline.",
+	readOnly: true,
+	input: {
+		project,
+		buildId
+	},
+	run: async (client, args) => await client.get(buildPath(client, args))
+};
+const getCaptureLogs = {
+	name: "get_capture_logs",
+	title: "Get capture logs",
+	description: "Get the capture attempts of a build and the log lines of one attempt (latest by default). Use it to debug failed or flaky captures.",
+	readOnly: true,
+	routeClass: "testing",
+	input: {
+		project,
+		buildId,
+		attemptNo: z.number().int().min(1).optional().describe("Attempt number (default: latest)"),
+		tail: z.number().int().min(1).max(500).default(100).describe("Last N log lines")
+	},
+	run: async (client, args) => {
+		const base = buildPath(client, args);
+		const attempts = await client.get(`${base}/attempts`);
+		const latest = attempts.at(-1)?.attemptNo;
+		const attemptNo = args["attemptNo"] ?? latest;
+		if (attemptNo === void 0) return {
+			attempts,
+			logs: []
+		};
+		const logs = await client.get(`${base}/attempts/${attemptNo}/logs`);
+		const tail = Number(args["tail"] ?? 100);
+		return {
+			attempts,
+			attemptNo,
+			logs: logs.slice(-tail).map((l) => pickFields(l, [
+				"seq",
+				"level",
+				"message",
+				"fields"
+			]))
+		};
+	}
+};
+function pickFields(source, keys) {
+	return Object.fromEntries(keys.map((key) => [key, source[key]]));
+}
+const buildTools = [
+	listBuilds,
+	getBuild,
+	getCaptureLogs
+];
+//#endregion
+export { buildTools, getBuild, getCaptureLogs, listBuilds };

package/dist/tools/comments.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import "node:path";
+import "node:url";
+import.meta.url;
+import { buildPath } from "./types.js";
+import { z } from "zod";
+//#region src/tools/comments.ts
+const project = z.string().optional().describe("Project slug (defaults to STORYSHELF_SLUG)");
+const buildId = z.string().describe("Build id (ULID)");
+const listComments = {
+	name: "list_comments",
+	title: "List comments",
+	description: "List review comments on a build: build comments, story comments and per-snapshot threads. A project with review off has none (the call fails with 404).",
+	readOnly: true,
+	input: {
+		project,
+		buildId
+	},
+	run: async (client, args) => await client.get(`${buildPath(client, args)}/comments`)
+};
+const addComment = {
+	name: "add_comment",
+	title: "Add comment",
+	description: "Add a review comment to a build, optionally on one story or one snapshot (not both) or as a reply. Needs a token with developer role or above. Visible to everyone on the project. There is no tool to approve or reject a build: a verdict is for people. Fails with 404 when the project has review off.",
+	readOnly: false,
+	input: {
+		project,
+		buildId,
+		body: z.string().min(1).max(4e3),
+		storyId: z.string().optional().describe("Attach to this story id (not with snapshotId)"),
+		snapshotId: z.string().optional().describe("Attach to this snapshot (not with storyId)"),
+		parentId: z.string().optional().describe("Reply to this comment id")
+	},
+	run: async (client, args) => await client.post(`${buildPath(client, args)}/comments`, {
+		body: args["body"],
+		...args["storyId"] ? { storyId: args["storyId"] } : {},
+		...args["snapshotId"] ? { snapshotId: args["snapshotId"] } : {},
+		...args["parentId"] ? { parentId: args["parentId"] } : {}
+	})
+};
+const resolveComment = {
+	name: "resolve_comment",
+	title: "Resolve comment",
+	description: "Mark a review comment as resolved. Needs developer role or above.",
+	readOnly: false,
+	input: {
+		project,
+		buildId,
+		commentId: z.string()
+	},
+	run: async (client, args) => await client.post(`${buildPath(client, args)}/comments/${encodeURIComponent(String(args["commentId"]))}/resolve`)
+};
+const commentTools = [
+	listComments,
+	addComment,
+	resolveComment
+];
+//#endregion
+export { addComment, commentTools, listComments, resolveComment };

package/dist/tools/index.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import "node:path";
+import "node:url";
+import.meta.url;
+import { buildTools } from "./builds.js";
+import { commentTools } from "./comments.js";
+import { insightTools } from "./insights.js";
+import { projectTools } from "./projects.js";
+import { snapshotTools } from "./snapshots.js";
+//#region src/tools/index.ts
+/**
+* Every tool exposed in v1: read-only review data plus comments. No approvals and no build
+* verdicts: an agent must not be able to sign off a build (ADR 0013, decision 10).
+*/
+const ALL_TOOLS = [
+	...projectTools,
+	...buildTools,
+	...snapshotTools,
+	...insightTools,
+	...commentTools
+];
+//#endregion
+export { ALL_TOOLS };

package/dist/tools/insights.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import "node:path";
+import "node:url";
+import.meta.url;
+import { buildPath, projectSlug } from "./types.js";
+import { z } from "zod";
+//#region src/tools/insights.ts
+const project = z.string().optional().describe("Project slug (defaults to STORYSHELF_SLUG)");
+const getBuildInsight = {
+	name: "get_build_insight",
+	title: "Get build AI triage",
+	description: "Get the latest cached AI triage of a build: verdict (likely-intended, needs-review, likely-regression), summary and per-snapshot notes. Advisory only. Read-only: it never triggers generation (an approver does that in the UI).",
+	readOnly: true,
+	routeClass: "testing",
+	input: {
+		project,
+		buildId: z.string().describe("Build id (ULID)")
+	},
+	run: async (client, args) => await client.get(`${buildPath(client, args)}/insights/latest`)
+};
+const getProjectHealth = {
+	name: "get_project_health",
+	title: "Get project health",
+	description: "Get the latest cached AI project-health digest (verdict, 0-100 score, trends) for a project. Read-only.",
+	readOnly: true,
+	routeClass: "testing",
+	input: {
+		project,
+		window: z.string().optional().describe("Window, e.g. 30d")
+	},
+	run: async (client, args) => await client.get(`/projects/${projectSlug(client, args["project"])}/insights/health`, { window: args["window"] })
+};
+const insightTools = [getBuildInsight, getProjectHealth];
+//#endregion
+export { getBuildInsight, getProjectHealth, insightTools };

package/dist/tools/projects.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import "node:path";
+import "node:url";
+import.meta.url;
+import { projectSlug } from "./types.js";
+import { z } from "zod";
+//#region src/tools/projects.ts
+const project = z.string().optional().describe("Project slug (defaults to STORYSHELF_SLUG)");
+const listProjects = {
+	name: "list_projects",
+	title: "List projects",
+	description: "List StoryShelf projects (one per Storybook). Needs a site-admin token; with a project token use get_project instead.",
+	readOnly: true,
+	input: {},
+	run: async (client) => {
+		return (await client.get("/projects")).map((p) => pick(p, [
+			"name",
+			"slug",
+			"gitRepository",
+			"gitDefaultBranch"
+		]));
+	}
+};
+const getProject = {
+	name: "get_project",
+	title: "Get project",
+	description: "Get a project's settings: default branch, diff thresholds, browser, play-function setting.",
+	readOnly: true,
+	input: { project },
+	run: async (client, args) => await client.get(`/projects/${projectSlug(client, args["project"])}`)
+};
+function pick(source, keys) {
+	return Object.fromEntries(keys.map((key) => [key, source[key]]));
+}
+const projectTools = [listProjects, getProject];
+//#endregion
+export { getProject, listProjects, projectTools };

package/dist/tools/snapshots.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import "node:path";
+import "node:url";
+import.meta.url;
+import { buildPath } from "./types.js";
+import { z } from "zod";
+//#region src/tools/snapshots.ts
+const SNAPSHOT_FIELDS = [
+	"id",
+	"storyId",
+	"storyTitle",
+	"storyName",
+	"viewportName",
+	"mode",
+	"status",
+	"diffPixels",
+	"diffRatio",
+	"diffPassed",
+	"inherited",
+	"reviewedBy"
+];
+const listSnapshots = {
+	name: "list_snapshots",
+	title: "List snapshots",
+	description: "List the story snapshots of a build with diff metrics (pixels, ratio, pass/fail) and review status. By default only changed/new/pending/rejected snapshots are returned; set includeUnchanged for all. Approving is intentionally not available: a human approves in the StoryShelf UI.",
+	readOnly: true,
+	routeClass: "testing",
+	input: {
+		project: z.string().optional().describe("Project slug (defaults to STORYSHELF_SLUG)"),
+		buildId: z.string().describe("Build id (ULID)"),
+		includeUnchanged: z.boolean().default(false),
+		limit: z.number().int().min(1).max(500).default(100)
+	},
+	run: async (client, args) => {
+		const all = await client.get(`${buildPath(client, args)}/snapshots`);
+		const wanted = args["includeUnchanged"] ? all : all.filter((s) => s["status"] !== "unchanged" && s["status"] !== "approved");
+		const limit = Number(args["limit"] ?? 100);
+		return {
+			total: all.length,
+			returned: Math.min(wanted.length, limit),
+			snapshots: wanted.slice(0, limit).map((s) => Object.fromEntries(SNAPSHOT_FIELDS.map((key) => [key, s[key]])))
+		};
+	}
+};
+const snapshotTools = [listSnapshots];
+//#endregion
+export { listSnapshots, snapshotTools };

package/dist/tools/types.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import "node:path";
+import "node:url";
+import.meta.url;
+import { ToolError } from "../client.js";
+//#region src/tools/types.ts
+/** Resolve the project slug from the call argument or the configured default. */
+function projectSlug(client, project) {
+	const slug = typeof project === "string" && project ? project : client.defaultSlug;
+	if (!slug) throw new ToolError("No project given: pass `project` or set STORYSHELF_SLUG");
+	return encodeURIComponent(slug);
+}
+/** Build the `/projects/{slug}/builds/{id}` path prefix. */
+function buildPath(client, args) {
+	return `/projects/${projectSlug(client, args["project"])}/builds/${encodeURIComponent(String(args["buildId"]))}`;
+}
+//#endregion
+export { buildPath, projectSlug };

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@storyshelf/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.7.0",
+  "description": "StoryShelf MCP server: let AI agents read builds, diffs and AI insights, and comment on reviews.",
+  "keywords": [
+    "agents",
+    "mcp",
+    "model-context-protocol",
+    "self-hosted",
+    "storybook",
+    "visual-testing"
+  ],
+  "homepage": "https://github.com/GuptaSiddhant/StoryShelf#readme",
+  "bugs": {
+    "url": "https://github.com/GuptaSiddhant/StoryShelf/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Siddhant Gupta",
+    "url": "https://guptasiddhant.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GuptaSiddhant/StoryShelf.git",
+    "directory": "packages/mcp"
+  },
+  "bin": {
+    "storyshelf-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.js",
+    "./http": "./dist/http.js",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown -w",
+    "fmt": "oxfmt ./src",
+    "lint": "oxlint --type-aware --type-check ./src",
+    "test": "vitest run",
+    "prepublishOnly": "nub run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.0",
+    "@storyshelf/core": "0.7.0",
+    "zod": "^4.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "@vitest/coverage-v8": "^4.0.0",
+    "oxfmt": "^0.65.0",
+    "oxlint": "^1.80.0",
+    "oxlint-tsgolint": "^7.0.2001",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "jsr": false
+}