Skip to content

waldzellai/clearthought-onepointfive

BranchesTags

Repository files navigation

Clear Thought 1.5 MCP Server

smithery badge

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:

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

Manual Installation

npm install @waldzellai/clear-thought-onepointfive

Or run with npx:

npx @waldzellai/clear-thought-onepointfive

Development Setup

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

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

Example: Mental Model

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)

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

// 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

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

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

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:

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

Run the container:

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, 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

About

OG Sequential Thinking fork, v1.5

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

49 stars

Watchers

1 watching

Forks

7 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 2

Languages