TheoTown MCP Server (theotown-mcp)

A production-grade Model Context Protocol (MCP) server bridging AI agents (Claude Desktop, Cursor IDE, Hermes Agent, Antigravity) to the TheoTown city simulation game. It empowers AI models to inspect city states, design urban layouts, and construct road networks, buildings, zones, and utilities through the official TheoTown Lua API and a durable JSON mailbox.

Ngôn ngữ / Languages: English | Tiếng Việt

English Documentation

1. Architecture & IPC Flow

theotown-mcp connects AI agent reasoning to TheoTown's in-game engine without per-command restarts or simulated UI mouse clicks:

+--------------------------------------------------------------------------------+
|                                AI AGENT RUNTIME                                |
|             (Claude Desktop / Cursor IDE / Hermes / Antigravity)               |
+--------------------------------------------------------------------------------+
                                       |
                   MCP JSON-RPC Protocol (stdio / streamable-http)
                                       v
+--------------------------------------------------------------------------------+
|                        PYTHON MCP SERVER (src/theotown_mcp)                    |
|  - MCPServer v2: 12 Tools, 2 Resources, 1 Prompt                               |
|  - Two-Layer Validation (Pydantic Schema + Dynamic City Bounds)                |
|  - Offline / Dynamic Catalog & Price Estimation                                |
|  - Hardened Windows Atomic Bridge (same-dir temp file + fsync + os.replace)   |
+--------------------------------------------------------------------------------+
                                       |
                  Atomic JSON Write (%USERPROFILE%\TheoTown\plugins\)
                                       v
+--------------------------------------------------------------------------------+
|                    DATA MAILBOX (requests.txt, protocol v2)                    |
|  - Cross-process lock plus atomic read-modify-write updates                    |
|  - Up to 64 concurrent queued jobs without command loss                       |
|  - Session binding, cancellation flags, TTL, and replay protection            |
+--------------------------------------------------------------------------------+
                                       |
                         Periodic mailbox polling
                                       v
+--------------------------------------------------------------------------------+
|                       CORE ENGINE (plugin/theotown_mcp/core.lua)               |
|  - Static startup script with a protocol-v2 execution engine                  |
|  - Durable job lifecycle with per-session anti-replay safeguards              |
|  - Workload throttling (max 16 work units per 100 ms tick)                    |
|  - Official Builder preflight checks plus post-build Tile verification        |
|  - Bounded, coordinate-aware failure details and live telemetry               |
+--------------------------------------------------------------------------------+
                                       |
                      Official TheoTown Lua Engine APIs
                                       v
+--------------------------------------------------------------------------------+
|                           THEOTOWN SIMULATION WORLD                            |
|             (City, Builder, Draft, Tile, Runtime Libraries)                    |
+--------------------------------------------------------------------------------+

Detailed IPC Sequence

1. Tool Invocation: An AI client invokes an MCP tool (e.g. theotown_build_road or theotown_execute_plan).

2. Two-Layer Validation:

   • Schema Layer: Pydantic v2 ensures non-negative coordinates, positive dimensions, and valid elevation.

   • Runtime Layer: Python checks current city bounds (City.getWidth(), City.getHeight()).

3. Durable Enqueue: Python appends the validated command to requests.txt under a cross-process lock, then commits the JSON with a same-directory atomic replace and bounded Windows retry loop.

4. Session Safety: Every job is tied to the active city session. Expired, replayed, or cross-city jobs fail closed instead of executing in the wrong save.

5. Queue & Budgeting: core.lua polls the mailbox, expands area operations into work units, and processes at most 16 units every 100 ms so large plans do not freeze the game.

6. Telemetry & Feedback: TheoTown writes protocol-v2 heartbeats to telemetry.txt and bounded job results to job_<job_id>.txt; MCP clients can poll progress or cancel pending work. Every 10 seconds, the heartbeat also refreshes city diagnostics: income, population tiers, jobs, taxes, infrastructure counts, estimated power/water balance, happiness by category, sampled service coverage, and representative problem coordinates.

2. Prerequisites & Installation

Requirements

• Windows 10/11 (AMD64)

• Python 3.10 or higher (Python 3.11+ recommended)

