English | 简体中文

heps-saxs-mcp

MCP server for 1D SAXS data analysis at the HEPS pink-beam small-angle scattering beamline. It turns "reference-literature methods + 1D SAXS data → standardized analysis results" into a conversational tool suite of 22 saxs_* / make_plots MCP tools, mountable by any Model Context Protocol client (TRAE, Claude Desktop, etc.).

Design principles: 100% of the analysis runs through MCP tools; critical parameters follow "better an error than a guess"; every fit automatically passes the L3 quality gate; every conclusion carries a mandatory reliability grade — the AI orchestrates the analysis but never makes the physics calls for the user.

Feature Overview

Core disciplines (built into tool contracts, not left to good intentions):

• q_unit must be explicit (A^-1 / nm^-1) — the system never guesses units;

• The default fit window is the full data range; saxs_suggest_window produces an evidence card (low-q direct-beam / high-q noise flags) and the window is used only after user confirmation;

• Every fit automatically runs the L3 quality gate: bound-hit / exploded-perr / normalized three-tier grading + χ²/dof attention flag;

• Once a work directory is confirmed, all outputs go to <workdir>/HEPS_SAXS_analysis/ — never the user's data root;

• Data files larger than 1 MB are rejected on ingest (protects the shared host from accidental 2D frames); the saxs_probe_curve diagnostic channel is unlimited;

• Three-zone model management: validated (passed verification gate) / candidates (explicit user consent required) / model_inbox (submission inbox, rejected by fitting tools).

Related MCP server: RELION MCP Server

Installation

1. conda environment (one-time)

conda create -p E:\CondaEnvs\saxsagent python=3.11 -y
E:\CondaEnvs\saxsagent\python.exe -m pip install -r requirements.txt
# Optional: official shape bridge (sphere / cylinder / core_shell_* — 8 external models)
E:\CondaEnvs\saxsagent\python.exe -m pip install "sasmodels>=1.1"

Dependencies: mcp>=1.0,<2 (must stay <2; 2.x renamed FastMCP and is incompatible), numpy, scipy, matplotlib.

2. Configure mcp.json (three placeholders)

Copy the repo-root mcp.json into your MCP client configuration (TRAE user-level %APPDATA%\Trae CN\User\mcp.json or project-level .trae/mcp.json) and replace:

Keep START_MCP_TIMEOUT_MS=60000 — conda environments start slower than the client default timeout; without it you get the silent "green check in the panel but no tools in the session" failure. Alternatively skip mcp.json and run saxs_mcp\run_server.bat directly (reads the SAXSAGENT_ENV environment variable, falling back to E:\CondaEnvs\saxsagent).

3. Verify

Restart the client and invoke saxs_selftest in a conversation — ok=true means deployed.

Quick Start

Data preparation: 1D SAXS curve (3 columns q I σ, whitespace-separated; use saxs_probe_curve first for variant formats). Conversation examples:

[Full analysis]  E:\data\liposome_A.txt, q_unit=nm^-1, liposome_membrane nopeg mode
[Curve restore]  E:\data\1.dat, x_semantic=q, x_unit=pixel, column 1
[Orientation]    E:\data\YR8_filled_book.dat, phi/deg, q_unit=nm^-1
[Multi-start]    verify global optimum of last nopeg fit, tau_t

The agent first replies with a four-element confirmation card (data path / q_unit / fit window = suggestion card / work directory); after confirmation it orchestrates: health check → window suggestion → fit (auto quality gate) → triple plot → 4-file report package (<mode>_分析报告.md / _参数表.csv / _拟合曲线.csv / _result.json).

Model Library (13 plugin models + 8 sasmodels bridges at release)

New models go through the intake flow: drop the three-piece plugin into model_inbox/<model>/ → verification gate → validated; see model_inbox/README.md.

Tests & Regression

• saxs_selftest: synthetic smoke tests for restoration/orientation/fitting engines + contract checks for all models (21 models, every mode);

• test_data/: liposome two-sample acceptance data, 7-dimension format-variant fixtures, Ruland L1 suite;

• baseline/: regression baselines — after refactors or engine swaps, results must be bit-identical to regression_baseline.json (cross-process 1-ULP parameter noise is adjudicated by the 1e-12 relative tolerance; see notes inside baseline/).

Project Layout

├── saxs_mcp/            # MCP server (14 modules, model-agnostic, plugin-based loading)
├── model_library/       # validated / candidate model plugins
├── model_inbox/         # model submission inbox
├── agent_prompts/       # agent orchestration SOP / user keyword library / capability report / lessons
├── test_data/           # acceptance & regression test data
├── baseline/            # regression baselines
├── mcp.json             # MCP client onboarding template (three placeholders)
└── requirements.txt

Scope & Boundaries

• 1D SAXS only (2D / GISAXS out of scope; orientation analysis consumes azimuthally integrated curves I(q_c, φ) produced by the beamline pyFAI pipeline);

• Custom physical models outside the library must go through the intake flow — the tools never invent models on the fly;

• No OCR for scanned PDFs (saxs_doc_extract reports empty_text honestly).

Acknowledgments

Methodology anchored to: Schilt 2016 (lipid membrane), Tsao 2013 (Al–Cu precipitates), Beaucage (unified), Hammouda 2010 (Guinier–Porod), Thünemann & Ruland 2000 (orientation), Teubner–Strey, and the sasmodels/SASview community — full anchors in each manifest.json.

License

MIT © 2026 chenrc