Story Mapper

Storymapper

プロダクトオーナーとAI コーディングエージェントが一緒に計画するユーザーストーリーマップ＋カンバンボードです。同じバックログをブラウザーとMCPクライアントからリアルタイムに操作でき、品質手法も組み込まれています。

Storymapperは、3つの機能を備えた1つのNode.jsパッケージです。

1. ブラウザーUI — ユーザーストーリーマップ（プロセスのステップ×リリース、各セルにエピックとストーリーを表示）、カンバンボードに加えて、テーブル、依存関係グラフ、要件、設定の各ビューを備えています。プレーンなHTML＋モジュール式JavaScriptで、ビルド手順は不要です。
2. HTTP＋WebSocketサーバー — プロジェクトごとの完全な改訂履歴とともに、すべてのプロジェクトをSQLiteに保存し、接続中のブラウザーに約100 ms以内に変更を反映します。
3. MCPサーバー（stdio）とパススルーCLI — 約70個の同じツールを、MCP経由でClaude Desktop／Claude Codeから利用できるほか、スクリプトやほかのハーネスから単発コマンドとして利用できます。エージェントが行った操作は、ハイライトと移動のアニメーションとともにプロダクトオーナーのブラウザーにリアルタイムで表示されます。手動で編集した内容は、エージェントが次に読み込む際に反映されます。

その結果、共有の計画画面が実現します。エージェントが人間には見えないデータベースに書き込むのではなく、2者が同じボードをリアルタイムで使います。

---

開発の背景

計画と作業が別々の場所にあると、AI支援開発の計画はうまく進みません。Storymapperは、計画を双方向にやり取りできるライブの成果物にします。

• プロダクトのアイデアと、作りたいもののおおまかな形を伝えると、エージェントがエピック、ストーリー、リリース、依存関係をボードに配置します。それが表示され、手動で並べ替える様子を確認できます。
• 優先順位の変更、分割、注釈の追加を行うと、エージェントは次の読み込み時にそれを取り込み、ボードの現在の状態から作業を続けます。
• すべての変更は改訂として記録され、確認や復元ができます。

プロダクトレベルでの品質管理

エージェントが開発を担うとき、人間の貢献はより上流へと移ります。プロダクトを説明し、その動作をレビューし、プロセスを通じて作業を導くのです。このプロセスこそがStorymapperの本質です。エンジンは、ツールレベルのルールとして完全な品質手法を適用します。チケットは作成前に仕様が確定され（Definition of Ready）、完了とみなす前に検証されます（Definition of Doneと、実行結果を記録した公開済みテストプラン）。また、要件は、それを実装するストーリーや検証するテストと追跡可能な形で関連付けられます。エージェントが手順を省こうとすると、不足している内容を具体的に示す構造化エラーが返され、エージェントはそれを修正します。これにより、プロダクトを軸に考えるすべての人、つまり創業者、ドメインエキスパート、プロダクトオーナーが、プロフェッショナルレベルの品質保証を利用できます。この手法はプロダクトの言葉で説明され、検証可能な基準でエージェントの作業を評価できます。ワークフローそのもの（ステータス、遷移、ゲート、ボードの列）はプロジェクトごとに設定でき、付属のスキルはツールの使い方だけでなく、規律もエージェントに教えます。

設計原則

• ビルド不要。 バンドラーもトランスパイラーも TypeScript もありません。ブラウザーは従来型の <script src> モジュールを読み込み、サーバーは UMD ラッパーを介して同じファイルを Node で実行します。クローンして実行できます。
• 純粋なロジックの信頼できる唯一の情報源。 すべてのドメインロジック（正規化、操作、ワークフロー／ガバナンスエンジン、グラフアルゴリズム）は shared/core.js にあり、フロントエンドからシンボリックリンクされ、サーバーから再エクスポートされます。ミラーリングによる差異が生じることなく、同じコードがブラウザー、HTTP サーバー、MCP サーバーで実行されます。
• フレームワークを使わない生の HTTP。 http.createServer と手動ルーティングを使用します。小規模で読みやすく、依存関係を最小限に抑えています。
• better-sqlite3 による同期 SQLite、保存ごとのアトミックなトランザクション、プロジェクトごとのミューテックス、件数上限付きのリビジョン保持。
• シングルユーザー、ローカルファースト。 1 台のマシンで、1 人のユーザーとそのエージェントが使用します。以下のセキュリティモデルをご覧ください。