• TheoTown (Steam or standalone) installed at %USERPROFILE%\TheoTown

Install for a person (recommended)

1. Download theotown_mcp-0.2.0-py3-none-any.whl from the latest GitHub release.

2. Open PowerShell and run:

$McpHome = Join-Path $env:USERPROFILE ".theotown-mcp"
py -3.11 -m venv $McpHome
& "$McpHome\Scripts\python.exe" -m pip install --upgrade pip
& "$McpHome\Scripts\python.exe" -m pip install "$env:USERPROFILE\Downloads\theotown_mcp-0.2.0-py3-none-any.whl"
& "$McpHome\Scripts\theotown-mcp.exe" install-plugin --backup
& "$McpHome\Scripts\theotown-mcp.exe" probe-ipc

3. Restart TheoTown once, open a city, and keep it open while the MCP client is operating.

4. Add the server to your MCP client using the absolute executable path shown below. Replace <USERNAME> with your Windows user name.

{
  "mcpServers": {
    "theotown": {
      "command": "C:\\Users\\<USERNAME>\\.theotown-mcp\\Scripts\\theotown-mcp.exe",
      "args": ["run", "--transport", "stdio"],
      "env": {
        "THEOTOWN_DATA_DIR": "C:\\Users\\<USERNAME>\\TheoTown"
      }
    }
  }
}

Restart the MCP client after saving its configuration. Ask it to call theotown_get_status; a healthy connection reports connected: true, protocol: 2, and diagnostics_error: null.

Install or upgrade with an AI agent / bot

Give the bot the following task. It is intentionally explicit so the bot can complete installation without guessing paths or editing game saves:

Install TheoTown MCP v0.2.0 on this Windows machine. Create an isolated virtual
environment at %USERPROFILE%\.theotown-mcp, install the wheel from
https://github.com/d-init-d/theotown-mcp/releases/download/v0.2.0/theotown_mcp-0.2.0-py3-none-any.whl,
run `theotown-mcp install-plugin --force --backup`, and then run
`theotown-mcp probe-ipc`. Configure my MCP client to start the server over stdio
using the absolute path to the virtual environment executable. Preserve all city
saves, telemetry files, and job history. Tell me to restart TheoTown once and open
a test city. After restart, verify `theotown_get_status` returns `connected: true`,
`protocol: 2`, and no `diagnostics_error`. Do not execute a construction plan until
`theotown_validate_plan` reports `valid: true`.

For unattended PowerShell installation, a bot can run:

$McpHome = Join-Path $env:USERPROFILE ".theotown-mcp"
if (-not (Test-Path "$McpHome\Scripts\python.exe")) { py -3.11 -m venv $McpHome }
& "$McpHome\Scripts\python.exe" -m pip install --upgrade pip
& "$McpHome\Scripts\python.exe" -m pip install --upgrade "https://github.com/d-init-d/theotown-mcp/releases/download/v0.2.0/theotown_mcp-0.2.0-py3-none-any.whl"
& "$McpHome\Scripts\theotown-mcp.exe" install-plugin --force --backup
& "$McpHome\Scripts\theotown-mcp.exe" probe-ipc

install-plugin only manages plugin.json, core.lua, and inbox.lua. It preserves city saves and runtime files such as telemetry, queued requests, and job results. --backup keeps .bak copies of replaced plugin files.

Install from source (contributors)

git clone https://github.com/d-init-d/theotown-mcp.git
Set-Location theotown-mcp
py -3.11 -m venv .venv
& ".\.venv\Scripts\python.exe" -m pip install -e ".[dev]"
& ".\.venv\Scripts\theotown-mcp.exe" install-plugin --force --backup
& ".\.venv\Scripts\python.exe" -m pytest

Initial discovery: TheoTown loads the static core.lua when the game starts. Restart the game after every plugin upgrade. New jobs then travel as JSON data and do not require further restarts.

3. Guardrails, Batch Limits & Job Lifecycle

• Batch Safeguards:

  • Maximum commands per plan: 250 commands.

  • Maximum affected tiles per plan: 10,000 tiles.

  • Strict coordinate validation: x >= 0, y >= 0, strictly bounded by the active city's width and height.

