ThoughtMCP

AI that thinks more like humans do.

ThoughtMCP gives AI systems human-like thinking capabilities. Instead of just processing text, it can think systematically, remember experiences, and check its own reasoning quality.

🚀 Production Ready: 789 tests, 79.63% coverage, stable API, ready for real-world use.

What Makes It Different?

Most AI systems process text once and respond. ThoughtMCP implements multiple thinking systems inspired by cognitive science:

🧠 Human-Like Thinking

• Fast intuitive responses for familiar problems
• Careful deliberation for complex decisions
• Creative exploration for innovation challenges
• Analytical reasoning for technical problems

💾 Learning Memory

• Remembers experiences and learns from them
• Builds knowledge that improves over time
• Recalls relevant information when making decisions
• Consolidates patterns from specific cases to general principles

🔍 Self-Monitoring

• Checks its own reasoning for quality and biases
• Provides confidence levels for transparency
• Suggests improvements to its own thinking
• Adapts approach based on problem complexity

⚡ Production Ready

• 789 comprehensive tests with 79.63% coverage
• Multiple thinking modes for different scenarios
• Configurable behavior for your specific needs
• Robust error handling with graceful degradation

Quick Start

1. Install and Setup

Option A: NPX (Recommended - No Installation Required)

# Use directly with npx - no installation needed
npx thoughtmcp@latest

# Or configure in your MCP client (see configuration examples below)

Option B: Local Development Setup

# Clone the repository
git clone https://github.com/keyurgolani/ThoughtMcp.git
cd ThoughtMcp

# Install dependencies
npm install

# Build and start the server
npm run build
npm start

# Run comprehensive demo (in another terminal)
npm run example:demo

# Or run performance benchmarks
npm run example:benchmark

🤖 Use in Your AI Environment

ThoughtMCP works with popular AI development environments:

• Kiro IDE - Workspace and user-level configuration
• Claude Desktop - Desktop app integration
• Cursor IDE - VS Code-based AI coding
• Void Editor - Modern AI editor
• Generic MCP - Any MCP-compatible system

Quick Kiro Setup (Local Development):

{
  "mcpServers": {
    "thoughtmcp": {
      "command": "node",
      "args": ["/path/to/ThoughtMcp/dist/index.js"],
      "env": {
        "COGNITIVE_DEFAULT_MODE": "balanced",
        "COGNITIVE_ENABLE_EMOTION": "true"
      }
    }
  }
}

Quick Kiro Setup (NPX - Recommended):

