xraylarch-mcp: Instructions file for Claude Code

CLAUDE.md — xraylarch-mcp Builder

Mission

Build a production-quality MCP (Model Context Protocol) server that wraps xraylarch (the headless X-ray spectroscopy analysis library) so that Claude can load, process, analyze, and plot X-ray spectra through natural tool calls. The package should be pip-installable and usable via Claude Desktop or Claude Code with zero configuration beyond pip install.

Repository

git remote: https://github.com/Joint-Photon-Sciences-Institute/xraylarch-mcp.git
branch: main

---

Phase 0: Probe xraylarch (DO THIS FIRST)

Before writing any MCP code, you must understand the xraylarch API by introspecting it directly. Do NOT rely on your training data — larch's API evolves and your knowledge may be stale.

0.1 Install xraylarch (headless)

pip install xraylarch
# Do NOT install GUI dependencies — we only need the computational core

0.2 Discover the API surface

Run Python introspection to catalog functions, their signatures, and docstrings. Focus on these critical modules:

import larch
from larch import Interpreter
session = Interpreter()

# Core I/O — discover all readers
import larch.io
# List all public functions: dir(larch.io)
# For each reader (read_ascii, read_xdi, read_athena, read_gsexdi, etc.):
#   - inspect.signature(func)
#   - func.__doc__

# XAFS analysis — the most important module
from larch.xafs import (
    pre_edge, autobk, xftf, xftr, xftf_fast,
    feffit, feffit_dataset, feffit_transform, feffpath,
    fluo_corr, over_absorption, mback, mback_norm,
    estimate_noise, pre_edge_baseline
)
# For each: get signature, docstring, required/optional params, defaults

# XRF analysis
from larch.xrf import xrf_background, xrf_calib_energy, xrf_calib_compute

# Fitting
from larch.fitting import param, param_group, guess, minimize, confidence_intervals

# XES (X-ray emission spectroscopy)  
# Check if larch.xes exists, catalog it

# Math/utilities
from larch.math import (
    index_of, index_nearest, interp, smooth, deriv,
    pca_train, pca_fit, nmf_train
)

# FEFF interface
from larch.xafs import feffpath, feffit, feffit_dataset, feffit_transform