• Job Lifecycle:

  • pending: Durably queued in requests.txt for the active city session.

  • running: Actively being executed in-game across frame ticks.

  • completed: All work units successfully placed.

  • failed: Any work unit failed (e.g. obstruction, terrain, insufficient funds), with structured error messages and step counts (attempted_steps, completed_steps, failed_steps).

  • cancelled: Aborted via theotown_cancel_job.

4. Client Configurations

Use the absolute virtual-environment executable path from the installation section. This avoids PATH differences between a terminal and a desktop MCP client.

Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "theotown": {
      "command": "C:\\Users\\<USERNAME>\\.theotown-mcp\\Scripts\\theotown-mcp.exe",
      "args": ["run", "--transport", "stdio"],
      "env": {
        "THEOTOWN_DATA_DIR": "C:\\Users\\<USERNAME>\\TheoTown"
      }
    }
  }
}

Cursor IDE

Add to .cursor/mcp.json or Cursor Settings -> Features -> MCP:

{
  "mcpServers": {
    "theotown": {
      "command": "C:\\Users\\<USERNAME>\\.theotown-mcp\\Scripts\\theotown-mcp.exe",
      "args": ["run", "--transport", "stdio"]
    }
  }
}

Hermes Agent

In your Hermes agent configuration file (hermes.yaml or config.json):

mcp_servers:
  theotown:
    command: C:\Users\<USERNAME>\.theotown-mcp\Scripts\theotown-mcp.exe
    args:
      - run
      - --transport
      - stdio
    env:
      THEOTOWN_DATA_DIR: "%USERPROFILE%\\TheoTown"

Streamable HTTP Transport (Remote / Containerized)

You can also run the server over HTTP:

theotown-mcp run --transport http --port 8000

Then connect clients to http://127.0.0.1:8000/mcp.

5. API Reference

Tools (12 Tools)

Resources (2 Resources)

Prompts (1 Prompt)

Related MCP server: Roblox Studio MCP

Tiếng Việt (Vietnamese Documentation)

1. Kiến Trúc & Luồng Truyền Thông IPC

theotown-mcp kết nối trực tiếp khả năng lập luận của các AI Agent tới game mô phỏng đô thị TheoTown mà không cần khởi động lại game hay giả lập click chuột trên màn hình:

• Python MCP Server (src/theotown_mcp): Xây dựng trên chuẩn MCP SDK v2 (MCPServer), cung cấp 12 công cụ (tools), 2 tài nguyên (resources) và 1 prompt hướng dẫn quy hoạch đô thị.

• Cầu nối tệp tin nguyên tử (bridge.py): Ghi dữ liệu JSON vào requests.txt bằng khóa liên tiến trình, tệp tạm cùng thư mục, fsync và os.replace có thử lại khi Windows tạm khóa tệp.

• Hộp thư giao thức v2: Giữ tối đa 64 tác vụ, gắn mỗi tác vụ với phiên thành phố hiện tại, hỗ trợ TTL, hủy có xác nhận và chống phát lại sau khi plugin khởi động lại.

• Bộ điều phối core.lua: Đọc hộp thư định kỳ, xử lý tối đa 16 đơn vị công việc mỗi 100 ms, dùng API Builder chính thức để kiểm tra/xây và API Tile để xác nhận kết quả.

• Phản hồi có giới hạn: Kết quả lưu số bước thành công/thất bại, tối đa 64 lỗi mẫu có tọa độ và bảng đếm lỗi, tránh làm phình file hoặc phản hồi MCP.

2. Cài Đặt & Khởi Chạy

Yêu cầu hệ thống

• Hệ điều hành: Windows 10 hoặc 11 (AMD64)

• Python: 3.10 trở lên

• Trò chơi TheoTown (Steam hoặc bản độc lập) cài đặt tại %USERPROFILE%\TheoTown

Cài cho người dùng (khuyến nghị)

1. Tải theotown_mcp-0.2.0-py3-none-any.whl từ GitHub Release mới nhất.

2. Mở PowerShell và chạy:

