クイックスタート

This project provides a generic Monte Carlo Tree Search (MCTS) framework. Its core concept is the replacement of the Genetic Programming (GP) engine from chess-ant with a modern AI agent. While inspired by AlphaZero, it uses a simpler, decoupled approach: the standard UCT algorithm is augmented by an external AI agent that performs Policy Pruning—narrowing the search space by supplying a pre-filtered list of promising moves.

This guide covers how to install the package and configure it for use with an AI agent like the Gemini CLI.

インストール

標準インストール

コアパッケージはpipを使い直接インストールできます：

pip install mcts-gen

ゲーム固有の依存関係を含むインストール

To include support for specific games, you can install optional dependencies (extras).

For Shogi support:
```
pip install mcts-gen[shogi]
```
This installs the python-shogi library.
For Chess support:
```
pip install mcts-gen[chess]
```
This installs the python-chess library.
For Ligand Generation:
```
pip install mcts-gen[ligand]
```
This installs rdkit and pandas for de novo ligand design capabilities. This feature allows for MCTS-based molecule generation guided by a protein pocket. It supports building ligands from single atoms or multi-atom fragments generated from a user-provided file of source molecules (e.g., SMILES, SDF, or CSV).

注釈

v0.0.4+ Change: The ligand generator now supports conformational diversity (including side-chain orientations) and AI-guided size control via the target_size parameter.
注釈

This feature also requires the external tool fpocket for identifying protein binding pockets. It can be installed on Debian/Ubuntu systems using snap:
```
sudo snap install fpocket
```

Gemini CLIのためのサーバー設定

To allow the Gemini agent to use the MCTS-Gen tools, you must register the server in your settings.json file. This allows the Gemini CLI to automatically manage the server process and provide the necessary context files.

注釈

v0.0.2+ Change: As of version 0.0.2, the core agent instructions are built-in. Specifying a context file is no longer required for standard operation. Only configure the context block if you wish to provide additional instructions to the agent.

Create or update your settings.json file with the following configuration:

{
  "context": {
    "fileName": [
      "src/mcts_gen/AGENTS.md",
      "GEMINI.md"
    ]
  },
  "mcpServers": {
    "mcts_gen_simulator_server": {
      "command": "python",
      "args": [
        "-m",
        "mcts_gen.fastmcp_server"
      ]
    }
  }
}

Note: The context block tells the Gemini CLI to load AGENTS.md (and GEMINI.md if it exists), which is crucial for the agent to understand how to use the tools.

高度な探索と探索予算（Search Limit）

MCTS-Gen provides high-level tools to manage search precision and efficiency, avoiding API throttling and repetitive tool call errors.

`run_mcts_analysis(exploration_constant, num_rounds, ...)`: This tool serves as the "Search Limit" (similar to the routine() loop in chess-ant). It executes a specified number of MCTS rounds in a single batch. AI agents use this tool to strategically allocate their search budget based on the complexity of the current state.
Conformational Diversity: For ligand generation, the engine now explores diverse 3D orientations (conformations) and side-chain rotations. These are represented as distinct actions in the MCTS tree, allowing for a more granular and realistic search.

空間分割と予測探索 (v0.0.5+)

巨大な探索空間への対処や、未来の状態の事前計算を可能にするため、 MCTS-Gen は空間ゾーン（Spatial Zone）と探索スロット（Search Slot）を導入しました。

Spatial Partitioning: For ligand generation in large binding pockets, you can restrict the search to a specific coordinate box using the spatial_filter argument in reinitialize_mcts. This reduces the branching factor and allows for focused exploration of specific pocket regions.
Predictive Search (Slots): You can initialize multiple independent search trees in parallel using the slot_id argument. This is particularly useful for pre-calculating the best response to an opponent's predicted moves in games like Shogi or Chess. Use activate_mcts_slot to instantly switch to a pre-calculated tree when a predicted state occurs.

uv によるインストール（推奨）

For a faster and more modern package management experience, we recommend using uv.

Install `pipx` and `uv`:

# Install pipx (a tool to install and run Python applications in isolated environments)
sudo apt install pipx

# Install uv using pipx
pipx install uv

Set up the environment and install `mcts-gen`:

# Create a virtual environment in your project directory
uv venv

# Activate the environment
source .venv/bin/activate

# Install mcts-gen with Shogi support
uv pip install mcts-gen[shogi]

To exit the virtual environment, simply run deactivate.

Configure `gemini-cli` with `fastmcp`:

Instead of manually editing settings.json, you can use the fastmcp command to automatically configure the tool server.
```
fastmcp install gemini-cli .venv/lib/python3.12/site-packages/mcts_gen/fastmcp_server.py:mcp
```
This command will automatically detect and configure the mcts_gen server, creating a .gemini/settings.json file for you.

Note on the ``:mcp`` suffix: The :mcp at the end is required because fastmcp_server.py contains multiple objects. This suffix explicitly tells fastmcp which object is the MCP server instance to be run.

uv でのエージェントコンテキスト設定

注釈

v0.0.2+ Change: The instructions below are for older versions or for cases where you need to add custom, additional context. As of v0.0.2, specifying AGENTS.md is not required for the agent to function correctly.

If you installed the package using uv or pip, the AGENTS.md file is included inside the package. To allow the Gemini agent to use it, you need to specify its full path in your .gemini/settings.json file.

Add the path to the context.fileName list. The exact path may vary depending on your Python version and environment.

Example `.gemini/settings.json`:

{
  "context": {
    "fileName": [
      ".venv/lib/python3.12/site-packages/mcts_gen/AGENTS.md",
      "GEMINI.md"
    ]
  },
  "mcpServers": {
    "mcts_gen_simulator_server": {
      "command": "uv",
      "args": [
        "run",
        "fastmcp",
        "run",
        ".venv/lib/python3.12/site-packages/mcts_gen/fastmcp_server.py:mcp"
      ]
    }
  }
}

メンテナー向け：新しいバージョンのリリース方法

パッケージの公開プロセスはGitHub Actionsを使用して自動化されています。

TestPyPIへのリリース（テスト用）

To release a version to the TestPyPI repository for verification, create and push a git tag with a -test suffix.

# Example for version 0.1.0
git tag v0.1.0-test1
git push origin v0.1.0-test1

PyPIへのリリース（公式）

To perform an official release, create and push a git tag that follows the semantic versioning format (e.g., vX.Y.Z).

# Example for version 0.1.0
git tag v0.1.0
git push origin v0.1.0