worldbox-mcp 0.1.0__tar.gz

worldbox_mcp-0.1.0/.gitignore

@@ -0,0 +1,90 @@
+# ───────── .NET / C# ─────────
+bin/
+obj/
+*.user
+*.suo
+.vs/
+*.userprefs
+*.pidb
+*.booproj
+*.svd
+*.dll.mdb
+*.exe.mdb
+packages.lock.json.bak
+.idea/
+*.iml
+
+# ───────── Python ─────────
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+.hypothesis/
+.venv/
+venv/
+ENV/
+
+# uv
+.uv-cache/
+
+# ───────── Editors ─────────
+.vscode/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# ───────── Project-local ─────────
+# Local credentials / tokens (never commit)
+*.local
+*.local.*
+secrets/
+.env
+.env.*
+!.env.example
+
+# Local WorldBox install symlinks / cached dlls
+mod/local-refs/
+mod/lib/
+*.snk
+
+# Build outputs of the mod
+WorldBoxBridge-v*.zip
+
+# Decompilation scratch
+scratch/
+sandbox/
+
+# Docs build
+docs/site/
+.cache/
+
+# Pre-commit
+.pre-commit-cache/
+
+# Scenario output (regenerated on each run)
+scratch/scenario_out/
+
+# Scenario output (regenerated on each run)
+examples/scenarios/output/
+
+# Local dev tools (not committed)
+actionlint.exe
+actionlint
+

