flox-mcp 0.6.0__tar.gz

flox_mcp-0.6.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: flox-mcp
+Version: 0.6.0
+Summary: Model Context Protocol server for FLOX — gives AI agents grounded access to indicators, error codes, and the C API.
+Author: FLOX Foundation
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/FLOX-Foundation/flox
+Project-URL: Repository, https://github.com/FLOX-Foundation/flox
+Project-URL: Docs, https://flox-foundation.github.io/flox/
+Keywords: trading,backtest,indicators,mcp,ai,claude,cursor
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.0
+Requires-Dist: flox-py>=0.5
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+
+# flox-mcp — Model Context Protocol server for FLOX
+
+Gives AI agents (Cursor, Claude Code, Cline) **grounded** access to the
+FLOX C-API surface, error catalog, and indicator library — so they can
+write code against real signatures instead of guessing.
+
+The server runs locally on the developer's machine; the IDE spawns it
+as a child process and talks to it over stdio. There is no public
+hosting; nothing leaves the machine.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `list_indicators` | Every indicator in `flox_py` with class signature, batch fn (if any), and shape. Filter by substring. |
+| `lookup_error_code` | `E_SYM_001` → full Markdown page with fix recipe, common causes, diagnostics. |
+| `list_capi_functions` | Search the FLOX C-API surface from the committed ABI snapshot. Returns `name + return type + parameter types`. |
+| `validate_strategy` | Static-analysis check on Python strategy code: AST parses, expected hooks present, no `eval`/`exec`. |
+| `explain_event` | Describe the fields of a FLOX event struct (`FloxTradeData`, `FloxBookData`, `FloxBarData`, `FloxSymbolContext`, `FloxSignal`). Accepts a struct name or a raw event dict. |
+| `lookup_symbol` | Take any binding-local spelling (`FloxBarData`, `BarData`, `flox_indicator_ema`, `ema`) and return what the symbol is called in C-API, Python, Node, and Codon. |
+| `list_bindings` | Enumerate the exports of one binding (capi, python, node, codon, quickjs). Substring filter and limit. |
+| `get_example` | Code from `docs/examples/` matching a topic (strategy, connector, indicator, event-handler, risk, backtest), optionally filtered by language. |
+| `scaffold_strategy` | Starter strategy class for Python or Node. Three kinds: bar-driven, trade-driven, hybrid. The Python output goes through `ast.parse` + `validate_strategy`; the Node output goes through `node --check`. CI fails if either breaks, so templates can't quietly rot. |
+| `docs_search` | Top-k FTS5 search over the docs. The index is built from an allowlist of roots; private trackers and `CLAUDE.md` are not in that allowlist. |
+| `run_backtest` | Run a Python strategy against a CSV dataset in a sandboxed subprocess. Caps CPU, memory, and output size; wall-clock timeout. **MVP sandbox** — caps resources but does not isolate filesystem or network. Treat the same way as any untrusted Python; use nsjail / firejail / Docker for production. |
+| `compute_indicator` | Run one FLOX indicator over a list of floats. Accepts class-form (`EMA`) or function-form (`ema`) names and forwards extra kwargs to the constructor. Input capped at 1 MiB. Needs `flox-py` installed (`pip install "flox-mcp[flox]"`). |
+| `suggest_indicator` | Map an English description ('trend filter', 'momentum oscillator', 'volatility band', 'mean revert', 'regime test') to a ranked shortlist of FLOX indicators. Pure keyword heuristic — no LLM call. Always confirm the chosen indicator with `list_indicators` before using it. |
+
+## Quickstart
+
+```bash
+pip install flox-mcp           # MCP server + flox-py (indicators, backtest, engine CLI)
+flox-mcp init                  # writes ./.mcp.json for the current project
+# restart your MCP client (Claude Code / Cursor / Cline) → done
+```
+
+You get the whole surface in one install: docs / lookup tools,
+indicator introspection, backtest, and the engine CLI
+(`flox engine sim`, `flox tape record`). For tier-5/6 (live state,
+`place_order`, `flatten_positions`), also start a paper engine and
+rerun `init` with the printed token:
+
+```bash
+flox engine sim --strategy s.py --tape ./tape       # prints engine URL + token
+flox-mcp init --engine-url URL --token T            # appends env to ./.mcp.json
+```
+
+`flox engine sim` boots a `Runner` + `SimulatedExecutor` +
+`ControlServer` and writes a runtime snapshot the read tools poll.
+See [`python/flox_py/engine_cli.py`](../python/flox_py/engine_cli.py)
+for the full set of flags.
+
+`flox engine sim` boots a `Runner` + `SimulatedExecutor` + `ControlServer`
+and writes a runtime snapshot the read tools poll. See
+[`python/flox_py/engine_cli.py`](../python/flox_py/engine_cli.py)
+for the full set of flags.
+
+### `flox-mcp init` flags
+
+| Flag | What it does |
+|---|---|
+| *(default)* | Writes `./.mcp.json` in the current directory. Merges with an existing file. |
+| `--global` | Writes `~/.config/claude/.mcp.json` instead. |
+| `--overwrite` | Replace an existing `mcpServers.flox` entry instead of refusing. |
+| `--print` | Print the merged config to stdout, don't write. |
+| `--engine-url URL` | Sets `FLOX_CONTROL_URL` (tier-5/6 wiring). |
+| `--token T` | Sets `FLOX_CONTROL_TOKEN` (printed by `flox engine sim`). |
+
+### Manual override
+
+If you'd rather hand-edit, the resulting `.mcp.json` is shaped like:
+
+```json
+{
+  "mcpServers": {
+    "flox": {
+      "command": "flox-mcp",
+      "args": ["serve"],
+      "env": {
+        "FLOX_RUNTIME_STATE": "$HOME/.flox/runtime.json"
+      }
+    }
+  }
+}
+```
+
+Same shape works for Claude Code, Cursor, and Cline — they all read
+`mcpServers.<name>` from a project-local `.mcp.json` (or the
+client-specific global path).
+
+## Develop
+
+```bash
+cd mcp
+pip install -e ".[dev]"
+
+# Run the server manually (stdio):
+flox-mcp
+
+# Run unit tests:
+pytest tests/
+
+# Sync bundled data from canonical sources (.api/, docs/errors/):
+python ../scripts/sync_mcp_data.py
+```
+
+## Bundled data
+
+Read-only copies in the wheel:
+
+- `flox_mcp/data/c-api.snapshot` — copy of `.api/c-api.snapshot`.
+- `flox_mcp/data/errors/E_*.md` — copies of `docs/errors/E_*.md`.
+- `flox_mcp/data/ir.snapshot.json` — IR (functions, structs, enums,
+  typedefs, function pointers) pulled from the IDL spec via libclang.
+  Versioned schema.
+- `flox_mcp/data/binding_manifest.json` — per-binding symbol map keyed
+  by IDL group. Built from `binding_parity.yaml` plus scans of
+  `flox_py/_flox_py/__init__.pyi`, `node/index.d.ts`, and the codon
+  golden file.
+- `flox_mcp/data/examples_index.json` — index of `docs/examples/`
+  (path, language, topic, sha256).
+- `flox_mcp/data/docs.fts.sqlite` — SQLite FTS5 index over six doc
+  roots: `bindings`, `how-to`, `tutorials`, `reference`, `explanation`,
+  `errors`. Anything outside that list is skipped at index build time.
+  Private trackers and `CLAUDE.md` are not in the allowlist.
+- `flox_mcp/data/templates/strategy/{python,node}/{bar,trade,hybrid}-driven.tmpl`
+  — strategy scaffolds rendered by `scaffold_strategy`.
+
+`scripts/sync_mcp_data.py --check` runs in CI. Any drift between a
+bundled copy and its canonical source fails the build. To update
+after editing a canonical source: run the script without `--check`
+and commit the diff.
+
+The `flox-mcp` package version is bumped in lockstep with `flox-py`
+and `@flox-foundation/flox` by `scripts/set-version.sh`. An installed
+`flox-mcp x.y.z` was built from the same source tree as the matching
+flox-py / npm release, so what the agent sees lines up with what the
+developer has installed.
+
+## Scope notes
+
+- The server is **local**. No network calls. AI clients spawn it as a
+  child process and talk via stdio.
+- Most tools are read-only data lookups. The two that execute code —
+  `compute_indicator` and `run_backtest` — run in-process / in a
+  resource-limited subprocess respectively. `run_backtest` is an MVP
+  sandbox: it caps CPU, memory, and output size, but does NOT isolate
+  filesystem or network. Wrap with nsjail / firejail / Docker for any
+  deployment that takes untrusted input.
+- The snapshot used by `list_capi_functions` is the same
+  `.api/c-api.snapshot` enforced by the codegen ABI gate; the IR
+  snapshot used by `lookup_symbol` / `list_bindings` is regenerated
+  from the same IDL spec on every release. So the agent's view of
+  the surface tracks what FLOX actually ships.
+
+## License
+
+MIT — same as FLOX.