レイヤー構成、データモデル、ライブ同期の仕組み、テスト方法、意図的に対象外とした項目など、全体像については ARCHITECTURE.md をご覧ください。

---

要件

• Node.js ≥ 20（Node 20 と 22 で開発およびテスト済みです。Node 18 はサポートが終了しています）。
• better-sqlite3 はネイティブモジュールです。主流のプラットフォーム（サポート対象の Node バージョンにおける x64 および arm64 の macOS／Linux／Windows）にはビルド済みバイナリーが用意されているため、通常は npm install だけで動作します。サポート対象外のプラットフォームと Node の組み合わせではソースからコンパイルされ、C/C++ ツールチェーン（Xcode Command Line Tools、build-essential、または Windows のビルドツール）が必要です。

インストール

git clone <your-fork-url> storymapper
cd storymapper
npm install

ブラウザー UI の実行

npm start
# → http://localhost:8770/   (data in ./.storymap-data)
# → Ctrl-C to stop

http://localhost:8770/ を開くだけです。ページは読み込まれたサーバーに接続し、すべてのプロジェクトをそこで保存します（SQLite に完全なリビジョン履歴とともに保存されます）。

ページを別の場所でホストしますか？ 別のオリジンから配信すると、UI は代わりにブラウザーの localStorage を使用します。稼働中のサーバーを ?api=<url> で指定してください。ページは localhost または 127.0.0.1 から読み込む必要があります。HTML を file:// ページとして直接開くことはサポートされていません（セキュリティモデルをご覧ください）。

Claude に接続する（各環境につき 1 つのコマンド）

Storymapper は 2 つの要素を通じてエージェントに接続します。MCP サーバー（ツール）と、付属のスキル（作業方法 — DoR/DoD の契約、ワークフローの規律、ボードを読むタイミングと書き込むタイミング）です。一方をインストールしても、もう一方はインストールされません。そのため、以下のセットアップコマンドでは常に両方をインストールします。

環境	コマンド	残りの作業
Claude Code（CLI）	npm run install-code	Claude Code のセッションを再起動します
Claude Desktop	npm run install-desktop	Settings → Capabilities → Skills から dist/storymap-skill.zip をアップロードし、アプリを完全に再起動します — また、Chat を使用します（下記参照）
ブラウザー上の claude.ai	—	リモートコネクターでのみ動作し、ローカルサーバーには接続できません。Claude Code または Claude Desktop を使用してください。

npm run install-code はスキルを ~/.claude/skills/storymap にコピーし、claude mcp add（ユーザースコープ）を通じて MCP サーバーを登録します。claude CLI を利用できない場合は、すぐに使えるコマンドを表示します。

npm run install-desktop はサーバーエントリーをプラットフォームの claude_desktop_config.json に書き込み（既存のエントリーは保持され、.bak バックアップが作成されます）、スキルの zip ファイルをビルドします。Claude Desktop のスキルストアはアプリによって管理されるため、スクリプトでは実行できない作業は、UI でのアップロード 1 回だけです。

Cowork ではなく Chat を使用してください。 Claude Desktop がローカル MCP サーバーに接続できるのは、Chat の会話のみです。Cowork モードでは Storymapper のツールを利用できません。Cowork が既定の環境になっている場合は、Chat に切り替えてください。ツールが表示されない場合は、まずここを確認してください。

