ThinkChain

A Python demonstration project showcasing Claude's advanced capabilities through interleaved thinking, fine-grained tool streaming, and dynamic tool discovery with MCP (Model Context Protocol) integration.

Created by Martin Bowling • GitHub • Twitter/X

Overview

ThinkChain demonstrates the power of Claude's streaming interface with advanced features like:

Interleaved and extended thinking - Claude thinks through problems step-by-step in real-time
Fine-grained tool streaming - Watch tools execute with live progress updates
Early interception of tool_use blocks - Tool results are injected back into Claude's thinking process
Multiple tool calls per turn - Execute multiple tools simultaneously for complex workflows
Pydantic-validated inputs - Robust type checking and validation for all tool interactions

The system combines local Python tools with MCP servers to create a unified, extensible tool ecosystem that works seamlessly with Claude's streaming capabilities.

🚀 Quick Start

Option 1: Zero-Setup with `uv run` (Recommended)

# Clone the repository
git clone https://github.com/martinbowling/ThinkChain.git
cd ThinkChain

# Set up your API key
echo "ANTHROPIC_API_KEY=your_api_key_here" > .env

# Run immediately - uv handles all dependencies automatically!
uv run thinkchain.py     # Enhanced UI with rich formatting
uv run thinkchain_cli.py # Minimal CLI version  
uv run run.py            # Smart launcher (auto-detects best UI)

Option 2: Traditional Installation

# Clone and set up
git clone https://github.com/martinbowling/ThinkChain.git
cd ThinkChain

# Install dependencies
uv pip install -r requirements.txt
# or: pip install -r requirements.txt

# Set up your API key
echo "ANTHROPIC_API_KEY=your_api_key_here" > .env

# Run the application
python run.py            # Smart launcher
python thinkchain.py     # Enhanced UI
python thinkchain_cli.py # CLI version

✨ Key Features

🧠 Advanced Thinking Integration

The core innovation of ThinkChain is how tool execution results are injected back into Claude's thinking stream. When Claude calls a tool:

The tool executes and returns results
Results are immediately fed back into Claude's thinking process
Claude can reason about the results before responding to the user
This creates a natural thinking → tool → thinking → response flow

🔧 Dynamic Tool Discovery

Local Tools: Automatically discovers Python tools from the /tools directory
MCP Integration: Connects to Model Context Protocol servers for extended functionality
Hot Reloading: Use refresh command to reload tools during development
Unified Registry: All tools (local + MCP) work identically in the streaming interface

🎨 Enhanced CLI Interface

Rich formatting with colors, borders, and progress indicators
Interactive tool browser with categorized displays
Command autocomplete and history
Real-time thinking visualization with syntax highlighting
Graceful degradation to standard text interface

⚡ Streaming Architecture

Server-sent events (SSE) for real-time communication
Fine-grained streaming of tool execution progress
Concurrent tool execution when possible
Robust error handling and recovery

🔧 Developer Experience

Zero-setup execution with uv run - no virtual environments or dependency installation needed
Automatic tool discovery from /tools directory
Hot reloading with /refresh command during development
Rich error messages and graceful degradation when dependencies are missing

🛠 Technical Architecture

Tool Injection System

The key technical innovation is the tool result injection mechanism:

# Tool results are injected back into Claude's thinking process
async def stream_once(messages, tools):
    # Start streaming with thinking enabled
    async with client.messages.stream(
        model="claude-sonnet-4-20250514",
        messages=messages,
        tools=tools,
        betas=["interleaved-thinking-2025-05-14", "fine-grained-tool-streaming-2025-05-14"],
        thinking_budget=1024
    ) as stream:
        
        async for event in stream:
            if event.type == "tool_use":
                # Execute tool and inject result back into stream
                result = await execute_tool(event.name, event.input)
                
                # This result becomes part of Claude's thinking context
                # for the remainder of the response
                yield {"type": "tool_result", "content": result}

This creates a feedback loop where:

Claude's initial thinking leads to tool use
Tool results inform continued thinking
Final response incorporates both reasoning and tool outcomes

Tool Discovery Pipeline

