🚦 Branch-Thinking MCP Tool

🚦 Branch-Thinking MCP Tool

新機能（2025-04）：

• 高度な可視化：クラスタリング（k-means／degree）、中心性オーバーレイ、エッジのバンドル化、タスクや優先度を表示するエージェント向けオーバーレイ
• エージェント向けキャッシュとプリフェッチ：埋め込み、要約、分析用のLRU+TTLキャッシュ、およびエージェントのキャッシュを事前に温める機能
• 分析機能の強化：リアルタイム、複数ブランチ、focusNodeへの対応、エージェント向けに最適化されたメタデータ
• エージェントとユーザー向けのドキュメントとオンボーディングを改善

---

機能

• 🌳 ブランチ管理： 複数の思考の流れを作成、フォーカス、移動できます
• 🔗 相互参照： ブランチ間で関連する思考をリンクします（タイプとスコア付き）
• 💡 AI インサイト： インサイトと要約を自動生成します
• 🧠 セマンティック検索： 埋め込みを使って関連する思考を見つけます
• 📊 高度な可視化：
  • ノードのクラスタリング（k-means／degree）
  • 中心性オーバーレイ（近接中心性、媒介中心性）
  • エッジのバンドル化
  • タスクのオーバーレイ（ステータス、優先度、次のアクション）
  • すべてのノード／エッジに対するエージェント向けオーバーレイとメタデータ
  • FocusNodeと複数ブランチの可視化
• ⚡ エージェント向けキャッシュとプリフェッチ：
  • 埋め込み、要約、分析用のLRU+TTLキャッシュ
  • エージェントのワークフロー向けにキャッシュを事前に温める機能
• 🗂️ 永続ストレージ： クエリ可能で拡張性があり、思考を失うことはありません
• 🔄 リアルタイムと複数ブランチ： 複数のブランチとノードをリアルタイムで可視化、分析します
• 🛠️ 本番環境対応： 堅牢なエラー処理、パフォーマンスの最適化、エージェントと人間の双方に使いやすいAPI

---

🛠️ 技術スタック

• Node.js（18+）
• TypeScript（4.x）
• @dagrejs/graphlib：グラフ構造、アルゴリズム、分析
• ml-kmeans：可視化向けのクラスタリング
• lru-cache：埋め込み、要約、分析用のLRU+TTLキャッシュ
• @xenova/transformers：埋め込みと要約のパイプライン
• @modelcontextprotocol/sdk：MCP プロトコルとエージェントの統合
• chalk：CLI 出力のスタイル設定
• Mermaid：ガントチャート／ロードマップの可視化
• pnpm：高速な依存関係管理

---

ロードマップ（ガントチャート）

gantt
    title Branch-Thinking MCP Roadmap (2025)
    dateFormat  YYYY-MM-DD
    section Q2 2025
    Advanced Visualization/Analytics :done,      vis1, 2025-04-01,2025-04-20
    Agentic Cache & Prefetch         :done,      cache1, 2025-04-10,2025-04-22
    Enhanced Agentic Docs            :done,      doc1, 2025-04-15,2025-04-25
    Real-time Collaboration          :active,    collab1, 2025-04-20,2025-06-01
    Web Visualization Dashboard      :active,    webviz1, 2025-04-25,2025-06-15
    section Q3 2025
    Plugin System                    :planned,   plugin1, 2025-06-15,2025-07-15
    Mobile/Tablet UI                 :planned,   mobile1, 2025-07-01,2025-08-01
    AI Branch Merging                :planned,   merge1, 2025-07-15,2025-08-15
    Knowledge Base Sync              :planned,   sync1, 2025-08-01,2025-09-01

---

目次

• Branch-Thinking を選ぶ理由
• 概要
• 機能
• クイックスタート
• はじめに
• 実践的な使用例
• アーキテクチャとフロー
• ロードマップ（ガントチャート）
• テストと品質
• セキュリティ
• アクセシビリティと国際化
• トラブルシューティングと FAQ
• ベストプラクティス
• 貢献
• 変更履歴
• 参考資料と関連プロジェクト
• クレジット
• ライセンス

---

Branch-Thinking を選ぶ理由

