# @storyshelf/mcp

> MCP server for AI agents — stdio and Streamable HTTP, a thin client over the StoryShelf REST API.

Source: https://storyshelf.js.org/packages/mcp/

`@storyshelf/mcp` is the [MCP server](https://storyshelf.js.org/ai/mcp/): 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](https://github.com/GuptaSiddhant/StoryShelf/blob/main/docs/adr/0017-mcp-server.md).

## Install

```sh
npm i @storyshelf/mcp
```

- [npm package](https://www.npmjs.com/package/@storyshelf/mcp) — install tarballs and version history.
- [Source on GitHub](https://github.com/GuptaSiddhant/storyshelf/tree/main/packages/mcp) — 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](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`

## 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`.

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