# MCP Search

[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![FastMCP](https://img.shields.io/badge/FastMCP-2.0+-green.svg)](https://github.com/jlowin/fastmcp)

> Advanced reasoning for Large Language Models using Monte Carlo Tree Search and Beam Search algorithms

A Python implementation of the MCP Search toolkit that enhances Large Language Model (LLM) reasoning at inference time through advanced search strategies. This package overcomes the limitations of greedy, autoregressive decoding by implementing Monte Carlo Tree Search (MCTS) and Beam Search algorithms to explore and evaluate multiple reasoning paths.

## 🚀 Quick Start

### Recommended: Streamable HTTP Transport

Due to limited support for uvx transport in many MCP clients, we recommend using the streamable-http transport for the best compatibility:

```bash
# Install dependencies
uv sync --all-packages
uv pip install -e .

# Start the server (recommended approach)
fastmcp run src/mcpmcts/cli.py --port 8080 --transport streamable-http
```

### Alternative: Development Mode

For development and debugging:

```bash
fastmcp dev src/mcpmcts/cli.py
```

## 📖 Overview

Large Language Models often suffer from myopic reasoning due to their standard token-by-token generation process. This leads to locally optimal but globally suboptimal solutions, especially in complex, multi-step reasoning scenarios. MCP Search addresses this challenge by constructing and evaluating a tree of possible reasoning paths, enabling the LLM to explore alternative lines of thought, look ahead, and select more coherent and accurate solutions.

## ✨ Key Features

### 🔍 **Advanced Search Strategies**
- **Monte Carlo Tree Search (MCTS)**: Intelligently balances exploration of new reasoning paths with exploitation of proven effective paths
- **Beam Search**: Efficient breadth-first search that maintains the top-k most promising paths at each step
- **Experimental Variants**: MCTS-002-Alpha and MCTS-002Alt-Alpha for enhanced reasoning capabilities

### 🧠 **Intelligent Reasoning Architecture**
- **Hybrid Two-Loop System**: Combines LLM-generated semantic thoughts with fast heuristic simulations
- **Thought Quality Evaluation**: Multi-factor scoring based on logical coherence, structural integrity, and completion status
- **Tree Visualization**: Real-time console visualization of the reasoning tree using the `rich` library

### 🚀 **FastMCP Integration**
- Built with [FastMCP 2.0+](https://github.com/jlowin/fastmcp) for modern MCP server capabilities
- Multiple tools for different reasoning operations
- Async support for efficient processing
- HTTP and stdio transport support

## 🛠️ Installation

### Prerequisites
- Python 3.12+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

### Install from Source

```bash
# Clone the repository
git clone https://github.com/your-org/mcp-search.git
cd mcp-search

# Install with uv (recommended)
uv sync

# Or install with pip
pip install -e .
```

## 🎯 Usage

### Production Deployment (Recommended)

For production use, we recommend the streamable-http transport:

```bash
# Start HTTP server
fastmcp run src/mcpmcts/cli.py --host 0.0.0.0 --port 8080 --transport streamable-http --log-level INFO
```

### Claude Desktop Integration

#### Streamable HTTP Configuration (Recommended)

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "mcp-search": {
      "command": "fastmcp",
      "args": [
        "run", 
        "src/mcpmcts/cli.py", 
        "--port", "8080", 
        "--transport", "streamable-http"
      ],
      "cwd": "/path/to/mcp-search"
    }
  }
}
```

#### Alternative: Stdio Transport

If your Claude Desktop version supports stdio transport:

```json
{
  "mcpServers": {
    "mcp-search": {
      "command": "uv",
      "args": ["run", "fastmcp", "run", "src/mcpmcts/cli.py", "--transport", "stdio"],
      "cwd": "/path/to/mcp-search"
    }
  }
}
```

> **Note**: Due to limited uvx transport support across MCP clients, we strongly recommend using the streamable-http configuration for better compatibility and reliability.

## 🔧 Available Tools

### 1. `mcp_reasoner` - Main Reasoning Tool
The core reasoning engine that processes thoughts and builds the search tree.

**Parameters:**
- `thought` (required): Current reasoning step content
- `thought_number` (required): Current step number (≥1)
- `total_thoughts` (required): Total expected steps (≥1)
- `next_thought_needed` (required): Whether another step is needed
- `strategy_type` (optional): Strategy to use
  - `beam_search`: Efficient breadth-first search (default)
  - `mcts`: Monte Carlo Tree Search for complex reasoning
  - `mcts_002_alpha`: Enhanced MCTS with policy guidance
  - `mcts_002_alt_alpha`: Bidirectional search variant
- `beam_width` (optional): Number of top paths to maintain (1-10, default: 3)
- `num_simulations` (optional): Number of MCTS simulations (1-150, default: 50)

### 2. `get_reasoning_stats` - Comprehensive Statistics
Retrieve detailed statistics about the current reasoning session including:
- Total nodes in the tree
- Strategy performance metrics
- Score distributions
- Search depth analysis

### 3. `get_best_path` - Optimal Path Retrieval
Get the best reasoning path found so far, with complete thought sequence and scoring information.

### 4. `clear_reasoning_state` - State Management
Clear all reasoning state and start fresh for a new reasoning session.

### 5. `get_available_strategies` - Strategy Information
List all available reasoning strategies with their descriptions and optimal use cases.

## 🏗️ Architecture

### Core Components

#### ThoughtNode
The fundamental data structure representing a point in the reasoning process:
- `id`: Unique identifier
- `thought`: Textual content of the thought
- `score`: Numerical quality evaluation
- `depth`: Position in the reasoning tree
- `children`: List of child node IDs
- `parent_id`: Parent node reference
- `is_complete`: Terminal state indicator

#### StateManager
Manages storage and retrieval of ThoughtNode objects using an LRU cache for optimal performance.

#### BaseStrategy
Abstract base class providing common evaluation logic:
- **Logical Coherence**: Analyzes logical keywords and mathematical operators
- **Structural Integrity**: Measures coherence with parent thoughts
- **Depth Penalty**: Encourages concise reasoning paths
- **Completion Bonus**: Rewards completed reasoning sequences

### Search Strategies Comparison

| Feature | Monte Carlo Tree Search (MCTS) | Beam Search |
|---------|--------------------------------|-------------|
| **Search Strategy** | Balances exploration and exploitation (stochastic) | Mostly greedy exploitation (deterministic) |
| **Completeness** | Probabilistically complete (finds optimal path given time) | Not complete (can prune optimal paths) |
| **Memory Usage** | Can grow large, focuses on promising areas | Bounded by beam width × max depth |
| **Best For** | Complex problems with large search spaces | Problems solvable with greedy approaches |
| **Computational Cost** | Higher due to simulations | Lower, more predictable |

### MCTS Implementation Details

The MCTS implementation uses a hybrid two-loop system:

1. **Outer Loop**: LLM agent generates semantic thoughts and submits them via `process_thought`
2. **Inner Loop**: MCTS algorithm performs fast simulations using placeholder nodes and heuristic evaluation

This design avoids the prohibitive cost of using the full LLM for every simulation step while maintaining the statistical benefits of MCTS exploration.

## 📊 Thought Quality Evaluation

The system evaluates thoughts using a multi-factor scoring system:

```
Final Score = (logical_score + depth_penalty + completion_bonus) / 3.0
```

**Logical Score Components:**
- Length & Complexity: Bonus for thoughtful, detailed reasoning
- Logical Connectors: Rewards causal, contrastive, and sequential keywords
- Mathematical Expressions: Bonus for quantitative reasoning
- Parent-Child Coherence: Measures semantic consistency in reasoning chains

## 🎯 Use Cases

### Ideal for MCTS
- Complex mathematical problem solving
- Multi-step logical reasoning
- Planning and strategy problems
- Scenarios requiring exploration of multiple approaches

### Ideal for Beam Search
- Straightforward reasoning tasks
- Time-sensitive applications
- Memory-constrained environments
- Problems with clear progression paths

## 🔧 Development

### Project Structure

```
mcp-search/
├── src/
│   └── mcpmcts/
│       ├── __init__.py
│       ├── cli.py             # FastMCP server and CLI entry point
│       ├── reasoner.py        # Main reasoner orchestrator
│       ├── state.py           # State management with LRU cache
│       ├── types.py           # Core data structures and enums
│       ├── base.py            # Base strategy with evaluation logic
│       ├── beam_search.py     # Beam search implementation
│       ├── mcts.py            # Monte Carlo Tree Search implementation
│       ├── factory.py         # Strategy factory
│       └── responses.py       # Response models
├── tests/
│   └── test_example.py
├── pyproject.toml
└── README.md
```

### Running Tests

```bash
# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=mcpmcts
```

### Code Quality

```bash
# Format code
uv run ruff format

# Lint code
uv run ruff check

# Type checking
uv run mypy src/mcpmcts
```

### VS Code Development

The project includes VS Code launch configurations:

- **MCTS Dev MCP**: Development server with hot reload
- **MCTS Prod HTTP MCP**: Production HTTP server on port 6278

## ⚡ Performance Considerations

- **MCTS Simulations**: Configurable from 1-150 simulations per step
- **Beam Width**: Adjustable from 1-10 paths maintained
- **Memory Management**: LRU cache prevents unbounded memory growth
- **Heuristic Evaluation**: Fast scoring without LLM calls during simulations

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Implement your changes with tests
4. Run code quality checks
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Based on academic research in search algorithms for LLM reasoning
- Built with [FastMCP 2.0+](https://github.com/jlowin/fastmcp) for modern MCP server capabilities
- Inspired by Monte Carlo Tree Search applications in game theory and AI planning
- Implements concepts from the paper "Search Reasoning in MCP-MCTS"

## 📞 Support

- 📖 [Documentation](https://github.com/your-org/mcp-search/wiki)
- 🐛 [Issue Tracker](https://github.com/your-org/mcp-search/issues)
- 💬 [Discussions](https://github.com/your-org/mcp-search/discussions)

---

<div align="center">
Made with ❤️ for the MCP community
</div>