MCTS MCP Server

MCTS MCP 服务

一个模型上下文协议（MCP）服务，提供高级贝叶斯蒙特卡洛树搜索（MCTS）引擎，用于 AI 辅助分析和推理。

概述

此 MCP 服务使 Claude 能够使用蒙特卡洛树搜索（MCTS）算法，对主题、问题或文本输入进行深入探索性分析。MCTS 算法采用贝叶斯方法，系统地探索不同的角度和解读，并通过多轮迭代不断完善，生成有见地的分析。

功能

• 贝叶斯 MCTS：使用概率方法，在分析过程中平衡探索与利用
• 多轮迭代分析：支持多轮思考，每轮包含多次模拟
• 状态持久化：在同一聊天的不同轮次之间记住关键结果、不合适的方法和先验信息
• 方法分类体系：将生成的想法归类到不同的哲学方法和流派中
• 汤普森采样：可使用汤普森采样或 UCT 进行节点选择
• 意外检测：识别令人意外或新颖的分析方向
• 意图分类：理解用户何时想要开始新的分析或继续之前的分析
• 多种大模型支持：支持 Ollama、OpenAI、Anthropic 和 Google Gemini 模型。

快速安装

MCTS MCP 服务现在包含适用于 Windows、macOS 和 Linux 的跨平台安装脚本。

前提条件

• Python 3.10+（必需）
• 互联网连接（用于下载依赖项）

自动设置

选项 1：跨平台 Python 设置（推荐）

# Clone the repository
git clone https://github.com/angrysky56/mcts-mcp-server.git
cd mcts-mcp-server

# Run the setup script
python setup.py

选项 2：平台专用脚本

Linux/macOS：

chmod +x setup.sh
./setup.sh

Windows：

setup_windows.bat

设置脚本的操作

设置脚本会自动：

1. ✅ 检查 Python 版本是否兼容（需要 3.10+）
2. ✅ 安装 UV 包管理器（如果尚未安装）
3. ✅ 创建虚拟环境
4. ✅ 安装所有依赖项，包括 google-genai
5. ✅ 根据模板创建 .env 文件
6. ✅ 生成 Claude Desktop 配置
7. ✅ 创建状态目录
8. ✅ 验证安装

验证安装

设置完成后，验证一切是否正常运行：

python verify_installation.py

此操作会执行全面检查，并告知你是否需要修复任何问题。

配置

1. 设置 API 密钥

编辑设置过程中创建的 .env 文件：

# Add your API keys (remove quotes and add real keys)
OPENAI_API_KEY=sk-your-openai-key-here
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key-here
GEMINI_API_KEY=your-gemini-api-key-here

# Set default provider and model (optional)
DEFAULT_LLM_PROVIDER=gemini
DEFAULT_MODEL_NAME=gemini-2.0-flash

获取 API 密钥：

• OpenAI：https://platform.openai.com/api-keys
• Anthropic：https://console.anthropic.com/
• Google Gemini：https://aistudio.google.com/app/apikey
• Ollama：无需 API 密钥（本地模型）

2. 集成 Claude Desktop

设置过程会创建 claude_desktop_config.json。将其内容添加到 Claude Desktop 配置中：

Linux/macOS：

# Config location
~/.config/claude/claude_desktop_config.json

Windows：

# Config location
%APPDATA%\Claude\claude_desktop_config.json

配置结构示例：

{
  "mcpServers": {
    "mcts-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcts-mcp-server/src",
        "run",
        "mcts-mcp-server"
      ],
      "env": {
        "UV_PROJECT_ENVIRONMENT": "/path/to/mcts-mcp-server"
      }
    }
  }
}

**重要：**更新路径，使其与安装目录相匹配。

3. 重启 Claude Desktop

添加配置后，重启 Claude Desktop 以加载 MCTS 服务。

用法

此服务会向你的大模型提供多个工具，以下以可复制粘贴的格式详细说明，供你添加到系统提示词中。

当你要求 Claude 深入分析某个主题或问题时，它会自动调用这些工具，使用 MCTS 算法和分析工具探索不同角度。

工作原理

MCTS MCP 服务采用本地推理方式，而不是尝试直接调用大模型。这与 MCP 协议兼容，因为 MCP 协议旨在让 AI 助手（如 Claude）调用工具，而不是让工具自行调用 AI 模型。

当 Claude 要求服务执行分析时，服务会：

