MCP Search

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:

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

fastmcp dev src/mcpmcts/cli.py

Related MCP server: Darbot Deepmind MCP Server

📖 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+ 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 (recommended) or pip

Install from Source

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

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

{
  "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:

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

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

# Run tests
uv run pytest

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

Code Quality

# 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 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 file for details.

🙏 Acknowledgments

• Based on academic research in search algorithms for LLM reasoning

• Built with FastMCP 2.0+ 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

• 🐛 Issue Tracker

• 💬 Discussions