greenroom MCP server
Commit Sep 3, 2026Allows AI coding agents to access Storybook review feedback, reply to threads, and address component changes based on human sign-offs.
Also known as igility/greenroom, @igility/greenroom-addon
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- 1,484
- Latest version
- —
- Last commit
- Sep 3, 2026
- License
- MIT
What is greenroom MCP?
greenroom allows AI coding agents to access Storybook review feedback, reply to threads, and address component changes based on human sign-offs.
Summary generated from the project's README
About greenroom MCP server
Connecting AI coding agents to Storybook review feedback allows developers to automate component fixes based on human sign-offs. This MCP server acts as a bridge to a sidecar service that stores review threads, story statuses, and screenshots. It enables agents to see exactly what a human reviewer flagged by providing the story ID, CSF file path, arguments, DOM selector, and a visual screenshot of the specific pin.
Users deploy a Node and SQLite sidecar next to their static Storybook build to manage the audit trail and reviewer magic links. To use the MCP server, you must mint an agent token and configure your client with the GREENROOM_URL and GREENROOM_TOKEN environment variables. The system ensures safety by requiring human approval for all changes, though an admin can record a written delegation to allow the approve_stories tool to function under strict conditions.
Agents interact with the component lifecycle through specific tools like list_stories to find work in the changes_requested state, list_feedback to view context, and mark_story_addressed once a fix is implemented. This setup prevents silent approval carry-overs by using content-manifest hashes to re-confirm stories when new builds are uploaded.
What you can do with it
- 1Identify pending component fixesAn AI agent can scan for all stories that currently have requested changes to build a task list.
- 2Communicate progress to reviewersThe agent can respond directly to a human's comment thread within the review system.
Written from the project's README. Every use case is checked against a quote from it.
How to install greenroom MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall greenroom MCP in Claude Code
$ claude mcp add greenroom -- npx -y @igility/greenroom-addonInstall greenroom MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"greenroom": {
"command": "npx",
"args": [
"-y",
"@igility/greenroom-addon"
]
}
}
}Install greenroom MCP in VS Code
.vscode/mcp.json
{
"servers": {
"greenroom": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@igility/greenroom-addon"
]
}
}
}Install greenroom MCP in VS Code CLI
$ code --add-mcp '{"name":"greenroom","type":"stdio","command":"npx","args":["-y","@igility/greenroom-addon"]}'Install greenroom MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"greenroom": {
"command": "npx",
"args": [
"-y",
"@igility/greenroom-addon"
]
}
}
}Install greenroom MCP in Codex
$ codex mcp add greenroom -- npx -y @igility/greenroom-addonInstall greenroom MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.greenroom] command = "npx" args = ["-y", "@igility/greenroom-addon"]
Install greenroom MCP in Gemini CLI
$ gemini mcp add -s user greenroom npx -- -y @igility/greenroom-addonInstall greenroom MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"greenroom": {
"command": "npx",
"args": [
"-y",
"@igility/greenroom-addon"
]
}
}
}Configuration
GREENROOM_ADMIN_KEYGREENROOM_TOKENGREENROOM_URL
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableigility/greenroom is public and reachablegithub.com/igility/greenroom ↗Pass
- Package names this repository as its source@igility/greenroom-addon names igility/greenroom as sourcenpmjs.com/package/@igility/greenroom-addon ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-03github.com/igility/greenroom ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @igility/greenroom-addonPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubGreenroom
Per-story review and sign-off for Storybook — readable by AI coding agents over MCP.
Humans review rendered components and approve them, one story at a time. Agents read that feedback — the story ID, CSF file path, args, DOM selector, and a screenshot of the exact pin — and do the work. Nothing ships until a person signs off.
Status: pre-release. Under active development; not yet published to npm.
How it fits together
@igility/greenroom-addon— a thin Storybook addon: a Review panel in the manager and a pin-drop overlay on the preview canvas. Capture and display only; no state lives here.@igility/greenroom-server— the sidecar: a small Node + SQLite service you deploy next to a static Storybook build. Holds threads, per-story status, reviewers, magic links, and the audit trail. Reviewers get a plain review page via magic link — no GitHub account, no Storybook UI.@igility/greenroom-mcp— an MCP server over the store. Agents list open feedback with full context, reply, and mark work addressed.
Approvals bind to a specific build (content-manifest hash). When a new build is uploaded, approved stories flip to "needs re-confirm" — render fingerprints sort that queue, but never silently carry an approval forward.
Who can approve
Approval is a human sign-off. Reviewers open a magic link — no account — and approve per
story or in a confirmed batch. An approver-role reviewer can sign off; a reviewer-role
one can only comment.
Agents cannot approve on their own. An admin may record a written client authorization (a
delegation); only then can the MCP approve_stories tool approve — and it still
requires an explicit confirm step and is labeled approved (delegated), with the
authorization, in the audit trail. It is never indistinguishable from a human click.
Quickstart (local)
pnpm install
pnpm -r build
# 1. Run the sidecar. It prints a generated admin key on first run;
# set GREENROOM_ADMIN_KEY to keep it stable.
GREENROOM_ADMIN_KEY=dev-admin GREENROOM_DATA_DIR=./.greenroom-data \
node packages/server/dist/cli.js serve
# → http://localhost:4788
# 2. Build a Storybook and upload it (any static Storybook works).
pnpm build:demo # builds examples/demo-storybook/storybook-static
node packages/server/dist/cli.js upload examples/demo-storybook/storybook-static \
--url http://localhost:4788 --token dev-admin --label "design-round-1"
# 3. Invite a reviewer and mint a magic link (no account needed).
curl -s -XPOST http://localhost:4788/api/reviewers \
-H "authorization: Bearer dev-admin" -H "content-type: application/json" \
-d '{"name":"Jordan Client","email":"jordan@example.com"}'
curl -s -XPOST http://localhost:4788/api/reviewers/<reviewer-id>/links \
-H "authorization: Bearer dev-admin"
# → open the returned url; review, comment, approve.
Connect an AI agent (MCP)
Mint an agent token and point the MCP server at the sidecar:
curl -s -XPOST http://localhost:4788/api/tokens \
-H "authorization: Bearer dev-admin" -H "content-type: application/json" \
-d '{"kind":"agent","name":"claude"}'
// e.g. an MCP client config
{
"mcpServers": {
"greenroom": {
"command": "node",
"args": ["packages/mcp/dist/index.js"],
"env": { "GREENROOM_URL": "http://localhost:4788", "GREENROOM_TOKEN": "<agent-token>" }
}
}
}
The agent then sees list_stories (state changes_requested is its work queue),
list_feedback/get_thread (with the pin screenshot as an image), reply_to_thread,
mark_story_addressed, and the delegation-gated approve_stories.
Add the addon to a Storybook (optional, for in-Storybook review)
// .storybook/main.ts
export default { addons: ['@igility/greenroom-addon'] };
Deploy the sidecar
docker build -t greenroom .
docker run -p 4788:4788 -v greenroom-data:/data \
-e GREENROOM_ADMIN_KEY=$(openssl rand -base64 24) \
-e GREENROOM_PUBLIC_URL=https://review.example.com \
greenroom
All state lives under GREENROOM_DATA_DIR (default /data in the image): the SQLite
database, the extracted builds, and pin screenshots. Back it up by copying that one
directory. No external services.
Configuration
| Env var | Default | Purpose |
|---|---|---|
GREENROOM_PORT |
4788 |
Listen port |
GREENROOM_DATA_DIR |
.greenroom-data |
SQLite + builds + attachments |
GREENROOM_ADMIN_KEY |
generated | Admin bearer token (set to keep stable) |
GREENROOM_PUBLIC_URL |
http://localhost:<port> |
Base for magic-link URLs; https:// enables the Secure cookie flag |
GREENROOM_MAX_UPLOAD_BYTES |
250MB |
Reject larger build uploads |
Development
pnpm -r typecheck
pnpm -r test # unit / integration (shared, server, mcp)
pnpm build:demo # build the demo Storybook the e2e suite serves
npx playwright test # end-to-end (spawns its own sidecars + static servers)
License
MIT
greenroom MCP questions
How do I add greenroom MCP to Claude Code?
Run claude mcp add greenroom -- npx -y @igility/greenroom-addon in your terminal. Add --scope user to make it available in every project.
How do I add greenroom MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Can AI agents approve stories?
Agents cannot approve on their own. They can only use the approve_stories tool if an admin has recorded a written client authorization (delegation), and even then it is explicitly labeled as delegated.
How do reviewers access the platform?
Reviewers do not need a GitHub account or the Storybook UI; they can access a plain review page via a magic link.
What happens to approvals when a new build is uploaded?
Approvals are tied to a specific build hash. When a new build is uploaded, approved stories are reset to 'needs re-confirm' to ensure changes are verified.