Story Mapper

Storymapper

A User Story Map + Kanban board that a product owner and an AI coding agent plan together — the same backlog, live, from a browser and from an MCP client — with the quality method built in.

Storymapper is one Node.js package that ships three things:

1. A browser UI — a User Story Map (process steps × releases, with epics and stories in the cells), a Kanban board, plus table, dependency-graph, requirements and settings views. Plain HTML + modular JavaScript, no build step.
2. An HTTP + WebSocket server — persists every project in SQLite with a full per-project revision history, and pushes changes to connected browsers within ~100 ms.
3. An MCP server (stdio) plus a pass-through CLI — the same ~70 tools, for Claude Desktop / Claude Code via MCP and for scripts or other harnesses as one-shot commands. Anything the agent does appears live in the product owner's browser with a highlight-and-move animation; anything edited by hand flows back to the agent on its next read.

The result is a shared planning surface: the agent isn't writing to a database the human can't see — the two work the same board in real time.

---

Why it exists

Planning AI-assisted development breaks down when the plan lives in one place and the work in another. Storymapper makes the plan a live, bidirectional artifact:

• You bring the product idea and a rough shape of what to build; the agent lays it out on the board — epics, stories, releases, dependencies — and you watch it appear and rearrange it by hand.
• You reprioritize, split, annotate — and the agent picks it up on its next read and continues from the current state of the board.
• Every change is a revision you can inspect and restore.

Quality steering at the product level

When an agent does the building, the human contribution moves up a level: you describe the product, review its behavior, and steer the work through the process. That process is Storymapper's real substance — a complete quality method the engine enforces as tool-level rules: a ticket is specified before it is built (Definition of Ready) and proven before it counts as done (Definition of Done plus a published test plan with recorded runs), and your requirements stay traceably linked to the stories that implement them and the tests that verify them. An agent that tries to skip a step gets a structured error naming exactly what is missing — and fixes it. This puts professional-grade quality assurance into the hands of everyone who thinks in products — founders, domain experts, product owners: the method speaks the language of the product and lets you hold an agent's work to a standard you can verify. The workflow itself (statuses, transitions, gates, board columns) is configurable per project, and the companion skill teaches the agent the discipline, not just the tools.

Design principles

• Zero build. No bundler, no transpiler, no TypeScript. The browser loads classical modules; the server runs the same files under Node via a UMD wrapper. Clone and run.
• One source of truth for pure logic. All domain logic (normalization, operations, the workflow/governance engines, graph algorithms) lives in shared/core.js and is *symlinked* into the frontend and *re-exported* by the server — the same code runs in the browser, the HTTP server and the MCP server, with no mirror step to drift.
• Raw HTTP, no framework. http.createServer + manual routing. Small, readable, dependency-light.
• Synchronous SQLite via better-sqlite3, atomic per-save transactions, a per-project mutex, and count-bounded revision retention.
• Single-user, local-first. One human plus their agent on one machine. See the security model below.

For the full picture — layering, data model, live-sync mechanism, testing approach and deliberate non-goals — see [ARCHITECTURE.md](ARCHITECTURE.md).

---

Requirements

• Node.js ≥ 20 (developed and tested on 20 and 22; Node 18 is end-of-life).
• better-sqlite3 is a native module. Prebuilt binaries cover mainstream platforms (macOS / Linux / Windows on x64 + arm64 for supported Node versions), so npm install usually just works. On an unsupported platform/Node combination it compiles from source and needs a C/C++ toolchain (Xcode Command Line Tools, build-essential, or the Windows build tools).

Install

git clone <your-fork-url> storymapper

cd storymapper npm install

Run the browser UI

npm start

→ http://localhost:8770/ (data in ./.storymap-data)

→ Ctrl-C to stop

Open http://localhost:8770/ — that's all. The page connects to the server it was loaded from and stores every project there (SQLite, with full revision history).

Hosting the page somewhere else? Served from a different origin, the UI

runs on browser localStorage instead; point it at a running server with

