worldbox-mcp 0.3.1

MCP server that lets any AI agent control WorldBox via the WorldBoxBridge BepInEx mod.

worldbox-mcp (Python MCP server)

The Python half of worldbox-mcp. Distributed on PyPI.

uvx worldbox-mcp           # stdio transport (default)
uvx worldbox-mcp --http    # Streamable HTTP transport
uvx worldbox-mcp --help

See the top-level README and the docs site for full installation instructions and client configuration recipes.

Development

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 HTTP API. It:

1. Speaks the MCP protocol 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 for the full picture.