$McpHome = Join-Path $env:USERPROFILE ".theotown-mcp"
py -3.11 -m venv $McpHome
& "$McpHome\Scripts\python.exe" -m pip install --upgrade pip
& "$McpHome\Scripts\python.exe" -m pip install "$env:USERPROFILE\Downloads\theotown_mcp-0.2.0-py3-none-any.whl"
& "$McpHome\Scripts\theotown-mcp.exe" install-plugin --backup
& "$McpHome\Scripts\theotown-mcp.exe" probe-ipc

3. Khởi động lại TheoTown một lần, mở một thành phố và giữ game chạy khi AI sử dụng MCP.

4. Thêm máy chủ vào cấu hình MCP. Thay <TÊN_USER> bằng tên tài khoản Windows:

{
  "mcpServers": {
    "theotown": {
      "command": "C:\\Users\\<TÊN_USER>\\.theotown-mcp\\Scripts\\theotown-mcp.exe",
      "args": ["run", "--transport", "stdio"],
      "env": {
        "THEOTOWN_DATA_DIR": "C:\\Users\\<TÊN_USER>\\TheoTown"
      }
    }
  }
}

Khởi động lại ứng dụng AI sau khi lưu cấu hình. Yêu cầu AI gọi theotown_get_status; kết nối đạt yêu cầu phải có connected: true, protocol: 2 và diagnostics_error: null.

Cài đặt hoặc nâng cấp bằng AI/bot

Gửi nguyên prompt sau cho bot:

Cài TheoTown MCP v0.2.0 trên máy Windows này. Tạo virtual environment riêng tại
%USERPROFILE%\.theotown-mcp, cài wheel từ
https://github.com/d-init-d/theotown-mcp/releases/download/v0.2.0/theotown_mcp-0.2.0-py3-none-any.whl,
chạy `theotown-mcp install-plugin --force --backup`, sau đó chạy
`theotown-mcp probe-ipc`. Cấu hình ứng dụng MCP của tôi chạy máy chủ qua stdio
bằng đường dẫn tuyệt đối tới executable trong virtual environment. Giữ nguyên mọi
save thành phố, telemetry và lịch sử job. Nhắc tôi khởi động lại TheoTown một lần
và mở thành phố thử nghiệm. Sau khi game mở lại, xác minh
`theotown_get_status` trả về `connected: true`, `protocol: 2` và không có
`diagnostics_error`. Không thực thi kế hoạch xây dựng trước khi
`theotown_validate_plan` trả về `valid: true`.

Bot có thể dùng khối PowerShell tự động trong phần English ở trên. Lệnh install-plugin chỉ quản lý plugin.json, core.lua và inbox.lua; save thành phố cùng dữ liệu runtime được giữ nguyên. Tùy chọn --backup tạo bản .bak cho plugin cũ.

Cài từ mã nguồn dành cho người phát triển

git clone https://github.com/d-init-d/theotown-mcp.git
Set-Location theotown-mcp
py -3.11 -m venv .venv
& ".\.venv\Scripts\python.exe" -m pip install -e ".[dev]"
& ".\.venv\Scripts\theotown-mcp.exe" install-plugin --force --backup
& ".\.venv\Scripts\python.exe" -m pytest

Lưu ý khi nâng cấp: TheoTown nạp core.lua tĩnh lúc khởi động. Hãy khởi động lại game sau mỗi lần nâng cấp plugin. Các job mới sau đó được truyền dưới dạng JSON và không cần khởi động lại tiếp.

3. Cơ Chế Bảo Vệ, Giới Hạn & Trạng Thái Tác Vụ

• Giới Hạn An Toàn:

  • Tối đa 250 lệnh cho mỗi kế hoạch (plan).

  • Tối đa 10,000 ô diện tích ảnh hưởng cho mỗi kế hoạch.

  • Tọa độ nghiêm ngặt: x >= 0, y >= 0, giới hạn chính xác theo kích thước bản đồ hiện tại.

• Vòng Đời Tác Vụ (Job Lifecycle):

  • pending: Đã được ghi bền vững vào requests.txt cho đúng phiên thành phố.

  • running: Đang được game thực thi từng bước theo khung hình tick.

  • completed: Toàn bộ các bước xây dựng thành công 100%.

  • failed: Có bước gặp lỗi (vướng địa hình, thiếu tiền...), lưu vết chi tiết attempted_steps, completed_steps, failed_steps và danh sách lỗi.

  • cancelled: Đã hủy thành công qua lệnh theotown_cancel_job.

