Flameox MCP server

flameox

Bounded local runtime evidence for coding agents.

<!-- mcp-name: io.github.morluto/flameox -->

Flameox coordinates profilers, benchmark tools, trace processors, and direct local targets. It gives an agent a short path from an explicit native artifact or live command to bounded evidence, while keeping preservation optional.

There is no workspace to initialize, flameox.toml, SQLite control plane, durable job to poll, or parent-directory discovery. Analyze existing artifacts by passing their exact paths and formats.

Quick start

uv sync --extra dev --extra memory --extra trace --extra cpu
uv run flameox mcp inspect
uv run flameox analyze artifact.preview /absolute/path/to/artifact.json
uv run flameox capture --provider direct --cwd "$PWD" -- python benchmark.py

The MCP server has no workspace or project binding:

uv run flameox mcp serve

Run the short global setup wizard through npm:

npx flameox@latest setup

Setup detects Claude Code, Cursor, OpenCode, Codex, Gemini CLI, and Google Antigravity, then asks which clients should use Flameox. It preserves unrelated client configuration and writes a Python 3.12 uvx launcher pinned to the exact Flameox release that ran setup. Restart or reconnect changed clients afterward. For automation, pass --client codex --yes, repeat --client, or use --all --yes; --dry-run reports the same global paths without writing them. Detection is never automation consent.

Explicit --provider selections prepare the exact version-pinned uvx environment in the saved launcher by resolving it once into uvx's cache; they do not create a persistent global uv tool installation. Each invocation declares the complete managed provider set for that launcher rather than adding to remembered state. Use --timeout-seconds for a slow cold resolution. System and vendor tools are diagnosed with external install guidance. Setup never initializes or mutates a project.

Authority model

explicit artifact paths / typed direct target
                    │
                    ▼
         bounded process-lifespan runtime
             │                │
             ▼                ▼
       inline evidence   session scratch/cache
                              │
                       explicit preservation
                              │
                              ▼
             user Flameox data directory

Analysis and unpreserved capture make no durable Flameox writes. Capture artifacts stay in bounded session scratch until preservation, least-recently-used eviction, or server shutdown. An evicted analysisid returns EXPIREDSESSIONANALYSIS; preserve conclusions before relying on them. The first preserveevidence call creates the user-level Flameox data directory and stores native bytes and a canonical evidence bundle by SHA-256. FLAMEOXDATADIR overrides the platform default for isolation or another storage location. Flameox never edits project Git files.

The console-retention default is bounded diagnostics in memory, with explicit omission counts. Keep native artifacts when needed; retain full console output on disk only when it is the evidence, an oracle needs it, or the caller requests it. Preservation alone does not request full logs. See console retention.

Workload time and RSS budgets are optional: use target.budget in MCP or --workload-budget in CLI capture. They do not inherit analysis-worker limits; cancellation and storage protection remain active when no workload budget is set.

The agent owns hypotheses and narrative findings in its own notes. Flameox owns only observed inputs, effective requests, execution provenance, typed evidence, coverage, truncation, limitations, and optional immutable preservation.

MCP interface

Shortened. The full README is on GitHub.