1. 使用问题初始化 MCTS 系统
2. 使用 MCTS 算法运行多轮探索
3. 针对各种分析任务生成确定性响应
4. 返回搜索过程中找到的最佳分析结果

手动安装（高级）

如果你更喜欢手动设置，或自动设置失败：

1. 安装 UV 包管理器

Linux/macOS：

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows（PowerShell）：

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. 设置项目

# Clone repository
git clone https://github.com/angrysky56/mcts-mcp-server.git
cd mcts-mcp-server

# Create virtual environment
uv venv .venv

# Activate virtual environment
# Linux/macOS:
source .venv/bin/activate
# Windows:
.venv\Scripts\activate

# Install dependencies
uv pip install .
uv pip install .[dev]  # Optional development dependencies

# Install Gemini package specifically (if not in pyproject.toml)
uv pip install google-genai>=1.20.0

3. 创建配置文件

# Copy environment file
cp .env.example .env

# Edit .env file with your API keys
nano .env  # or use your preferred editor

# Create state directory
mkdir -p ~/.mcts_mcp_server

故障排除

常见问题

1. Python 版本错误

Solution: Install Python 3.10+ from python.org

2. 安装后找不到 UV

# Add UV to PATH manually
export PATH="$HOME/.cargo/bin:$PATH"
# Or on Windows: Add %USERPROFILE%\.cargo\bin to PATH

3. Google Gemini 导入错误

# Install Gemini package manually
uv pip install google-genai

4. 权限被拒绝（Linux/macOS）

# Make scripts executable
chmod +x setup.sh setup_unix.sh

5. Claude Desktop 未检测到服务

• 确认配置文件的位置和语法
• 检查配置中的路径是否为绝对路径且正确
• 完全重启 Claude Desktop
• 检查 Claude Desktop 日志中的错误

获取帮助

1. 运行验证：python verify_installation.py
2. 检查日志：查看 Claude Desktop 的开发者工具
3. 测试组件：运行仓库中的各项测试
4. 查看文档：参阅 USAGE_GUIDE.md，获取详细说明

API 密钥管理

要使用 OpenAI、Anthropic 和 Google Gemini 等大模型提供商，你需要提供 API 密钥。此服务会从仓库根目录下的 .env 文件中加载 API 密钥。

1. 复制示例文件：cp .env.example .env
2. 编辑 .env：打开 .env 文件，将占位密钥替换为你实际的 API 密钥：

   OPENAI_API_KEY="your_openai_api_key_here"
   ANTHROPIC_API_KEY="your_anthropic_api_key_here"
   GEMINI_API_KEY="your_google_gemini_api_key_here"
   

3. 设置默认值（可选）：你也可以在 .env 文件中设置默认大模型提供商和模型名称：

   # 要使用的默认大模型提供商（例如："ollama"、"openai"、"anthropic"、"gemini"）
   DEFAULT_LLM_PROVIDER="ollama"
   # 所选提供商的默认模型名称
   DEFAULT_MODEL_NAME="cogito:latest"
   

   如果未设置这些项，系统默认使用 "ollama"，并尝试使用类似 "cogito:latest" 的模型或其他提供商特定的默认模型。

.env 文件已列入 .gitignore，因此你的实际密钥不会提交到仓库中。

建议的系统提示词和更新后的工具

---

# MCTS server and usage instructions:

# List available Ollama models (if using Ollama)
list_ollama_models()

# Set the active LLM provider and model
# provider_name can be "ollama", "openai", "anthropic", "gemini"
# model_name is specific to the provider (e.g., "cogito:latest" for ollama, "gpt-4" for openai)
set_active_llm(provider_name="openai", model_name="gpt-3.5-turbo")
# Or, to use defaults from .env or provider-specific defaults:
# set_active_llm(provider_name="openai")

# Initialize analysis (can also specify provider and model here to override active settings for this run)
initialize_mcts(question="Your question here", chat_id="unique_id", provider_name="openai", model_name="gpt-4")
# Or using the globally set active LLM:
# initialize_mcts(question="Your question here", chat_id="unique_id")

run_mcts(iterations=1, simulations_per_iteration=5)

After run_mcts is called it can take quite a long time ie minutes to hours
- so you may discuss any ideas or questions or await user confirmation of the process finishing,
- then proceed to synthesis and analysis tools on resumption of chat.

## MCTS-MCP Tools Overview