{
  "mcpServers": {
    "task-manager": {
      "command": "npx",
      "args": ["thoughtmcp@latest"],
      "env": {
        "COGNITIVE_DEFAULT_MODE": "balanced",
        "COGNITIVE_ENABLE_EMOTION": "true",
        "COGNITIVE_ENABLE_METACOGNITION": "true",
        "COGNITIVE_WORKING_MEMORY_CAPACITY": "7",
        "COGNITIVE_EPISODIC_MEMORY_SIZE": "1000",
        "COGNITIVE_SEMANTIC_MEMORY_SIZE": "5000",
        "COGNITIVE_TEMPERATURE": "0.7",
        "COGNITIVE_TIMEOUT_MS": "30000",
        "COGNITIVE_BRAIN_DIR": "~/.brain",
        "LOG_LEVEL": "INFO"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

👉 Complete Integration Guide | Environment-Specific Setup

MCP Server Configuration

ThoughtMCP can be configured as an MCP server using environment variables. All configuration options are optional and have sensible defaults.

Environment Variables

Example Configurations

Kiro IDE Configuration

{
  "mcpServers": {
    "task-manager": {
      "command": "npx",
      "args": ["thoughtmcp@latest"],
      "env": {
        "COGNITIVE_DEFAULT_MODE": "balanced",
        "COGNITIVE_ENABLE_EMOTION": "true",
        "COGNITIVE_ENABLE_METACOGNITION": "true",
        "COGNITIVE_WORKING_MEMORY_CAPACITY": "7",
        "COGNITIVE_EPISODIC_MEMORY_SIZE": "1000",
        "COGNITIVE_SEMANTIC_MEMORY_SIZE": "5000",
        "COGNITIVE_TEMPERATURE": "0.7",
        "COGNITIVE_TIMEOUT_MS": "30000",
        "COGNITIVE_BRAIN_DIR": "~/.brain",
        "LOG_LEVEL": "INFO"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Claude Desktop Configuration

{
  "mcpServers": {
    "thought": {
      "command": "npx",
      "args": ["thoughtmcp@latest"],
      "env": {
        "COGNITIVE_DEFAULT_MODE": "analytical",
        "COGNITIVE_ENABLE_EMOTION": "false",
        "COGNITIVE_TEMPERATURE": "0.5"
      }
    }
  }
}

High-Performance Configuration

{
  "mcpServers": {
    "thought-fast": {
      "command": "npx",
      "args": ["thoughtmcp@latest"],
      "env": {
        "COGNITIVE_DEFAULT_MODE": "intuitive",
        "COGNITIVE_WORKING_MEMORY_CAPACITY": "5",
        "COGNITIVE_TIMEOUT_MS": "10000",
        "COGNITIVE_TEMPERATURE": "0.3",
        "LOG_LEVEL": "WARN"
      }
    }
  }
}

Creative Mode Configuration

{
  "mcpServers": {
    "thought-creative": {
      "command": "npx",
      "args": ["thoughtmcp@latest"],
      "env": {
        "COGNITIVE_DEFAULT_MODE": "creative",
        "COGNITIVE_TEMPERATURE": "1.2",
        "COGNITIVE_ENABLE_EMOTION": "true",
        "COGNITIVE_WORKING_MEMORY_CAPACITY": "9"
      }
    }
  }
}

2. Try Your First Example

Ask ThoughtMCP to help with a decision:

{
  "tool": "think",
  "arguments": {
    "input": "I'm trying to decide between two job offers. One pays more but has longer hours, the other has better work-life balance but lower pay. How should I approach this decision?",
    "mode": "deliberative"
  }
}

What happens:

• Analyzes your question systematically
• Considers multiple factors and perspectives
• Provides structured reasoning with confidence levels
• Suggests ways to improve the decision-making process

3. Build Knowledge Over Time

Store important insights:

{
  "tool": "remember",
  "arguments": {
    "content": "When choosing between job offers, work-life balance often matters more than salary for long-term satisfaction",
    "type": "semantic",
    "importance": 0.8
  }
}

Recall relevant knowledge:

{
  "tool": "recall",
  "arguments": {
    "cue": "job decision work-life balance"
  }
}

The Four Thinking Tools

🧠 Think - Systematic Reasoning

Process complex questions using human-like reasoning:

• Intuitive mode: Fast, gut-reaction responses
• Deliberative mode: Slow, careful analysis
• Creative mode: Innovative problem-solving
• Analytical mode: Logical, data-driven reasoning

💾 Remember - Build Knowledge

Store experiences and insights for future use:

• Episodic memory: Specific experiences and events
• Semantic memory: General knowledge and principles
• Importance weighting: Prioritize what matters most
• Emotional tagging: Remember how things felt

🔍 Recall - Find Relevant Information

Retrieve past experiences and knowledge when needed:

• Similarity matching: Find related experiences
• Context-aware: Consider current situation
• Confidence scoring: Know how relevant results are
• Cross-memory search: Search both experience and knowledge

🔬 Analyze Reasoning - Quality Control

Check thinking quality and identify potential problems:

• Bias detection: Spot common reasoning errors
• Logic validation: Ensure arguments are sound
• Confidence assessment: Evaluate certainty levels
• Improvement suggestions: Get better at reasoning

Real-World Examples

See ThoughtMCP in action with practical scenarios:

• Customer Support Agent - Solving technical problems systematically
• Personal Finance Advisor - Making complex financial decisions
• Recipe Recommendation - Personalized suggestions with constraints
• Study Buddy - Helping students learn effectively
• Travel Planning - Complex multi-constraint planning

Each example shows:

• The real-world problem
• Step-by-step tool usage
• How cognitive thinking improves outcomes
• Lessons you can apply to your own use cases

Documentation

🚀 New to ThoughtMCP?

• Getting Started - 5-minute tutorial and basic concepts
• Installation Guide - Detailed setup instructions
• Basic Concepts - How human-like thinking works
• Examples - From simple to complex real-world scenarios

👩‍💻 For Developers

• API Reference - Complete tool documentation and schemas
• Integration Guide - Add to your applications
• Agentic Environments - Configure in Kiro, Claude, Cursor, Void, and more
• Configuration - Customize behavior and performance
• Troubleshooting - Common issues and solutions

🧠 Understanding the Architecture

• Architecture Overview - How the cognitive system works
• Cognitive Components - Individual system details
• Research Background - Academic foundations and algorithms
• Performance Benchmarks - Speed and accuracy metrics

🛠️ Contributing

• Development Setup - Set up for development
• Contributing Guide - How to contribute effectively
• Architecture for Developers - Codebase structure
• Testing Guide - Writing and running tests

📚 Documentation & Examples

Comprehensive Documentation

• Complete API Reference - Detailed documentation for all four cognitive tools
• Cognitive Architecture Guide - Deep dive into the human-like reasoning system
• Performance & Benchmarking - Optimization strategies and performance testing

Practical Examples

• Example Applications - Complete working examples demonstrating all features
• Integration Patterns - Real-world integration examples
• Performance Testing - Automated benchmarking tools

Quick Links

• 🚀 Quick Start Guide - Get up and running in minutes
• 🔧 Configuration Guide - Tune the system for your needs
• 🏗️ Development Setup - Contributing to the project

Why Choose ThoughtMCP?

For AI Applications

• Better Decision Making: Considers multiple perspectives and checks reasoning quality
• Continuous Learning: Gets smarter over time by remembering experiences
• Transparency: Shows reasoning process and confidence levels
• Adaptability: Different thinking modes for different types of problems

For Developers

• Production Ready: 789 tests, comprehensive error handling, performance monitoring
• Easy Integration: Standard MCP protocol, clear API, extensive documentation
• Configurable: Tune behavior for your specific use case and performance needs
• Open Source: MIT license, active community, extensible architecture

For Researchers

• Scientifically Grounded: Based on established cognitive science research
• Comprehensive Implementation: Full dual-process theory, memory systems, metacognition
• Benchmarked Performance: Validated against cognitive psychology principles
• Extensible Design: Add new cognitive components and reasoning strategies

Community and Support

• 📖 Documentation: Comprehensive guides from beginner to advanced
• 💬 GitHub Discussions: Ask questions and share ideas
• 🐛 Issues: Report bugs and request features
• 🤝 Contributing: Join our community of contributors
• 📧 Contact: Reach out to @keyurgolani

Project Status

• ✅ Stable API: All four cognitive tools fully implemented
• ✅ Production Ready: 789 tests with 79.63% coverage
• ✅ Well Documented: Comprehensive documentation for all user levels
• ✅ Active Development: Regular updates and community contributions
• ✅ Open Source: MIT license, community-driven development

Ready to give your AI human-like thinking capabilities?

👉 Get Started in 5 Minutes | 📚 View Documentation | 🤝 Join Community