flox_mcp-0.6.0/README.md

@@ -0,0 +1,158 @@
+# flox-mcp — Model Context Protocol server for FLOX
+
+Gives AI agents (Cursor, Claude Code, Cline) **grounded** access to the
+FLOX C-API surface, error catalog, and indicator library — so they can
+write code against real signatures instead of guessing.
+
+The server runs locally on the developer's machine; the IDE spawns it
+as a child process and talks to it over stdio. There is no public
+hosting; nothing leaves the machine.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `list_indicators` | Every indicator in `flox_py` with class signature, batch fn (if any), and shape. Filter by substring. |
+| `lookup_error_code` | `E_SYM_001` → full Markdown page with fix recipe, common causes, diagnostics. |
+| `list_capi_functions` | Search the FLOX C-API surface from the committed ABI snapshot. Returns `name + return type + parameter types`. |
+| `validate_strategy` | Static-analysis check on Python strategy code: AST parses, expected hooks present, no `eval`/`exec`. |
+| `explain_event` | Describe the fields of a FLOX event struct (`FloxTradeData`, `FloxBookData`, `FloxBarData`, `FloxSymbolContext`, `FloxSignal`). Accepts a struct name or a raw event dict. |
+| `lookup_symbol` | Take any binding-local spelling (`FloxBarData`, `BarData`, `flox_indicator_ema`, `ema`) and return what the symbol is called in C-API, Python, Node, and Codon. |
+| `list_bindings` | Enumerate the exports of one binding (capi, python, node, codon, quickjs). Substring filter and limit. |
+| `get_example` | Code from `docs/examples/` matching a topic (strategy, connector, indicator, event-handler, risk, backtest), optionally filtered by language. |
+| `scaffold_strategy` | Starter strategy class for Python or Node. Three kinds: bar-driven, trade-driven, hybrid. The Python output goes through `ast.parse` + `validate_strategy`; the Node output goes through `node --check`. CI fails if either breaks, so templates can't quietly rot. |
+| `docs_search` | Top-k FTS5 search over the docs. The index is built from an allowlist of roots; private trackers and `CLAUDE.md` are not in that allowlist. |
+| `run_backtest` | Run a Python strategy against a CSV dataset in a sandboxed subprocess. Caps CPU, memory, and output size; wall-clock timeout. **MVP sandbox** — caps resources but does not isolate filesystem or network. Treat the same way as any untrusted Python; use nsjail / firejail / Docker for production. |
+| `compute_indicator` | Run one FLOX indicator over a list of floats. Accepts class-form (`EMA`) or function-form (`ema`) names and forwards extra kwargs to the constructor. Input capped at 1 MiB. Needs `flox-py` installed (`pip install "flox-mcp[flox]"`). |
+| `suggest_indicator` | Map an English description ('trend filter', 'momentum oscillator', 'volatility band', 'mean revert', 'regime test') to a ranked shortlist of FLOX indicators. Pure keyword heuristic — no LLM call. Always confirm the chosen indicator with `list_indicators` before using it. |
+
+## Quickstart
+
+```bash
+pip install flox-mcp           # MCP server + flox-py (indicators, backtest, engine CLI)
+flox-mcp init                  # writes ./.mcp.json for the current project
+# restart your MCP client (Claude Code / Cursor / Cline) → done
+```
+
+You get the whole surface in one install: docs / lookup tools,
+indicator introspection, backtest, and the engine CLI
+(`flox engine sim`, `flox tape record`). For tier-5/6 (live state,
+`place_order`, `flatten_positions`), also start a paper engine and
+rerun `init` with the printed token:
+
+```bash
+flox engine sim --strategy s.py --tape ./tape       # prints engine URL + token
+flox-mcp init --engine-url URL --token T            # appends env to ./.mcp.json
+```
+
+`flox engine sim` boots a `Runner` + `SimulatedExecutor` +
+`ControlServer` and writes a runtime snapshot the read tools poll.
+See [`python/flox_py/engine_cli.py`](../python/flox_py/engine_cli.py)
+for the full set of flags.
+
+`flox engine sim` boots a `Runner` + `SimulatedExecutor` + `ControlServer`
+and writes a runtime snapshot the read tools poll. See
+[`python/flox_py/engine_cli.py`](../python/flox_py/engine_cli.py)
+for the full set of flags.
+
+### `flox-mcp init` flags
+
+| Flag | What it does |
+|---|---|
+| *(default)* | Writes `./.mcp.json` in the current directory. Merges with an existing file. |
+| `--global` | Writes `~/.config/claude/.mcp.json` instead. |
+| `--overwrite` | Replace an existing `mcpServers.flox` entry instead of refusing. |
+| `--print` | Print the merged config to stdout, don't write. |
+| `--engine-url URL` | Sets `FLOX_CONTROL_URL` (tier-5/6 wiring). |
+| `--token T` | Sets `FLOX_CONTROL_TOKEN` (printed by `flox engine sim`). |
+
+### Manual override
+
+If you'd rather hand-edit, the resulting `.mcp.json` is shaped like:
+
+```json
+{
+  "mcpServers": {
+    "flox": {
+      "command": "flox-mcp",
+      "args": ["serve"],
+      "env": {
+        "FLOX_RUNTIME_STATE": "$HOME/.flox/runtime.json"
+      }
+    }
+  }
+}
+```
+
+Same shape works for Claude Code, Cursor, and Cline — they all read
+`mcpServers.<name>` from a project-local `.mcp.json` (or the
+client-specific global path).
+
+## Develop
+
+```bash
+cd mcp
+pip install -e ".[dev]"
+
+# Run the server manually (stdio):
+flox-mcp
+
+# Run unit tests:
+pytest tests/
+
+# Sync bundled data from canonical sources (.api/, docs/errors/):
+python ../scripts/sync_mcp_data.py
+```
+
+## Bundled data
+
+Read-only copies in the wheel:
+
+- `flox_mcp/data/c-api.snapshot` — copy of `.api/c-api.snapshot`.
+- `flox_mcp/data/errors/E_*.md` — copies of `docs/errors/E_*.md`.
+- `flox_mcp/data/ir.snapshot.json` — IR (functions, structs, enums,
+  typedefs, function pointers) pulled from the IDL spec via libclang.
+  Versioned schema.
+- `flox_mcp/data/binding_manifest.json` — per-binding symbol map keyed
+  by IDL group. Built from `binding_parity.yaml` plus scans of
+  `flox_py/_flox_py/__init__.pyi`, `node/index.d.ts`, and the codon
+  golden file.
+- `flox_mcp/data/examples_index.json` — index of `docs/examples/`
+  (path, language, topic, sha256).
+- `flox_mcp/data/docs.fts.sqlite` — SQLite FTS5 index over six doc
+  roots: `bindings`, `how-to`, `tutorials`, `reference`, `explanation`,
+  `errors`. Anything outside that list is skipped at index build time.
+  Private trackers and `CLAUDE.md` are not in the allowlist.
+- `flox_mcp/data/templates/strategy/{python,node}/{bar,trade,hybrid}-driven.tmpl`
+  — strategy scaffolds rendered by `scaffold_strategy`.
+
+`scripts/sync_mcp_data.py --check` runs in CI. Any drift between a
+bundled copy and its canonical source fails the build. To update
+after editing a canonical source: run the script without `--check`
+and commit the diff.
+
+The `flox-mcp` package version is bumped in lockstep with `flox-py`
+and `@flox-foundation/flox` by `scripts/set-version.sh`. An installed
+`flox-mcp x.y.z` was built from the same source tree as the matching
+flox-py / npm release, so what the agent sees lines up with what the
+developer has installed.
+
+## Scope notes
+
+- The server is **local**. No network calls. AI clients spawn it as a
+  child process and talk via stdio.
+- Most tools are read-only data lookups. The two that execute code —
+  `compute_indicator` and `run_backtest` — run in-process / in a
+  resource-limited subprocess respectively. `run_backtest` is an MVP
+  sandbox: it caps CPU, memory, and output size, but does NOT isolate
+  filesystem or network. Wrap with nsjail / firejail / Docker for any
+  deployment that takes untrusted input.
+- The snapshot used by `list_capi_functions` is the same
+  `.api/c-api.snapshot` enforced by the codegen ABI gate; the IR
+  snapshot used by `lookup_symbol` / `list_bindings` is regenerated
+  from the same IDL spec on every release. So the agent's view of
+  the surface tracks what FLOX actually ships.
+
+## License
+
+MIT — same as FLOX.