### Core MCTS Tools:
- `initialize_mcts`: Start a new MCTS analysis with a specific question. Can optionally specify `provider_name` and `model_name` to override defaults for this run.
- `run_mcts`: Run the MCTS algorithm for a set number of iterations/simulations.
- `generate_synthesis`: Generate a final summary of the MCTS results.
- `get_config`: View current MCTS configuration parameters, including active LLM provider and model.
- `update_config`: Update MCTS configuration parameters (excluding provider/model, use `set_active_llm` for that).
- `get_mcts_status`: Check the current status of the MCTS system.
- `set_active_llm(provider_name: str, model_name: Optional[str])`: Select which LLM provider and model to use for MCTS.
- `list_ollama_models()`: Show all available local Ollama models (if using Ollama provider).

Default configuration prioritizes speed and exploration, but you can customize parameters like exploration_weight, beta_prior_alpha/beta, surprise_threshold.

## Configuration

You can customize the MCTS parameters in the config dictionary or through Claude's `update_config` tool. Key parameters include:

- `max_iterations`: Number of MCTS iterations to run
- `simulations_per_iteration`: Number of simulations per iteration
- `exploration_weight`: Controls exploration vs. exploitation balance (in UCT)
- `early_stopping`: Whether to stop early if a high-quality solution is found
- `use_bayesian_evaluation`: Whether to use Bayesian evaluation for node scores
- `use_thompson_sampling`: Whether to use Thompson sampling for selection

Articulating Specific Pathways:
Delving into the best_path nodes (using mcts_instance.get_best_path_nodes() if you have the instance) and examining the sequence of thought and content
at each step can provide a fascinating micro-narrative of how the core insight evolved.

Visualizing the tree (even a simplified version based on export_tree_summary) could also be illuminating and I will try to set up this feature.

Modifying Parameters: This is a great way to test the robustness of the finding or explore different "cognitive biases" of the system.

Increasing Exploration Weight: Might lead to more diverse, less obviously connected ideas.

Decreasing Exploration Weight: Might lead to deeper refinement of the initial dominant pathways.

Changing Priors (if Bayesian): You could bias the system towards certain approaches (e.g., increase alpha for 'pragmatic') to see how it influences the
outcome.

More Iterations/Simulations: Would allow for potentially deeper convergence or exploration of more niche pathways.

### Results Collection:
- Automatically stores results in `/home/ty/Repositories/ai_workspace/mcts-mcp-server/results` (path might be system-dependent or configurable)
- Organizes by provider, model name, and run ID
- Stores metrics, progress info, and final outputs

# MCTS Analysis Tools

This extension adds powerful analysis tools to the MCTS-MCP Server, making it easy to extract insights and understand results from your MCTS runs.

The MCTS Analysis Tools provide a suite of integrated functions to:

1. List and browse MCTS runs
2. Extract key concepts, arguments, and conclusions
3. Generate comprehensive reports
4. Compare results across different runs
5. Suggest improvements for better performance

## Available Run Analysis Tools

### Browsing and Basic Information

- `list_mcts_runs(count=10, model=None)`: List recent MCTS runs with key metadata
- `get_mcts_run_details(run_id)`: Get detailed information about a specific run
- `get_mcts_solution(run_id)`: Get the best solution from a run

### Analysis and Insights

- `analyze_mcts_run(run_id)`: Perform a comprehensive analysis of a run
- `get_mcts_insights(run_id, max_insights=5)`: Extract key insights from a run
- `extract_mcts_conclusions(run_id)`: Extract conclusions from a run
- `suggest_mcts_improvements(run_id)`: Get suggestions for improvement

### Reporting and Comparison

- `get_mcts_report(run_id, format='markdown')`: Generate a comprehensive report (formats: 'markdown', 'text', 'html')
- `get_best_mcts_runs(count=5, min_score=7.0)`: Get the best runs based on score
- `compare_mcts_runs(run_ids)`: Compare multiple runs to identify similarities and differences

## Usage Examples

# To list your recent MCTS runs:

list_mcts_runs()

# To get details about a specific run:

get_mcts_run_details('ollama_cogito:latest_1745979984') # Example run_id format

### Extracting Insights

# To get key insights from a run:

get_mcts_insights(run_id='ollama_cogito:latest_1745979984')

### Generating Reports

# To generate a comprehensive markdown report:

get_mcts_report(run_id='ollama_cogito:latest_1745979984', format='markdown')


### Improving Results

# To get suggestions for improving a run:

suggest_mcts_improvements(run_id='ollama_cogito:latest_1745979984')

### Comparing Runs

To compare multiple runs:

compare_mcts_runs(['ollama_cogito:latest_1745979984', 'openai_gpt-3.5-turbo_1745979584']) # Example run_ids

## Understanding the Results

The analysis tools extract several key elements from MCTS runs:

1. **Key Concepts**: The core ideas and frameworks in the analysis
2. **Arguments For/Against**: The primary arguments on both sides of a question
3. **Conclusions**: The synthesized conclusions or insights from the analysis
4. **Tags**: Automatically generated topic tags from the content

## Troubleshooting

If you encounter any issues with the analysis tools:

1. Check that your MCTS run completed successfully (status: "completed")
2. Verify that the run ID you're using exists and is correct
3. Try listing all runs to see what's available: `list_mcts_runs()`
4. Make sure the `.best_solution.txt` file exists in the run's directory

## Advanced Example Usage

### Customizing Reports

You can generate reports in different formats:

# Generate a markdown report

report = get_mcts_report(run_id='ollama_cogito:latest_1745979984', format='markdown')

# Generate a text report

report = get_mcts_report(run_id='ollama_cogito:latest_1745979984', format='text')

# Generate an HTML report

report = get_mcts_report(run_id='ollama_cogito:latest_1745979984', format='html')

### Finding the Best Runs

To find your best-performing runs:

best_runs = get_best_mcts_runs(count=3, min_score=8.0)

This returns the top 3 runs with a score of at least 8.0.

## Simple Usage Instructions

1. **Setting the LLM Provider and Model**:
   # For Ollama:
   list_ollama_models()  # See available Ollama models
   set_active_llm(provider_name="ollama", model_name="cogito:latest")

   # For OpenAI:
   set_active_llm(provider_name="openai", model_name="gpt-4")

   # For Anthropic:
   set_active_llm(provider_name="anthropic", model_name="claude-3-opus-20240229")

   # For Gemini:
   set_active_llm(provider_name="gemini", model_name="gemini-1.5-pro-latest")

2. **Starting a New Analysis**:
   # Uses the LLM set by set_active_llm, or defaults from .env
   initialize_mcts(question="Your question here", chat_id="unique_identifier")
   # Alternatively, specify provider/model for this specific analysis:
   # initialize_mcts(question="Your question here", chat_id="unique_identifier", provider_name="openai", model_name="gpt-4-turbo")

3. **Running the Analysis**:

   run_mcts(iterations=3, simulations_per_iteration=10)

4. **Comparing Performance (Ollama specific example)**:

   run_model_comparison(question="Your question", iterations=2)

5. **Getting Results**:

   generate_synthesis()  # Final summary of results
   get_mcts_status()     # Current status and metrics

---

提示词示例

• "分析人工智能对人类创造力的影响"
• "继续探索这一主题的伦理层面"
• "上次运行中找到的最佳分析结果是什么？"
• "MCTS 流程是如何工作的？"
• "显示当前的 MCTS 配置"

面向开发者

开发环境设置

# Activate virtual environment
source .venv/bin/activate

# Install development dependencies
uv pip install .[dev]

# Run the server directly (for testing)
uv run server.py

# OR use the MCP CLI tools
uv run -m mcp dev server.py

测试服务

要测试服务是否正常工作：

# Activate the virtual environment
source .venv/bin/activate

# Run the verification script
python verify_installation.py

# Run the test script
python test_server.py

这将测试大模型适配器，确保其正常工作。

项目结构

mcts-mcp-server/
├── src/mcts_mcp_server/          # Main package
│   ├── adapters/                 # LLM adapters
│   ├── analysis_tools/           # Analysis and reporting tools
│   ├── mcts_core.py             # Core MCTS algorithm
│   ├── tools.py                 # MCP tools
│   └── server.py                # MCP server
├── setup.py                     # Cross-platform setup script
├── setup.sh                     # Unix setup script
├── setup_windows.bat            # Windows setup script
├── verify_installation.py       # Installation verification
├── pyproject.toml               # Project configuration
├── .env.example                 # Environment template
└── README.md                    # This file

贡献

欢迎为改进 MCTS MCP 服务贡献力量。以下是一些可供改进的方面：

• 改进本地推理适配器，以支持更复杂的分析
• 添加更复杂的思维模式和评估策略
• 改进树形可视化和结果报告
• 优化 MCTS 算法参数

开发工作流

1. Fork 仓库
2. 运行设置：python setup.py
3. 验证安装：python verify_installation.py
4. 进行更改
5. 测试更改：python test_server.py
6. 提交拉取请求

许可证：MIT