@storyshelf/mcp

View as Markdown

@storyshelf/mcp is the MCP server: it lets AI agents read builds, snapshot diffs and AI triage and comment on reviews, using your existing API tokens. It never approves or rejects: an agent cannot sign off a build, so there is no snapshot-approval tool and no build-verdict tool. See ADR 0017.

Install

npm i @storyshelf/mcp

pnpm add @storyshelf/mcp

yarn add @storyshelf/mcp

npm package — install tarballs and version history.
Source on GitHub — package directory on main.

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 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

Usage

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.

The @storyshelf/mcp/http subpath exports createMcpHttpHandler (a Request to Response handler) and serveHttp (a Node server) for embedding.