@davenportsociety/clear-thought-patterns/README.md

A Model Context Protocol (MCP) server providing systematic thinking tools, mental models, and debugging approaches for enhanced problem-solving capabilities

# Clear Thought Patterns - MCP Thinking Tools

A comprehensive Model Context Protocol (MCP) server providing 16 systematic thinking tools, mental models, and analytical frameworks for enhanced problem-solving, decision-making, and cognitive analysis.

## Overview

Clear Thought Patterns offers a complete toolkit for structured thinking and analysis through the Model Context Protocol. Whether you're debugging complex systems, making strategic decisions, or exploring creative solutions, these tools provide systematic approaches to enhance your cognitive processes.

## Tool Inventory

### 🧠 Core Thinking Tools

#### Sequential Thinking (`sequentialthinking`)
Process complex problems through structured sequential reasoning with branching, revision, and memory management.

**When to use:** Complex multi-step problem-solving, planning major features, analyzing system-wide changes
**Key features:** Numbered thought progression, branching alternatives, revision capability, memory management
**Combines well with:** Mental Models, Decision Framework, Scientific Method

#### Mental Models (`mentalmodel`)
Apply structured mental models to analyze problems systematically and gain deeper insights.

**Available models:**
- `first_principles` - Break down to fundamental truths, rebuild understanding
- `opportunity_cost` - Analyze what you give up by choosing one option
- `error_propagation` - Understand how errors cascade through systems
- `rubber_duck` - Explain the problem step-by-step to clarify thinking
- `pareto_principle` - Identify the 20% of causes creating 80% of effects
- `occams_razor` - Choose the simplest explanation that fits the facts

**When to use:** Initial problem understanding, breaking down complex systems, analyzing trade-offs
**Combines well with:** Sequential Thinking, Decision Framework, Scientific Method

#### Creative Thinking (`creativethinking`)
Engage in creative and lateral thinking to generate innovative solutions and break through conventional thinking patterns.

**Creative techniques:** Brainstorming, lateral thinking, analogical thinking, random stimulation, constraint removal, perspective shifting
**When to use:** Innovation challenges, breaking mental blocks, exploring alternative solutions
**Combines well with:** Collaborative Reasoning, Mental Models, Decision Framework

#### Systems Thinking (`systemsthinking`)
Analyze complex systems by understanding components, relationships, feedback loops, and emergent behaviors.

**Key concepts:** Components, relationships, feedback loops, emergent properties, leverage points
**When to use:** Understanding complex organizational/technical systems, identifying root causes in multi-component systems
**Combines well with:** Mental Models, Collaborative Reasoning, Decision Framework

### 🔍 Analysis Tools

#### Debugging Approach (`debuggingapproach`)
Apply systematic debugging methodologies to identify, isolate, and resolve complex issues efficiently.

**Available approaches:**
- `binary_search` - Systematically narrow down problem space
- `reverse_engineering` - Work backwards from symptoms
- `divide_conquer` - Break complex problems into manageable pieces
- `backtracking` - Retrace steps to find where problems were introduced
- `cause_elimination` - Systematically rule out potential causes
- `program_slicing` - Focus on specific code paths relevant to the issue

**When to use:** Troubleshooting production issues, performance optimization, integration problems
**Combines well with:** Scientific Method, Sequential Thinking, Mental Models

#### Scientific Method (`scientificmethod`)
Apply systematic, evidence-based investigation and hypothesis testing.

**Stages:** Observation, question, hypothesis, experiment, analysis, conclusion, iteration
**When to use:** Investigating system behavior, testing causal relationships, validating assumptions
**Combines well with:** Debugging Approach, Sequential Thinking, Decision Framework

#### Metacognitive Monitoring (`metacognitivemonitoring`)
Monitor and assess your thinking processes, knowledge boundaries, and reasoning quality.

**Monitoring stages:** Knowledge assessment, confidence calibration, bias detection, uncertainty mapping, approach evaluation
**When to use:** Assessing expertise limits, evaluating confidence levels, detecting reasoning biases
**Combines well with:** Decision Framework, Scientific Method, Sequential Thinking

### 🎯 Decision Tools

#### Decision Framework (`decisionframework`)
Apply structured decision-making frameworks for rational choice between alternatives with systematic evaluation.

**Analysis types:** Expected-utility, pros-cons, criteria-matrix, risk-assessment, stakeholder-impact
**Decision stages:** Problem definition, option generation, criteria establishment, evaluation, selection, implementation planning
**When to use:** Choosing between multiple alternatives, technology selection, resource allocation
**Combines well with:** Mental Models, Collaborative Reasoning, Scientific Method

#### Socratic Method (`socraticmethod`)
Guide inquiry through systematic Socratic questioning to deepen understanding and challenge assumptions.

**Stages:** Clarification, assumptions, evidence, perspectives, implications, questions
**Argument types:** Deductive, inductive, abductive, analogical
**When to use:** Examining beliefs critically, deepening understanding, challenging reasoning
**Combines well with:** Mental Models, Structured Argumentation, Metacognitive Monitoring

