🧠 Thought Chain MCP Server

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.

🚀 Key Benefit: Advanced Reasoning for All AI Models

While modern AI models vary in their native reasoning capabilities, the Thought Chain MCP Server levels the playing field by providing:

• Structured Thinking Framework: Guides any AI model through systematic, logical reasoning processes

• Persistent Memory: Maintains context and reasoning chains across conversations and sessions

• Complex Problem Decomposition: Breaks down intricate problems into manageable, logical steps

• Structured Analysis: Enables thorough, documented decision-making processes

• Cross-Model Consistency: Ensures high-quality reasoning regardless of the underlying AI model

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.

Overview

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.

Features

Core Functionality

• Thought Chain: Build reasoning chains step by step with reflections

• Persistence: Automatically saves all thought chains to SQLite database

• Recall System: Search and load previous thought processes by content

• Chain Management: Start new chains, review progress, conclude thoughts

• Reflection Support: Add notes on how each step builds on previous ones

• Cross-Session Continuity: Thought chains persist across assistant restarts

• Cross-Platform Compatibility: Use the same thought chains across different AI assistants

Advanced Features

• Reliable Data Storage: SQLite database with ACID compliance

• Secure Design: Input validation and secure data handling

• Optimized Performance: Efficient query patterns and resource management

• Modular Architecture: Clean separation of concerns for maintainability

Quick Start

Prerequisites

• Node.js: Version 20.0.0 or higher

• npm: Latest stable version

• AI Coding Assistant: ANY MCP-compatible tool including:

  • Claude Desktop

  • Cursor

  • Cline

  • Roo Code

  • Windsurf

  • VS Code with MCP extensions

  • Custom MCP implementations

  • Any editor or tool that supports the Model Context Protocol

Installation Options

Option 1: NPX Installation (Recommended)

The easiest way to install and use the Thought Chain MCP Server:

For global access:

Once installed globally, you can run:

Option 2: Direct NPX Usage (No Installation)

Run directly without installing:

Option 3: Local Development Setup

1. Navigate to the project directory:

   cd c:\mcpservers\thought-chain-mcp

2. Install dependencies:

   npm install

3. Configure your AI Assistant:

   This MCP server works with multiple AI coding assistants. Choose your preferred platform below:

   Claude Desktop

   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" } } }

   Cursor

   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" } } }

   Cline

   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" } } }

   Roo Code

   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" } } }

   Windsurf

   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" } } }

   ANY MCP-Compatible Tool

   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:

   • VS Code with MCP extensions

   • Custom MCP implementations

   • Any editor that supports the Model Context Protocol

   • Development environments with MCP integration

   • Standalone MCP clients

4. 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:

   • Copy mcp.instructions.md to your Copilot prompts directory

   • This helps guide the AI on when and how to use the thinking tools

   • The server works perfectly without these instructions - they're just for consistency

5. Database Initialization

   The server will automatically create a fresh SQLite database in your home directory (~/.thought-chain-mcp/thoughts.db) on first run. This database:

   • Stores all your thought chains locally in your user directory

   • Is created automatically if it doesn't exist

   • Persists across different installations and projects

   • Can be safely deleted to start fresh

   • Is portable and works with npx installations

6. Restart your AI Assistant to load the new MCP server

Running the Server

• Development mode (with auto-restart):

  npm run dev

• Production mode:

  npm start

• Run tests:

  npm test

• Security audit:

  npm run security-check

Usage Examples

Basic Thought Chain Usage

Recalling Previous Work

Advanced Usage Patterns

Problem-Solving Workflow

Research and Analysis

Thought Chain Example

Here's a complete example of using the thought chain process to solve a complex problem:

Scenario: Optimizing Database Performance

Key Benefits of This Approach

• Structured Thinking: Each step builds logically on the previous one

• Documentation: Complete reasoning process is preserved

• Revisitable: Can load this chain later to continue analysis

• Shareable: Chain ID can be shared with team members

• Iterative: Can add more steps as new information emerges

Available Tools

thought_chain

Main tool for building Thought Chain

Actions:

• new_chain: Start a fresh thought process

• add_step: Add reasoning step (requires thought)

• review_chain: Show complete thought chain

• conclude: 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 steps

• action: What to do (required)

recall_thoughts

Search 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_chain

Continue working on previous chain

Parameters:

• chain_id: ID of the thought chain to load (required)

Project Structure

Note: The database is now stored in ~/.thought-chain-mcp/thoughts.db for better portability and npx compatibility.

✅ 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

Log Analysis

Check the following locations for diagnostic information:

• Console output for server status

• Database logs for query performance

• Error logs for troubleshooting

Dependencies

Runtime Dependencies

• @modelcontextprotocol/sdk: ^1.0.0 - MCP protocol implementation

• better-sqlite3: ^12.2.0 - High-performance SQLite driver

• @vscode/webview-ui-toolkit: ^1.4.0 - UI toolkit components

Development Requirements

• Node.js: >=20.0.0

• npm: Latest stable version

Optional Development Tools

• Testing: Built-in Node.js test runner

• Security: npm audit for vulnerability scanning

• Development: --watch flag for auto-restart during development

Security Considerations

Data Protection

• All data stored locally in SQLite database

• No external network connections required

• Input validation prevents injection attacks

• Secure error handling prevents information leakage

Best Practices

• Regular security audits via npm run security-check

• Dependency updates monitored for vulnerabilities

• Code follows security best practices

• Comprehensive input validation and sanitization

Contributing

This project follows established coding standards. When contributing:

1. Follow the established code patterns and architecture

2. Ensure all code passes security checks

3. Add comprehensive tests for new functionality

4. Update documentation for any API changes

5. Adhere to the coding standards defined in the project

Version History

v1.0.2 (Current)

• Renamed sequential_think tool to thought_chain for clarity

• Enhanced security validation with improved XSS prevention

• Fixed duplicate configuration issues

• Updated test suite with comprehensive coverage

• Improved database handling and .gitignore configuration

• Added support for multiple AI assistants and editors

• Enhanced documentation with detailed setup instructions

v1.0.1

• Enhanced security features

• Improved error handling

• Performance optimizations

• Updated documentation

• Added npx support for easy installation

v1.0.0

• Initial release

• Core sequential thinking functionality

• SQLite persistence

• MCP integration

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Issues: GitHub Issues

• Repository: GitHub Repository

• Documentation: Project Wiki

Author

Chris Bunting cbunting99@gmail.com