• エージェントを前提とした設計： 人間と AI の両方のワークフロー向けに構築されており、すべてのコマンドがエージェントに対応しています。
• 真の分岐： アイデア、コード、タスクを並行して整理し、相互にリンクし、推論できます。
• AI ネイティブ： セマンティック検索、自動要約、インサイト生成を標準で利用できます。
• 永続性と視覚化： 考えを失うことはありません。すべてを検索、視覚化、拡張できます。

概要

Branch-Thinking MCP Tool は、分岐する思考、タスク、コード、ナレッジを管理、視覚化し、それらについて推論するための、高度なエージェント型プラットフォームです。強力なブランチベースのパラダイムにより、AI エージェントと人間の両方が複雑なプロジェクトを整理し、アイデアを相互にリンクし、インサイトの生成を自動化できます。セマンティック検索、視覚化、永続的なタスク／コード管理を備え、次世代の協調型・自律型ワークフロー向けに設計されています。

Branch-Thinking MCP Tool は、分岐する思考、タスク、コード、ナレッジを管理、視覚化し、それらについて推論するための、高度なエージェント型プラットフォームです。強力なブランチベースのパラダイムにより、AI エージェントと人間の両方が複雑なプロジェクトを整理し、アイデアを相互にリンクし、インサイトの生成を自動化できます。セマンティック検索、視覚化、永続的なタスク／コード管理を備え、次世代の協調型・自律型ワークフロー向けに設計されています。

---

アーキテクチャとフロー

flowchart TD
    User([User/Agent 🤖])
    CLI([CLI/API])
    BM[BranchManager 🧠]
    EmbCache[[Embedding/Summary Cache]]
    Storage[(Persistent Storage 💾)]
    Viz([Visualization/Analytics])
    Tasks([Task Extraction])
    Snippets([Code Snippet Storage])

    User-->|Commands/Queries|CLI
    CLI-->|Manage/Query|BM
    BM-->|Cache|EmbCache
    BM-->|Save/Load|Storage
    BM-->|Visualize|Viz
    BM-->|Tasks|Tasks
    BM-->|Snippets|Snippets
    BM-->|Results|CLI
    CLI-->|Output|User

---

クイックスタート

数秒で利用を開始できます。

pnpm install  # Recommended for speed (or npm install)
pnpm build
node dist/index.js --help  # See available commands

---

はじめに

1. クローンとインストール

git clone https://github.com/your-org/branch-thinking-mcp.git
cd branch-thinking-mcp
pnpm install  # Or npm install
pnpm build   # Or npm run build

2. 設定（任意）

Claude Desktop と連携するには、claude_desktop_config.json に追加します。

"branch-thinking": {
  "command": "node",
  "args": [
    "/your-custom-mcp-dir-here/branch-thinking/dist/index.js"
  ]
}

3. 実行

node dist/index.js

---

実践的な使用例

1. ナレッジの記録とリンク

# Batch capture meeting notes
add-thought dev "Discussed semantic search improvements" note
add-thought dev "Agreed to refactor API" decision
# Link related thoughts
link-thoughts t1 t2 supports "API refactor supports search improvements"

2. エージェントによるタスクの抽出

# Extract and manage tasks from a research branch
extract-tasks research
list-tasks research open
update-task-status task-1 in_progress

3. インサイトを得るための視覚化

# Generate and interpret a knowledge graph
visualize dev
# Review AI-generated summary
summarize-branch dev

---

🧑‍💻 ライブ例：エージェント型ワークフロー

# 1. Create a new branch for your project or idea
create-branch "AI Research"

# 2. Add thoughts and observations
add-thought [branchId] "Explore semantic search for agent workflows" analysis
add-thought [branchId] "Test cross-linking and summarization" observation

# 3. Link related thoughts
link-thoughts [thoughtId1] [thoughtId2] supports "Thought 2 validates Thought 1"

# 4. See your knowledge graph
visualize [branchId]

# 5. Extract tasks and get AI review
extract-tasks [branchId]
review-branch [branchId]

[branchId] と [thoughtIdX] は、list と history で取得した実際の ID に置き換えてください。

---

コマンドリファレンス

ブランチ管理

