thought-chain-mcp
Advanced tools
Transform any AI model into an advanced reasoning engine
This MCP server empowers non-reasoning models with sophisticated step-by-step thinking capabilities, enabling complex problem-solving, structured analysis, and persistent thought processes across sessions.
While modern AI models vary in their native reasoning capabilities, the Thought Chain MCP Server levels the playing field by providing:
Perfect for: Enhancing models that lack native reasoning capabilities, standardizing thinking processes across different AI assistants, and maintaining audit trails for complex decision-making.
A Model Context Protocol (MCP) server that enables step-by-step reasoning with persistence, allowing you to save and recall thought processes across sessions.
The Thought Chain MCP Server provides a structured approach to complex reasoning by enabling users to build thought chains incrementally, with full persistence and recall capabilities. This reliable solution ensures that complex reasoning work is never lost and can be built upon across sessions and across different AI coding assistants.
Universal Compatibility: Works with ANY MCP-compatible editor, extension, or AI assistant including Claude Desktop, Cursor, Cline, Roo Code, Windsurf, VS Code with MCP extensions, and custom implementations. Your thought chains persist regardless of which tool you're using.
The easiest way to install and use the Thought Chain MCP Server:
npx thought-chain-mcp
For global access:
npm install -g thought-chain-mcp
Once installed globally, you can run:
thought-chain-mcp
Run directly without installing:
npx thought-chain-mcp@latest
Navigate to the project directory:
cd c:\mcpservers\thought-chain-mcp
Install dependencies:
npm install
Configure your AI Assistant:
This MCP server works with multiple AI coding assistants. Choose your preferred platform below:
On Windows, edit your Claude Desktop config file at:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"thought-chain": {
"command": "npx",
"args": ["thought-chain-mcp"]
}
}
}
Alternative (if installed globally):
{
"mcpServers": {
"thought-chain": {
"command": "thought-chain-mcp"
}
}
}
Add to your Cursor settings (settings.json):
{
"mcp.servers": {
"thought-chain": {
"command": "npx",
"args": ["thought-chain-mcp"]
}
}
}
Alternative (if installed globally):
{
"mcp.servers": {
"thought-chain": {
"command": "thought-chain-mcp"
}
}
}
Add to your Cline configuration file:
{
"mcpServers": {
"thought-chain": {
"command": "npx",
"args": ["thought-chain-mcp"]
}
}
}
Alternative (if installed globally):
{
"mcpServers": {
"thought-chain": {
"command": "thought-chain-mcp"
}
}
}
Add to your Roo Code MCP configuration:
{
"mcpServers": {
"thought-chain": {
"command": "npx",
"args": ["thought-chain-mcp"]
}
}
}
Alternative (if installed globally):
{
"mcpServers": {
"thought-chain": {
"command": "thought-chain-mcp"
}
}
}
Add to your Windsurf configuration:
{
"mcp.servers": {
"thought-chain": {
"command": "npx",
"args": ["thought-chain-mcp"]
}
}
}
Alternative (if installed globally):
{
"mcp.servers": {
"thought-chain": {
"command": "thought-chain-mcp"
}
}
}
For ANY editor, extension, or tool that supports MCP, add the server configuration to your MCP settings:
{
"mcpServers": {
"thought-chain": {
"command": "npx",
"args": ["thought-chain-mcp"]
}
}
}
Alternative (if installed globally):
{
"mcpServers": {
"thought-chain": {
"command": "thought-chain-mcp"
}
}
}
This includes:
Optional: Add AI Instructions (Copilot Users)
While not required for the MCP server to function, you can add the mcp.instructions.md file to your Copilot prompts directory to encourage consistent use of the thought chain process:
mcp.instructions.md to your Copilot prompts directoryDatabase Initialization
The server will automatically create a fresh SQLite database in your home directory (~/.thought-chain-mcp/thoughts.db) on first run. This database:
Restart your AI Assistant to load the new MCP server
Development mode (with auto-restart):
npm run dev
Production mode:
npm start
Run tests:
npm test
Security audit:
npm run security-check
I need to solve a complex problem. Let me think through it step by step.
1. thought_chain(action="new_chain") - Start fresh
2. thought_chain(action="add_step", thought="First, I need to understand the core issue...")
3. thought_chain(action="add_step", thought="Based on my analysis above, the key factors are...", reflection="This builds on my initial understanding by identifying specific elements")
4. thought_chain(action="review_chain") - See full reasoning chain
5. thought_chain(action="conclude", thought="Therefore, my recommendation is...")
1. recall_thoughts(query="optimization") - Find chains about optimization
2. load_thought_chain(chain_id="abc123") - Continue previous work
3. thought_chain(action="add_step", thought="Building on my previous analysis...")
1. thought_chain(action="new_chain", thought="Analyzing the system architecture challenge...")
2. thought_chain(action="add_step", thought="Current bottlenecks identified: database queries, API response times", reflection="This establishes the baseline issues to address")
3. thought_chain(action="add_step", thought="Proposed solutions: connection pooling, query optimization, caching layer", reflection="These solutions directly address the identified bottlenecks")
4. thought_chain(action="review_chain")
5. thought_chain(action="conclude", thought="Implementation priority: caching first, then query optimization, finally connection pooling")
1. thought_chain(action="new_chain", thought="Researching best practices for microservices security...")
2. thought_chain(action="add_step", thought="Key areas: authentication, authorization, data encryption, service mesh", reflection="This categorizes the security domains to investigate")
3. thought_chain(action="add_step", thought="Authentication findings: OAuth 2.0 with JWT tokens recommended", reflection="Industry standard approach with good tooling support")
4. thought_chain(action="add_step", thought="Authorization approach: RBAC with fine-grained permissions", reflection="Balances security with operational flexibility")
Here's a complete example of using the thought chain process to solve a complex problem:
User: I need to optimize our slow database queries. The system is taking 10+ seconds for some reports.
AI: Let me think through this systematically using the thought chain process.
1. **Start Analysis**
thought_chain(action="new_chain", thought="Analyzing database performance issue with 10+ second query times")
✅ Started new thought chain: analyzing-database-performance
2. **Identify Root Causes**
thought_chain(action="add_step",
thought="Potential causes: missing indexes, large table scans, inefficient joins, lack of query optimization")
✅ Added step 1: Potential causes identified
3. **Analyze Current State**
thought_chain(action="add_step",
thought="Need to examine: EXPLAIN plans, slow query logs, table sizes, index usage statistics",
reflection="This builds on the potential causes by identifying specific diagnostic steps")
✅ Added step 2: Diagnostic approach defined
4. **Propose Solutions**
thought_chain(action="add_step",
thought="Solutions: add composite indexes, optimize WHERE clauses, implement query caching, consider denormalization")
✅ Added step 3: Solution strategies identified
5. **Prioritize Implementation**
thought_chain(action="add_step",
thought="Priority order: 1) Add missing indexes (quick win), 2) Optimize queries (medium effort), 3) Add caching (long-term solution)",
reflection="This prioritization balances impact vs implementation effort")
✅ Added step 4: Implementation priority set
6. **Review Full Chain**
thought_chain(action="review_chain")
📋 Complete Thought Chain:
Step 1: Analyzing database performance issue with 10+ second query times
Step 2: Potential causes: missing indexes, large table scans, inefficient joins, lack of query optimization
Step 3: Need to examine: EXPLAIN plans, slow query logs, table sizes, index usage statistics
Step 4: Solutions: add composite indexes, optimize WHERE clauses, implement query caching, consider denormalization
Step 5: Priority order: 1) Add missing indexes (quick win), 2) Optimize queries (medium effort), 3) Add caching (long-term solution)
7. **Conclude with Action Plan**
thought_chain(action="conclude",
thought="Action plan: Start with index analysis using EXPLAIN, implement top 3 missing indexes, then optimize slow queries, finally implement Redis caching for frequently accessed data")
✅ Concluded thought chain with actionable implementation plan
thought_chainMain tool for building Thought Chain
Actions:
new_chain: Start a fresh thought processadd_step: Add reasoning step (requires thought)review_chain: Show complete thought chainconclude: Finish with final conclusion (requires thought)Parameters:
thought: Your current thought or reasoning step (required for add_step and conclude)reflection: Optional reflection on how this builds on previous stepsaction: What to do (required)recall_thoughtsSearch previous thought chains
Parameters:
query: Search term to find in previous thoughts (optional - if empty, shows recent chains)limit: Maximum number of results to return (default: 5)load_thought_chainContinue working on previous chain
Parameters:
chain_id: ID of the thought chain to load (required)thought-chain-mcp/
├── index.js # Main entry point and MCP server setup
├── package.json # Project configuration and dependencies
├── readme.md # This documentation file
├── SECURITY.md # Security documentation and policies
├── mcp.instructions.md # Optional AI instructions for consistent usage
├── .gitignore # Git ignore patterns (excludes database files)
├── src/ # Source code directory
│ ├── server.js # MCP server implementation
│ ├── handlers.js # Tool request handlers
│ ├── models.js # Data models and validation
│ └── database.js # Database operations and management
├── tests/ # Test suite
│ └── server.test.js # Server and functionality tests
└── data/ # Legacy data directory (git-ignored)
└── thoughts.db # Legacy SQLite database (migrated to home directory)
Note: The database is now stored in ~/.thought-chain-mcp/thoughts.db for better portability and npx compatibility.
## Architecture
### Data Storage
- **Database**: SQLite (`thoughts.db`) in the project directory
- **Schema**: Optimized for fast queries and full-text search
- **Persistence**: ACID compliance ensures data integrity
- **Performance**: Indexed queries for efficient retrieval
### Security Features
- **Input Validation**: All inputs validated at boundaries
- **SQL Injection Protection**: Parameterized queries throughout
- **Data Sanitization**: Context-specific sanitization for all data
- **Error Handling**: Secure error messages without information leakage
### Performance Characteristics
- **Query Optimization**: Efficient database queries with proper indexing
- **Resource Management**: Proper connection pooling and timeout handling
- **Memory Efficiency**: Optimized for minimal memory footprint
- **Scalability**: Designed to handle large volumes of thought chains
## Benefits
### For Individual Users
- **Externalized Memory**: Thoughts persist across conversations
- **Reviewable Process**: Full reasoning chain always available
- **Iterative Refinement**: Build on previous analysis
- **Knowledge Retention**: Never lose complex reasoning work
### For Teams
- **Collaborative Thinking**: Share thought chain IDs with team members
- **Consistent Methodology**: Standardized approach to complex reasoning
- **Knowledge Transfer**: Preserve and share analytical processes
- **Quality Assurance**: Review and refine reasoning chains
- **Tool Agnostic**: Team members can use different editors, extensions, or AI assistants while maintaining shared thought processes
- **Platform Independent**: Works across different development environments and tools
### For Organizations
- **Decision Documentation**: Complete audit trail of reasoning processes
- **Compliance Support**: Structured approach to regulatory requirements
- **Training Resource**: Example chains for onboarding and development
- **Process Improvement**: Identify patterns in successful reasoning
## Example Output
✅ Added step 2 to thought chain
Step 2: Given the constraints, I should prioritize solutions that are both cost-effective and scalable Reflection: This builds on my problem analysis by focusing on practical implementation criteria
Chain progress: 2 steps
## Troubleshooting
### Common Issues
1. **"Command not found"**: Ensure Node.js is installed and in your PATH
2. **"Module not found"**: Run `npm install` in the project directory
3. **"Permission denied"**: Make sure the project directory is accessible
4. **No thoughts saving**: Check write permissions in the project directory
5. **AI Assistant not connecting**:
- Verify the config file path for your specific assistant
- Restart your AI assistant
- Check that the MCP server is running (`npm run dev` or `npm start`)
- Consult your assistant's documentation for MCP configuration
6. **Server not starting**: Check for port conflicts or run `npm run dev` for detailed error messages
7. **Database errors**:
- Ensure the `data/` directory exists and is writable
- Delete `data/thoughts.db` to start fresh if corrupted
- Check that SQLite is properly installed
8. **Tool not found**:
- Verify the MCP server is properly configured in your AI assistant
- Check that the server is running and accessible
- Restart both the server and your AI assistant
### Debug Mode
For detailed debugging, run:
```bash
DEBUG=* npm run dev
Check the following locations for diagnostic information:
--watch flag for auto-restart during developmentnpm run security-checkThis project follows established coding standards. When contributing:
sequential_think tool to thought_chain for clarityThis project is licensed under the MIT License - see the LICENSE file for details.
Chris Bunting cbunting99@gmail.com
Specializing in enterprise-grade software solutions with focus on security, performance, and maintainability.
FAQs
MCP Server for Thought Chain with persistence - Installable via npx
We found that thought-chain-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.