Metadata-Version: 2.4
Name: cegm-broker
Version: 0.1.0a1
Summary: CheatEngineGM broker — MCP HTTP server, browser dashboard, and LLM client over miscusi-peek/cheatengine-mcp-bridge.
Project-URL: Homepage, https://github.com/dwgx/CEGM
Project-URL: Repository, https://github.com/dwgx/CEGM
Project-URL: Issues, https://github.com/dwgx/CEGM/issues
Author-email: dwgx <dwgx1337@outlook.com>
License-Expression: GPL-2.0-only
Keywords: cheat-engine,claude,llm,mcp,memory-editor,reverse-engineering
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Debuggers
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: anyio>=4.6.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: mcp>=1.27.0
Requires-Dist: openai>=1.50.0
Requires-Dist: psutil>=6.1.0
Requires-Dist: pydantic-settings>=2.7.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: starlette>=0.42.0
Requires-Dist: uvicorn[standard]>=0.32.0
Provides-Extra: dev
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Requires-Dist: types-psutil>=6.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# broker/ — CEGM Python broker

The long-running broker. Auto-spawned by `plugin/cegm.lua` on Cheat Engine startup. Hosts an MCP Streamable HTTP server, a built-in browser dashboard, and a WebSocket event stream — all on `http://127.0.0.1:27077` by default. Spawns the vendored [miscusi-peek/cheatengine-mcp-bridge](https://github.com/miscusi-peek/cheatengine-mcp-bridge) Python child as a stdio MCP server and proxies its tools through.

See [docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md) and [ADR-0004](../docs/decisions/0004-build-on-miscusi-peek.md).

## Stack

- Python 3.12+
- [`mcp`](https://pypi.org/project/mcp/) 1.27+ (FastMCP merged in-tree)
- `starlette` + `uvicorn[standard]` for HTTP + WebSocket
- `openai` SDK with custom `base_url` for LLM (default DeepSeek)
- `anyio` for async, `pydantic` v2 for models, `psutil` for parent-PID watching
- `ruff` (format + lint), `mypy --strict`, `pytest` + `pytest-asyncio`
- `uv` for env management and distribution (`uv tool install cegm-broker`)

## Layout (Phase 1)

```
broker/
├── pyproject.toml           # PEP 621 metadata, all deps + dev deps, tool configs
├── .python-version          # 3.12
├── README.md
├── src/cegm_broker/
│   ├── __init__.py          # __version__
│   ├── __main__.py          # python -m cegm_broker -> cli.main()
│   ├── cli.py               # argparse: --port, --parent-pid, --log-level, --print-config
│   ├── config.py            # %LOCALAPPDATA%/CEGM/config.json loader (Pydantic)
│   ├── _logging.py          # JSONL logger to file + stderr
│   ├── server.py            # Starlette app, route mount
│   ├── mcp_proxy.py         # spawns miscusi-peek child, forwards tools/list + tools/call
│   ├── mcp_extras.py        # CEGM-namespaced @mcp.tool definitions
│   ├── llm.py               # openai SDK wrapper, tool-call routing for /api/chat
│   ├── event_bus.py         # asyncio fan-out to WebSocket subscribers
│   ├── ws.py                # WebSocket handler at /events
│   ├── api.py               # /api/chat, /api/config REST endpoints
│   ├── parent_watch.py      # exits broker when CE PID disappears
│   └── snapshots.py         # snapshot store under %LOCALAPPDATA%/CEGM/snapshots/
└── tests/
    ├── conftest.py
    ├── test_smoke.py        # imports work; CLI prints help
    ├── test_mcp_proxy.py    # spawn fake child, verify tool listing + call
    ├── test_event_bus.py
    └── test_extras_cegm.py  # cegm.preview_write/commit/cancel round-trip
```

## Run (developer)

```bash
cd broker
uv sync               # creates .venv, installs deps + dev deps
uv run cegm-broker --help
uv run cegm-broker --port 27077 --log-level debug
```

## Run (end-user, once published)

```bash
uv tool install cegm-broker     # one-time
# then CE plugin spawns it automatically; manual run is also fine:
cegm-broker --port 27077
```

## Logging

Structured JSONL to `%LOCALAPPDATA%\CEGM\logs\broker-YYYYMMDD.jsonl` and mirrored to stderr. Stdout is reserved (kept clean in case we ever support MCP stdio transport). Activity events (tool calls, chat turns) are also appended to a session-specific file at `%LOCALAPPDATA%\CEGM\activity\<session_id>.jsonl`.

## Status

Scaffold only — see [docs/ROADMAP.md](../docs/ROADMAP.md) Phase 1.
