Metadata-Version: 2.4
Name: worldbox-mcp
Version: 0.3.3
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.
