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.
