FigOps

From messy analysis folders to traceable, publication-oriented figures.

FigOps is a small research-ops toolkit for figure work: it reads a project config, checks the declared data contract, runs analysis and plotting scripts, applies journal/presentation styling, and records enough provenance to make the figure auditable later.

It is intentionally boring in the best way: one config, one command, clear inputs, repeatable outputs.

python -m pip install figops
figops --help
figops-mcp --smoke

If those commands work, the CLI is installed and the MCP surface is alive.

Why FigOps exists

Research figures often start as a few scripts and a folder of exported data. That works until the figure changes, a collaborator asks where a value came from, or a manuscript revision needs the same plot in a different journal style.

FigOps keeps that workflow lightweight while making the important parts explicit:

• Data is the API — inputs are declared, checked, and traceable.
• Figures are rebuildable — analysis, plotting, diagrams, and assembly live behind the same project contract.
• Style is reusable — journal and presentation targets are selected through config instead of one-off plotting edits.
• Agents can inspect safely — the MCP server exposes read, render, and smoke surfaces for tool-assisted figure workflows.

Current State

The source checkout is a 0.20.0 release candidate. The latest published PyPI package, TestPyPI dry run, and GitHub Release asset remain at 0.19.0 until a separate release promotion is approved and run.

Install

For normal use:

python -m pip install figops

For a pinned, reproducible install:

python -m pip install figops==0.19.0

If you need the exact GitHub Release asset:

gh release download v0.19.0 --repo Moonweave-Research/figops --pattern "*.whl" --dir dist-release
python -m pip install dist-release/figops-0.19.0-py3-none-any.whl
figops-mcp --smoke

Quick start

For an installed package, verify the published CLI surface first:

figops --help
figops-mcp --smoke
figops-mcp doctor

For a source checkout, use hub_uv.py instead of bare uv run so the managed environment stays outside the repository:

python hub_uv.py sync
python hub_uv.py --print-env
python hub_uv.py run python figops_mcp_server.py --hub-path . --research-root . --runtime-root .omo/evidence/task-6-runtime doctor --json
python hub_uv.py run python figops_mcp_server.py doctor
python hub_uv.py run python -m pytest tests/test_doctor.py -q

If uv is not installed, the source-checkout path cannot bootstrap itself. Use an already prepared Python 3.12+ environment with the FigOps runtime/dev dependencies, or install uv outside the repository and rerun the wrapper commands. The JSON doctor output reports the active Python, uv on PATH, the resolved runtime root, and the planned external uv environment/cache paths. R is only required for projects that declare lang: R.

Create a new figure project:

figops --init --project my_figure_project
cd my_figure_project

That creates a scaffold with:

my_figure_project/
├── project_config.yaml
├── raw/
│   ├── example.csv
│   └── .raw_manifest.json
├── hub_scripts/
│   ├── analysis/analyze.R
│   ├── figures/
│   │   ├── plot.py
│   │   └── device_cross_section.py
│   └── shared/project_context.py
└── results/
    ├── data/{intermediate,source}/
    ├── tables/
    ├── figures/
    ├── evidence/
    └── publication/

The scaffold manifest records these durable role roots and explicitly marks runtime state as external and disposable. Scaffolding never creates runtime, cache, log, preview, or temporary directories inside the project.

Run the project:

figops --project . --step all

For a first sanity check, list the available CLI options:

figops --help

What FigOps does

A FigOps run coordinates the work around a research figure:

1. read project_config.yaml,
2. resolve declared input files,
3. validate data contracts and research-ops rules,
4. run analysis scripts when needed,
5. render figures, diagrams, or assembled panels,
6. apply the selected style profile,
7. write provenance and runtime metadata for auditability.

A minimal config looks like this:

project:
  name: "Example Study"

visual_style:
  target_format: nature
  font_scale: 1.0
  profile: baseline

pipeline:
  analysis:
    - script: "hub_scripts/analyze.R"
      lang: R
      cache: true

figures:
  - id: Fig1
    script: "hub_scripts/plot.py"
    output: "results/figures/Fig1.png"
    cache: true

R is only required when your configured analysis scripts use R. Python plotting and package/MCP smoke checks run from the Python package install.

Everyday commands

# Choose a configured project interactively
figops

# List configured projects
figops --list-projects

# Run the full pipeline for one project
figops --project "ProjectName" --step all

# Re-render figures only
figops --project "ProjectName" --step plot

# Re-render diagrams only
figops --project "ProjectName" --step diagrams

# Force a clean rerun and bypass cache
figops --project "ProjectName" --step all --force

From a source checkout, use the repo-local runtime wrapper:

python hub_uv.py sync
python hub_uv.py run python orchestrator.py --list-projects
python hub_uv.py run python -m pytest tests/test_runtime_paths.py -q

hub_uv.py keeps the Python runtime outside the repository so the working tree does not get polluted with local virtualenv state.

MCP for agents

FigOps includes a Model Context Protocol server entry point:

figops-mcp --smoke

A healthy smoke response looks like:

{"status": "ok", "health_status": "ok", "tool_surface": "figops_mcp"}

Use this before wiring FigOps into Claude, Codex, or another MCP-capable client. For compatibility with earlier local setups, graphhub-mcp remains available as an alias.

Migrating MCP discovery in 0.20.0

The launcher now returns the compact AI-native v2 profile from tools/list by default. Existing tool handlers and payload schemas were not removed. Clients that depend on the full pre-v2 list—including the frozen canonical tools and graphhub.* aliases—must explicitly select the compatibility surface profile. This opt-in preserves existing calls while keeping new-agent discovery small and evidence-first. Set GRAPH_HUB_MCP_SURFACE_PROFILE=compatibility in launcher configuration, or pass surface_profile="compatibility" when embedding FigOpsMCPServer. See docs/tools-v2.md and docs/tools-compatibility.md.

Projects outside the primary PROJECT_ROOT may be admitted explicitly with GRAPH_HUB_MCP_ALLOWED_PROJECT_ROOTS (a path-separated list), or by repeating --allowed-project-root on the MCP launcher. This includes NAS-backed research roots; the disposable MCP runtime root is intentionally never a project root.

Troubleshooting

For maintainers

Release candidates are checked with the packaging and test gates below:

uv build
python scripts/package_metadata_smoke.py
python scripts/public_package_surface.py
python scripts/consumer_install_smoke.py
uv run --with twine python -m twine check dist/*
python hub_uv.py run python -m pytest -q
python hub_uv.py run ruff check .

After release assets are uploaded, verify both the GitHub artifact and the public install path:

python scripts/github_release_asset_smoke.py
python -m pip install figops==0.19.0
figops-mcp --smoke

Publishing uses the manual Trusted Publishing workflow in .github/workflows/publish.yml: TestPyPI first, install smoke, then PyPI. See docs/packaging/trusted-publishing.md for the exact runbook.

Repository map

Next release checklist

For the next release, keep the same conservative path:

1. bump the version,
2. rebuild wheel/sdist from a clean tree,
3. confirm package artifacts exclude private docs/tests/research markers,
4. publish to TestPyPI through .github/workflows/publish.yml,
5. install-check from TestPyPI,
6. promote the same version to PyPI,
7. install-check from public PyPI.

License

FigOps is distributed under the Apache-2.0 license. See LICENSE and NOTICE.