champollion-sulcal-mcp

A FastMCP server wrapping the Champollion sulcal embedding pipeline — exposes each pipeline stage as an MCP tool so an agent can run, monitor, and debug the pipeline without shelling out manually.

Overview

This is a stdio MCP server (not a web service). It doesn't run the pipeline in-process — each start_* tool launches one of the pipeline's CLI scripts as a subprocess and tracks it as a background job (status + log file on disk), which callers poll until it reaches a terminal state.

Any MCP client can drive it. The repository also ships its own Claude Code subagent definition and skills, so it can be driven directly from Claude Code.

Related MCP server: dat-ai-mcp

How it works

1. A caller (an MCP client) invokes a tool such as start_cortical_tiles.

2. The tool validates its arguments (paths must be absolute), resolves the pipeline's script location via preflight.detect(), and builds an argv matching that script's real CLI.

3. runner.launch() spawns the script as a subprocess with an environment built by _build_env() (selectively passes HF_TOKEN, injects BRAINVISA_SHARE, prepends BrainVISA/pixi bins to PATH), and returns immediately with a job_id.

4. The subprocess's combined stdout/stderr is streamed line-by-line into a log file; progress lines matching fold N/M update the job's progress.

5. The caller polls get_job_status(output_dir, job_id) (and can tail get_job_log) until the job is succeeded, failed, or cancelled.

Pipeline stages

Project layout

src/champollion_sulcal_mcp/
├── server.py            # FastMCP instance, tool registration, entry point (main())
├── preflight.py          # locates the champollion_pipeline repo + its scripts/submodules
├── job_store.py           # JobState/JobProgress models, JSON job file persistence
├── runner.py               # subprocess launch, log capture, progress parsing, cancel
└── tools/
    ├── stages.py           # one start_<stage> tool per pipeline stage + maintenance tools
    ├── pipeline.py          # start_pipeline composite/umbrella job orchestration
    ├── jobs.py               # get_job_status, list_jobs, cancel_job, get_job_log
    └── utils.py               # get_pipeline_info, preflight_check
agents/
└── champollion-pipeline.md  # Claude Code subagent definition for this MCP server
skills/
├── run-pipeline/             # SKILL.md guiding pipeline runs and their parameters
├── monitor/                   # SKILL.md for the job-polling loop
└── debug/                      # SKILL.md + known error patterns for failure diagnosis
tests/                           # pytest suite with fake_pipeline_dir / recording_runner fixtures

MCP tools reference

Registered in server.py:

Stage launchers — start_morphologist, start_cortical_tiles, start_config, start_training, start_embeddings, start_combine, start_snapshots

Composite pipeline — start_pipeline

Maintenance — purge_subject (remove a subject's cortical_tiles derivatives), prune_failed_subjects (remove outputs for subjects that failed QC)

Job lifecycle — get_job_status, list_jobs, cancel_job, get_job_log

Utilities — get_pipeline_info (server/stage metadata), preflight_check (verify the pipeline is correctly configured and accessible)

Requirements

• Python 3.11 or 3.12

• pixi

• A checkout of the champollion_pipeline repository (not included here) — must contain the stage scripts under src/ (generate_morphologist_graphs.py, run_cortical_tiles.py, generate_champollion_config.py, generate_embeddings.py, put_together_embeddings.py, generate_snapshots.py, train_champollion.py) and the external/champollion_V1 and external/cortical_tiles submodules.

Installation

pixi install

Configuration

Running

This is a stdio server meant to be launched by an MCP client or coding agent (see Coding agents integration for ready-to-paste configurations), not run interactively on its own:

pixi run run                  # python -m champollion_sulcal_mcp.server
# or, once installed:
champollion-sulcal-mcp

Coding agents integration

Any coding agent or MCP client that can launch a local stdio server can use this server. Every configuration below starts it with pixi run --manifest-path /path/to/champollion_sulcal_mcp/pixi.toml run, so it works from any working directory. Replace the /path/to/... placeholders with absolute paths.

• CHAMPOLLION_PIPELINE_DIR is required: the absolute path of your champollion_pipeline checkout.

• HF_TOKEN is optional: set it only to download models from Hugging Face. Prefer an environment reference over writing the token in a configuration file, and never commit a token.

• The first start can take a few seconds while pixi resolves the environment, so the snippets raise the client's start-up timeout.

Claude Code

Register it with the CLI (user scope shown; --scope project writes a shared .mcp.json instead):

claude mcp add --transport stdio --scope user \
  --env CHAMPOLLION_PIPELINE_DIR=/path/to/champollion_pipeline \
  champollion-sulcal \
  -- pixi run --manifest-path /path/to/champollion_sulcal_mcp/pixi.toml run

or add it to .mcp.json at the root of your project:

{
  "mcpServers": {
    "champollion-sulcal": {
      "command": "pixi",
      "args": ["run", "--manifest-path", "/path/to/champollion_sulcal_mcp/pixi.toml", "run"],
      "env": {
        "CHAMPOLLION_PIPELINE_DIR": "/path/to/champollion_pipeline",
        "HF_TOKEN": "${HF_TOKEN:-}"
      }
    }
  }
}

This repository also ships Claude Code assets:

• agents/champollion-pipeline.md — a subagent scoped to exactly the MCP tools it needs, with an operational playbook: always preflight first, never guess paths, default output layout, per-stage required parameters, a known-error-pattern table, and the exact CLI invocation each tool wraps.

• skills/run-pipeline — guides choosing between the full pipeline and individual stages, and gathering the right parameters.

• skills/monitor — a poll-every-30-seconds monitoring loop with per-job-type progress reporting.

• skills/debug — systematic failure diagnosis: read the full log, match against known error patterns, report root cause and fix.

They are Markdown files: other coding agents can read them as plain instructions, for example by pointing their own agent or rules file at them.

OpenCode

In opencode.json (project) or ~/.config/opencode/opencode.json (global):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "champollion-sulcal": {
      "type": "local",
      "command": ["pixi", "run", "--manifest-path", "/path/to/champollion_sulcal_mcp/pixi.toml", "run"],
      "enabled": true,
      "timeout": 30000,
      "environment": {
        "CHAMPOLLION_PIPELINE_DIR": "/path/to/champollion_pipeline",
        "HF_TOKEN": "{env:HF_TOKEN}"
      }
    }
  }
}

