UltraThink MCP Server

A Python MCP server for sequential thinking and problem-solving

Enhanced Python port of the Sequential Thinking MCP Server by Anthropic. Maintains full compatibility while adding confidence scoring, auto-assigned thought numbers, and multi-session support.

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):

Development Setup

For local development:

Usage

Task Commands (npm-like)

Direct Commands (Alternative)

For direct execution without task runner:

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

With Enhanced Features

With Uncertainty Notes and Outcome

With Assumption Tracking

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)

Local Development

For local development from source:

Local Configuration File

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

Example configuration (.mcp.json.example):

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

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

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

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

Type Checking

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