コマンド	説明
list	すべてのブランチとステータスを表示
focus [branchId]	フォーカスするブランチを切り替え
history [branchId?]	思考の履歴を表示
summarize-branch [branchId?]	ブランチを AI で要約
review-branch [branchId?]	ブランチを AI でレビュー
visualize [branchId?]	関連をグラフで視覚化

思考とインサイトの管理

コマンド	説明
insights [branchId?]	AI が生成したインサイトを取得
crossrefs [branchId?]	相互参照を表示
hub-thoughts [branchId?]	ハブとなる思考を一覧表示
semantic-search [query]	類似する思考を検索
link-thoughts [from] [to] [type] [reason?]	2 つの思考をリンク
add-snippet [content] [tags]	コードスニペットを保存
snippet-search [query]	コードスニペットを検索
doc-thought [thoughtId]	思考を文書化

タスク管理

コマンド	説明
extract-tasks [branchId?]	実行可能な項目を抽出
list-tasks [branchId] [status] [assignee] [due]	タスクを一覧表示／フィルター
update-task-status [taskId] [status]	タスクのステータスを更新
summarize-tasks [branchId]	タスクを要約

AI とナレッジ

コマンド	説明
ask [question]	ナレッジベースからの AI による回答

ベストプラクティス

• クリーンなコンテキストを確保するため、必ず create-branch から始めてください。
• プロジェクトや思考の流れを切り替えるには、list と focus を使用してください。
• いくつかの思考を追加した後に summarize-branch と insights を活用し、AI が生成したコンテキストを取得してください。
• アイデア、タスク、コードを明示的に結び付け、より豊かなセマンティックグラフを作成するには、link-thoughts を使用してください。
• コードを変更した後は、早期にエラーを検出するため、必ず pnpm lint と pnpm build を実行してください。
• 複雑な目標は、思考・タスク・インサイトのコマンドを組み合わせた手順に分解してください。
• 反復と適応を重ねてください。要約、レビュー、可視化から得たフィードバックを活用し、次のアクションを改善してください。
• 正確な結果を得るため、パラメーター（branchId、status、assignee など）を明示的に指定してください。
• 相互参照と複数ホップのリンクを活用し、創造性を促してアイデアを結び付けてください。
• 最良の結果を得るため、エージェント（Claude、GPT-4 など）には「段階的に考える」または「思考の連鎖を使用する」よう促してください。

セキュリティ

• すべての永続データはローカルに保存されます（デフォルト：プロジェクトディレクトリまたは MCP_STORAGE_PATH）。
• 設定しない限り、外部 API 呼び出しは行われません。
• 保存された思考やタスクのプライバシー保護は、エージェント／ユーザーの責任です。
• セキュリティ上の問題を報告するには、issue を作成するか、メンテナーにメールでご連絡ください。

トラブルシューティングと FAQ

Q：ツールが応答しません！ A：MCP サーバーのログを確認し、設定が正しいことを確認してください。

Q：ストレージをリセットするにはどうすればよいですか？ A：永続ストレージのディレクトリを削除するか、別の場所に移動してください（設定を参照）。

Q：新しいコマンドを追加するにはどうすればよいですか？ A：src/index.ts の handleCommand を拡張し、README に記載してください。

アクセシビリティと国際化

• すべてのバッジ／画像に説明的な代替テキストが付いています。
• デフォルトの言語は英語です。翻訳への貢献を歓迎します。
• このツールのローカライズにご協力いただける場合は、PR または issue を作成してください。

コントリビューション

コントリビューション、issue、機能リクエストを歓迎します！GitHub で PR または issue を作成してください。

1. このリポジトリをフォークします
2. 新しいブランチを作成します（git checkout -b feature/your-feature）
3. 変更をコミットします
4. ブランチにプッシュします
5. プルリクエストを作成します

参考資料と関連プロジェクト

• Model Context Protocol (MCP)
• Sequential Thinking Tool
• Obsidian
• Logseq

---

クレジット

• コンセプトとテスト： @ssdeanx
• コアコード生成： Claude、GPT-4、Cascade
• 実装、修正、ドキュメント： @ssdeanx

---

ライセンス

MIT