Skip to main content
Glama

🚦 Branch-Thinking MCP Tool

Changelog Issues Node.js TypeScript MCP MIT License @dagrejs/graphlib ml-kmeans lru-cache @xenova/transformers @modelcontextprotocol/sdk chalk Mermaid pnpm

What’s New (2025-04):

  • Advanced visualization: clustering (k-means/degree), centrality overlays, edge bundling, and agentic overlays for tasks and priorities

  • Agentic cache & prefetch: LRU+TTL caches for embeddings, summaries, analytics, and proactive agent cache warming

  • Enhanced analytics: real-time, multi-branch, and focusNode support; agent-optimized metadata

  • Upgraded documentation and onboarding for agents and users


Features

  • 🌳 Branch Management: Create, focus, and navigate multiple lines of thought

  • 🔗 Cross-References: Link related thoughts across branches (typed, scored)

  • 💡 AI Insights: Automatic insight and summary generation

  • 🧠 Semantic Search: Find related thoughts using embeddings

  • 📊 Advanced Visualization:

    • Node clustering (k-means/degree)

    • Centrality overlays (closeness, betweenness)

    • Edge bundling

    • Task overlays (status, priority, next-action)

    • Agentic overlays and metadata for all nodes/edges

    • FocusNode and multi-branch visualization

  • ⚡ Agentic Cache & Prefetch:

    • LRU+TTL caches for embeddings, summaries, analytics

    • Proactive cache warming for agent workflows

  • 🗂️ Persistent Storage: Queryable, extensible, and never lose a thought

  • 🔄 Real-Time & Multi-Branch: Visualize and analyze multiple branches and nodes in real-time

  • 🛠️ Production-Grade: Robust error handling, performance optimizations, and agent/human-friendly APIs


Related MCP server: Thought Space - MCP Advanced Branch-Thinking Tool

🛠️ Technology Stack

  • Node.js (18+)

  • TypeScript (4.x)

  • @dagrejs/graphlib: Graph structure, algorithms, and analytics

  • ml-kmeans: Clustering for visualization

  • lru-cache: LRU+TTL caching for embeddings, summaries, analytics

  • @xenova/transformers: Embedding and summarization pipelines

  • @modelcontextprotocol/sdk: MCP protocol and agent integration

  • chalk: CLI output styling

  • Mermaid: Gantt/roadmap visualization

  • pnpm: Fast dependency management


Roadmap (Gantt)

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

Table of Contents


Why Branch-Thinking?

  • Agentic by Design: Built for both human and AI workflows—every command is agent-friendly.

  • True Branching: Organize, cross-link, and reason over ideas, code, and tasks in parallel.

  • AI-Native: Semantic search, auto-summarization, and insight generation out-of-the-box.

  • Persistent & Visual: Never lose a thought—everything is queryable, visualizable, and extensible.

Summary

Branch-Thinking MCP Tool is an advanced agentic platform for managing, visualizing, and reasoning over branching thoughts, tasks, code, and knowledge. It empowers both AI agents and humans to organize complex projects, cross-link ideas, and automate insight generation using a powerful branch-based paradigm. With semantic search, visualization, and persistent task/code management, it is designed for next-generation collaborative and autonomous workflows.

Branch-Thinking MCP Tool is an advanced agentic platform for managing, visualizing, and reasoning over branching thoughts, tasks, code, and knowledge. It empowers both AI agents and humans to organize complex projects, cross-link ideas, and automate insight generation using a powerful branch-based paradigm. With semantic search, visualization, and persistent task/code management, it is designed for next-generation collaborative and autonomous workflows.


Architecture & Flow

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

Quick Start

Get up and running in seconds:

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

Getting Started

1. Clone & Install

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. Configure (Optional)

For Claude Desktop integration, add to your claude_desktop_config.json:

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

3. Run

node dist/index.js

Real-World Usage Recipes

1. Knowledge Capture & Linking

# 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. Agentic Task Extraction

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

3. Visualization for Insight

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

🧑‍💻 Live Example: Agentic Workflow

# 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]

Replace [branchId] and [thoughtIdX] with actual IDs from list and history.


Command Reference

Branch Management

Command

Description

list

Show all branches with status

focus [branchId]

Switch focus to a branch

history [branchId?]

Show thought history

summarize-branch [branchId?]

