NanoJev MCP

简体中文|English

Wraps NanoJev's decision service as an MCP server, letting any MCP-capable agent (Claude Code, ccwitch, Cline, Cursor, ...) query the NanoJev model in natural language.

agent ──stdio(MCP)──> mcp_nanojev.py ──HTTP──> NanoJev repo's serve_decisions.py :8765 (model loaded once)

The MCP process is a thin proxy that never loads the model; multiple agents can share the same inference service simultaneously.

Prerequisite: Install NanoJev

git clone https://github.com/TianyuCodings/NanoJev.git
cd NanoJev
python -m pip install -r requirements-toy.txt huggingface_hub

Download the checkpoint (~2.3 GB; see the NanoJev README for details):

from huggingface_hub import snapshot_download

snapshot_download(
    repo_id="C-Tianyu/NanoJev",
    revision="unified-games-v1",
    local_dir="checkpoints/NanoJev-unified",
    allow_patterns=["best.safetensors", "config.json", "tokenizer/*", "backbone_config/*"],
)

Related MCP server: jev-mcp

Setup

1. Download this package (clone / unzip to any directory, e.g. D:\nanojev_mcp)

2. One-command configuration

python setup_mcp.py

The script will: install the mcp SDK -> probe the inference service -> register nanojev into Claude Code (user scope) -> print JSON for other clients. Common options:

python setup_mcp.py --service-url http://127.0.0.1:9000/api/evaluate   # non-default port
python setup_mcp.py --python D:\NanoJev\.venv\Scripts\python.exe       # use NanoJev's venv
python setup_mcp.py --skip-claude                                      # only print JSON, leave claude config untouched

3. Start the NanoJev inference service (in the NanoJev repo directory)

python scripts/serve_decisions.py --checkpoint-dir checkpoints/NanoJev-unified --web-root web --port 8765 --disable-native-triton

Done. Just ask your agent in natural language, e.g.:

Use nanojev to decide: the agent is at (2,2), is the cell to the north passable? Which of the four directions is the best move?

Running Directly (stdio)

The MCP server uses the stdio transport (JSON-RPC over stdin/stdout) and listens on no port. Launch it directly with:

python mcp_nanojev.py                    # default service URL http://127.0.0.1:8765/api/evaluate

Override the service URL with the NANOJEV_EVALUATE_URL environment variable:

# Linux / macOS
NANOJEV_EVALUATE_URL=http://127.0.0.1:9000/api/evaluate python mcp_nanojev.py
# Windows PowerShell
$env:NANOJEV_EVALUATE_URL = "http://127.0.0.1:9000/api/evaluate"; python mcp_nanojev.py

Agents spawn it as a subprocess and communicate over stdin/stdout; when run standalone the terminal only shows raw JSON-RPC traffic. Ctrl+C to exit.

Manual MCP Client Configuration

If you prefer to register manually (or use a client other than Claude Code), copy config.json and adjust the paths:

{
  "mcpServers": {
    "nanojev": {
      "command": "python",
      "args": ["D:\\nanojev_mcp\\mcp_nanojev.py"],
      "env": {
        "NANOJEV_EVALUATE_URL": "http://127.0.0.1:8765/api/evaluate"
      }
    }
  }
}

• command — path to a Python interpreter that has the mcp package installed.

• args — absolute path to mcp_nanojev.py in this package.

• env.NANOJEV_EVALUATE_URL — (optional) override the default service URL http://127.0.0.1:8765/api/evaluate.

Drop this into your client's config file:

Tools Available to the Agent

Four Decision-Loop Stages Where the Agent Uses the Model

1. Feasibility gate (Boolean) — Before moving, ask per-direction "is one cell north passable?" to prune illegal actions first.

2. Action selection (Choice) — Choose the next step from candidate actions; a single forward pass returns the full distribution over 2-255 candidates.

3. Risk / urgency (Score) — Ask "how urgent is it to change direction?" (0-3); set a threshold on the expected score to turn it into a rule.

4. Look-ahead planning (Boolean + Choice) — Batch-encode future states from candidate action sequences into a single nanojev_evaluate call, compare branch scores, then commit.

See docs/MCP.md for more examples and troubleshooting. When not using an agent, you can also use the interactive terminal client:

python ask_nanojev.py