#### Structured Argumentation (`structuredargumentation`)
Construct and analyze formal logical arguments with clear premises, reasoning chains, and evidence-based conclusions.

**Argument types:** Deductive, inductive, abductive, analogical, causal
**When to use:** Building persuasive cases, analyzing logical structure, evaluating competing positions
**Combines well with:** Socratic Method, Decision Framework, Scientific Method

### 🛠️ Technical Tools

#### Design Pattern (`designpattern`)
Apply proven design patterns to solve recurring software architecture and design problems.

**Pattern categories:**
- Creational: Singleton, Factory, Builder, Prototype
- Structural: Adapter, Decorator, Facade, Proxy, Composite
- Behavioral: Observer, Strategy, Command, State, Template Method
- Architectural: MVC, MVP, MVVM, Repository, Dependency Injection

**When to use:** Implementing new components, refactoring code, solving common architectural challenges
**Combines well with:** Programming Paradigms, Systems Thinking, Decision Framework

#### Programming Paradigm (`programmingparadigm`)
Apply programming paradigms to select optimal coding approaches and solve problems using paradigm-specific thinking.

**Available paradigms:** Object-Oriented, Functional, Procedural, Reactive, Declarative, Concurrent
**When to use:** Selecting coding approaches, understanding language strengths, optimizing for specific problem types
**Combines well with:** Design Patterns, Decision Framework, Mental Models

#### Stochastic Algorithm (`stochasticalgorithm`)
Apply stochastic algorithms to solve decision-making problems involving uncertainty, probability, and sequential choices. Enhanced with scenario generation, sensitivity analysis, and comprehensive uncertainty quantification.

**Algorithm types:**
- `mdp` - Markov Decision Processes for sequential decision-making
- `mcts` - Monte Carlo Tree Search for game-like decision problems
- `bandit` - Multi-armed bandit algorithms for exploration vs exploitation
- `bayesian` - Bayesian inference for learning under uncertainty
- `hmm` - Hidden Markov Models for sequential data with hidden states

**Enhanced features:**
- **Scenario Generation**: Optimistic, pessimistic, most-likely, and black swan scenarios
- **Sensitivity Analysis**: Parameter importance ranking with confidence intervals
- **Uncertainty Quantification**: Comprehensive metrics including confidence intervals and percentiles
- **Multiple Output Formats**: Detailed, summary, and visual formats for different use cases

**When to use:** Decision-making under uncertainty, optimization with random elements, learning from incomplete data, risk assessment, scenario planning
**Combines well with:** Decision Framework, Scientific Method, Systems Thinking

### 📊 Visualization Tools

#### Visual Reasoning (`visualreasoning`)
Process visual reasoning through diagrammatic representation, spatial analysis, and visual problem-solving techniques.

**Diagram types:** Flowchart, network, hierarchy, timeline, spatial, conceptual
**Operations:** Create, analyze, modify, connect, simplify
**When to use:** Spatial problem-solving, conceptual mapping, pattern recognition, system visualization
**Combines well with:** Systems Thinking, Creative Thinking, Sequential Thinking

### 🤝 Collaboration Tools

#### Collaborative Reasoning (`collaborativereasoning`)
Facilitate multi-perspective collaborative reasoning by simulating diverse expert viewpoints and structured group analysis.

**Stages:** Problem definition, ideation, critique, integration, decision, reflection
**When to use:** Complex multi-faceted problems, high-stakes decisions, innovation requiring diverse perspectives
**Combines well with:** Decision Framework, Mental Models, Systems Thinking

### ⚙️ Utility Tools

#### Session Management (`session_info`, `session_export`, `session_import`)
Manage session state, export data for backup, and import previous sessions.

**Features:** Session statistics, data export/import, cross-tool context tracking
**When to use:** Managing long analysis sessions, backing up work, sharing analysis contexts

## Prerequisites

- Node.js 18.0.0 or higher
- pnpm (recommended) or npm

## Installation

### Quick Start with NPX (Recommended)

Run the MCP Thinking Tools server directly from npm:

```bash
npx @davenportsociety/clear-thought-patterns
```

### Alternative Installation Methods

#### Option 1: Install Globally

```bash
# Using pnpm (recommended)
pnpm add -g @davenportsociety/clear-thought-patterns

# Using npm
npm install -g @davenportsociety/clear-thought-patterns

# Run the server
clear-thought-patterns
```

#### Option 2: Install from GitHub

```bash
npx github:TheDavenportSociety/clear-thought-patterns
```

#### Option 3: Local Development Setup

1. Clone the repository:

```bash
git clone https://github.com/TheDavenportSociety/clear-thought-patterns.git
```

2. Navigate to the project directory:

```bash
cd clear-thought-patterns
```

3. Install dependencies:

```bash
pnpm install
```

4. Build the project:

```bash
pnpm run build
```

## Usage

### Running the Server

