{"id":32722815,"url":"https://github.com/husniadil/ultrathink","last_synced_at":"2026-05-14T13:32:09.305Z","repository":{"id":321948493,"uuid":"1087249446","full_name":"husniadil/ultrathink","owner":"husniadil","description":"MCP server for sequential thinking and complex problem-solving. Built iteratively using itself. Features confidence scoring,   assumption tracking, and multi-session support.","archived":false,"fork":false,"pushed_at":"2025-11-09T14:21:16.000Z","size":224,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-09T15:21:07.189Z","etag":null,"topics":["developer-tools","fastmcp","mcp","model-context-protocol","problem-solving","python","sequential-thinking"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/husniadil.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-31T15:49:34.000Z","updated_at":"2025-11-09T14:21:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/husniadil/ultrathink","commit_stats":null,"previous_names":["husniadil/ultrathink"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/husniadil/ultrathink","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/husniadil%2Fultrathink","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/husniadil%2Fultrathink/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/husniadil%2Fultrathink/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/husniadil%2Fultrathink/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/husniadil","download_url":"https://codeload.github.com/husniadil/ultrathink/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/husniadil%2Fultrathink/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33026818,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["developer-tools","fastmcp","mcp","model-context-protocol","problem-solving","python","sequential-thinking"],"created_at":"2025-11-02T22:01:20.271Z","updated_at":"2026-05-14T13:32:09.244Z","avatar_url":"https://github.com/husniadil.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# UltraThink MCP Server\n\n\u003cdiv align=\"center\"\u003e\n\n**A Python MCP server for sequential thinking and problem-solving**\n\n[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)\n[![FastMCP](https://img.shields.io/badge/FastMCP-2.13.0.2-green.svg)](https://github.com/jlowin/fastmcp)\n[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Claude Code Plugin](https://img.shields.io/badge/Claude_Code-Plugin_Available-orange.svg)](https://github.com/husniadil/ekstend/tree/main/plugins/ultrathink)\n\n\u003c/div\u003e\n\n---\n\n\u003e **Enhanced Python port** of the [Sequential Thinking MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking) by Anthropic.\n\u003e Maintains full compatibility while adding **confidence scoring**, **auto-assigned thought numbers**, and **multi-session support**.\n\n\u003e [!TIP]\n\u003e **Using Claude Code?** Install the [UltraThink Plugin](https://github.com/husniadil/ekstend/tree/main/plugins/ultrathink) for seamless integration - no MCP server setup required!\n\u003e ```bash\n\u003e # Via terminal\n\u003e claude plugin marketplace add husniadil/ekstend\n\u003e claude plugin install ultrathink@ekstend\n\u003e\n\u003e # Or interactively in Claude Code\n\u003e /plugin marketplace add husniadil/ekstend\n\u003e /plugin install ultrathink@ekstend\n\u003e ```\n\n\u003e [!NOTE]\n\u003e **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.\n\n---\n\n## Features\n\n- **UltraThink**: Break down complex problems into manageable steps\n- **Dynamic Adjustments**: Revise and refine thoughts as understanding deepens\n- **Branching**: Explore alternative paths of reasoning\n- **Confidence Scoring**: Explicit uncertainty tracking (0.0-1.0 scale)\n- **Auto-adjustment**: Automatically adjusts total thoughts if needed\n- **Multi-Session Support**: Manage multiple concurrent thinking sessions with session IDs\n- **Formatted Logging**: Colored terminal output with rich formatting (can be disabled)\n- **100% Test Coverage**: Comprehensive test suite with full code coverage\n- **Type Safety**: Full mypy strict mode type checking for production code\n- **Simple Layered Architecture**: Clean separation with models, services, and interface layers\n\n## Installation\n\n### Quick Install (Recommended)\n\nRun directly with uvx from GitHub (no installation needed):\n\n```bash\nuvx --from git+https://github.com/husniadil/ultrathink ultrathink\n```\n\n### Development Setup\n\nFor local development:\n\n```bash\n# Clone the repository\ngit clone https://github.com/husniadil/ultrathink.git\ncd ultrathink\n\n# Install all dependencies (including dev dependencies)\nuv sync\n```\n\n## Usage\n\n### Task Commands (npm-like)\n\n```bash\n# List all available tasks\nuv run task --list\n\n# Run the server\nuv run task run\n\n# Run tests with coverage\nuv run task test\n\n# Run tests without coverage (quick)\nuv run task test-quick\n\n# Run the test client\nuv run task client\n\n# Format code (ruff + prettier)\nuv run task format\n\n# Lint code\nuv run task lint\n\n# Type check with mypy\nuv run task typecheck\n\n# Clean cache files\nuv run task clean\n```\n\n### Direct Commands (Alternative)\n\nFor direct execution without task runner:\n\n```bash\n# Run the server directly\nuv run ultrathink\n\n# Run the test client directly\nuv run python examples/client.py\n```\n\n**Note:** For testing, linting, and formatting, prefer using `uv run task` commands shown above.\n\n## Tool: ultrathink\n\nThe server provides a single tool for dynamic and reflective problem-solving through structured thinking.\n\n### Parameters\n\n**Required:**\n\n- `thought` (str): Your current thinking step\n- `total_thoughts` (int): Estimated total thoughts needed (\u003e=1)\n\n**Optional:**\n\n- `thought_number` (int): Current thought number - auto-assigned sequentially if omitted (1, 2, 3...), or provide explicit number for branching/semantic control\n- `next_thought_needed` (bool): Whether another thought step is needed. Auto-assigned as `thought_number \u003c total_thoughts` if omitted. Set explicitly to override default behavior\n- `session_id` (str): Session identifier for managing multiple thinking sessions (None = create new, provide ID to continue session)\n- `is_revision` (bool): Whether this revises previous thinking\n- `revises_thought` (int): Which thought number is being reconsidered\n- `branch_from_thought` (int): Branching point thought number\n- `branch_id` (str): Branch identifier\n- `needs_more_thoughts` (bool): If more thoughts are needed\n- `confidence` (float): Confidence level (0.0-1.0, e.g., 0.7 for 70% confident)\n- `uncertainty_notes` (str): Optional explanation for doubts or concerns about this thought\n- `outcome` (str): What was achieved or expected as result of this thought\n- `assumptions` (list[Assumption]): Assumptions made in this thought (id, text, confidence, critical, verifiable)\n- `depends_on_assumptions` (list[str]): Assumption IDs this thought depends on (e.g., [\"A1\", \"A2\"])\n- `invalidates_assumptions` (list[str]): Assumption IDs proven false (e.g., [\"A3\"])\n\n### Response\n\nReturns a JSON object with:\n\n- `session_id`: Session identifier for continuation\n- `thought_number`: Current thought number\n- `total_thoughts`: Total thoughts (auto-adjusted if needed)\n- `next_thought_needed`: Whether more thinking is needed\n- `branches`: List of branch IDs\n- `thought_history_length`: Number of thoughts processed in this session\n- `confidence`: Confidence level of this thought (0.0-1.0, optional)\n- `uncertainty_notes`: Explanation for doubts or concerns (optional)\n- `outcome`: What was achieved or expected (optional)\n- `all_assumptions`: All assumptions tracked in this session (keyed by ID)\n- `risky_assumptions`: IDs of risky assumptions (critical + low confidence + unverified)\n- `falsified_assumptions`: IDs of assumptions proven false\n\n### Example\n\n#### Basic Usage\n\n```python\nfrom fastmcp import Client\nfrom ultrathink import mcp\n\nasync with Client(mcp) as client:\n    # Simple sequential thinking with auto-assigned fields\n    result = await client.call_tool(\"ultrathink\", {\n        \"thought\": \"Let me analyze this problem step by step\",\n        \"total_thoughts\": 3\n        # thought_number auto-assigned: 1\n        # next_thought_needed auto-assigned: True (1 \u003c 3)\n    })\n```\n\n#### With Enhanced Features\n\n```python\nasync with Client(mcp) as client:\n    # With confidence scoring and explicit session\n    result = await client.call_tool(\"ultrathink\", {\n        \"thought\": \"Initial hypothesis - this approach might work\",\n        \"total_thoughts\": 5,\n        \"confidence\": 0.6,  # 60% confident\n        # next_thought_needed auto-assigned: True\n        \"session_id\": \"problem-solving-session-1\"\n    })\n\n    # Continue the same session with higher confidence\n    result2 = await client.call_tool(\"ultrathink\", {\n        \"thought\": \"After analysis, I'm more certain about this solution\",\n        \"total_thoughts\": 5,\n        \"confidence\": 0.9,  # 90% confident\n        # next_thought_needed auto-assigned: True\n        \"session_id\": \"problem-solving-session-1\"  # Same session\n    })\n\n    # Branch from a previous thought\n    result3 = await client.call_tool(\"ultrathink\", {\n        \"thought\": \"Let me explore an alternative approach\",\n        \"total_thoughts\": 6,\n        \"confidence\": 0.7,\n        \"branch_from_thought\": 1,\n        \"branch_id\": \"alternative-path\",\n        # next_thought_needed auto-assigned: True\n        \"session_id\": \"problem-solving-session-1\"\n    })\n```\n\n#### With Uncertainty Notes and Outcome\n\n```python\nasync with Client(mcp) as client:\n    # Track uncertainty and outcomes\n    result = await client.call_tool(\"ultrathink\", {\n        \"thought\": \"Testing the authentication fix\",\n        \"total_thoughts\": 5,\n        \"confidence\": 0.8,\n        \"uncertainty_notes\": \"Haven't tested under high load yet\",\n        \"outcome\": \"Login flow works for standard users\"\n    })\n\n    # Response includes the new fields\n    print(result[\"confidence\"])          # 0.8\n    print(result[\"uncertainty_notes\"])   # \"Haven't tested under high load yet\"\n    print(result[\"outcome\"])             # \"Login flow works for standard users\"\n```\n\n#### With Assumption Tracking\n\n```python\nasync with Client(mcp) as client:\n    # Thought 1: State assumptions explicitly\n    result = await client.call_tool(\"ultrathink\", {\n        \"thought\": \"Redis should meet our performance requirements\",\n        \"total_thoughts\": 4,\n        \"assumptions\": [\n            {\n                \"id\": \"A1\",\n                \"text\": \"Network latency to Redis \u003c 5ms\",\n                \"confidence\": 0.8,\n                \"critical\": True,\n                \"verifiable\": True,\n                \"evidence\": \"Based on preliminary network tests in staging environment\"\n            }\n        ]\n    })\n\n    # Thought 2: Build on previous assumptions\n    result2 = await client.call_tool(\"ultrathink\", {\n        \"thought\": \"Based on low latency, Redis can handle 10K req/sec\",\n        \"total_thoughts\": 4,\n        \"depends_on_assumptions\": [\"A1\"],\n        \"session_id\": result[\"session_id\"]\n    })\n\n    # Thought 3: Invalidate if proven false\n    result3 = await client.call_tool(\"ultrathink\", {\n        \"thought\": \"After testing, latency is 15ms, not 5ms!\",\n        \"total_thoughts\": 4,\n        \"invalidates_assumptions\": [\"A1\"],\n        \"session_id\": result[\"session_id\"]\n    })\n\n    # Track all assumptions and detect risky ones\n    print(result3[\"all_assumptions\"])      # {\"A1\": {...}}\n    print(result3[\"falsified_assumptions\"]) # [\"A1\"]\n```\n\n## Configuration\n\n### Environment Variables\n\n- `DISABLE_THOUGHT_LOGGING`: Set to `\"true\"` to disable colored thought logging to stderr\n\n### Usage with Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n#### Using uvx from GitHub (Recommended)\n\n```json\n{\n  \"mcpServers\": {\n    \"UltraThink\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"--from\",\n        \"git+https://github.com/husniadil/ultrathink\",\n        \"ultrathink\"\n      ]\n    }\n  }\n}\n```\n\n#### Local Development\n\nFor local development from source:\n\n```json\n{\n  \"mcpServers\": {\n    \"UltraThink\": {\n      \"command\": \"uv\",\n      \"args\": [\"--directory\", \"/path/to/ultrathink\", \"run\", \"ultrathink\"]\n    }\n  }\n}\n```\n\n### Local Configuration File\n\nFor local development and testing, you can create a `.mcp.json` file (see `.mcp.json.example`):\n\n```bash\n# Copy the example file\ncp .mcp.json.example .mcp.json\n\n# Edit to match your local path\n# Change /path/to/ultrathink to your actual directory\n```\n\nExample configuration (`.mcp.json.example`):\n\n```json\n{\n  \"mcpServers\": {\n    \"UltraThink\": {\n      \"command\": \"uv\",\n      \"args\": [\"--directory\", \"/path/to/ultrathink\", \"run\", \"ultrathink\"],\n      \"env\": {\n        \"DISABLE_THOUGHT_LOGGING\": \"false\"\n      }\n    }\n  }\n}\n```\n\nThis configuration:\n\n- Enables thought logging by default (`DISABLE_THOUGHT_LOGGING: \"false\"`)\n- Can be used with MCP clients that support `.mcp.json` configuration\n- Useful for testing the server locally with colored output enabled\n- **Note:** `.mcp.json` is gitignored - customize it for your local setup\n\n## Session Management\n\n### Session Lifecycle\n\n**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:\n\n- Thought history for that session\n- Branch tracking\n- Sequential thought numbering\n\n**Implications:**\n\n- Sessions do not persist across server restarts\n- All thinking context is lost when the server stops\n- For production use cases requiring persistent sessions, you would need to implement custom session persistence (e.g., to disk, database, or external state management)\n\n**Best Practices:**\n\n- Use custom session IDs (instead of auto-generated UUIDs) for resilient recovery if you need to recreate session context\n- Keep session-critical information in your application layer if persistence is required\n- Consider sessions as ephemeral working memory for active problem-solving tasks\n\n## Architecture\n\nBuilt with **Simple Layered Architecture** principles for clean separation of concerns and maintainable code.\n\n### Files\n\n**src/ultrathink/** (3-layer structure)\n\n**Models Layer** (`models/`)\n\n- **thought.py**: Thought, ThoughtRequest, ThoughtResponse models\n- **session.py**: ThinkingSession model\n\n**Services Layer** (`services/`)\n\n- **thinking_service.py**: UltraThinkService business logic\n\n**Interface Layer** (`interface/`)\n\n- **mcp_server.py**: MCP server entry point with FastMCP tool registration\n\n**Package Entry Points**\n\n- **\\_\\_init\\_\\_.py**: Package exports\n- **\\_\\_main\\_\\_.py**: CLI entry point (enables `uv run ultrathink`)\n\n**tests/** (100% coverage, mirroring source structure)\n\n**Models Tests** (`models/`)\n\n- **test_thought.py**: Thought model tests (properties, formatting)\n- **test_session.py**: Session logging and formatting tests\n\n**Services Tests** (`services/`)\n\n- **test_thinking_service.py**: Service tests (validation, functionality, branching, multi-session)\n\n**Interface Tests** (`interface/`)\n\n- **test_mcp_server.py**: MCP tool function tests\n\n**Root Test Files**\n\n- **test_cli.py**: CLI entry point tests\n\n**examples/**\n\n- **client.py**: Test client demonstrating tool usage\n\n### Architecture Layers\n\n#### 1. Models Layer\n\nPydantic models for data representation and validation:\n\n**Thought**: Core model representing a single thought with validation and behaviors\n**ThoughtRequest**: Input model from MCP clients with validation\n**ThoughtResponse**: Output model to MCP clients with structured data\n**ThinkingSession**: Session model managing thought history and branches\n\n```python\n# Type-safe model usage\nrequest = ThoughtRequest(\n    thought=\"My thinking step\",\n    thought_number=1,\n    total_thoughts=3,\n    next_thought_needed=True\n)\nresponse = ThoughtResponse(\n    thought_number=1,\n    total_thoughts=3,\n    next_thought_needed=True,\n    branches=[],\n    thought_history_length=1\n)\n```\n\n#### 2. Services Layer\n\nBusiness logic and orchestration:\n\n**UltraThinkService**: Orchestrates the thinking process\n\n**Responsibilities:**\n\n- **Model Translation**: `ThoughtRequest → Thought` model (input)\n- **Business Logic**: Delegate to `ThinkingSession`\n- **Response Building**: Session state → `ThoughtResponse` model (output)\n- **Validation**: Leverages Pydantic for automatic validation\n- **Session Management**: Create and manage multiple thinking sessions\n\n**Key Method:**\n\n- `process_thought(request: ThoughtRequest) → ThoughtResponse`: Main orchestration\n\n```python\nservice = UltraThinkService()\n\n# Full flow:\n# 1. Receives ThoughtRequest from interface layer\n# 2. Translates to Thought model\n# 3. Calls session.add_thought() (business logic)\n# 4. Builds ThoughtResponse from session state\n# 5. Returns response\nrequest = ThoughtRequest(thought=\"...\", thought_number=1, ...)\nresponse = service.process_thought(request)\n```\n\n#### 3. Interface Layer\n\nExternal interface using FastMCP:\n\n**mcp_server.py**: MCP server tool registration\n\n**Responsibilities:**\n\n- Define MCP tools using `@mcp.tool` decorator\n- Map tool parameters to model types\n- Call services layer for processing\n- Return responses to MCP clients\n\n```python\n@mcp.tool\ndef ultrathink(thought: str, total_thoughts: int, ...) -\u003e ThoughtResponse:\n    request = ThoughtRequest(thought=thought, total_thoughts=total_thoughts, ...)\n    return thinking_service.process_thought(request)\n```\n\n**Type Safety Benefits:**\n\n- Pydantic validation on all inputs/outputs\n- No arbitrary dicts - strict typing throughout\n- Automatic validation errors\n- Clear separation between interface and business logic\n\n### Architecture Benefits\n\n1. **Clear Separation of Concerns**:\n   - Models layer = Data models with validation and behaviors\n   - Services layer = Business logic and orchestration\n   - Interface layer = External API (MCP tools)\n\n2. **Simpler Structure**: Flatter folder hierarchy (2 levels instead of 3)\n\n3. **Easier Imports**: Shorter relative import paths (`..models` vs `...domain.entities`)\n\n4. **Consolidated Models**: Related models grouped together (Thought, ThoughtRequest, ThoughtResponse in one file)\n\n5. **Testable**: Easy to test each layer in isolation\n\n6. **Maintainable**:\n   - Change interface? → Update interface layer only\n   - Change business rules? → Update services layer only\n   - Change validation? → Update models layer only\n\n7. **Extensible**: Easy to add new models, services, or tools\n\n8. **Interface Independence**: Services can be reused with different interfaces (REST API, gRPC, CLI, etc.)\n\n9. **Type Safety**: Pydantic models throughout ensure validation at all boundaries\n\n## Development\n\n### Running Tests\n\n```bash\n# Run all tests with coverage (recommended)\nuv run task test\n\n# Run tests without coverage (quick)\nuv run task test-quick\n\n# Coverage is 100%\n```\n\n### Type Checking\n\n```bash\n# Run mypy type checker on all code\nuv run task typecheck\n\n# Mypy runs in strict mode on entire codebase\n```\n\nThe project uses **mypy in strict mode** across the entire codebase (`src/`, `tests/`, `examples/`) to ensure complete type safety.\n\n### Test Organization\n\nTests are organized by layers, mirroring the source structure (100% coverage):\n\n**Models Layer Tests** (`tests/models/`)\n\n- **test_thought.py**: Model properties, auto-adjustment, formatting, validation, and confidence scoring\n- **test_session.py**: Session logging and formatted output\n\n**Services Layer Tests** (`tests/services/`)\n\n- **test_thinking_service.py**: Service validation, functionality, branching, edge cases, response format, reference validation, and multi-session support\n\n**Interface Layer Tests** (`tests/interface/`)\n\n- **test_mcp_server.py**: MCP tool function invocation\n\n**Root Tests**\n\n- **test_cli.py**: CLI entry point\n\n## Credits\n\nThis 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.\n\n## New Features\n\nWhile maintaining full compatibility with the original design, UltraThink adds several enhancements:\n\n1. **Confidence Scoring** - Explicit uncertainty tracking with 0.0-1.0 scale for each thought\n2. **Auto-assigned Thought Numbers** - Optional thought numbering (auto-increments if omitted)\n3. **Multi-Session Support** - Manage multiple concurrent thinking sessions with session IDs\n4. **Assumption Tracking** - Make reasoning transparent with explicit assumptions, dependencies, and invalidation tracking\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhusniadil%2Fultrathink","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhusniadil%2Fultrathink","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhusniadil%2Fultrathink/lists"}