AI summary of branch

review-branch [branchId?]

AI review of branch

visualize [branchId?]

Visual graph of connections

Thought & Insight Management

Command

Description

insights [branchId?]

Get AI-generated insights

crossrefs [branchId?]

Show cross-references

hub-thoughts [branchId?]

List hub thoughts

semantic-search [query]

Find similar thoughts

link-thoughts [from] [to] [type] [reason?]

Link two thoughts

add-snippet [content] [tags]

Save a code snippet

snippet-search [query]

Search code snippets

doc-thought [thoughtId]

Document a thought

Task Management

Command

Description

extract-tasks [branchId?]

Extract actionable items

list-tasks [branchId] [status] [assignee] [due]

List/filter tasks

update-task-status [taskId] [status]

Update a task’s status

summarize-tasks [branchId]

Summarize tasks

AI & Knowledge

Command

Description

ask [question]

AI answer from knowledge base

Best Practices

  • Always start with create-branch to ensure clean context.

  • Use list and focus to navigate between projects or lines of thought.

  • Leverage summarize-branch and insights after adding several thoughts to get AI-generated context.

  • Use link-thoughts to explicitly connect ideas, tasks, or code for richer semantic graphs.

  • After code changes, always run pnpm lint and pnpm build to catch errors early.

  • Decompose complex goals into sequences of thought/task/insight commands.

  • Iterate and adapt: Use feedback from summaries, reviews, and visualizations to refine next actions.

  • Explicitly specify parameters (branchId, status, assignee, etc.) for precise results.

  • Use cross-references and multi-hop links to foster creativity and bridge ideas.

  • Prompt agents (Claude, GPT-4, etc.) to "think step by step" or "use chain of thought" for best results.

Security

  • All persistent data is stored locally (default: project directory or MCP_STORAGE_PATH)

  • No external API calls unless configured

  • Agents/users are responsible for privacy of stored thoughts and tasks

  • To report security issues, please open an issue or email the maintainer.

Troubleshooting and FAQ

Q: The tool isn't responding! A: Check the MCP server logs and ensure configuration is correct.

Q: How do I reset storage? A: Delete or move the persistent storage directory (see config).

Q: How do I add a new command? A: Extend handleCommand in src/index.ts and document it in the README.

Accessibility and Internationalization

  • All badges/images have descriptive alt text.

  • English is the default language; contributions for translations are welcome.

  • Please open a PR or issue if you want to help localize this tool.

Contributing

Contributions, issues, and feature requests are welcome! Please open a PR or issue on GitHub.

  1. Fork this repo

  2. Create a new branch (git checkout -b feature/your-feature)

  3. Commit your changes

  4. Push to the branch

  5. Open a Pull Request


Credits

  • Concept & Testing: @ssdeanx

  • Core Code Generation: Claude, GPT-4, and Cascade

  • Implementation, Fixes, and Documentation: @ssdeanx


License

MIT

Available Tools

1 tool
branch-thinkingC

Branch-Thinking Tool

Purpose: Use branching commands to create, navigate, and analyze thought branches and tasks.

Usage: Provide a JSON payload with 'type' and relevant parameters in 'args' object. The tool returns an array of items in the format { type: string, text: string }.

Supported Commands:

  • create-branch: { type: 'create-branch', branchId }

  • focus: { type: 'focus', branchId }

  • add-thought: { type: 'add-thought', branchId, content }

  • semantic-search: { type: 'semantic-search', query, topN? }

  • extract-tasks: { type: 'extract-tasks', branchId? }

  • visualize: { type: 'visualize', branchId?, options? }

  • list-branches: { type: 'list-branches' }

  • history: { type: 'history', branchId }

  • insights: { type: 'insights', branchId }

  • crossrefs: { type: 'crossrefs', branchId }

  • hub-thoughts: { type: 'hub-thoughts', branchId }

  • link-thoughts: { type: 'link-thoughts', fromThoughtId, toThoughtId, linkType, reason? }

  • add-snippet: { type: 'add-snippet', content, tags, author? }

  • snippet-search: { type: 'snippet-search', query, topN? }

  • summarize-branch: { type: 'summarize-branch', branchId? }

  • doc-thought: { type: 'doc-thought', thoughtId }

  • review-branch: { type: 'review-branch', branchId? }

  • ask: { type: 'ask', question }

  • summarize-tasks: { type: 'summarize-tasks', branchId? }

  • advance-task: { type: 'advance-task', taskId, status }

  • assign-task: { type: 'assign-task', taskId, assignee }

  • reset-session: { type: 'reset-session' }

  • clear-cache: { type: 'clear-cache' }

  • get-cache-stats: { type: 'get-cache-stats' }