どちらのコマンドも冪等です — Storymapper の新しいバージョンを取得した後に再実行してください。--data-dir=DIR を指定すると、データディレクトリを上書きできます（既定値：<repo>/.storymap-data）。

手動セットアップ（その他の MCP クライアント、その他のハーネス）

stdio MCP クライアントであれば、次の形式でサーバーを実行できます。

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

スキルパッケージ（npm run package-skill → dist/storymap-skill.zip）は通常の Markdown です — storymap/SKILL.md とその reference/ ファイルで構成されます。Codex のようなハーネスでは、指示ファイルを置く場所に展開し、たとえば AGENTS.md からハーネスが参照できるようにします。

Before planning work on the Storymapper board, read storymap/SKILL.md
(and the reference/ files it names) and follow that working method.

--data-dir には、HTTP サーバーが使用するものと同じディレクトリを指定してください。どちらのプロセスも 1 つの SQLite ファイルに対して同時に実行できます（WAL モードと busy-timeout を使用）。HTTP サーバーはすべての MCP 書き込みを WebSocket 経由で接続中のブラウザーに中継します。

MCP を使わずにスクリプトを実行する：CLI

すべてのツールは、同じツールコア上で実行される単発の CLI コマンドとしても利用できます。

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

結果の JSON は stdout に出力されます（終了コード：0 正常、1 ツールエラー、2 不明なツール／不正な引数）。引数は位置指定の JSON 文字列、--json=<json>、またはパイプからの stdin で指定します。これにより、MCP に対応していないシェルスクリプト、CI ジョブ、ハーネスでも、すべてのツールを利用できます。

1 つのデータディレクトリにつき実行できる storymapper server は 1 つだけです（PID ロックにより 2 つ目の起動を拒否します。クラッシュ後に古いロックを引き継ぐには --force を指定します）。MCP プロセスはこの制約の対象外で、常に同じデータディレクトリを共有できます。

セキュリティモデル（ローカルの単一ユーザー向け）

Storymapper はローカルの単一ユーザー向けツールです。1 台のマシンで、1 人のユーザーとそのエージェントが使用します。意図的に認証レイヤーを設けていません。

• サーバーはデフォルトで localhost にバインドします。認証を独自に用意しないまま、ループバック以外のインターフェースに公開しないでください（--host=0.0.0.0、リバースプロキシ、Docker のポートマッピングなど）。ポートにアクセスできる人は誰でも、すべてのプロジェクトを読み書きできます。
• CORS はループバックのオリジンに限定されています。クロスオリジンのブラウザーリクエストには Access-Control-Allow-Origin が返されず、変更を伴うメソッドは拒否されます。これにより、アクセスした不審なウェブサイトがローカル API を操作するのを防ぎます。WebSocket のアップグレードも同様にオリジンを検証します。
• 配信される HTML には Content-Security-Policy が設定され、すべてのレスポンスに X-Content-Type-Options: nosniff が含まれます。
• X-Actor-* ヘッダーは認証ではなく、実行者の記録に使用します。リビジョン履歴に誰が何をしたかを記録するもので、検証は行われません。
• 検証済みの ID、トークンで保護されたリモートアクセス、RBAC は後の段階で意図的に導入する予定です。認可の接続部分（server/identity.js）はすでに用意されています。

テスト

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

テストスイートは、tests/test-*.js を実行する独自のランナー（tests/run.js）です。純粋なユニットテスト、ストレージ／ミューテックス／リビジョンのテスト、プロセス内および stdio の MCP ラウンドトリップテスト、JSDOM レンダラーのテスト、実サーバーを使ったエンドツーエンドテストが含まれます。CI では Node 20 と 22 で実行します。テストが使用するのは一時ディレクトリのみです。テストを実行しても、データに触れることはありません。

ライセンス

Apache License 2.0 のもとでライセンスされています。詳しくは LICENSE と NOTICE をご覧ください。