ultrathink: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

UltraThink is an MCP (Model Context Protocol) server built with FastMCP framework. The project provides tools that can be consumed by MCP clients.

Development Commands

Setup & Dependencies

# Install dependencies (managed by uv)
uv sync

Task Commands (npm-like)

# List all tasks
uv run task --list

# Run server
uv run task run

# Run tests with coverage
uv run task test

# Quick tests (no coverage)
uv run task test-quick

# Run 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
uv run task clean

Direct Commands (Alternative)

Prefer using uv run task commands above. For direct execution:

# Run the server directly
uv run ultrathink

# Run the test client directly (connects to server via in-memory transport)
uv run task client
# Or: uv run python examples/client.py

This will test all available tools by connecting to the MCP server and calling each tool with sample inputs.

Architecture

Project Structure

src/ultrathink/                    # Main package
├── models/                        # DATA MODELS
│   ├── thought.py                 # Thought, ThoughtRequest, ThoughtResponse models
│   └── session.py                 # ThinkingSession model
├── services/                      # BUSINESS LOGIC
│   └── thinking_service.py        # UltraThinkService
├── interface/                     # EXTERNAL INTERFACE
│   └── mcp_server.py              # FastMCP server & tool registration
├── __init__.py                    # Package exports
└── __main__.py                    # CLI entry point

tests/                             # Test files (100% coverage, mirroring source structure)
├── models/
│   ├── test_thought.py            # Thought model tests
│   └── test_session.py            # Session logging tests
├── services/
│   └── test_thinking_service.py   # Service validation, functionality, branching, multi-session
├── interface/
│   └── test_mcp_server.py         # MCP tool function tests
└── test_cli.py                    # CLI entry point tests

examples/                          # Example/demo scripts
└── client.py                      # Test harness for the MCP server