flox_mcp-0.6.0/flox_mcp/__init__.py

@@ -0,0 +1,21 @@
+"""flox_mcp — Model Context Protocol server for FLOX.
+
+Run via the `flox-mcp` console script or `python -m flox_mcp`. The server
+speaks MCP over stdio and is meant to be spawned as a child process by
+Cursor / Claude Code / Cline; see README for client config.
+
+Exposed tools:
+
+- list_indicators       — alphabetical map of every indicator in flox_py
+                          with its constructor signature and class shape.
+- lookup_error_code     — given a code like "E_SYM_001", return the full
+                          Markdown page from the canonical error catalog.
+- list_capi_functions   — search the FLOX C-API surface (from the
+                          committed ABI snapshot); returns name + signature.
+- validate_strategy     — Python AST sanity-check on strategy code:
+                          imports resolve, required hooks present,
+                          forbidden patterns absent.
+- explain_event         — describe the fields of a FLOX event struct
+                          (FloxTradeData, FloxBookData, FloxBarData, ...).
+"""
+__version__ = "0.1.0"

flox_mcp-0.6.0/flox_mcp/cli.py

@@ -0,0 +1,187 @@
+"""``flox-mcp`` console-script entry point with subcommands.
+
+Two verbs:
+
+* ``flox-mcp serve`` — start the MCP server over stdio. This is the
+  same behaviour the bare ``flox-mcp`` invocation has always had,
+  preserved for back-compat (and because that's what MCP clients
+  invoke directly).
+* ``flox-mcp init`` — write a working ``.mcp.json`` for the current
+  shell environment so users do not hand-craft the JSON.
+
+Bare ``flox-mcp`` (no args) keeps invoking ``serve`` for back-compat
+with existing MCP client configurations.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+# ── init ──────────────────────────────────────────────────────────────
+
+
+_DEFAULT_RUNTIME_STATE = "$HOME/.flox/runtime.json"
+
+
+def _resolve_command() -> List[str]:
+    """Pick the most portable form of 'launch the flox-mcp server'.
+
+    Prefer the installed console script (`flox-mcp serve`) — it
+    works from any active Python regardless of which interpreter the
+    MCP client launches. Fall back to `python -m flox_mcp.server`
+    when the script is not yet on PATH (e.g. an editable install in
+    a venv whose ``bin/`` is not exported)."""
+    bin_path = shutil.which("flox-mcp")
+    if bin_path:
+        return [bin_path, "serve"]
+    return [sys.executable, "-m", "flox_mcp.server"]
+
+
+def _build_flox_entry(engine_url: Optional[str],
+                      token: Optional[str]) -> Dict[str, Any]:
+    cmd = _resolve_command()
+    env: Dict[str, str] = {
+        "FLOX_RUNTIME_STATE": _DEFAULT_RUNTIME_STATE,
+    }
+    if engine_url:
+        env["FLOX_CONTROL_URL"] = engine_url
+    if token:
+        env["FLOX_CONTROL_TOKEN"] = token
+    return {
+        "command": cmd[0],
+        "args": cmd[1:],
+        "env": env,
+    }
+
+
+def _global_config_path() -> Path:
+    """Where MCP clients look for a global server config.
+
+    Claude Code reads ``~/.config/claude/.mcp.json`` on POSIX and
+    Claude Desktop reads a platform-specific path. We standardise on
+    the POSIX location; users with the Desktop client can pass an
+    explicit path via the upcoming ``--out`` flag (out of scope for
+    the v1 init).
+    """
+    return Path(os.environ.get("XDG_CONFIG_HOME", "~/.config")).expanduser() \
+        / "claude" / ".mcp.json"
+
+
+def _local_config_path() -> Path:
+    return Path.cwd() / ".mcp.json"
+
+
+def _read_existing(path: Path) -> Dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text())
+    except json.JSONDecodeError as exc:
+        raise SystemExit(
+            f"flox-mcp init: existing {path} is not valid JSON ({exc}). "
+            f"Fix or remove it before running init."
+        )
+
+
+def _render(config: Dict[str, Any]) -> str:
+    return json.dumps(config, indent=2, sort_keys=True) + "\n"
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    target = _global_config_path() if args.global_ else _local_config_path()
+
+    flox_entry = _build_flox_entry(args.engine_url, args.token)
+    new_config: Dict[str, Any] = _read_existing(target) if not args.print else {}
+    new_config.setdefault("mcpServers", {})
+
+    if "flox" in new_config["mcpServers"] and not args.overwrite \
+            and not args.print:
+        print(
+            f"flox-mcp init: {target} already has an `mcpServers.flox` "
+            f"entry. Re-run with --overwrite to replace it.",
+            file=sys.stderr,
+        )
+        return 2
+    new_config["mcpServers"]["flox"] = flox_entry
+
+    rendered = _render(new_config)
+    if args.print:
+        sys.stdout.write(rendered)
+        return 0
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(rendered)
+    print(f"wrote {target}")
+    print("restart your MCP client to pick up the flox server.")
+    return 0
+
+
+# ── dispatcher ────────────────────────────────────────────────────────
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """``flox-mcp`` console-script entry point.
+
+    Bare ``flox-mcp`` (no subcommand) still launches the server, so
+    existing MCP-client configurations keep working. ``init`` is the
+    new bootstrap path.
+    """
+    raw = sys.argv[1:] if argv is None else list(argv)
+
+    # Back-compat: bare invocation = serve. That's what every MCP
+    # client config in the wild does.
+    if not raw or raw[0] not in ("init", "serve"):
+        from flox_mcp.server import main as serve_main
+        return serve_main() or 0
+
+    p = argparse.ArgumentParser(prog="flox-mcp")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    init_p = sub.add_parser(
+        "init",
+        help="Write a working .mcp.json for the current environment.",
+    )
+    init_p.add_argument(
+        "--global", dest="global_", action="store_true",
+        help="Write to the user-global config (~/.config/claude/.mcp.json) "
+             "instead of ./.mcp.json.",
+    )
+    init_p.add_argument(
+        "--overwrite", action="store_true",
+        help="Replace an existing mcpServers.flox entry instead of "
+             "refusing.",
+    )
+    init_p.add_argument(
+        "--print", action="store_true",
+        help="Print the merged config to stdout, write nothing.",
+    )
+    init_p.add_argument(
+        "--engine-url",
+        help="Wire tier-5/6 control tools at this engine URL "
+             "(sets FLOX_CONTROL_URL). Pair with --token.",
+    )
+    init_p.add_argument(
+        "--token",
+        help="ControlServer token (sets FLOX_CONTROL_TOKEN). The "
+             "token is printed by `flox engine sim` (W2-T035).",
+    )
+
+    sub.add_parser("serve", help="Start the MCP server over stdio.")
+
+    args = p.parse_args(raw)
+    if args.cmd == "init":
+        return cmd_init(args)
+    if args.cmd == "serve":
+        from flox_mcp.server import main as serve_main
+        return serve_main() or 0
+    return 0  # pragma: no cover
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())