Mistral Vibe

In ./.vibe/config.toml (project) or ~/.vibe/config.toml (global). Vibe does not expand environment variables in this file; add "HF_TOKEN" = "<your token>" to env only in a private, uncommitted config.

[[mcp_servers]]
name = "champollion-sulcal"
transport = "stdio"
command = "pixi"
args = ["run", "--manifest-path", "/path/to/champollion_sulcal_mcp/pixi.toml", "run"]
startup_timeout_sec = 60
env = { "CHAMPOLLION_PIPELINE_DIR" = "/path/to/champollion_pipeline" }

Codex

In ~/.codex/config.toml (global) or .codex/config.toml (trusted project); env_vars forwards HF_TOKEN from your shell without storing it in the file:

[mcp_servers.champollion-sulcal]
command = "pixi"
args = ["run", "--manifest-path", "/path/to/champollion_sulcal_mcp/pixi.toml", "run"]
startup_timeout_sec = 60
env_vars = ["HF_TOKEN"]

[mcp_servers.champollion-sulcal.env]
CHAMPOLLION_PIPELINE_DIR = "/path/to/champollion_pipeline"

or from the command line:

codex mcp add champollion-sulcal \
  --env CHAMPOLLION_PIPELINE_DIR=/path/to/champollion_pipeline \
  -- pixi run --manifest-path /path/to/champollion_sulcal_mcp/pixi.toml run

Other MCP clients

Most other clients (Claude Desktop, Cursor, and others) read the common mcpServers format, for example Claude Desktop's claude_desktop_config.json or Cursor's .cursor/mcp.json:

{
  "mcpServers": {
    "champollion-sulcal": {
      "command": "pixi",
      "args": ["run", "--manifest-path", "/path/to/champollion_sulcal_mcp/pixi.toml", "run"],
      "env": {
        "CHAMPOLLION_PIPELINE_DIR": "/path/to/champollion_pipeline"
      }
    }
  }
}

If your client has no env setting, export CHAMPOLLION_PIPELINE_DIR (and optionally HF_TOKEN) in the environment the client is started from.

Job tracking

Each job is persisted as <output_dir>/.mcp_jobs/<job_id>.json (atomic write) with its combined stdout/stderr log at <output_dir>/.mcp_jobs/<job_id>.log. Status lifecycle: pending → running → one of succeeded / failed / cancelled. start_pipeline additionally writes an "umbrella" job whose progress tracks current_stage / stages_done / stages_total and the currently active child job_id.

Testing

pixi run test           # full suite
pixi run test-unit        # unit-marked tests only
pixi run test-fast         # stop on first failure
pixi run test-cov           # with coverage report

tests/conftest.py provides fake_pipeline_dir (a temp dir with stub stage scripts and submodule folders) and recording_runner (stubs runner.launch to record calls instead of spawning real subprocesses), so most tool behavior can be tested without a real champollion_pipeline checkout.

Linting

pixi run lint        # ruff check
pixi run lint-fix      # ruff check --fix
pixi run format         # ruff format

Contributing

See CONTRIBUTING.md for the development setup, checks, branch model and how to report issues.

License

Released under the CeCILL-B free software licence, the same as champollion_pipeline. See LICENSE.