MCP Brainstorm Server

インタラクティブなAI支援によるブレインストーミング、計画立案、および視覚化のための、軽量でリソース効率の高いローカルホストUIを起動するMCP（Model Context Protocol）サーバーです。Claudeやその他のAIエージェントとシームレスに連携し、共同作業ワークフローを実現するように設計されています。

機能概要

基本ワークフロー

1. 検出: ブレインストーミングに関連するキーワード（brainstorm, plan, think, how do...など）に言及すると、AIエージェントがインタラクティブUIを使用するかどうかを尋ねます。

2. 起動: サーバーがローカルホスト上でセッション固有のURLで起動します。

3. インタラクション: Mermaid図やTailwindスタイルのHTML UIを使用してブレインストーミング資料をレンダリングします。

4. 送信: ユーザーはクリック可能なボタンを操作したり、コメントを入力したり、必要に応じて画像をアップロード/貼り付けたりします。

5. 取得: AIエージェントが送信された回答を読み取り、作業を継続します。

6. ドキュメント化: 将来の参照用に plans/*.md への保存が可能です。

特徴

• マルチセッションサポート: 各AIエージェントセッションには独自のURL (localhost:{port}/{sessionid}) が割り当てられ、タブ名には作業ディレクトリが反映されるため、容易に区別できます。

• エージェント間での単一インストール共有: 1つのローカルクローンと1つのPython環境をClaude、Codex、その他のMCP互換エージェントで同時に再利用できるため、エージェントごとにインストールするのではなく、マシンごとに1回インストールするだけで済みます。

• リッチコンテンツレンダリング:

  • グラフ、フローチャート、視覚化のためのMermaid図

  • ブレインストーミングのオプションやインターフェースのためのTailwind CSSスタイルのUI

  • 図や表を埋め込んだMarkdown互換フォーマットのレンダラー

• インタラクティブ要素:

  • セクションやオプションの自動生成ID（参照用）

  • ユーザー選択用のクリック可能なボタン

  • インラインコメント入力フィールド

  • 送信/完了ワークフロー

• 画像サポート:

  • ファイルピッカーによるローカルファイルアップロード

  • インターネットアクセス可能なURL

  • クリップボードからの貼り付け機能

• リソース効率: シングルユーザー操作向けに設計された軽量なPythonサーバー

• ループバック限定: HTTP UIはループバックアドレスに厳密に制限されており、ローカル以外のクライアントからのアクセスを拒否します。

Related MCP server: tldraw-mcp

アーキテクチャ

コンポーネント

├── mcp_server.py          # MCP server implementation (Python)
├── server/                # localhost UI server
│   ├── app.py            # Flask/FastAPI server
│   ├── templates/        # HTML templates
│   └── static/           # CSS, JS, assets
└── requirements.txt      # Dependencies

ランタイムデータは、デフォルトでリポジトリ外の ~/.mcp/brainstorm-mcp/ に保存されます：

~/.mcp/brainstorm-mcp/
├── sessions/             # Session state storage
│   └── assets/           # Uploaded or pasted image data
├── plans/                # User-saved markdown plans
└── preferences/          # Brainstorm preferences (instructions to the AI)
    ├── global.json       # Machine-wide defaults
    └── projects/         # Per-project overrides, keyed by hashed absolute path

プロジェクトごとの設定は中央データルート（プロジェクトリポジトリ内ではありません）に保存されるため、プロジェクトを設定してもそのプロジェクトの作業ツリーにファイルが追加されることはありません。

セッション管理

• 各セッションには一意の sessionid (UUIDなど) が割り当てられます

• セッション状態は、デフォルトでユーザーの ~/.mcp/brainstorm-mcp/ ディレクトリ内の軽量な永続ストレージに保存されます

• URL: localhost:PORT/{sessionid}

• タブタイトルにはAIエージェント端末の作業ディレクトリ (pwd) が反映されます

技術スタック

• MCPフレームワーク: Python MCP SDK

• バックエンド: Python (軽量HTTPサーバー用のFlask/FastAPI)

• フロントエンドレンダリング:

  • 図: Mermaid.js

  • UI/スタイリング: Tailwind CSS

  • Markdown: Mermaidサポートを埋め込んだ互換フォーマット

• ストレージ: JSON/SQLite (セッション状態用の最小限の構成)

インストールと使用方法

前提条件

• Python 3.9+

• MCPクライアント (Claudeまたは互換性のあるAIエージェント)

完全なインストールガイド

以下を含む完全なインストール手順については：

• 既存のローカルクローンの使用

• 推奨される共有MCPサーバー場所へのクローン

• Codexへのサーバー接続

• Claude Codeへのサーバー接続

• 複数のエージェント間での1つのインストールの再利用

INSTALL.md を参照してください。

セットアップ

git clone <repo-url>
cd mcp-brainstorm-server
pip install -r requirements.txt

サーバーの実行

サーバーは、AIエージェントがブレインストーミングのキーワードを検出したときにMCPツールによってオンデマンドで起動されます。ユーザーが手動で起動することも可能です：

python mcp_server.py

必要な依存関係

anthropic-mcp
flask  # or fastapi
pydantic
python-dotenv

プロトコルフロー

例: 機能の計画立案

1. ユーザー: 「この機能のアーキテクチャをブレインストーミングしよう」

2. AIエージェント: キーワードを検出 → 「インタラクティブなブレインストーミングUIを開きますか？」と尋ねる

3. ユーザー: 「はい」

4. サーバー: localhost:8080/abc-def-123-ghi で起動 (pwdに基づくsessionid)

5. UI: クリック可能なオプション、コメントフィールド、画像アップロードエリアを備えた、考えられるアーキテクチャのMermaid図をレンダリング

6. ユーザー: 好みのアーキテクチャオプションをクリックし、コメントを追加し、必要に応じて参照図をアップロード

7. ユーザー: 「送信」をクリック

8. サーバー: sessionidの下に送信内容を保存

9. ユーザー: AIエージェントに戻り、「回答を送信しました」と伝える

10. AIエージェント: MCP経由で送信内容を取得 → ユーザーの入力を基に計画を継続

11. AIエージェント (オプション): 「この計画を保存しますか？推奨場所: plans/feature-architecture.md」 ディスク上のデフォルト保存場所: ~/.mcp/brainstorm-mcp/plans/feature-architecture.md

MCPツール仕様

利用可能なツール

start_brainstorm_session

インタラクティブなブレインストーミングUIセッションを開始します。

入力:

• prompt (str): 初期のブレインストーミングプロンプト/コンテキスト

• content_type (str): "mermaid", "html", または "markdown"

• working_dir (str, オプション): 現在の作業ディレクトリ (タブタイトルに使用)

出力:

• session_id (str): 一意のセッション識別子

• url (str): UIにアクセスするための完全なローカルホストURL

• port (int): 使用されたポート番号

get_session_response

完了したセッションからユーザーの送信内容を取得します。

入力:

• session_id (str): セッション識別子

出力:

• response (dict): ユーザーが送信した選択肢、コメント、画像

• timestamp (str): 送信日時

• status (str): "pending", "submitted", "expired"

list_sessions

すべてのアクティブなセッションを一覧表示します。

出力:

• sessions (list): ID、URL、作成時間を含むアクティブなセッションオブジェクトの配列

close_session

セッションを終了し、クリーンアップします。

入力:

• session_id (str): 閉じるセッション

set_brainstorm_preferences

AIがどのようにブレインストーミングを行うかを決定するユーザー向け指示を保存します。設定されていないフィールドは以前の値を保持するため、一度に1つのフィールドを更新できます。

入力:

• scope (str): "global" (マシン全体のデフォルト) または "project" (1つのプロジェクトに対する上書き — project_path が必要)

• project_path (str, オプション): プロジェクトへの絶対パス。scope="project" の場合に必須。検索キーとして使用され、ファイル自体は ~/.mcp/brainstorm-mcp/preferences/projects/ の下に中央管理されます。

• uiux_level (str, オプション): ユーザーのUI/UXスキルレベル（自由記述）。推奨値: never_before, amateur, intermediate, expert。

• uiux_style (str, オプション): プロジェクトのUI/UXスタイル（自由記述）。例: corporate internal tool, marketing-heavy landing page, children education app。

• questioning_style (str, オプション): AIがどのようにユーザーに質問すべきか。推奨値: autonomous_review (AIが構築し、ユーザーは最小限の質問でレビューする) または collaborative_stepwise (AIが段階的にブレインストーミングを行い、想像されるUIに収束させるために多くの質問をする)。

出力: マージ後の有効な設定（プロジェクトがグローバルを上書き）、および各フィールドのソース。

get_brainstorm_preferences

有効なブレインストーミング設定を読み取ります。プロジェクトの値は、フィールドごとにグローバル値を上書きします。

入力:

• project_path (str, オプション): グローバルデフォルトにマージする絶対プロジェクトパス。省略した場合はグローバルのみを読み取ります。

出力: set_brainstorm_preferences と同じ形式。AIはすべての start_brainstorm_session レスポンスでこのオブジェクトをインラインで受け取るため、二度質問する必要はありません。

設計原則

• 最小限のリソース使用: シングルユーザー操作、重い依存関係なし

• 可能な限りステートレス: セッションはディスクに保存されない限り一時的

• 参照の容易さ: すべてのインタラクティブ要素に自動生成IDを付与

• AIエージェントフレンドリー: 解析と継続が容易な構造化レスポンス形式

• 視覚的な明瞭さ: Markdown/MermaidレンダリングによるUIセクションの明確な分離

今後の拡張予定

• 永続的なセッション履歴

• リアルタイムコラボレーション（将来的なマルチユーザーサポート）

• ブレインストーミングテンプレート用のカスタムTailwindコンポーネントライブラリ

• さまざまな形式（PDF、PNGなど）への組み込みエクスポート

• 自動計画バージョン管理のためのgit統合

ライセンス

MIT

貢献

貢献を歓迎します。PythonコードについてはPEP 8に従い、サーバーが軽量であることを維持してください。