4. Hướng Dẫn Cấu Hình Cho Các Nền Tảng AI

Luôn dùng đường dẫn tuyệt đối tới executable trong virtual environment để ứng dụng AI không phụ thuộc biến PATH của cửa sổ terminal.

Claude Desktop

Mở tệp cấu hình tại %APPDATA%\Claude\claude_desktop_config.json và thêm:

{
  "mcpServers": {
    "theotown": {
      "command": "C:\\Users\\<TÊN_USER>\\.theotown-mcp\\Scripts\\theotown-mcp.exe",
      "args": ["run", "--transport", "stdio"],
      "env": {
        "THEOTOWN_DATA_DIR": "C:\\Users\\<TÊN_USER>\\TheoTown"
      }
    }
  }
}

Cursor IDE

Thêm vào .cursor/mcp.json:

{
  "mcpServers": {
    "theotown": {
      "command": "C:\\Users\\<TÊN_USER>\\.theotown-mcp\\Scripts\\theotown-mcp.exe",
      "args": ["run", "--transport", "stdio"]
    }
  }
}

Hermes Agent

Thêm vào tệp cấu hình hermes.yaml:

mcp_servers:
  theotown:
    command: C:\Users\<TÊN_USER>\.theotown-mcp\Scripts\theotown-mcp.exe
    args:
      - run
      - --transport
      - stdio

5. Danh Sách Công Cụ & Tài Nguyên

• Công cụ xây dựng & quản trị (12 Tools):

  • theotown_get_status: Đọc tài chính, dân số, thuế, việc làm, hạnh phúc theo từng yếu tố, điện/nước, độ phủ dịch vụ và các tọa độ đang có vấn đề.

  • theotown_build_road: Xây đường ngang hoặc dọc giữa hai tọa độ với draft và cao độ chỉ định.

  • theotown_build_zone: Quy hoạch các khu dân cư, thương mại, công nghiệp.

  • theotown_build_building: Đặt công trình theo ID hoặc tên gọi đại diện (alias).

  • theotown_build_utilities: Đặt ống nước hoặc dây điện theo đường ngang/dọc; game có thể từ chối ô đã bị chiếm, ô nước hoặc địa hình không phù hợp.

  • theotown_demolish: Giải phóng mặt bằng, phá dỡ công trình hoặc đường sá.

  • theotown_validate_plan: Kiểm tra trước tính hợp lệ và ước lượng chi phí của kế hoạch quy hoạch mà không làm thay đổi bản đồ.

  • theotown_execute_plan: Đưa một danh sách lệnh vào hàng đợi để xây dựng dần theo khung hình.

  • theotown_get_job: Kiểm tra tiến độ hoàn thành của tác vụ.

  • theotown_cancel_job: Hủy tác vụ xây dựng đang thực thi.

  • theotown_set_speed: Điều chỉnh tốc độ mô phỏng game (0: Tạm dừng, 1: Bình thường, 2: Nhanh, 3: Siêu nhanh, 4: Cực nhanh).

  • theotown_get_draft_catalog: Tra cứu danh mục mẫu công trình, đường xá và các bí danh thân thiện.

• Tài nguyên (Resources):

  • theotown://city/status: Dữ liệu trạng thái thành phố theo thời gian thực (JSON).

  • theotown://catalog/drafts: Danh mục toàn bộ các bản thiết kế (drafts) trong game.

• Prompt Hướng Dẫn:

  • urban_planner: Hướng dẫn chuyên sâu cho AI về nguyên lý quy hoạch mạng lưới giao thông hình học, cân đối tỷ lệ phân vùng RCI và tối ưu hóa hạ tầng điện nước.

6. Kiểm Thử Tự Động (Testing)

Để chạy toàn bộ bộ kiểm thử tự động (Unit Tests & End-to-End Suite):

# Chạy toàn bộ pytest
pytest

# Hoặc sử dụng runner chuyên dụng cho E2E
python tests/e2e/runner.py --tier all

License

Dự án được phát hành theo giấy phép MIT License. Bản quyền © 2026 TheoTown MCP Team.