MCTS MCP Server

MCTS MCP サーバー

AI を活用した分析と推論のための高度なベイズ型モンテカルロ木探索（MCTS）エンジンを公開する、Model Context Protocol（MCP）サーバーです。

概要

この MCP サーバーを使用すると、Claude はモンテカルロ木探索（MCTS）アルゴリズムを利用して、トピック、質問、テキスト入力を深く探索しながら分析できます。MCTS アルゴリズムはベイズ的アプローチを用いて、さまざまな観点や解釈を体系的に探索し、複数回の反復を経て発展する洞察に富んだ分析を生成します。

機能

• ベイズ型 MCTS：確率論的アプローチを用いて、分析中の探索と活用のバランスを取ります
• 複数回の反復分析：各反復で複数のシミュレーションを実行し、思考を複数回反復できます
• 状態の永続化：同じチャット内のターン間で、主要な結果、不適切なアプローチ、事前分布を記憶します
• アプローチの分類体系：生成された思考を、さまざまな哲学的アプローチや系統に分類します
• トンプソンサンプリング：ノード選択にトンプソンサンプリングまたは UCT を使用できます
• 意外性の検出：意外な分析の方向性や新しい分析の方向性を特定します
• 意図の分類：ユーザーが新しい分析を始めたいのか、以前の分析を続けたいのかを理解します
• 複数の LLM をサポート：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 サーバーを読み込みます。

使い方

このサーバーは多数のツールを LLM に公開します。以下は、システムプロンプトにコピーして貼り付けられる形式で詳しく説明しています。

Claude にトピックや質問の詳細な分析を依頼すると、MCTS アルゴリズムと分析ツールを使ってさまざまな観点を自動的に探索します。

動作の仕組み

MCTS MCP サーバーは、LLM を直接呼び出そうとするのではなく、ローカル推論方式を使用します。これは、ツールが AI モデルを自ら呼び出すのではなく、AI アシスタント（Claude など）によって呼び出されるように設計された MCP プロトコルに準拠しています。

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 などの LLM プロバイダーを使用するには、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 ファイルで、デフォルトの LLM プロバイダーとモデル名も設定できます。

   # 使用するデフォルトの LLM プロバイダー（例："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

これにより、LLM アダプターが正しく動作していることを確認できます。

プロジェクト構成

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. リポジトリをフォークする
2. セットアップを実行する：python setup.py
3. インストールを検証する：python verify_installation.py
4. 変更を加える
5. 変更をテストする：python test_server.py
6. プルリクエストを送信する

ライセンス：MIT