🚦 Branch-Thinking MCP Tool
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
🛠️ 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)
Table of Contents
- Why Branch-Thinking?
- Summary
- Features
- Quick Start
- Getting Started
- Real-World Usage Recipes
- Architecture & Flow
- Roadmap (Gantt)
- Testing & Quality
- Security
- Accessibility & Internationalization
- Troubleshooting & FAQ
- Best Practices
- Contributing
- Changelog
- References & Related Projects
- Credits
- License
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
Quick Start
Get up and running in seconds:
Getting Started
1. Clone & Install
2. Configure (Optional)
For Claude Desktop integration, add to your claude_desktop_config.json
:
3. Run
Real-World Usage Recipes
1. Knowledge Capture & Linking
2. Agentic Task Extraction
3. Visualization for Insight
🧑💻 Live Example: Agentic Workflow
Replace
[branchId]
and[thoughtIdX]
with actual IDs fromlist
andhistory
.
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
andfocus
to navigate between projects or lines of thought. - Leverage
summarize-branch
andinsights
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
andpnpm 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.
- Fork this repo
- Create a new branch (
git checkout -b feature/your-feature
) - Commit your changes
- Push to the branch
- Open a Pull Request
References and Related Projects
Credits
- Concept & Testing: @ssdeanx
- Core Code Generation: Claude, GPT-4, and Cascade
- Implementation, Fixes, and Documentation: @ssdeanx
License
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
An MCP server that enables managing multiple lines of thought with features like branch navigation, cross-references between related thoughts, and insight generation from key points.
- Features
- 🛠️ Technology Stack
- Roadmap (Gantt)
- Table of Contents
- Why Branch-Thinking?
- Summary
- Architecture & Flow
- Quick Start
- Getting Started
- Real-World Usage Recipes
- 🧑💻 Live Example: Agentic Workflow
- Command Reference
- Best Practices
- Security
- Troubleshooting and FAQ
- Accessibility and Internationalization
- Contributing
- References and Related Projects
- Credits
- License
Related MCP Servers
- AsecurityAlicenseAqualityAn MCP server for navigating thought processes using branches, supporting thought cross-references and priority tracking to enhance insight generation and structured idea exploration.Last updated -120TypeScriptMIT License
- AsecurityAlicenseAqualityAn adaptation of the MCP Sequential Thinking Server designed to guide tool usage in problem-solving. This server helps break down complex problems into manageable steps and provides recommendations for which MCP tools would be most effective at each stage.Last updated -1361121TypeScriptMIT License
- -securityAlicense-qualityAn MCP tool enabling structured thinking and analysis across multiple AI platforms through branch management, semantic analysis, and cognitive enhancement.Last updated -8TypeScriptMIT License
- -securityAlicense-qualityAn MCP server that implements the 'think' tool, providing Claude with a dedicated space for structured thinking during complex problem-solving tasks to improve reasoning capabilities.Last updated -48PythonMIT License