?api= . The page must be loaded from localhost / 127.0.0.1 — opening

the HTML directly as a file:// page is not supported (see the security

model).

Connect it to your Claude (one command per surface)

Storymapper reaches an agent through two parts: the MCP server (the tools) and the companion skill (the working method — the DoR/DoD contract, the workflow discipline, when to read the board and when to write to it). Installing one does not install the other, so the setup commands below always install both:

npm run install-code copies the skill to ~/.claude/skills/storymap and registers the MCP server via claude mcp add (user scope). If the claude CLI is unavailable it prints the ready-made command instead.

npm run install-desktop writes the server entry into the platform's claude_desktop_config.json (existing entries survive, a .bak backup is kept) and builds the skill zip. The skill store in Claude Desktop is managed by the app, so the one upload in the UI is the single step no script can do for you.

Chat, not Cowork. Claude Desktop reaches local MCP servers from Chat

conversations only — in Cowork mode the Storymapper tools are not

available. If Cowork is your default surface, switch to a Chat; when the

tools don't show up, this is the first thing to check.

Both commands are idempotent — re-run them after pulling a new Storymapper version. --data-dir=DIR overrides the data directory (default: /.storymap-data).

Manual setup (other MCP clients, other harnesses)

Any stdio MCP client can run the server with this shape:

{

"mcpServers": { "storymapper": { "command": "node", "args": [ "/absolute/path/to/storymapper/server/index.js", "mcp", "--data-dir=/absolute/path/to/storymapper/.storymap-data" ] } } }

The skill package (npm run package-skill → dist/storymap-skill.zip) is plain Markdown — storymap/SKILL.md plus its reference/ files. For harnesses like Codex, unpack it wherever instructions live and point the harness at it, e.g. from an AGENTS.md:

Before planning work on the Storymapper board, read storymap/SKILL.md

(and the reference/ files it names) and follow that working method.

Point --data-dir at the same directory the HTTP server uses. Both processes can run concurrently against one SQLite file (WAL mode + a busy-timeout); the HTTP server relays every MCP write to connected browsers over WebSocket.

Scripting without MCP: the CLI

Every tool is also a one-shot CLI command running over the same tool core:

node server/index.js tool list_projects

node server/index.js tool ticket_create '{"projectId": "…", "title": "…"}'

The result JSON goes to stdout (exit codes: 0 ok, 1 tool error, 2 unknown tool / bad arguments); arguments come from the positional JSON string, --json= , or piped stdin. This opens the full tool surface to shell scripts, CI jobs and harnesses that don't speak MCP.

Only one storymapper server may run per data directory (a PID lock refuses a

second; --force takes over a stale lock after a crash). The MCP process is

exempt and may always share the data dir.

Security model (single-user, local)

Storymapper is a local single-user tool — one human plus their agent on one machine. There is deliberately no authentication layer:

• The server binds to localhost by default. Do not expose it on a non-loopback interface (--host=0.0.0.0, a reverse proxy, a Docker port map) without putting your own authentication in front — anyone who can reach the port can read and write every project.
• CORS is locked to loopback origins: cross-origin browser requests get no Access-Control-Allow-Origin and mutating methods are rejected — this stops a random website you visit from driving your local API. WebSocket upgrades are origin-checked the same way.
• Served HTML carries a Content-Security-Policy; all responses send X-Content-Type-Options: nosniff.
• X-Actor-* headers are attribution, not authentication — they label who did what in the revision history and are not verified.
• Verified identity, token-gated remote access and RBAC are a deliberate later stage; the authorization seam (server/identity.js) is already in place.

Testing

npm test          # ≈1800 assertions, plain Node scripts, no test framework

The suite is a homegrown runner (tests/run.js) over tests/test-*.js: pure unit tests, storage/mutex/revision tests, in-process and stdio MCP round-trips, JSDOM renderer tests, and a real-server end-to-end test. CI runs it on Node 20 and 22. Tests only ever touch temporary directories — running them never touches your data.

License

Licensed under the Apache License 2.0 — see LICENSE and NOTICE.