lrvx-mcp — Model Context Protocol server for lrvx

Gives AI agents (Cursor, Claude Code, Cline) grounded access to the lrvx 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

Quickstart

pip install lrvx-mcp           # MCP server + lrvx (indicators, backtest, engine CLI)
lrvx-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 (lrvx engine sim, lrvx tape record). For tier-5/6 (live state, place_order, flatten_positions), also start a paper engine and rerun init with --overwrite and the printed token:

lrvx engine sim --strategy s.py --tape ./tape         # prints engine URL + token
lrvx-mcp init --overwrite --engine-url URL --token T  # rewrites the lrvx entry with the engine env

lrvx engine sim boots a Runner + SimulatedExecutor + ControlServer and writes a runtime snapshot the read tools poll. See python/lrvx/engine_cli.py for the full set of flags.

lrvx-mcp init flags

An existing mcpServers.flox entry that launches flox-mcp, the server's FLOX-era name, is replaced by the lrvx entry instead of kept next to it. The FLOX_CONTROL_URL and FLOX_CONTROL_TOKEN it set move over as LRVX_CONTROL_URL and LRVX_CONTROL_TOKEN unless --engine-url or --token sets them.

Manual override

If you'd rather hand-edit, the resulting .mcp.json is shaped like:

{
  "mcpServers": {
    "lrvx": {
      "command": "lrvx-mcp",
      "args": ["serve"],
      "env": {
        "LRVX_RUNTIME_STATE": "$HOME/.lrvx/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

cd mcp
pip install -e ".[dev]"

# Run the server manually (stdio):
lrvx-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:

• lrvx_mcp/data/c-api.snapshot — copy of .api/c-api.snapshot.
• lrvx_mcp/data/errors/E_*.md — copies of docs/errors/E_*.md.
• lrvx_mcp/data/ir.snapshot.json — IR (functions, structs, enums, typedefs, function pointers) pulled from the IDL spec via libclang. Versioned schema.
• lrvx_mcp/data/binding_manifest.json — per-binding symbol map keyed by IDL group. Built from binding_parity.yaml plus scans of lrvx/_lrvx/__init__.pyi, node/index.d.ts, and the codon golden file.
• lrvx_mcp/data/examples_index.json — index of docs/examples/ (path, language, topic, sha256).
• lrvx_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.
• lrvx_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 lrvx-mcp package version is bumped in lockstep with lrvx and lrvx by scripts/set-version.sh. An installed lrvx-mcp x.y.z was built from the same source tree as the matching lrvx / 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 lrvx actually ships.

License

MIT — same as lrvx.