# UltraThink MCP Server

<div align="center">

**A Python MCP server for sequential thinking and problem-solving**

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![FastMCP](https://img.shields.io/badge/FastMCP-2.13.0.2-green.svg)](https://github.com/jlowin/fastmcp)
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Claude Code Plugin](https://img.shields.io/badge/Claude_Code-Plugin_Available-orange.svg)](https://github.com/husniadil/ekstend/tree/main/plugins/ultrathink)

</div>

---

> **Enhanced Python port** of the [Sequential Thinking MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking) by Anthropic.
> Maintains full compatibility while adding **confidence scoring**, **auto-assigned thought numbers**, and **multi-session support**.

> [!TIP]
> **Using Claude Code?** Install the [UltraThink Plugin](https://github.com/husniadil/ekstend/tree/main/plugins/ultrathink) for seamless integration - no MCP server setup required!
> ```bash
> # Via terminal
> claude plugin marketplace add husniadil/ekstend
> claude plugin install ultrathink@ekstend
>
> # Or interactively in Claude Code
> /plugin marketplace add husniadil/ekstend
> /plugin install ultrathink@ekstend
> ```

> [!NOTE]
> **Meta**: This MCP server was built iteratively using UltraThink itself - a practical example of the tool's capability to break down complex problems, manage architectural decisions, and maintain context across development sessions.

---

## Features

- **UltraThink**: Break down complex problems into manageable steps
- **Dynamic Adjustments**: Revise and refine thoughts as understanding deepens
- **Branching**: Explore alternative paths of reasoning
- **Confidence Scoring**: Explicit uncertainty tracking (0.0-1.0 scale)
- **Auto-adjustment**: Automatically adjusts total thoughts if needed
- **Multi-Session Support**: Manage multiple concurrent thinking sessions with session IDs
- **Formatted Logging**: Colored terminal output with rich formatting (can be disabled)
- **100% Test Coverage**: Comprehensive test suite with full code coverage
- **Type Safety**: Full mypy strict mode type checking for production code
- **Simple Layered Architecture**: Clean separation with models, services, and interface layers

## Installation

### Quick Install (Recommended)

Run directly with uvx from GitHub (no installation needed):

```bash
uvx --from git+https://github.com/husniadil/ultrathink ultrathink
```

### Development Setup

For local development:

```bash
# Clone the repository
git clone https://github.com/husniadil/ultrathink.git
cd ultrathink

# Install all dependencies (including dev dependencies)
uv sync
```

## Usage

### Task Commands (npm-like)

```bash
# List all available tasks
uv run task --list

# Run the server
uv run task run

# Run tests with coverage
uv run task test

# Run tests without coverage (quick)
uv run task test-quick

# Run the test client
uv run task client

# Format code (ruff + prettier)
uv run task format

# Lint code
uv run task lint

# Type check with mypy
uv run task typecheck

# Clean cache files
uv run task clean
```

### Direct Commands (Alternative)

For direct execution without task runner:

```bash
# Run the server directly
uv run ultrathink

# Run the test client directly
uv run python examples/client.py
```

**Note:** For testing, linting, and formatting, prefer using `uv run task` commands shown above.

## Tool: ultrathink

The server provides a single tool for dynamic and reflective problem-solving through structured thinking.

### Parameters

**Required:**

- `thought` (str): Your current thinking step
- `total_thoughts` (int): Estimated total thoughts needed (>=1)

**Optional:**

- `thought_number` (int): Current thought number - auto-assigned sequentially if omitted (1, 2, 3...), or provide explicit number for branching/semantic control
- `next_thought_needed` (bool): Whether another thought step is needed. Auto-assigned as `thought_number < total_thoughts` if omitted. Set explicitly to override default behavior
- `session_id` (str): Session identifier for managing multiple thinking sessions (None = create new, provide ID to continue session)
- `is_revision` (bool): Whether this revises previous thinking
- `revises_thought` (int): Which thought number is being reconsidered
- `branch_from_thought` (int): Branching point thought number
- `branch_id` (str): Branch identifier
- `needs_more_thoughts` (bool): If more thoughts are needed
- `confidence` (float): Confidence level (0.0-1.0, e.g., 0.7 for 70% confident)
- `uncertainty_notes` (str): Optional explanation for doubts or concerns about this thought
- `outcome` (str): What was achieved or expected as result of this thought
- `assumptions` (list[Assumption]): Assumptions made in this thought (id, text, confidence, critical, verifiable)
- `depends_on_assumptions` (list[str]): Assumption IDs this thought depends on (e.g., ["A1", "A2"])
- `invalidates_assumptions` (list[str]): Assumption IDs proven false (e.g., ["A3"])

### Response

Returns a JSON object with:

- `session_id`: Session identifier for continuation
- `thought_number`: Current thought number
- `total_thoughts`: Total thoughts (auto-adjusted if needed)
- `next_thought_needed`: Whether more thinking is needed
- `branches`: List of branch IDs
- `thought_history_length`: Number of thoughts processed in this session
- `confidence`: Confidence level of this thought (0.0-1.0, optional)
- `uncertainty_notes`: Explanation for doubts or concerns (optional)
- `outcome`: What was achieved or expected (optional)
- `all_assumptions`: All assumptions tracked in this session (keyed by ID)
- `risky_assumptions`: IDs of risky assumptions (critical + low confidence + unverified)
- `falsified_assumptions`: IDs of assumptions proven false

### Example

#### Basic Usage

```python
from fastmcp import Client
from ultrathink import mcp

async with Client(mcp) as client:
    # Simple sequential thinking with auto-assigned fields
    result = await client.call_tool("ultrathink", {
        "thought": "Let me analyze this problem step by step",
        "total_thoughts": 3
        # thought_number auto-assigned: 1
        # next_thought_needed auto-assigned: True (1 < 3)
    })
```

#### With Enhanced Features

```python
async with Client(mcp) as client:
    # With confidence scoring and explicit session
    result = await client.call_tool("ultrathink", {
        "thought": "Initial hypothesis - this approach might work",
        "total_thoughts": 5,
        "confidence": 0.6,  # 60% confident
        # next_thought_needed auto-assigned: True
        "session_id": "problem-solving-session-1"
    })

    # Continue the same session with higher confidence
    result2 = await client.call_tool("ultrathink", {
        "thought": "After analysis, I'm more certain about this solution",
        "total_thoughts": 5,
        "confidence": 0.9,  # 90% confident
        # next_thought_needed auto-assigned: True
        "session_id": "problem-solving-session-1"  # Same session
    })

    # Branch from a previous thought
    result3 = await client.call_tool("ultrathink", {
        "thought": "Let me explore an alternative approach",
        "total_thoughts": 6,
        "confidence": 0.7,
        "branch_from_thought": 1,
        "branch_id": "alternative-path",
        # next_thought_needed auto-assigned: True
        "session_id": "problem-solving-session-1"
    })
```

#### With Uncertainty Notes and Outcome

```python
async with Client(mcp) as client:
    # Track uncertainty and outcomes
    result = await client.call_tool("ultrathink", {
        "thought": "Testing the authentication fix",
        "total_thoughts": 5,
        "confidence": 0.8,
        "uncertainty_notes": "Haven't tested under high load yet",
        "outcome": "Login flow works for standard users"
    })

    # Response includes the new fields
    print(result["confidence"])          # 0.8
    print(result["uncertainty_notes"])   # "Haven't tested under high load yet"
    print(result["outcome"])             # "Login flow works for standard users"
```

#### With Assumption Tracking

```python
async with Client(mcp) as client:
    # Thought 1: State assumptions explicitly
    result = await client.call_tool("ultrathink", {
        "thought": "Redis should meet our performance requirements",
        "total_thoughts": 4,
        "assumptions": [
            {
                "id": "A1",
                "text": "Network latency to Redis < 5ms",
                "confidence": 0.8,
                "critical": True,
                "verifiable": True,
                "evidence": "Based on preliminary network tests in staging environment"
            }
        ]
    })

    # Thought 2: Build on previous assumptions
    result2 = await client.call_tool("ultrathink", {
        "thought": "Based on low latency, Redis can handle 10K req/sec",
        "total_thoughts": 4,
        "depends_on_assumptions": ["A1"],
        "session_id": result["session_id"]
    })

    # Thought 3: Invalidate if proven false
    result3 = await client.call_tool("ultrathink", {
        "thought": "After testing, latency is 15ms, not 5ms!",
        "total_thoughts": 4,
        "invalidates_assumptions": ["A1"],
        "session_id": result["session_id"]
    })

    # Track all assumptions and detect risky ones
    print(result3["all_assumptions"])      # {"A1": {...}}
    print(result3["falsified_assumptions"]) # ["A1"]
```

## Configuration

### Environment Variables

- `DISABLE_THOUGHT_LOGGING`: Set to `"true"` to disable colored thought logging to stderr

### Usage with Claude Desktop

Add to your `claude_desktop_config.json`:

#### Using uvx from GitHub (Recommended)

```json
{
  "mcpServers": {
    "UltraThink": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/husniadil/ultrathink",
        "ultrathink"
      ]
    }
  }
}
```

#### Local Development

For local development from source:

```json
{
  "mcpServers": {
    "UltraThink": {
      "command": "uv",
      "args": ["--directory", "/path/to/ultrathink", "run", "ultrathink"]
    }
  }
}
```

### Local Configuration File

For local development and testing, you can create a `.mcp.json` file (see `.mcp.json.example`):

```bash
# Copy the example file
cp .mcp.json.example .mcp.json

# Edit to match your local path
# Change /path/to/ultrathink to your actual directory
```

Example configuration (`.mcp.json.example`):

```json
{
  "mcpServers": {
    "UltraThink": {
      "command": "uv",
      "args": ["--directory", "/path/to/ultrathink", "run", "ultrathink"],
      "env": {
        "DISABLE_THOUGHT_LOGGING": "false"
      }
    }
  }
}
```

This configuration:

- Enables thought logging by default (`DISABLE_THOUGHT_LOGGING: "false"`)
- Can be used with MCP clients that support `.mcp.json` configuration
- Useful for testing the server locally with colored output enabled
- **Note:** `.mcp.json` is gitignored - customize it for your local setup

## Session Management

### Session Lifecycle

**Important:** Sessions are stored **in-memory only** and will be lost when the server restarts or terminates. Each session is identified by a unique session ID and maintains:

- Thought history for that session
- Branch tracking
- Sequential thought numbering

**Implications:**

- Sessions do not persist across server restarts
- All thinking context is lost when the server stops
- For production use cases requiring persistent sessions, you would need to implement custom session persistence (e.g., to disk, database, or external state management)

**Best Practices:**

- Use custom session IDs (instead of auto-generated UUIDs) for resilient recovery if you need to recreate session context
- Keep session-critical information in your application layer if persistence is required
- Consider sessions as ephemeral working memory for active problem-solving tasks

## Architecture

Built with **Simple Layered Architecture** principles for clean separation of concerns and maintainable code.

### Files

**src/ultrathink/** (3-layer structure)

**Models Layer** (`models/`)

- **thought.py**: Thought, ThoughtRequest, ThoughtResponse models
- **session.py**: ThinkingSession model

**Services Layer** (`services/`)

- **thinking_service.py**: UltraThinkService business logic

**Interface Layer** (`interface/`)

- **mcp_server.py**: MCP server entry point with FastMCP tool registration

**Package Entry Points**

- **\_\_init\_\_.py**: Package exports
- **\_\_main\_\_.py**: CLI entry point (enables `uv run ultrathink`)

**tests/** (100% coverage, mirroring source structure)

**Models Tests** (`models/`)

- **test_thought.py**: Thought model tests (properties, formatting)
- **test_session.py**: Session logging and formatting tests

**Services Tests** (`services/`)

- **test_thinking_service.py**: Service tests (validation, functionality, branching, multi-session)

**Interface Tests** (`interface/`)

- **test_mcp_server.py**: MCP tool function tests

**Root Test Files**

- **test_cli.py**: CLI entry point tests

**examples/**

- **client.py**: Test client demonstrating tool usage

### Architecture Layers

#### 1. Models Layer

Pydantic models for data representation and validation:

**Thought**: Core model representing a single thought with validation and behaviors
**ThoughtRequest**: Input model from MCP clients with validation
**ThoughtResponse**: Output model to MCP clients with structured data
**ThinkingSession**: Session model managing thought history and branches

```python
# Type-safe model usage
request = ThoughtRequest(
    thought="My thinking step",
    thought_number=1,
    total_thoughts=3,
    next_thought_needed=True
)
response = ThoughtResponse(
    thought_number=1,
    total_thoughts=3,
    next_thought_needed=True,
    branches=[],
    thought_history_length=1
)
```

#### 2. Services Layer

Business logic and orchestration:

**UltraThinkService**: Orchestrates the thinking process

**Responsibilities:**

- **Model Translation**: `ThoughtRequest → Thought` model (input)
- **Business Logic**: Delegate to `ThinkingSession`
- **Response Building**: Session state → `ThoughtResponse` model (output)
- **Validation**: Leverages Pydantic for automatic validation
- **Session Management**: Create and manage multiple thinking sessions

**Key Method:**

- `process_thought(request: ThoughtRequest) → ThoughtResponse`: Main orchestration

```python
service = UltraThinkService()

# Full flow:
# 1. Receives ThoughtRequest from interface layer
# 2. Translates to Thought model
# 3. Calls session.add_thought() (business logic)
# 4. Builds ThoughtResponse from session state
# 5. Returns response
request = ThoughtRequest(thought="...", thought_number=1, ...)
response = service.process_thought(request)
```

#### 3. Interface Layer

External interface using FastMCP:

**mcp_server.py**: MCP server tool registration

**Responsibilities:**

- Define MCP tools using `@mcp.tool` decorator
- Map tool parameters to model types
- Call services layer for processing
- Return responses to MCP clients

```python
@mcp.tool
def ultrathink(thought: str, total_thoughts: int, ...) -> ThoughtResponse:
    request = ThoughtRequest(thought=thought, total_thoughts=total_thoughts, ...)
    return thinking_service.process_thought(request)
```

**Type Safety Benefits:**

- Pydantic validation on all inputs/outputs
- No arbitrary dicts - strict typing throughout
- Automatic validation errors
- Clear separation between interface and business logic

### Architecture Benefits

1. **Clear Separation of Concerns**:
   - Models layer = Data models with validation and behaviors
   - Services layer = Business logic and orchestration
   - Interface layer = External API (MCP tools)

2. **Simpler Structure**: Flatter folder hierarchy (2 levels instead of 3)

3. **Easier Imports**: Shorter relative import paths (`..models` vs `...domain.entities`)

4. **Consolidated Models**: Related models grouped together (Thought, ThoughtRequest, ThoughtResponse in one file)

5. **Testable**: Easy to test each layer in isolation

6. **Maintainable**:
   - Change interface? → Update interface layer only
   - Change business rules? → Update services layer only
   - Change validation? → Update models layer only

7. **Extensible**: Easy to add new models, services, or tools

8. **Interface Independence**: Services can be reused with different interfaces (REST API, gRPC, CLI, etc.)

9. **Type Safety**: Pydantic models throughout ensure validation at all boundaries

## Development

### Running Tests

```bash
# Run all tests with coverage (recommended)
uv run task test

# Run tests without coverage (quick)
uv run task test-quick

# Coverage is 100%
```

### Type Checking

```bash
# Run mypy type checker on all code
uv run task typecheck

# Mypy runs in strict mode on entire codebase
```

The project uses **mypy in strict mode** across the entire codebase (`src/`, `tests/`, `examples/`) to ensure complete type safety.

### Test Organization

Tests are organized by layers, mirroring the source structure (100% coverage):

**Models Layer Tests** (`tests/models/`)

- **test_thought.py**: Model properties, auto-adjustment, formatting, validation, and confidence scoring
- **test_session.py**: Session logging and formatted output

**Services Layer Tests** (`tests/services/`)

- **test_thinking_service.py**: Service validation, functionality, branching, edge cases, response format, reference validation, and multi-session support

**Interface Layer Tests** (`tests/interface/`)

- **test_mcp_server.py**: MCP tool function invocation

**Root Tests**

- **test_cli.py**: CLI entry point

## Credits

This project is a Python port of the [Sequential Thinking MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking) by Anthropic, part of the Model Context Protocol servers collection. The original implementation provides the foundation for structured thinking and problem-solving.

## New Features

While maintaining full compatibility with the original design, UltraThink adds several enhancements:

1. **Confidence Scoring** - Explicit uncertainty tracking with 0.0-1.0 scale for each thought
2. **Auto-assigned Thought Numbers** - Optional thought numbering (auto-increments if omitted)
3. **Multi-Session Support** - Manage multiple concurrent thinking sessions with session IDs
4. **Assumption Tracking** - Make reasoning transparent with explicit assumptions, dependencies, and invalidation tracking

## License

[MIT](LICENSE)