#### Using NPX (Recommended)
```bash
npx @davenportsociety/clear-thought-patterns
```

#### Using Global Installation
```bash
clear-thought-patterns
```

#### Local Development
Start the server with:

```bash
pnpm start
```

This will start the MCP server using stdio transport, which can be connected to by MCP clients.

### Development Mode

For development with automatic reloading:

```bash
pnpm run dev
```

### Using with MCP Clients

The server can be used with any MCP-compatible client. Here are some examples:

#### Using with Claude Desktop

Add the server to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "clear-thought-patterns": {
      "command": "npx",
      "args": ["@davenportsociety/clear-thought-patterns"]
    }
  }
}
```

#### Using with the MCP Inspector

1. Install the MCP Inspector:

```bash
pnpm add -g @modelcontextprotocol/inspector
```

2. Run the server with inspector:

```bash
mcp-inspector npx @davenportsociety/clear-thought-patterns
```

#### Using with Other MCP Clients

The server can be integrated with any MCP-compatible application. Refer to the [MCP documentation](https://modelcontextprotocol.io/) for specific integration details.

### Example Tool Usage

Once connected to an MCP client, you can use any of the 16 thinking tools:

```javascript
// Use mental models for problem analysis
await client.callTool('mentalmodel', {
  modelName: 'first_principles',
  problem: 'How should we architect our new microservices system?',
  steps: ['Identify core requirements', 'Break down into fundamental components'],
  reasoning: 'Starting with basic needs and building up systematically...',
  conclusion: 'A service-per-domain approach with shared infrastructure'
});

// Apply debugging approaches for issue resolution
await client.callTool('debuggingapproach', {
  approachName: 'binary_search',
  steps: ['Identify midpoint', 'Test functionality', 'Narrow search space'],
  resolution: 'Found the issue in the authentication middleware'
});
```

## Tool Selection

For detailed tool selection guidance, use cases, and combinations, see `.augment-rules/thinking-tools.md`.

Each tool includes comprehensive usage guidance in its description. The tools are designed to be self-contained while integrating with the overall guidance system.

## Project Structure

```
clear-thought-patterns/
├── dist/                    # Compiled JavaScript files
├── src/                     # TypeScript source code
│   ├── index.ts            # Main server entry point
│   ├── config.ts           # Configuration management
│   ├── models/             # Data interfaces and types
│   │   └── interfaces.ts   # Core data structures
│   ├── state/              # Session state management
│   │   ├── session-state.ts # Main session state class
│   │   └── stores/         # Individual data stores
│   ├── tools/              # Tool implementations (16 tools)
│   │   ├── index.ts        # Tool registry
│   │   ├── mental-model.ts # Mental models tool
│   │   ├── sequential-thinking.ts
│   │   ├── debugging-approach.ts
│   │   ├── collaborative-reasoning.ts
│   │   ├── decision-framework.ts
│   │   ├── metacognitive.ts
│   │   ├── socratic-method.ts
│   │   ├── creative-thinking.ts
│   │   ├── systems-thinking.ts
│   │   ├── scientific-method.ts
│   │   ├── structured-argumentation.ts
│   │   ├── visual-reasoning.ts
│   │   ├── design-pattern.ts
│   │   ├── programming-paradigm.ts
│   │   ├── stochastic-algorithm.ts
│   │   └── session-management.ts
│   └── types/              # TypeScript type definitions
│       └── index.ts        # Exported types
├── scripts/                # Testing and utility scripts
├── package.json            # Project dependencies and scripts
├── tsconfig.json          # TypeScript configuration
├── tsup.config.ts         # Build configuration
└── README.md              # Project documentation
```

## Development

### Building the Project

```bash
# Build for production
pnpm run build

# Build with watch mode
pnpm run build:watch
```

### Testing

```bash
# Run all tool tests
pnpm test

# Run simple tests
pnpm test:simple

# Run key tool tests
pnpm test:key

# Test NPX installation
pnpm test:npx
```

### Code Quality

```bash
# Type checking
pnpm run type-check

# Linting
pnpm run lint
pnpm run lint:fix

# Formatting
pnpm run format
pnpm run format:check

# Run all checks
pnpm run check
```

## Tech Stack

- **Runtime:** Node.js 18.0.0+
- **Language:** TypeScript
- **Protocol:** Model Context Protocol (MCP) SDK
- **Validation:** Zod
- **Build:** tsup
- **Package Manager:** pnpm
- **Code Quality:** ESLint, Prettier

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/new-tool`
3. Make your changes and add tests
4. Run quality checks: `pnpm run check`
5. Commit your changes: `git commit -m 'Add new thinking tool'`
6. Push to the branch: `git push origin feature/new-tool`
7. Submit a pull request

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Author

**John Mendez** - [GitHub](https://github.com/JM-Mendez)

## Repository

[https://github.com/TheDavenportSociety/clear-thought-patterns](https://github.com/TheDavenportSociety/clear-thought-patterns)