# Clear Thought 1.5 MCP Server

[![smithery badge](https://smithery.ai/badge/@waldzellai/clear-thought-onepointfive)](https://smithery.ai/server/@waldzellai/clear-thought-onepointfive)

A Model Context Protocol (MCP) server that provides a unified reasoning tool with multiple operations, including systematic thinking, mental models, debugging approaches, and interactive notebook capabilities for enhanced problem-solving. This server exposes a single `clear_thought` tool with a comprehensive suite of operations to facilitate complex reasoning tasks, plus interactive Srcbook notebook resources.

## 🚀 New: Modular Architecture

The codebase has been completely refactored from a monolithic 2867-line file into a clean, modular architecture with 38 separate operations organized by category. Each operation is now self-contained, making the codebase more maintainable, testable, and extensible.

## Operations

The `clear_thought` tool provides the following operations. For detailed information on parameters, please refer to the operations guide resource at `guide://clear-thought-operations`.

### Core Thinking Operations
- **sequential_thinking**: Executes a chain-of-thought process. Can be configured to use different reasoning patterns like 'tree', 'beam', 'mcts', 'graph', or 'auto'.
- **mental_model**: Applies a specified mental model to a problem.
- **debugging_approach**: Guides through a structured debugging process.
- **creative_thinking**: Facilitates idea generation and exploration.
- **visual_reasoning**: Works with diagrams and visual structures.
- **metacognitive_monitoring**: Monitors and assesses the reasoning process itself.
- **scientific_method**: Follows the steps of the scientific method for inquiry.

### Collaborative & Decision Operations
- **collaborative_reasoning**: Simulates a multi-persona discussion to explore a topic from different viewpoints.
- **decision_framework**: Uses a structured framework to analyze options and make decisions.
- **socratic_method**: Employs a question-driven approach to challenge and refine arguments.
- **structured_argumentation**: Constructs and analyzes formal arguments.

### Systems & Analysis Operations
- **systems_thinking**: Models a problem as a system with interconnected components.
- **research**: Generates placeholders for research findings and citations.
- **analogical_reasoning**: Draws parallels and maps insights between different domains.
- **causal_analysis**: Investigates cause-and-effect relationships.
- **statistical_reasoning**: Performs statistical analysis (summary, bayes, hypothesis_test, monte_carlo modes).
- **simulation**: Runs simple simulations.
- **optimization**: Finds the best solution from a set of alternatives.
- **ethical_analysis**: Evaluates a situation using an ethical framework.

### Advanced Operations
- **visual_dashboard**: Creates a skeleton for a visual dashboard.
- **custom_framework**: Allows defining a custom reasoning framework.
- **code_execution**: Executes code in a restricted environment (currently Python only).
- **tree_of_thought, beam_search, mcts, graph_of_thought**: Aliases for `sequential_thinking` with a fixed reasoning pattern.
- **orchestration_suggest**: Suggests a sequence of tools to use for a complex task.

### Session Management
- **session_info**: Get information about the current reasoning session.
- **session_export**: Export session data for persistence.
- **session_import**: Import session data to restore state.

### Metagame Operations
- **ooda_loop**: Implements the OODA (Observe, Orient, Decide, Act) loop methodology.
- **ulysses_protocol**: High-stakes debugging and problem-solving framework.

### Notebook Operations
- **notebook_create**: Create a new interactive Srcbook notebook.
- **notebook_add_cell**: Add cells to an existing notebook.
- **notebook_run_cell**: Execute cells in a notebook.
- **notebook_export**: Export notebook content.

## Choosing an Operation

With a wide range of operations available, it's helpful to have a guide for selecting the best one for your task.

- For **general problem-solving** and step-by-step reasoning, start with `sequential_thinking`.
- To **analyze a problem from a specific viewpoint**, use `mental_model`.
- When **troubleshooting issues**, `debugging_approach` provides a structured workflow.
- To **generate new ideas**, use `creative_thinking`.
- For **complex decisions**, `decision_framework` can help you weigh your options.
- To **simulate a discussion** with multiple perspectives, use `collaborative_reasoning`.
- For **high-stakes debugging**, use `ulysses_protocol` with systematic phases and gates.
- For **rapid decision-making**, use `ooda_loop` for iterative observe-orient-decide-act cycles.
- For **interactive learning**, use notebook operations with Srcbook resources.
- If you're not sure where to start, `orchestration_suggest` can recommend a sequence of operations.

For a complete list of operations and their parameters, refer to the operations guide available as a resource at `guide://clear-thought-operations`.

## Installation

### Installing via Smithery

To install Clear Thought MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@waldzellai/clear-thought-onepointfive):

```bash
npx -y @smithery/cli install @waldzellai/clear-thought-onepointfive --client claude
```

### Manual Installation
```bash
npm install @waldzellai/clear-thought-onepointfive
```

Or run with npx:

```bash
npx @waldzellai/clear-thought-onepointfive
```

### Development Setup
```bash
git clone <repository-url>
cd clearthought-onepointfive
npm install
npx @smithery/cli dev
```

## Usage

All operations are accessed through the `clear_thought` tool. You specify the desired operation using the `operation` parameter.

### Example: Sequential Thinking
```typescript
const response = await mcp.callTool("clear_thought", {
  operation: "sequential_thinking",
  prompt: "How to implement a new feature?",
  parameters: {
    pattern: "chain"
  }
});
```

### Example: Mental Model
```typescript
const response = await mcp.callTool("clear_thought", {
  operation: "mental_model",
  prompt: "Analyze the trade-offs of using a microservices architecture.",
  parameters: {
    model: "first_principles"
  }
});
```

### Example: Ulysses Protocol (High-Stakes Debugging)
```typescript
const response = await mcp.callTool("clear_thought", {
  operation: "ulysses_protocol",
  prompt: "Fix critical authentication failure in production system",
  parameters: {
    stakes: "critical",
    budget: "4 hours"
  }
});
```

### Example: Notebook Operations
```typescript
// Create a new notebook
const createResponse = await mcp.callTool("clear_thought", {
  operation: "notebook_create",
  prompt: "Create a notebook for learning TypeScript",
  parameters: {
    name: "typescript-learning"
  }
});

// Add a cell to the notebook
const addCellResponse = await mcp.callTool("clear_thought", {
  operation: "notebook_add_cell",
  prompt: "Add a code cell demonstrating TypeScript interfaces",
  parameters: {
    notebookId: "typescript-learning",
    cellType: "code",
    content: "interface User { name: string; age: number; }"
  }
});
```

### Example: Statistical Reasoning
```typescript
const response = await mcp.callTool("clear_thought", {
  operation: "statistical_reasoning",
  prompt: "Analyze the performance data of our API endpoints",
  parameters: {
    mode: "summary",
    data: [/* your data here */]
  }
});
```

### Example: MDP Planning
```typescript
const response = await mcp.callTool("clear_thought", {
  operation: "mdp_planning",
  prompt: "Plan warehouse robot navigation",
  parameters: {
    states: ["start", "aisle", "packing", "error"],
    actions: ["go_to_aisle", "go_to_packing", "charge"],
    transitions: [
      { from: "start", action: "go_to_aisle", to: "aisle", probability: 0.9 },
      { from: "start", action: "go_to_aisle", to: "error", probability: 0.1 }
    ],
    rewards: [
      { state: "packing", action: "go_to_packing", value: 10 },
      { state: "error", value: -20 }
    ],
    discount: 0.95,
    algorithm: "value_iteration"
  }
});
```

### Example: Decision Networks
```typescript
const response = await mcp.callTool("clear_thought", {
  operation: "decision_networks",
  prompt: "Choose marketing strategy with demand uncertainty",
  parameters: {
    randomVariables: [
      {
        name: "demand",
        states: ["high", "low"],
        cpt: [{ when: {}, distribution: { high: 0.6, low: 0.4 } }]
      }
    ],
    decision: {
      name: "strategy",
      states: ["aggressive", "cautious"]
    },
    utilityNodes: [
      {
        name: "profitUtility",
        table: [
          { when: { strategy: "aggressive", demand: "high" }, value: 100 },
          { when: { strategy: "aggressive", demand: "low" }, value: -30 }
        ]
      }
    ]
  }
});
```

## Resources

The server provides several resources for enhanced functionality:

### Operations Guide
- **URI**: `guide://clear-thought-operations`
- **Description**: Complete documentation for all operations and their parameters
- **MIME Type**: `text/markdown`

### Interactive Notebooks
- **URI Template**: `notebook:///{name}`
- **Description**: Access Srcbook notebooks for interactive TypeScript/JavaScript execution
- **MIME Type**: `text/markdown`

### Notebook Interaction Guide
- **URI**: `guide://notebook-interaction`
- **Description**: Instructions for working with Srcbook notebooks in MCP
- **MIME Type**: `text/markdown`

## Docker

Build the Docker image:

```bash
docker build -t waldzellai/clear-thought-onepointfive .
```

Run the container:

```bash
docker run -it waldzellai/clear-thought-onepointfive
```

## Development

1. Clone the repository
2. Install dependencies: `npm install`
3. Dev server (single entry via CLI): `npx @smithery/cli dev`
4. Build for deployment: `npx @smithery/cli build`

### Available Scripts
- `npm run build:stdio` - Build STDIO server
- `npm run build:http` - Build HTTP server
- `npm run build` - Build both servers
- `npm run dev` - Start development server
- `npm run typecheck` - TypeScript type checking
- `npm run check` - Biome linting and formatting
- `npm run test` - Run tests with Vitest

### Dev Modes

- **HTTP (Playground via Smithery)**
  - `npm run dev`
  - Starts the Smithery sHTTP dev server (prints a public URL). It also performs an initial build automatically.

- **Local Inspector (browser UI over STDIO)**
  - `npm run build`
  - `npx @modelcontextprotocol/inspector dist/src/index.js`
  - Open the printed URL (with prefilled token) to interact in the browser.

Note: `prompts/list` is not implemented by design, so seeing 32601 “Method not found” for that endpoint is expected.

### Tested Operations Summary

All operations were verified end-to-end with multi-step, stateful behavior:

- Core: sequential_thinking, mental_model, debugging_approach, creative_thinking, visual_reasoning, metacognitive_monitoring, scientific_method, collaborative_reasoning, decision_framework, socratic_method, structured_argumentation, systems_thinking
- Advanced analysis: analogical_reasoning, causal_analysis, statistical_reasoning, simulation, optimization, ethical_analysis, research
- Search patterns: tree_of_thought, beam_search, mcts, graph_of_thought
- Specialized: visual_dashboard, custom_framework, code_execution, orchestration_suggest, ooda_loop, ulysses_protocol, pdr_reasoning
- Notebook: notebook_create, notebook_add_cell, notebook_run_cell, notebook_export
- Session: session_info, session_export, session_import

Key findings:
- Multi-step flows with session continuity and metrics
- Rich structured outputs with suggested next steps
- Resources include operation guides and examples

### Architecture

The codebase follows a modular architecture:

```
src/tools/
├── operations/           # All operations organized by category
│   ├── core/            # Core thinking operations (7)
│   ├── session/         # Session management (3)
│   ├── collaborative/   # Collaborative reasoning (5)
│   ├── analysis/        # Analysis operations (7)
│   ├── patterns/        # Reasoning patterns (5)
│   ├── ui/              # UI operations (2)
│   ├── notebook/        # Notebook operations (4)
│   ├── metagame/        # Advanced frameworks (2)
│   └── special/         # Special operations (3)
├── helpers/             # Helper utilities
│   └── ui-generation.ts # UI generation helpers
└── index.ts             # Main orchestrator
```

Each operation:
- Extends `BaseOperation` class
- Implements the `Operation` interface
- Is self-contained (~100-150 lines)
- Auto-registers on import
- Has consistent error handling

## Contributing

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

## License

MIT License - see LICENSE for details.

## Key Features

### 🧠 **Unified Reasoning Tool**
Single `clear_thought` tool with 30+ operations covering all aspects of systematic thinking and problem-solving.

### 📓 **Interactive Notebooks**
Srcbook notebook integration for interactive TypeScript/JavaScript execution and learning.

### 🎯 **Metagame Operations**
Advanced frameworks like Ulysses Protocol and OODA Loop for high-stakes problem-solving.

### 📊 **Statistical Analysis**
Multiple statistical reasoning modes including Bayesian analysis, hypothesis testing, and Monte Carlo simulation.

### 🔄 **Session Management**
Persistent session state with export/import capabilities for long-running reasoning tasks.

### 🛡️ **Code Execution**
Secure Python code execution in restricted environments.

## Acknowledgments

- Based on the Model Context Protocol (MCP) by Anthropic, and uses the code for the sequentialthinking server
- Mental Models framework inspired by [James Clear's comprehensive guide to mental models](https://jamesclear.com/mental-models), which provides an excellent overview of how these thinking tools can enhance decision-making and problem-solving capabilities
- Ulysses Protocol inspired by systematic debugging and problem-solving methodologies
- OODA Loop implementation based on John Boyd's military strategy framework