Local Tools (/tools/*.py) → Validation → Registry
                                         ↓
MCP Servers (config.json) → Connection → Registry → Unified Tool List → Claude API

Each tool must implement the BaseTool interface:

class BaseTool:
    @property
    def name(self) -> str: ...
    
    @property  
    def description(self) -> str: ...
    
    @property
    def input_schema(self) -> Dict[str, Any]: ...
    
    def execute(self, **kwargs) -> str: ...

Streaming Event Flow

User Input → Claude API → Thinking Stream → Tool Detection → Tool Execution
     ↑                                                            ↓
Response ← Thinking Integration ← Tool Result Injection ← Tool Output

📚 Available Tools

Local Tools (`/tools` directory)

🌐 Web & Data Tools:

weathertool: Real weather data from wttr.in API for any location worldwide
duckduckgotool: Live DuckDuckGo search results for web queries and restaurant searches
webscrapertool: Enhanced web scraper that extracts main content from any webpage

📁 File & Development Tools:

filecreatortool: Creates new files with specified content and directory structure
fileedittool: Advanced file editing with full/partial content replacement and search/replace
filecontentreadertool: Reads and returns content from multiple files simultaneously
createfolderstool: Creates directories and nested folder structures
diffeditortool: Precise text snippet replacement in files

⚙️ Development & Package Management:

uvpackagemanager: Complete interface to uv package manager for Python projects
lintingtool: Runs Ruff linter on Python files to detect and fix code issues
toolcreator: Dynamically creates new tools based on natural language descriptions

MCP Server Support

Configure in mcp_config.json:

SQLite: Database operations and queries
Puppeteer: Web browser automation
Filesystem: Advanced file system operations
Brave Search: Real web search integration

🎮 Interactive Commands

While chatting with Claude, you can use these slash commands:

/refresh or /reload - Refresh tool discovery (picks up new tools)
/tools - Browse all available tools by category
/status - Show comprehensive system status
/clear - Clear screen while preserving status bar
/config - Show current configuration
/config model <model_name> - Switch between Claude models (sonnet/opus)
/config thinking <1024-16000> - Adjust thinking token budget
/help - Show help information
/exit or /quit - End the conversation

Legacy Support: All commands work without the / prefix for backward compatibility.

⚙️ Configuration

Environment Setup

Create .env file:

ANTHROPIC_API_KEY=your_api_key_here

MCP Server Configuration

Edit mcp_config.json:

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "./database.db"],
      "enabled": true
    },
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"],
      "enabled": false
    }
  }
}

Model Configuration

The system supports both Claude models with configurable settings:

Available Models:

claude-sonnet-4-20250514 (default) - Fast and efficient
claude-opus-4-20250514 - Most capable, slower

Configurable Settings:

Thinking budget: 1024-16000 tokens (default: 1024)
Max response tokens: 1024
Beta features: interleaved-thinking-2025-05-14, fine-grained-tool-streaming-2025-05-14

Runtime Configuration:

# Change model during conversation
/config model claude-opus-4-20250514

# Increase thinking budget for complex problems  
/config thinking 8192

🔧 Development

Creating New Local Tools

Creating a new tool is straightforward - just follow these steps:

1. Create Tool File

Create a new Python file in the /tools/ directory (e.g., /tools/mytool.py):

from tools.base import BaseTool

class MyTool(BaseTool):
    name = "mytool"
    description = """
    A detailed description of what your tool does.
    
    Use this tool when users ask about:
    - Specific use case 1
    - Specific use case 2
    - "Keywords that should trigger this tool"
    """
    
    input_schema = {
        "type": "object",
        "properties": {
            "input_param": {
                "type": "string",
                "description": "Description of this parameter"
            },
            "optional_param": {
                "type": "integer", 
                "description": "Optional parameter with default",
                "default": 10
            }
        },
        "required": ["input_param"]
    }
    
    def execute(self, **kwargs) -> str:
        input_param = kwargs.get("input_param")
        optional_param = kwargs.get("optional_param", 10)
        
        # Your tool logic here
        result = f"Processed: {input_param} with {optional_param}"
        
        return result

2. Key Requirements

Class name: Must match filename (e.g., MyTool for mytool.py)
Inherit from BaseTool: Import from tools.base
Four required attributes: name, description, input_schema, execute() method
Return strings: The execute() method must return a string result

3. Tool Discovery

Tools are automatically discovered on startup
Use /refresh command to reload tools without restarting
Check with /tools command to see your new tool listed

4. Best Practices

Descriptive names: Use clear, action-oriented names
Rich descriptions: Include use cases and keywords that should trigger the tool
Input validation: Use comprehensive JSON schemas
Error handling: Wrap risky operations in try/catch blocks
Helpful output: Return formatted, readable results

Adding MCP (Model Context Protocol) Servers

MCP allows integration with external servers that provide additional tools:

1. Install MCP Server

Most MCP servers can be installed via uvx or npx:

# Install SQLite MCP server
uvx install mcp-server-sqlite

# Install Puppeteer MCP server (requires Node.js)
npm install -g @modelcontextprotocol/server-puppeteer

# Install Brave Search MCP server  
npm install -g @modelcontextprotocol/server-brave-search

2. Configure MCP Server

Edit mcp_config.json to add your server:

{
  "mcpServers": {
    "my-server": {
      "command": "uvx",
      "args": ["my-mcp-server", "--custom-arg", "value"],
      "description": "Description of what this server provides",
      "enabled": true,
      "env": {
        "API_KEY": "your_api_key_if_needed"
      }
    }
  }
}

3. Available MCP Servers

Popular MCP servers you can integrate:

Data & Storage:

mcp-server-sqlite - Database operations
mcp-server-postgres - PostgreSQL integration
mcp-server-redis - Redis cache operations

Web & Automation:

@modelcontextprotocol/server-puppeteer - Browser automation
@modelcontextprotocol/server-brave-search - Web search
@modelcontextprotocol/server-filesystem - File operations

APIs & Services:

@modelcontextprotocol/server-github - GitHub integration
@modelcontextprotocol/server-slack - Slack integration
mcp-server-aws - AWS operations

4. Test MCP Integration

After adding a server, test it:

# Test MCP functionality
python test_mcp.py

# Start ThinkChain and check tools
python thinkchain.py
/tools  # Should show both local and MCP tools

Development Workflow

1. Tool Development Cycle

# Create tool
vim tools/newtool.py

# Test tool
python thinkchain.py
/refresh  # Reload tools
"Use my new tool for X"  # Test with Claude

# Iterate and improve
vim tools/newtool.py
/refresh  # Reload again

2. Debugging Tools

Use print() statements in your execute() method - they'll show in console
Return error messages as strings for Claude to see
Check the tool discovery logs on startup

Running Different Interfaces

# Traditional Python execution
python run.py            # Smart launcher
python thinkchain.py     # Full-featured UI
python thinkchain_cli.py # Minimal dependencies

# Using uv run (handles dependencies automatically)
uv run run.py            # Smart launcher
uv run thinkchain.py     # Full-featured UI
uv run thinkchain_cli.py # Minimal dependencies

📋 Dependencies

Core Requirements

anthropic>=0.25.0 - Claude API client
sseclient-py - Server-sent events handling
pydantic - Data validation and schemas
python-dotenv - Environment variable management

Enhanced UI (Optional)

rich - Terminal formatting and colors
prompt_toolkit - Interactive command line features

MCP Integration (Optional)

mcp - Model Context Protocol client
MCP server packages (installed via uvx or npx)

Tool Dependencies (Optional)

Some tools require additional packages that are installed automatically:

Web Tools: (weathertool, duckduckgotool, webscrapertool)

requests - HTTP requests
beautifulsoup4 - HTML parsing

Note: Missing dependencies are handled gracefully - tools that can't import will be skipped during discovery with informative error messages.

UV Run Support

All main scripts include inline dependency declarations that make them compatible with uv run:

#!/usr/bin/env python3
# /// script
# dependencies = [
#     "anthropic>=0.25.0",
#     "sseclient-py",
#     "pydantic", 
#     "python-dotenv",
#     "rich>=13.0.0",
#     "requests",
#     "beautifulsoup4",
#     "mcp",
#     "httpx",
# ]
# ///

Benefits of uv run:

✅ Zero setup - No need to create virtual environments or install dependencies
✅ Automatic dependency management - uv handles everything
✅ Isolated execution - Each run gets a clean environment
✅ Cross-platform - Works identically on macOS, Linux, and Windows

# All these work immediately after cloning:
uv run thinkchain.py     # Enhanced UI with all features
uv run thinkchain_cli.py # Minimal CLI version  
uv run run.py            # Smart launcher
uv run test_mcp.py       # Test MCP integration

🤝 Contributing

This project is designed to be forked and extended! Here are some ideas:

Add new local tools for your specific use cases
Integrate additional MCP servers from the growing ecosystem
Enhance the UI with new visualization features
Extend the streaming architecture for custom event types
Build domain-specific tool collections (data science, web dev, etc.)

Getting Started with Your Fork

The process is straightforward with uv run:

# Fork and clone
git clone https://github.com/yourusername/your-thinkchain-fork.git
cd your-thinkchain-fork

# Set up API key
echo "ANTHROPIC_API_KEY=your_key" > .env

# Create your first tool
vim tools/yourtool.py

# Test immediately with uv run (no setup needed!)
uv run thinkchain.py
/refresh  # Loads your new tool
"Use my new tool for X"  # Test with Claude

Fork Ideas

Data Science ThinkChain: Add pandas, matplotlib, jupyter tools
Web Development ThinkChain: Add React, npm, git, deployment tools
DevOps ThinkChain: Add Docker, Kubernetes, AWS/GCP tools
Research ThinkChain: Add academic paper search, citation tools

📄 License

MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Inspired by Pietro Schirano's chain of tools concept - we loved the idea and decided to crank out our own version!
Built with Anthropic's Claude API
MCP integration powered by the Model Context Protocol
Enhanced UI built with Rich and Prompt Toolkit

Ready to think differently about AI tool integration? Fork ThinkChain and start building! 🚀

thinkchain