Visualization Options:

  • clustering: { type: 'clustering', algorithm? }

  • centrality: { type: 'centrality', metric? }

  • overlays: { type: 'overlays', features? }

  • analytics: { type: 'analytics', metrics? }

Example Calls and Expected Responses:

// Add a thought
{ "name": "branch-thinking", "args": { "type": "add-thought", "branchId": "research", "content": "Define MCP best practices" } }
// →
[{"type":"text","text":"Thought added to branch research."}]
// Get insights
{ "name": "branch-thinking", "args": { "type": "insights", "branchId": "research" } }
// →
[{"type":"text","text":"Insights for branch research: ['Best practices cluster around workflow safety and semantic search.', 'Cross-references indicate high reuse of planning patterns.']"}]
// Get cross-references
{ "name": "branch-thinking", "args": { "type": "crossrefs", "branchId": "research" } }
// →
[{"type":"text","text":"Cross-references for branch research: [{ from: 't1', to: 't3', type: 'supports', reason: 't1 evidence for t3' }, { from: 't2', to: 't4', type: 'related' }]"}]
// Extract tasks
{ "name": "branch-thinking", "args": { "type": "extract-tasks", "branchId": "research" } }
// →
[{"type":"text","text":"Tasks extracted: [{ id: 'task-123', content: 'Document MCP safety rules', status: 'open' }]"}]
// Summarize tasks
{ "name": "branch-thinking", "args": { "type": "summarize-tasks", "branchId": "research" } }
// →
[{"type":"text","text":"Task summary: 1 open, 2 in progress, 0 closed."}]
// Advance a task
{ "name": "branch-thinking", "args": { "type": "advance-task", "taskId": "task-123", "status": "in_progress" } }
// →
[{"type":"text","text":"Task task-123 status updated to in_progress."}]
// Assign a task
{ "name": "branch-thinking", "args": { "type": "assign-task", "taskId": "task-123", "assignee": "alice" } }
// →
[{"type":"text","text":"Task task-123 assigned to alice."}]
// Semantic search
{ "name": "branch-thinking", "args": { "type": "semantic-search", "query": "workflow planning", "topN": 3 } }
// →
[{"type":"text","text":"Top 3 semantic matches for 'workflow planning' returned."}]
// Link thoughts
{ "name": "branch-thinking", "args": { "type": "link-thoughts", "fromThoughtId": "t1", "toThoughtId": "t2", "linkType": "supports" } }
// →
[{"type":"text","text":"Linked thought t1 to t2 as 'supports'."}]
// Summarize branch
{ "name": "branch-thinking", "args": { "type": "summarize-branch", "branchId": "research" } }
// →
[{"type":"text","text":"Summary for branch research: ..."}]
// Review branch
{ "name": "branch-thinking", "args": { "type": "review-branch", "branchId": "research" } }
// →
[{"type":"text","text":"Branch research reviewed. 2 suggestions found."}]

Inputs: content, branchId, parentBranchId, type, +5 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 1 tool

    Disambiguation5/5

    The single tool 'branch-thinking' has no other tools to be confused with, so disambiguation is perfect. All functionality is contained within one tool, eliminating any possibility of misselection between multiple tools.

    Naming Consistency5/5

    With only one tool named 'branch-thinking', naming consistency is inherently perfect. There are no other tool names to compare against, so no inconsistency can exist in the tool set.

    Tool Count2/5

    The server has only one tool despite offering extensive functionality (over 20 commands). This is a significant mismatch as the domain suggests a need for multiple specialized tools (e.g., separate tools for branch management, task operations, search, etc.). A single tool forces all operations through one interface, which is inappropriate for the apparent scope.

    Completeness5/5

    The tool provides comprehensive coverage for thought branching and task management, including creation, navigation, analysis, visualization, task extraction, assignment, and various utility functions. No obvious gaps exist; it supports full lifecycle operations for branches, thoughts, and tasks within its domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers