mcp-think-tank

MCP Think Tank

Overview

MCP Think Tank provides Cursor and Claude @Web with a dedicated space for structured reasoning, persistent memory, advanced task management, and web research via Exa. It enhances these clients' natural capabilities for systematic problem-solving, project planning, and knowledge building, all while maintaining a persistent knowledge graph.

🎯 Philosophy

MCP Think Tank is built on three core principles:

• Elegant Simplicity: We believe in the power of minimal, well-designed tools that work with Claude's natural capabilities rather than trying to replicate or override them.

• Enhanced Reflection: By providing gentle guidance rather than rigid structure, we enable better reasoning and self-reflection without constraining Claude's thinking process.

• Persistent Context: The knowledge graph provides memory across conversations while maintaining simplicity in both storage and retrieval.

🧠 The Power of Structured Thinking

The think tool provides a dedicated space for systematic reasoning, encouraging:

• Clear problem definition
• Relevant context gathering
• Step-by-step analysis
• Self-reflection on reasoning
• Well-formed conclusions

Recent studies show significant improvements when using structured thinking:

• 54% relative improvement in complex decision-making tasks
• Enhanced consistency across multiple trials
• Improved performance on software engineering benchmarks

🚀 Key Features

• 💭 Think Tool: Dedicated space for structured reasoning and self-reflection
• 🧩 Knowledge Graph: Simple but effective persistent memory
• 📝 Task Management Tools: Plan, track, and update tasks with full knowledge graph integration
• 🌐 Web Research Tools (Exa): Search the web and get sourced answers using Exa API
• 🔍 Memory Tools: Easy-to-use tools for storing and retrieving information
• 🤝 Client Support: Seamless integration with Cursor, Claude @Web, and other MCP clients

📦 Installation

⚠️ Important: MCP Think Tank requires a pre-built server. The package is automatically built before publishing, so users do not need to take any extra steps. Just install and run!

NPX (Recommended)

The easiest way to use MCP Think Tank is via NPX:

npx mcp-think-tank@latest

Global Installation

npm install -g mcp-think-tank
mcp-think-tank

⚙️ Configuration

Quick Start: Essential Setup

• Install MCP Think Tank (see Installation above)
• Get your Exa API Key (required for web search):
  • Sign up at exa.ai and copy your API key.
• Configure your MCP server (for Cursor, add to .cursor/mcp.json):

{
  "mcpServers": {
    "think-tool": {
      "command": "npx",
      "args": ["-y", "mcp-think-tank"],
      "type": "stdio",
      "env": {
        "MEMORY_PATH": "/absolute/path/to/your/memory.jsonl",
        "EXA_API_KEY": "your-exa-api-key-here"
      }
    }
  }
}

⚠️ Important: Always set a unique MEMORY_PATH for each project!

Using the default (centralized) memory path can cause knowledge graph conflicts between projects. For best results and to keep your project memories isolated, specify a custom MEMORY_PATH in your configuration for every project. If omitted, defaults to ~/.mcp-think-tank/memory.jsonl.

• EXA_API_KEY (required for Exa web search): Enables exa_search and exa_answer tools. Without it, web search will not work.

For more details, see exa.ai and Cursor MCP documentation.

Advanced: Other Configuration Options

• You can also set MEMORY_PATH or EXA_API_KEY as environment variables when running the server directly:

  EXA_API_KEY=your-exa-api-key-here mcp-think-tank --memory-path=/absolute/path/to/your/memory.jsonl
  

• The directory for MEMORY_PATH will be created automatically if it doesn't exist.
• If the file doesn't exist, an empty knowledge graph will be initialized.
• The .jsonl extension is recommended for the storage file.

Logging

MCP Think Tank uses a minimal, stable logging approach designed for FastMCP and production best practices:

• Logs are written to a single file at ~/.mcp-think-tank/logs/mcp-think-tank.log.
• Before each log write, the file size is checked. If it exceeds 10MB, the log file is renamed with a timestamp and a new one is started.
• Only Node.js built-in modules are used for logging.
• Debug logging can be enabled by setting the environment variable MCP_DEBUG=true.
• File logging can be disabled by setting MCP_LOG_FILE=false.