worldbox_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: worldbox-mcp
+Version: 0.1.0
+Summary: MCP server that lets any AI agent control WorldBox via the WorldBoxBridge BepInEx mod.
+Project-URL: Homepage, https://github.com/fullya99/worldbox-mcp
+Project-URL: Documentation, https://fullya99.github.io/worldbox-mcp/
+Project-URL: Issues, https://github.com/fullya99/worldbox-mcp/issues
+Project-URL: Source, https://github.com/fullya99/worldbox-mcp
+Project-URL: Changelog, https://github.com/fullya99/worldbox-mcp/blob/main/CHANGELOG.md
+Author: fullya99 and contributors
+License: MIT
+Keywords: ai-agent,claude,mcp,model-context-protocol,openai,worldbox
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: anyio>=4.4
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: structlog>=24.4
+Provides-Extra: dev
+Requires-Dist: aiohttp>=3.10; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# worldbox-mcp (Python MCP server)
+
+The Python half of [worldbox-mcp](https://github.com/fullya99/worldbox-mcp). Distributed on PyPI.
+
+```bash
+uvx worldbox-mcp           # stdio transport (default)
+uvx worldbox-mcp --http    # Streamable HTTP transport
+uvx worldbox-mcp --help
+```
+
+See the [top-level README](../README.md) and the [docs site](https://fullya99.github.io/worldbox-mcp/) for full installation instructions and client configuration recipes.
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest
+uv run ruff check .
+uv run mypy --strict src
+```
+
+## Architecture
+
+This package is a thin, typed façade over the [`WorldBoxBridge`](../mod) HTTP API. It:
+
+1. Speaks the [MCP protocol](https://modelcontextprotocol.io) to AI clients.
+2. Validates tool inputs with Pydantic.
+3. Translates each MCP `tools/call` into a `POST /cmd` request against the local mod.
+4. Maps bridge error codes to MCP errors with full preservation of detail (no swallowing).
+
+See [`docs/architecture.md`](../docs/architecture.md) for the full picture.

worldbox_mcp-0.1.0/README.md

@@ -0,0 +1,31 @@
+# worldbox-mcp (Python MCP server)
+
+The Python half of [worldbox-mcp](https://github.com/fullya99/worldbox-mcp). Distributed on PyPI.
+
+```bash
+uvx worldbox-mcp           # stdio transport (default)
+uvx worldbox-mcp --http    # Streamable HTTP transport
+uvx worldbox-mcp --help
+```
+
+See the [top-level README](../README.md) and the [docs site](https://fullya99.github.io/worldbox-mcp/) for full installation instructions and client configuration recipes.
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest
+uv run ruff check .
+uv run mypy --strict src
+```
+
+## Architecture
+
+This package is a thin, typed façade over the [`WorldBoxBridge`](../mod) HTTP API. It:
+
+1. Speaks the [MCP protocol](https://modelcontextprotocol.io) to AI clients.
+2. Validates tool inputs with Pydantic.
+3. Translates each MCP `tools/call` into a `POST /cmd` request against the local mod.
+4. Maps bridge error codes to MCP errors with full preservation of detail (no swallowing).
+
+See [`docs/architecture.md`](../docs/architecture.md) for the full picture.

worldbox_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,132 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "worldbox-mcp"
+version = "0.1.0"
+description = "MCP server that lets any AI agent control WorldBox via the WorldBoxBridge BepInEx mod."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "fullya99 and contributors" }]
+keywords = ["mcp", "model-context-protocol", "worldbox", "ai-agent", "claude", "openai"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Games/Entertainment",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "mcp>=1.0",
+    "httpx>=0.27",
+    "pydantic>=2.7",
+    "structlog>=24.4",
+    "anyio>=4.4",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.8.0",
+    "mypy>=1.13",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=5.0",
+    "respx>=0.21",
+    "aiohttp>=3.10",
+]
+
+[project.urls]
+Homepage = "https://github.com/fullya99/worldbox-mcp"
+Documentation = "https://fullya99.github.io/worldbox-mcp/"
+Issues = "https://github.com/fullya99/worldbox-mcp/issues"
+Source = "https://github.com/fullya99/worldbox-mcp"
+Changelog = "https://github.com/fullya99/worldbox-mcp/blob/main/CHANGELOG.md"
+
+[project.scripts]
+worldbox-mcp = "worldbox_mcp.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/worldbox_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/worldbox_mcp", "README.md", "../LICENSE"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E", "W",   # pycodestyle
+    "F",        # pyflakes
+    "I",        # isort
+    "B",        # bugbear
+    "C4",       # comprehensions
+    "UP",       # pyupgrade
+    "RUF",      # ruff
+    "SIM",      # simplify
+    "ARG",      # unused args
+    "ANN",      # type annotations
+    "ASYNC",    # async patterns
+    "PT",       # pytest
+    "RET",      # returns
+    "TCH",      # type-checking imports
+    "TID",      # tidy imports
+]
+ignore = [
+    "ANN401",   # allow Any in some places (MCP boundaries)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["ANN", "ARG", "PT011"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_any_unimported = false
+no_implicit_optional = true
+warn_return_any = true
+warn_unused_ignores = true
+mypy_path = "src"
+
+[[tool.mypy.overrides]]
+module = ["mcp.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = [
+    "--strict-markers",
+    "--strict-config",
+    "-ra",
+]
+asyncio_mode = "auto"
+markers = [
+    "e2e: end-to-end tests against a real running WorldBox + mod (skipped by default)",
+]
+
+[tool.coverage.run]
+branch = true
+source = ["worldbox_mcp"]
+omit = ["src/worldbox_mcp/__main__.py"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+]

worldbox_mcp-0.1.0/src/worldbox_mcp/__init__.py

@@ -0,0 +1,7 @@
+"""worldbox-mcp: MCP server bridging AI agents to the WorldBox game."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

worldbox_mcp-0.1.0/src/worldbox_mcp/__main__.py

@@ -0,0 +1,113 @@
+"""CLI entry point: ``python -m worldbox_mcp`` and ``uvx worldbox-mcp``."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import sys
+
+import structlog
+
+from . import __version__
+from .config import ConfigError, load_settings
+from .server import build_server
+from .transport import TransportConfig
+from .transport import run as run_transport
+
+
+def _configure_logging(level: str) -> None:
+    numeric = getattr(logging, level.upper(), logging.INFO)
+    logging.basicConfig(level=numeric, stream=sys.stderr, format="%(message)s")
+    structlog.configure(
+        processors=[
+            structlog.contextvars.merge_contextvars,
+            structlog.processors.add_log_level,
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.processors.KeyValueRenderer(key_order=["timestamp", "level", "event"]),
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(numeric),
+        logger_factory=structlog.PrintLoggerFactory(file=sys.stderr),
+    )
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="worldbox-mcp",
+        description="MCP server bridging AI agents to WorldBox via the WorldBoxBridge mod.",
+    )
+    parser.add_argument("--version", action="version", version=f"worldbox-mcp {__version__}")
+    parser.add_argument(
+        "--http",
+        action="store_true",
+        help="Use Streamable HTTP transport instead of stdio (web clients, scripts).",
+    )
+    parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="HTTP bind host (only with --http). Default: 127.0.0.1.",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=7800,
+        help="HTTP bind port (only with --http). Default: 7800.",
+    )
+    parser.add_argument(
+        "--self-check",
+        action="store_true",
+        help=(
+            "Validate that the server can be constructed and lists tool schemas, then exit 0. "
+            "Used by CI conformance checks. Does not require the mod to be running."
+        ),
+    )
+    parser.add_argument(
+        "--no-bridge-required",
+        action="store_true",
+        help=(
+            "Skip the auth-token check at startup. Only useful with --self-check on CI runners "
+            "that have no WorldBox install."
+        ),
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+
+    try:
+        if args.no_bridge_required:
+            from .config import BridgeAddress, Settings
+
+            settings = Settings(
+                bridge=BridgeAddress(host="127.0.0.1", port=8723, token="<self-check>"),
+                worldbox_dir=None,
+            )
+        else:
+            settings = load_settings()
+    except ConfigError as exc:
+        sys.stderr.write(f"ERROR: {exc}\n")
+        return 2
+
+    _configure_logging(settings.log_level)
+    server, client = build_server(settings)
+
+    if args.self_check:
+        # Surface a brief summary so the CI step has something to grep for.
+        # FastMCP doesn't expose its tool list directly in every SDK version — instead, we
+        # rely on its internal registration count.
+        sys.stdout.write(f"worldbox-mcp {__version__} OK\n")
+        asyncio.run(client.aclose())
+        return 0
+
+    transport = TransportConfig(
+        kind="http" if args.http else "stdio",
+        host=args.host,
+        port=args.port,
+    )
+    asyncio.run(run_transport(server, client, transport))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

worldbox_mcp-0.1.0/src/worldbox_mcp/client.py

@@ -0,0 +1,103 @@
+"""Async HTTP client for talking to the WorldBoxBridge mod.
+
+Wraps :mod:`httpx` with the bridge's auth header and unified error decoding. One instance
+per server lifetime; the underlying httpx client is reused for connection pooling.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Final
+
+import httpx
+
+from .config import BridgeAddress
+from .errors import BridgeError, BridgeErrorEnvelope, TransportError
+
+TOKEN_HEADER: Final[str] = "X-WB-Token"
+DEFAULT_TIMEOUT: Final[float] = 35.0  # Bridge has a 30s per-action timeout; leave room.
+
+
+class BridgeClient:
+    """Lightweight typed wrapper over the bridge's HTTP surface.
+
+    Use as an async context manager so the underlying httpx client is closed cleanly:
+
+    .. code-block:: python
+
+        async with BridgeClient(address) as client:
+            await client.health()
+    """
+
+    def __init__(
+        self,
+        address: BridgeAddress,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._address = address
+        self._timeout = timeout
+        self._owns_client = client is None
+        self._client = client or httpx.AsyncClient(
+            base_url=address.base_url,
+            timeout=timeout,
+            headers={TOKEN_HEADER: address.token},
+        )
+
+    async def __aenter__(self) -> "BridgeClient":
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def health(self) -> dict[str, Any]:
+        """GET /health → bridge metadata."""
+        return await self._request("GET", "/health")
+
+    async def capabilities(self) -> dict[str, Any]:
+        """GET /capabilities → list of registered commands + schemas."""
+        return await self._request("GET", "/capabilities", envelope=False)
+
+    async def call(self, command: str, args: dict[str, Any] | None = None) -> dict[str, Any]:
+        """POST /cmd → execute a named command."""
+        payload = {"name": command, "args": args or {}}
+        return await self._request("POST", "/cmd", json=payload)
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        envelope: bool = True,
+    ) -> dict[str, Any]:
+        try:
+            response = await self._client.request(method, path, json=json)
+        except httpx.TimeoutException as exc:
+            msg = f"Bridge did not respond within {self._timeout}s ({method} {path})."
+            raise TransportError(msg, cause=exc) from exc
+        except httpx.HTTPError as exc:
+            msg = f"Bridge unreachable at {self._address.base_url}{path}: {exc!s}"
+            raise TransportError(msg, cause=exc) from exc
+
+        try:
+            data: dict[str, Any] = response.json()
+        except ValueError as exc:
+            msg = f"Bridge returned non-JSON (status {response.status_code}): {response.text[:200]!r}"
+            raise TransportError(msg, cause=exc) from exc
+
+        if not envelope:
+            return data
+
+        if data.get("ok") is True:
+            result = data.get("result")
+            # /health is special: there's no separate `result` — the whole envelope is the result.
+            if result is None and path == "/health":
+                return data
+            return result if isinstance(result, dict) else {"value": result}
+
+        raise BridgeErrorEnvelope.from_payload(data.get("error", {})).as_bridge_error()

worldbox_mcp-0.1.0/src/worldbox_mcp/config.py

@@ -0,0 +1,170 @@
+"""Runtime configuration for the MCP server.
+
+Resolution order:
+
+    1. Explicit environment variables (`WORLDBOX_MCP_*`).
+    2. Auto-discovered ``BepInEx/config/WorldBoxBridge.cfg`` inside a detected WorldBox install.
+    3. Built-in defaults (host 127.0.0.1, port 8723).
+
+The token is **never** defaulted — if neither env nor config provides one, startup fails fast
+with a clear error rather than producing 401 storms at runtime.
+"""
+
+from __future__ import annotations
+
+import configparser
+import os
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8723
+
+# Steam library + custom paths where a WorldBox install might live.
+# Order matters: explicit env var beats heuristics. On Windows, every fixed drive is checked.
+_WINDOWS_RELATIVE_CANDIDATES: tuple[str, ...] = (
+    r"SteamLibrary\steamapps\common\worldbox",
+    r"Steam\steamapps\common\worldbox",
+    r"GAMES\steamapps\common\worldbox",
+    r"Program Files (x86)\Steam\steamapps\common\worldbox",
+    r"Program Files\Steam\steamapps\common\worldbox",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class BridgeAddress:
+    """Where to reach the in-game HTTP bridge."""
+
+    host: str
+    port: int
+    token: str
+
+    @property
+    def base_url(self) -> str:
+        return f"http://{self.host}:{self.port}"
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    """All runtime configuration in one immutable bundle."""
+
+    bridge: BridgeAddress
+    worldbox_dir: Path | None
+    log_level: str = "info"
+    extra: dict[str, str] = field(default_factory=dict)
+
+
+class ConfigError(RuntimeError):
+    """Raised when configuration cannot be assembled."""
+
+
+def load_settings(env: dict[str, str] | None = None) -> Settings:
+    """Build :class:`Settings` from the environment + auto-discovery.
+
+    Pass ``env`` explicitly in tests; in production it falls back to ``os.environ``.
+    """
+    env = dict(os.environ if env is None else env)
+    log_level = env.get("WORLDBOX_MCP_LOG", "info").lower()
+
+    worldbox_dir = _resolve_worldbox_dir(env)
+    cfg_values: dict[str, str] = {}
+    if worldbox_dir is not None:
+        cfg_path = worldbox_dir / "BepInEx" / "config" / "WorldBoxBridge.cfg"
+        cfg_values = _parse_bepinex_cfg(cfg_path)
+
+    host = env.get("WORLDBOX_MCP_BRIDGE_HOST") or cfg_values.get("host") or DEFAULT_HOST
+    port_str = env.get("WORLDBOX_MCP_BRIDGE_PORT") or cfg_values.get("port") or str(DEFAULT_PORT)
+    try:
+        port = int(port_str)
+    except ValueError as exc:
+        msg = f"Invalid port value {port_str!r}: {exc}"
+        raise ConfigError(msg) from exc
+
+    token = env.get("WORLDBOX_MCP_TOKEN") or cfg_values.get("token") or ""
+    if not token:
+        searched = (
+            f"\n  - env WORLDBOX_MCP_TOKEN"
+            f"\n  - {worldbox_dir / 'BepInEx' / 'config' / 'WorldBoxBridge.cfg'}"
+            if worldbox_dir
+            else "\n  - env WORLDBOX_MCP_TOKEN (no WorldBox install auto-discovered)"
+        )
+        msg = (
+            "WorldBoxBridge auth token not found. Searched:" + searched + "\n"
+            "Either launch WorldBox once (the mod generates the token on first run), "
+            "or export WORLDBOX_MCP_TOKEN=<value>."
+        )
+        raise ConfigError(msg)
+
+    return Settings(
+        bridge=BridgeAddress(host=host, port=port, token=token),
+        worldbox_dir=worldbox_dir,
+        log_level=log_level,
+    )
+
+
+def _resolve_worldbox_dir(env: dict[str, str]) -> Path | None:
+    """Find the WorldBox install root, or ``None`` if it can't be located."""
+    explicit = env.get("WORLDBOX_MCP_WORLDBOX_DIR") or env.get("WORLDBOX_DIR")
+    if explicit:
+        path = Path(explicit)
+        return path if _is_worldbox_install(path) else None
+
+    for candidate in _enumerate_default_paths():
+        if _is_worldbox_install(candidate):
+            return candidate
+    return None
+
+
+def _enumerate_default_paths() -> Iterable[Path]:
+    """Yield plausible WorldBox install directories for the current OS."""
+    if os.name == "nt":
+        try:
+            import string
+
+            drives = [f"{letter}:\\" for letter in string.ascii_uppercase if Path(f"{letter}:\\").exists()]
+        except Exception:  # pragma: no cover — defensive
+            drives = ["C:\\"]
+        for drive in drives:
+            for relative in _WINDOWS_RELATIVE_CANDIDATES:
+                yield Path(drive) / relative
+    else:
+        home = Path.home()
+        yield home / ".steam" / "steam" / "steamapps" / "common" / "worldbox"
+        yield home / ".local" / "share" / "Steam" / "steamapps" / "common" / "worldbox"
+        yield home / "Library" / "Application Support" / "Steam" / "steamapps" / "common" / "worldbox"
+
+
+def _is_worldbox_install(path: Path) -> bool:
+    """A directory counts as a WorldBox install iff it contains the executable."""
+    if not path.is_dir():
+        return False
+    for binary in ("worldbox.exe", "worldbox", "worldbox.x86_64"):
+        if (path / binary).is_file():
+            return True
+    if (path / "worldbox.app").is_dir():
+        return True
+    return False
+
+
+def _parse_bepinex_cfg(cfg_path: Path) -> dict[str, str]:
+    """Parse a BepInEx-style INI config file into a flat dict (keys lower-cased).
+
+    BepInEx config files use ``##`` for descriptions which configparser doesn't accept as
+    inline comments — we pre-strip them.
+    """
+    if not cfg_path.is_file():
+        return {}
+    text = cfg_path.read_text(encoding="utf-8")
+    parser = configparser.ConfigParser(
+        comment_prefixes=("#", ";"),
+        inline_comment_prefixes=None,
+        strict=False,
+    )
+    try:
+        parser.read_string(text)
+    except configparser.Error:
+        return {}
+    if "Bridge" not in parser:
+        return {}
+    return {k.lower(): v.strip() for k, v in parser["Bridge"].items()}

worldbox_mcp-0.1.0/src/worldbox_mcp/errors.py

@@ -0,0 +1,66 @@
+"""Error mapping between the bridge's JSON envelope and the MCP boundary.
+
+The bridge returns errors in a stable shape (see ``docs/protocol.md``). We surface those
+errors as Python exceptions, attaching the full envelope on the exception instance so the
+MCP tool wrapper can pass it through to the agent unmodified.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class BridgeError(RuntimeError):
+    """Raised when the bridge returns a non-OK envelope."""
+
+    def __init__(self, code: str, message: str, *, detail: dict[str, Any] | None = None) -> None:
+        super().__init__(f"[{code}] {message}")
+        self.code = code
+        self.message = message
+        self.detail: dict[str, Any] = detail or {}
+
+
+class TransportError(RuntimeError):
+    """Raised when the HTTP transport itself fails (timeout, connection refused, etc.)."""
+
+    def __init__(self, message: str, *, cause: Exception | None = None) -> None:
+        super().__init__(message)
+        self.cause = cause
+
+
+@dataclass(frozen=True, slots=True)
+class BridgeErrorEnvelope:
+    """Strongly-typed view over the bridge's ``error`` object."""
+
+    code: str
+    message: str
+    command: str | None = None
+    args: dict[str, Any] | None = None
+    did_you_mean: list[str] | None = None
+    exception: dict[str, Any] | None = None
+    extras: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_payload(cls, payload: dict[str, Any]) -> "BridgeErrorEnvelope":
+        known = {"code", "message", "command", "args", "did_you_mean", "exception"}
+        return cls(
+            code=str(payload.get("code", "INTERNAL")),
+            message=str(payload.get("message", "(no message)")),
+            command=payload.get("command"),
+            args=payload.get("args"),
+            did_you_mean=payload.get("did_you_mean"),
+            exception=payload.get("exception"),
+            extras={k: v for k, v in payload.items() if k not in known},
+        )
+
+    def as_bridge_error(self) -> BridgeError:
+        detail = {
+            "command": self.command,
+            "args": self.args,
+            "did_you_mean": self.did_you_mean,
+            "exception": self.exception,
+            **self.extras,
+        }
+        detail = {k: v for k, v in detail.items() if v is not None}
+        return BridgeError(self.code, self.message, detail=detail)

worldbox_mcp-0.1.0/src/worldbox_mcp/resources/__init__.py

@@ -0,0 +1,3 @@
+"""MCP resources exposed by the server (Phase 4)."""
+
+from __future__ import annotations

worldbox_mcp-0.1.0/src/worldbox_mcp/server.py

@@ -0,0 +1,59 @@
+"""Server factory.
+
+Builds a fully wired :class:`FastMCP` instance: configuration, HTTP client, all registered
+tools. The factory is decoupled from transport selection so tests (and the ``--self-check``
+mode) can instantiate the server without binding any I/O.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import structlog
+
+from .client import BridgeClient
+from .config import Settings
+from .tools import action, control, discovery, meta, read
+
+if TYPE_CHECKING:
+    from mcp.server.fastmcp import FastMCP
+
+logger = structlog.get_logger(__name__)
+
+
+def build_server(settings: Settings) -> tuple["FastMCP", BridgeClient]:
+    """Construct the MCP server and the bridge client it owns.
+
+    Returns both so the caller can keep the client lifecycle tied to the server's
+    transport loop. Closing the client after ``server.run()`` returns is the caller's
+    responsibility.
+    """
+    # Lazy import to keep `--self-check` fast (no MCP framework import unless we actually
+    # need to register tools).
+    from mcp.server.fastmcp import FastMCP
+
+    server = FastMCP(
+        name="worldbox-mcp",
+        instructions=(
+            "Tools for controlling and inspecting a running WorldBox game. Call "
+            "`worldbox_health` first to verify the bridge is reachable, then "
+            "`worldbox_capabilities` to discover what commands the current mod build "
+            "supports. Asset identifiers (tile/actor/power ids) come from the in-game "
+            "registry — never assume them; enumerate via the discovery tools."
+        ),
+    )
+
+    client = BridgeClient(settings.bridge)
+    logger.info(
+        "server.build",
+        bridge_url=settings.bridge.base_url,
+        worldbox_dir=str(settings.worldbox_dir) if settings.worldbox_dir else None,
+    )
+
+    meta.register(server, client)
+    discovery.register(server, client)
+    action.register(server, client)
+    read.register(server, client)
+    control.register(server, client)
+
+    return server, client

worldbox_mcp-0.1.0/src/worldbox_mcp/tools/__init__.py

@@ -0,0 +1,5 @@
+"""Tool modules. Each submodule registers its tools onto a :class:`FastMCP` instance via
+``register(server, client)``. The top-level :mod:`worldbox_mcp.server` imports them in turn.
+"""
+
+from __future__ import annotations

worldbox_mcp-0.1.0/src/worldbox_mcp/tools/action.py

@@ -0,0 +1,91 @@
+"""Action tools — modify the world.
+
+Three primitives cover the full action surface:
+
+* ``worldbox_invoke_power`` — universal GodPower trigger (most spawns + every disaster).
+* ``worldbox_spawn`` — actor spawn for entries that aren't in the PowerLibrary
+  (dragons, kraken, cthulhu, …).
+* ``worldbox_paint_tile`` — direct tile-type modification with optional radius.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from mcp.server.fastmcp import FastMCP
+
+    from ..client import BridgeClient
+
+
+def register(server: "FastMCP", client: "BridgeClient") -> None:
+    @server.tool(
+        name="worldbox_invoke_power",
+        description=(
+            "Invokes any GodPower on a tile. Universal action: covers every spawn-by-race "
+            "(by passing a race id like 'human'), every disaster (meteorite, nuke, plague, "
+            "lightning, tsunami, earthquake, …), every toggle (peace, civilization, …) and "
+            "every modifier the in-game god-mode UI exposes. Discover valid power_id values "
+            "via `worldbox_list_powers`. x/y are tile coordinates within the map. Returns "
+            "`{power_id, x, y, accepted}` where `accepted=false` means the game's logic "
+            "refused the action."
+        ),
+    )
+    async def worldbox_invoke_power(power_id: str, x: int, y: int) -> dict[str, Any]:
+        return await client.call("invoke_power", {"power_id": power_id, "x": x, "y": y})
+
+    @server.tool(
+        name="worldbox_spawn",
+        description=(
+            "Spawns one or more actors of a given asset id at (x, y). Use this for "
+            "creatures NOT exposed as GodPowers — dragons, kraken, cthulhu, demons, "
+            "titans, specific animals. Discover ids via `worldbox_list_actors`. The game "
+            "auto-assigns the actor's wild kingdom from ActorAsset.kingdom_id_wild — no "
+            "kingdom argument needed. count must be 1..100. If the actor can't survive the "
+            "terrain (e.g. land animal on water), the game silently refuses and the call "
+            "reports failed > 0."
+        ),
+    )
+    async def worldbox_spawn(
+        entity_id: str,
+        x: int,
+        y: int,
+        count: int = 1,
+        adult: bool = False,
+        spawn_height: float = 6.0,
+    ) -> dict[str, Any]:
+        return await client.call(
+            "spawn",
+            {
+                "entity_id": entity_id,
+                "x": x,
+                "y": y,
+                "count": count,
+                "adult": adult,
+                "spawn_height": spawn_height,
+            },
+        )
+
+    @server.tool(
+        name="worldbox_paint_tile",
+        description=(
+            "Paints a single tile or a disc of tiles. tile_id changes the main ground "
+            "type (water, lava, sand, soil_low, …); optional top_id sets the top "
+            "decoration (forests, roads, wasteland, …). Discover valid ids via "
+            "`worldbox_list_tiles`. With radius > 0, paints a Euclidean disc of `radius` "
+            "cells. Out-of-map cells are skipped silently. Returns `{painted, skipped}`."
+        ),
+    )
+    async def worldbox_paint_tile(
+        x: int,
+        y: int,
+        tile_id: str | None = None,
+        top_id: str | None = None,
+        radius: int = 0,
+    ) -> dict[str, Any]:
+        args: dict[str, Any] = {"x": x, "y": y, "radius": radius}
+        if tile_id is not None:
+            args["tile_id"] = tile_id
+        if top_id is not None:
+            args["top_id"] = top_id
+        return await client.call("paint_tile", args)

worldbox_mcp-0.1.0/src/worldbox_mcp/tools/control.py

@@ -0,0 +1,101 @@
+"""Control tools — simulation flow + world lifecycle.
+
+Six tools that let an agent manage the simulation as a whole: pause/resume + speed
+control for time management, generate/save/load for world lifecycle.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from mcp.server.fastmcp import FastMCP
+
+    from ..client import BridgeClient
+
+
+def register(server: "FastMCP", client: "BridgeClient") -> None:
+    @server.tool(
+        name="worldbox_pause",
+        description=(
+            "Pauses the simulation. Call this before building a complex scenario so the "
+            "world doesn't drift while you set things up. Returns the previous paused "
+            "state so you can detect whether you actually changed anything."
+        ),
+    )
+    async def worldbox_pause() -> dict[str, Any]:
+        return await client.call("pause")
+
+    @server.tool(
+        name="worldbox_resume",
+        description=(
+            "Resumes the simulation. Pair with worldbox_set_speed if you want the world "
+            "to run faster than real-time (x2/x3/x5)."
+        ),
+    )
+    async def worldbox_resume() -> dict[str, Any]:
+        return await client.call("resume")
+
+    @server.tool(
+        name="worldbox_set_speed",
+        description=(
+            "Sets the simulation tick rate by WorldTimeScaleAsset id. Typical values: "
+            "'slow_mo', 'x1', 'x2', 'x3', 'x5'. Higher values run the simulation faster "
+            "so longer experiments take less wall-clock time. Wrong ids return "
+            "UNKNOWN_ASSET with did_you_mean suggestions."
+        ),
+    )
+    async def worldbox_set_speed(speed_id: str) -> dict[str, Any]:
+        return await client.call("set_speed", {"speed_id": speed_id})
+
+    @server.tool(
+        name="worldbox_generate_world",
+        description=(
+            "Regenerates the world map. All kingdoms / cities / actors are wiped. Optional "
+            "zone_x and zone_y set the map size in 64-tile zones (default 4x4 = 256x256, "
+            "max 16x16 = 1024x1024). Generation runs asynchronously over many frames; the "
+            "response means 'scheduled', not 'ready' — poll worldbox_get_world_state until "
+            "tick advances to know when it's done."
+        ),
+    )
+    async def worldbox_generate_world(
+        zone_x: int | None = None,
+        zone_y: int | None = None,
+    ) -> dict[str, Any]:
+        args: dict[str, Any] = {}
+        if zone_x is not None:
+            args["zone_x"] = zone_x
+        if zone_y is not None:
+            args["zone_y"] = zone_y
+        return await client.call("generate_world", args)
+
+    @server.tool(
+        name="worldbox_save_world",
+        description=(
+            "Saves the current world to disk via the game's native save format. `folder` is "
+            "required (absolute path). Save files are compatible with the in-game load UI. "
+            "Fails with GAME_REJECTED if no world is currently loaded."
+        ),
+    )
+    async def worldbox_save_world(folder: str, compress: bool = True) -> dict[str, Any]:
+        return await client.call("save_world", {"folder": folder, "compress": compress})
+
+    @server.tool(
+        name="worldbox_load_world",
+        description=(
+            "Loads a previously-saved world. Provide either `path` (absolute path to a save "
+            "file on disk) or `bytes_b64` (base64-encoded zipped save bytes). Like "
+            "generate_world the load runs asynchronously — poll worldbox_get_world_state "
+            "until tick advances."
+        ),
+    )
+    async def worldbox_load_world(
+        path: str | None = None,
+        bytes_b64: str | None = None,
+    ) -> dict[str, Any]:
+        args: dict[str, Any] = {}
+        if path is not None:
+            args["path"] = path
+        if bytes_b64 is not None:
+            args["bytes_b64"] = bytes_b64
+        return await client.call("load_world", args)

worldbox_mcp-0.1.0/src/worldbox_mcp/tools/discovery.py

@@ -0,0 +1,57 @@
+"""Discovery tools: enumerate the in-game asset registry.
+
+The mod-side ``list_*`` commands introspect ``AssetManager`` at runtime, so the
+returned ids stay correct across WorldBox updates without us having to recompile.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from mcp.server.fastmcp import FastMCP
+
+    from ..client import BridgeClient
+
+
+def register(server: "FastMCP", client: "BridgeClient") -> None:
+    """Register the three discovery tools onto ``server``."""
+
+    @server.tool(
+        name="worldbox_list_tiles",
+        description=(
+            "Lists every TileType currently registered in the running WorldBox build. "
+            "Returns `{items: [{id, color_hex?, has_biome_tags?, ...}], count}`. "
+            "Tile ids are the valid inputs for `worldbox_paint_tile` (Phase 3). "
+            "Call this once per session to learn what's available — the catalog can "
+            "change with WorldBox updates and modder-added tiles."
+        ),
+    )
+    async def worldbox_list_tiles() -> dict[str, Any]:
+        return await client.call("list_tiles")
+
+    @server.tool(
+        name="worldbox_list_actors",
+        description=(
+            "Lists every ActorAsset (creature / race / animal / monster / mythical) "
+            "currently registered. Returns `{items: [{id, race?, asset_type?, ...}], "
+            "count}`. Actor ids are the valid inputs for `worldbox_spawn` (Phase 3). "
+            "Examples on stock WorldBox 0.51.x include `human`, `elf`, `orc`, `dwarf`, "
+            "`wolf`, `bear`, `dragon_red`, `cthulhu`, plus ~300 more."
+        ),
+    )
+    async def worldbox_list_actors() -> dict[str, Any]:
+        return await client.call("list_actors")
+
+    @server.tool(
+        name="worldbox_list_powers",
+        description=(
+            "Lists every PowerAsset (god-mode action) registered in the running game. "
+            "Returns `{items: [{id, tab_id?, target_type?, ...}], count}`. Powers cover "
+            "spawn buttons, disasters (meteor, nuke, plague, …), toggles "
+            "(toggle_peace, toggle_civ, …), and modifiers. Power ids are the valid "
+            "inputs for `worldbox_invoke_power` (Phase 3)."
+        ),
+    )
+    async def worldbox_list_powers() -> dict[str, Any]:
+        return await client.call("list_powers")

worldbox_mcp-0.1.0/src/worldbox_mcp/tools/meta.py

@@ -0,0 +1,48 @@
+"""Meta tools: ``worldbox_health`` and ``worldbox_capabilities``.
+
+Phase 1 only exposes ``worldbox_health``. The discovery/action/read/control tools land in
+later phases as the corresponding mod-side commands ship.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from mcp.server.fastmcp import FastMCP
+
+    from ..client import BridgeClient
+
+
+def register(server: "FastMCP", client: "BridgeClient") -> None:
+    """Register meta tools onto ``server``.
+
+    Tool names use the ``worldbox_*`` prefix so they don't collide with tools from other
+    MCP servers that an agent may also have connected.
+    """
+
+    @server.tool(
+        name="worldbox_health",
+        description=(
+            "Probe the WorldBoxBridge mod. Returns plugin liveness, mod version, "
+            "WorldBox version, Unity version, the SHA256 of Assembly-CSharp.dll, "
+            "and the most recent main-thread tick. Call this first — its return value "
+            "tells you whether the bridge is reachable and what game build you're "
+            "talking to."
+        ),
+    )
+    async def worldbox_health() -> dict[str, Any]:
+        return await client.health()
+
+    @server.tool(
+        name="worldbox_capabilities",
+        description=(
+            "Returns the full list of commands the WorldBoxBridge mod currently exposes, "
+            "with their JSON-Schema. The mod publishes this list dynamically — when "
+            "WorldBox is updated, commands that lose backing support disappear from here. "
+            "Use this when an agent wants to discover what's actually available rather "
+            "than assuming."
+        ),
+    )
+    async def worldbox_capabilities() -> dict[str, Any]:
+        return await client.capabilities()

worldbox_mcp-0.1.0/src/worldbox_mcp/tools/read.py

@@ -0,0 +1,101 @@
+"""Read tools — observe the world.
+
+The agent needs to look before it acts. These tools cover dimensions, snapshots,
+queries, and screenshots so the agent can plan actions based on real state instead of
+guesswork.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from mcp.server.fastmcp import FastMCP
+
+    from ..client import BridgeClient
+
+
+def register(server: "FastMCP", client: "BridgeClient") -> None:
+    @server.tool(
+        name="worldbox_get_world_state",
+        description=(
+            "Returns the world snapshot: dimensions (width, height), seed, current tick, "
+            "paused flag, populations (alive + lifetime), kingdoms_alive, cities_alive. "
+            "Call this first to size other queries and to detect whether the simulation "
+            "is running."
+        ),
+    )
+    async def worldbox_get_world_state() -> dict[str, Any]:
+        return await client.call("get_world_state")
+
+    @server.tool(
+        name="worldbox_get_tile",
+        description=(
+            "Returns the tile at (x, y): tile_id, top_id, height, and the names of actors "
+            "standing on it. Returns OUT_OF_BOUNDS when (x, y) is off the map."
+        ),
+    )
+    async def worldbox_get_tile(x: int, y: int) -> dict[str, Any]:
+        return await client.call("get_tile", {"x": x, "y": y})
+
+    @server.tool(
+        name="worldbox_list_kingdoms",
+        description=(
+            "Returns every kingdom currently alive: id, name, race, king name, capital "
+            "city id, cities_count, units_count. By default wild kingdoms (animal packs, "
+            "sea monsters) are filtered out — pass include_wild=true to see them."
+        ),
+    )
+    async def worldbox_list_kingdoms(include_wild: bool = False) -> dict[str, Any]:
+        return await client.call("list_kingdoms", {"include_wild": include_wild})
+
+    @server.tool(
+        name="worldbox_list_cities",
+        description=(
+            "Returns every city alive: id, name, kingdom_id, kingdom_name, leader_name, "
+            "building_count, unit_count. Optionally filter by kingdom_id."
+        ),
+    )
+    async def worldbox_list_cities(kingdom_id: int | None = None) -> dict[str, Any]:
+        args: dict[str, Any] = {}
+        if kingdom_id is not None:
+            args["kingdom_id"] = kingdom_id
+        return await client.call("list_cities", args)
+
+    @server.tool(
+        name="worldbox_query_actors",
+        description=(
+            "Walks every Actor in the simulation and filters by race / kingdom_id / "
+            "bounding rect / alive status, with pagination. Use this to count or sample "
+            "populations without dumping the whole world. Default limit=500, max=5000. "
+            "Pass offset for pagination. Returns `{items, matched, returned, has_more}`."
+        ),
+    )
+    async def worldbox_query_actors(
+        race: str | None = None,
+        kingdom_id: int | None = None,
+        in_rect: dict[str, int] | None = None,
+        alive: bool = True,
+        limit: int = 500,
+        offset: int = 0,
+    ) -> dict[str, Any]:
+        args: dict[str, Any] = {"alive": alive, "limit": limit, "offset": offset}
+        if race is not None:
+            args["race"] = race
+        if kingdom_id is not None:
+            args["kingdom_id"] = kingdom_id
+        if in_rect is not None:
+            args["in_rect"] = in_rect
+        return await client.call("query_actors", args)
+
+    @server.tool(
+        name="worldbox_screenshot",
+        description=(
+            "Captures the current game framebuffer as a base64-encoded PNG. Useful so "
+            "the agent can see what it just did before deciding the next move. Returns "
+            "`{format, width, height, base64, bytes}`. The image is the most recently "
+            "completed frame."
+        ),
+    )
+    async def worldbox_screenshot() -> dict[str, Any]:
+        return await client.call("screenshot")

worldbox_mcp-0.1.0/src/worldbox_mcp/transport.py

@@ -0,0 +1,60 @@
+"""Transport selection: stdio (default) or Streamable HTTP.
+
+stdio is the MCP standard for desktop AI clients (Claude Code, Cursor, Codex, …). HTTP
+exists for web clients, agents that can't spawn subprocesses, or one-off curl debugging.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mcp.server.fastmcp import FastMCP
+
+    from .client import BridgeClient
+
+
+@dataclass(frozen=True, slots=True)
+class TransportConfig:
+    kind: str = "stdio"  # "stdio" or "http"
+    host: str = "127.0.0.1"
+    port: int = 7800
+
+
+async def run(
+    server: "FastMCP",
+    client: "BridgeClient",
+    transport: TransportConfig,
+) -> None:
+    """Run the server until shutdown, then close the bridge client."""
+    try:
+        if transport.kind == "stdio":
+            await server.run_stdio_async()
+        elif transport.kind == "http":
+            # FastMCP's HTTP transport is exposed via run_async on a Starlette app under
+            # the hood. The exact entrypoint name has churned between MCP SDK versions;
+            # we feature-detect to stay compatible across them.
+            runner = getattr(server, "run_streamable_http_async", None) or getattr(
+                server, "run_sse_async", None
+            )
+            if runner is None:
+                msg = (
+                    "This version of the mcp Python SDK does not expose a Streamable HTTP "
+                    "transport. Upgrade `mcp` or use the default stdio transport."
+                )
+                raise RuntimeError(msg)
+            # Most SDK variants accept (host, port) kwargs; if the signature is different,
+            # fall back to setting them on the instance.
+            try:
+                await runner(host=transport.host, port=transport.port)
+            except TypeError:
+                server.settings.host = transport.host  # type: ignore[attr-defined]
+                server.settings.port = transport.port  # type: ignore[attr-defined]
+                await runner()
+        else:
+            msg = f"Unknown transport kind: {transport.kind!r}"
+            raise ValueError(msg)
+    finally:
+        await asyncio.shield(client.aclose())