This approach is intentional to keep the focus on core MCP server tools and avoid unnecessary complexity.

📝 MCP Think Tank: Project Rule Setup

To ensure Cursor and all agents use MCP Think Tank's full capabilities, create a single, always-on project rule as follows:

Exa Web Search API Key Required

Note: To use Exa-based web research tools (exa_search, exa_answer), you must provide an Exa API key. Without it, web search will not work.

• Get your API key: Sign up and obtain an API key at exa.ai.
• Set the key in your MCP server config: Add EXA_API_KEY to the env section of your MCP server configuration. Example for .cursor/mcp.json:

{
  "mcpServers": {
    "think-tool": {
      "command": "npx",
      "args": ["-y", "mcp-think-tank"],
      "type": "stdio",
      "env": {
        "MEMORY_PATH": "/absolute/path/to/your/memory.jsonl",
        "EXA_API_KEY": "your-exa-api-key-here"
      }
    }
  }
}

For more details, see exa.ai and Cursor MCP documentation.

1. Add a New Rule in Cursor

• Open Cursor.
• Go to the Command Palette (Cmd+Shift+P or Ctrl+Shift+P).
• Select "New Cursor Rule".
• Name the rule (e.g., mcp-think-tank.mdc).
• In the rule editor, set the metadata as shown below and paste the rule content.

2. Example Rule File (.cursor/rules/mcp-think-tank.mdc)

---
description: >
  Unified guidance for using MCP Think Tank tools in this project.
  Always apply this rule to provide agents and users with structured reasoning, memory, task management, and research capabilities.
globs: 
alwaysApply: true
---

# MCP Think Tank: Unified Project Rule

This project uses MCP Think Tank for structured reasoning, persistent memory, advanced task management, and web research.  
**All agents and users should follow these guidelines to ensure consistent, effective use of the MCP server and its tools.**

---

## 1. Thinking & Reasoning

- Use the `think` tool for all complex decisions, architecture planning, and problem-solving.
- Break down problems into clear steps and reflect on reasoning.
- Store important decisions and patterns in memory for future reference.

## 2. Memory & Knowledge Graph

- Use memory tools (`create_entities`, `add_observations`, `create_relations`, etc.) to:
  - Commit key decisions, reusable patterns, and architectural choices.
  - Build relationships between concepts and reference previous knowledge.
- Before creating new solutions, search memory for relevant prior work.

## 3. Task Management

- Use the task tools (`plan_tasks`, `list_tasks`, `next_task`, `complete_task`, `update_tasks`) to:
  - Plan, track, and update project tasks.
  - Mark tasks as complete when finished and update their status as work progresses.
  - Use task dependencies and priorities to organize work.

## 4. Web Research

- Use the Exa tools (`exa_search`, `exa_answer`) for all web research and fact-finding.
- Always cite sources and summarize findings in memory when relevant.
- **Note:** Exa tools require a valid `EXA_API_KEY` in your MCP server configuration.

## 5. Logging & Debugging

- Use the logging system for all operational events.
- Check logs for troubleshooting and ensure log rotation is configured.

## 6. General Workflow

- Reference and build upon previous decisions and patterns.
- Document all significant changes and rationale.
- Maintain consistent coding and architectural patterns.
- Update this rule as new tools or workflows are added.

---

## 🛠️ Available Tools (with Example Usage)

| Tool         | Purpose                                      | Example Usage                                                                 |
|--------------|----------------------------------------------|-------------------------------------------------------------------------------|
| `think`      | Structured reasoning & reflection            | `think("Design auth system for microservices...")`                            |
| `create_entities` | Add new concepts to memory              | `create_entities([{name: "AuthSystem", ...}])`                                |
| `add_observations` | Add facts to existing entities         | `add_observations([{entityName: "AuthSystem", contents: ["Uses JWT"]}])`      |
| `create_relations` | Link concepts in the knowledge graph   | `create_relations([{from: "AuthSystem", to: "Security", relationType: "enhances"}])` |
| `plan_tasks` | Create multiple project tasks                | `plan_tasks([{description: "Implement login", priority: "high"}])`            |
| `list_tasks` | List tasks by status/priority                | `list_tasks({status: "todo"})`                                                |
| `next_task`  | Get and start the next highest priority task | `next_task({})`                                                               |
| `complete_task` | Mark a task as done                       | `complete_task({id: "task-uuid"})`                                            |
| `exa_search` | Web search via Exa API                       | `exa_search({query: "latest in LLMs"})`                                       |
| `exa_answer` | Get sourced answers from the web             | `exa_answer({question: "What is quantum advantage?"})`                        |

## 🧠 Think Tank Instructions

This section provides detailed, actionable guidance for using MCP Think Tank within Cursor AI IDE (or any MCP-compliant agent), with a focus on coding and large project development. The tools are grouped into four main categories:

### 1. Think Tools (Structured Reasoning)
- Use the `think` tool for all complex decisions, architecture planning, and problem-solving.
- Always provide clear, step-by-step reasoning and relevant context.
- **To persist your reasoning for future reference, set `storeInMemory: true` in your tool call.**
  - Example: When you want your analysis or decision to be available across sessions or for team traceability.
- If you do not set `storeInMemory: true`, your reasoning will be processed but not saved in the knowledge graph.
- Agents (like Cursor or Claude) can be prompted to "save this reasoning in memory" to ensure persistence.
- You can later retrieve saved thoughts using the `search_nodes` or `open_nodes` tools.

> ⚠️ **Important:**
> The `storeInMemory` parameter is not activly used by the user, the user simply > writes "Please save this reasoning in memory for future reference" and the tool will save the reasoning in the knowledge graph.


#### How `storeInMemory` Works
- The `think` tool accepts a `storeInMemory` parameter (default: false).
- When `storeInMemory: true`, your structured reasoning, context, and tags are saved as an entity in the knowledge graph.
- This enables robust project memory, traceability, and continuity.
- Example tool call:
  ```json
  {
    "tool": "think",
    "parameters": {
      "structuredReasoning": "Analyzed the pros and cons of REST vs GraphQL for our new API. Decided REST is simpler for our use case.",
      "context": "API design meeting 2024-07-10",
      "category": "architecture",
      "tags": ["api", "meeting"],
      "storeInMemory": true
    }
  }

• To retrieve saved thoughts, use:
  • search_nodes (by keyword, tag, or context)
  • open_nodes (by entity name)

2. Research Tools

• Use exa_search for web search and exa_answer for sourced answers.
• Always cite sources and, when relevant, summarize findings in memory using add_observations or by saving a think entry.
• Research tools require a valid EXA_API_KEY in your MCP server configuration.
• Integrate research findings into your code and reasoning for robust, up-to-date solutions.

3. Task Manager Tools

• Use plan_tasks to create and organize project tasks.
• Use list_tasks, next_task, complete_task, and update_tasks to manage your workflow.
• All tasks are synchronized with the knowledge graph, enabling persistent, queryable project management.
• For large projects, leverage task dependencies and priorities to maintain clarity and momentum.

4. Memory Tools

• Use create_entities, add_observations, create_relations, and related tools to build and maintain your project's knowledge graph.
• Store key decisions, reusable patterns, and architectural choices for future reference.
• Before starting new work, search memory for relevant prior knowledge to avoid duplication and leverage past insights.

Best Practices for Cursor/Claude and Large Projects:

• Use the think tool liberally for all non-trivial reasoning and always persist important thoughts.
• Integrate research and task management into your coding workflow for seamless project development.
• Regularly review and update your knowledge graph to keep project memory relevant and actionable.
• Reference and build upon previous decisions and patterns for consistent, high-quality code.

Keep this section up to date as new tools or workflows are added.

3. Reference Links

• Cursor Rules Documentation
• MCP Model Context Protocol
• Exa API

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add some amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

📄 License

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

📚 Related Projects

• Model Context Protocol
• FastMCP
• Claude 3.7 Sonnet

📚 Further Reading

• Anthropic's Research on Structured Thinking
• Model Context Protocol Documentation
• Claude Desktop Integration Guide

Developed by flight505

Give a ⭐️ if this project helped you!

Changelog

1.4.1 (2024-07-11)

Fixed

• Version update to fix publishing error - version 1.4.0 was already in the registry.
• All changes from 1.4.0 are included in this release.