Chinese (Simplified) · English
AI-Agent-Friendly MCP Server for MAUD — Combined Analysis of Diffraction Data
MAUD-MCP wraps MAUD as a standard MCP (Model Context Protocol) server, enabling AI agents and automated workflows to directly invoke Rietveld refinement, phase analysis, texture analysis, stress analysis, and more.
This repository is a MAUD fork + MCP wrapper. The Java sources stay as upstream; the MCP layer is a self-contained Python package that drives Maud.jar via subprocess.
| Feature | Description |
|---|---|
| 🧩 MCP protocol service | Exposes 12 MCP tools over stdio |
| 🤖 AI agent interface | AI can load data, create parameters, run calculations, and parse results directly |
| ☕ Java bridge | Calls Maud.jar via subprocess, with zero changes to Java sources |
| ⚙️ Headless operation | No MAUD GUI needed, command line only |
| 📄 PAR file editing | .par (CIF format) read/write, loop parsing, constraint editing |
| 🧪 Test coverage | 6 test files, 64 cases |
| 🔍 Smart diagnostics | Refinement quality assessment + parameter recommendations + report generation |
| Branch | |
|---|---|
| Default branch of this repository | version2 |
Default branch of upstream luttero/maud |
version3 |
The MCP layer is maintained on version2; the sync status with upstream is determined by the commit history.
AI Agent (Claude/Copilot)
│ MCP stdio
▼
┌───────────────────────┐ subprocess ┌───────────────────────┐
│ src/maud_mcp/ │ ─────────────────→ │ Maud.jar (Java) │
│ (MCP protocol/bridge) │ │ (Rietveld engine) │
└───────────────────────┘ └───────────────────────┘
MAUD-MCP/
├── src/ # MAUD Java sources + MCP server
│ ├── com/ # Core MAUD Java packages (76 .java files)
│ ├── ij/ gov/ org/ net/ fr/ it/ # ImageJ and other third-party Java dependency sources
│ ├── HTTPClient/ Jama/ gl4java/ ... # Other upstream dependency sources
│ └── maud_mcp/ # 💚 MCP server (added in this fork)
│ ├── __init__.py # Version declaration
│ ├── __main__.py # CLI: status / validate / test-ins / server
│ ├── config.py # Engine auto-detection (MAUD_HOME / JAVA_HOME)
│ ├── exceptions.py # Custom exceptions
│ ├── core/ # Core engine
│ │ ├── java_bridge.py # ☕ Java subprocess bridge
│ │ ├── par_editor.py # 📄 .par (CIF format) reader/writer
│ │ ├── data_manager.py # 🔄 Data format conversion + CIF parsing
│ │ └── result_parser.py # 📊 Result parsing (Rwp / GOF / unit cell)
│ ├── server/mcp_server.py # MCP protocol layer (12 tools)
│ ├── ai/ # 🤖 Parameter recommendations / diagnostics / reports
│ ├── tests/ # 🧪 6 test files (64 cases)
│ └── _legacy/ # Backup of the legacy implementation
├── libs/ # Upstream Java dependency JARs (build time)
├── ImageJ/ media/ docs/ # Upstream resources
├── build.xml # 🏗️ Ant build config
├── Maud.iml / Maud.ipr / Maud.iws # IntelliJ IDEA project files
└── ant_maud_v2.properties # Ant build properties
maud_mcp (Python MCP Server)
│
├── core/java_bridge.py — subprocess call to Maud.jar
├── core/par_editor.py — Parse/edit .par (CIF format) parameter files
├── core/data_manager.py — Diffraction data format conversion + CIF parsing
├── core/result_parser.py — Parse MAUD stdout and .par results
├── server/mcp_server.py — FastMCP server (12 tools)
└── ai/ — Parameter recommendations, diagnostics, report generation
This repository does not include Maud.jar. libs/ contains the third-party dependency JARs needed to build upstream MAUD, not MAUD itself. Prepare the runtime yourself before running the MCP server:
# Method A: download the upstream prebuilt package
wget https://github.com/luttero/maud/releases/download/v2.99993/maud.zip
unzip maud.zip -d maud_runtime/ # Expected layout: maud_runtime/lib/Maud.jar
# Method B: build it yourself (requires Apache Ant + JDK 21)
ant -buildfile build.xml jar
cp build/Maud.jar maud_runtime/lib/The MCP server locates MAUD in the following priority order (see src/maud_mcp/config.py):
| Priority | Source |
|---|---|
| 1 | Environment variable MAUD_HOME |
| 2 | <repo>/maud_runtime/lib/Maud.jar |
| 3 | ~/maud_runtime/lib/Maud.jar |
| 4 | <cwd>/maud_runtime/lib/Maud.jar |
| Dependency | Purpose | How to install |
|---|---|---|
| Java 21+ | Run the MAUD engine | Adoptium Temurin |
| Python 3.10+ | MCP server | apt install python3.11 |
| Python packages | MCP / numpy / scipy | pip install mcp>=1.0 numpy scipy PyCifRW |
| Maud.jar | Rietveld refinement engine | See above (obtain it yourself) |
git clone https://github.com/FullPatt/MAUD-MCP.git
cd MAUD-MCP
pip install mcp>=1.0 numpy scipy PyCifRWwget -qO- https://github.com/adoptium/temurin21-binaries/releases/latest/download/OpenJDK21U-jdk_x64_linux_hotspot_21.0.6_7.tar.gz | tar xz
export JAVA_HOME=$(pwd)/jdk-21.0.6+7
export PATH=$JAVA_HOME/bin:$PATH
java -versionSee "About the MAUD runtime" above.
python -m src.maud_mcpSample output:
=== MAUD Engine Status ===
Status: ✅ ready
Maud.jar: /path/to/MAUD-MCP/maud_runtime/lib/Maud.jar
Exists: ✅
Java: /path/to/jdk-21.0.6+7/bin/java
Exists: ✅
Version: 21.0.6
Platform: Linux
python -m src.maud_mcp --test-ins
# → ✅ INS executed successfully| Variable | Description | Default |
|---|---|---|
MAUD_HOME |
MAUD installation directory (containing lib/Maud.jar) |
Auto-detected |
MAUD_JAVA_HOME |
JDK installation directory | Auto-detected |
MAUD_WORK_DIR |
Working directory | /tmp/maud_work |
MAUD_MAX_MEM |
Maximum Java heap size | 2g |
MAUD_TIMEOUT |
Refinement timeout (seconds) | 180 |
MAUD_LOG_LEVEL |
Log level | INFO |
python -m src.maud_mcp --server{
"mcpServers": {
"maud-mcp": {
"command": "python3",
"args": ["-m", "src.maud_mcp", "--server"],
"cwd": "/path/to/MAUD-MCP"
}
}
}| Category | Tool | Function |
|---|---|---|
| System | get_status |
MAUD engine status, Java version, JAR path |
| Data | load_data |
Load diffraction data and return a summary (points, range, format) |
convert_data |
Convert data format (→ .xye / .dat / .raw) | |
data_stats |
Data statistics histogram | |
| PAR editing | read_par |
Read .par files and return structured CIF JSON |
edit_par |
Modify .par parameters (unit cell, atoms, iterations, title) | |
import_cif |
Generate .par files from CIF | |
generate_ins |
Automatically generate INS control files from data + CIF | |
| Refinement | refine |
Run MAUD Rietveld refinement |
compute |
Simulation calculation (0 iterations) | |
get_results |
Parse refinement results (Rwp, GOF, cell parameters) | |
| Diagnostics | diagnose |
Analyze refinement logs and give diagnoses and fix suggestions |
The table above matches the 12 tools registered with
@mcp.tool()inserver/mcp_server.pyone by one. The parameter recommendation (params.py) and report generation (reporter.py) modules underai/are currently internal modules and not yet registered as standalone MCP tools.
import sys
sys.path.insert(0, "/path/to/MAUD-MCP/src")
from maud_mcp.core.java_bridge import JavaBridge
bridge = JavaBridge()
status = bridge.get_status()
print(f"MAUD ready: {status['status']}")
result = bridge.run_ins("""
_riet_analysis_iteration_number 0
""")
print(f"SUCCESS: {result.success}")MAUD (Materials Analysis Using Diffraction) is an open-source Java combined diffraction analysis program developed by Luca Lutterotti (University of Trento).
| Category | Determinable parameters |
|---|---|
| Crystal structure | Lattice parameters, atomic coordinates, occupancies, temperature factors |
| Microstructure | Crystallite size, microstrain distribution, stacking faults, dislocation density |
| Texture (ODF) | WIMV/EWIMV/harmonic/standard function methods, MTEX integration |
| Residual stress | Macroscopic stress tensor, triaxial stress, EPSC model |
| Phase quantification | Crystalline + amorphous phase mass/volume fractions |
| Chemical composition | XRF / EDXRF / TXRF elemental analysis |
| Reflectometry | Film thickness, density, roughness (Parrat / matrix method) |
| Structure solution | Genetic algorithm, simulated annealing, reverse Monte Carlo, Charge Flipping |
| Pair distribution function export | |
| Electron density maps | 3D Fourier / MEM reconstruction |
Radiation sources: X-rays (Cu/Co/Cr/Mo/Fe/Ag/Ga…), synchrotron radiation, neutrons (constant wavelength ILL / TOF LANSCE·HIPPO·ISIS GEM), electron diffraction
Geometry: Bragg-Brentano, Debye-Scherrer, flat-plate IP, CPS detector, TOF multi-bank, Laue transmission, reflectometry
Data formats: 60+ (Bruker/Siemens UXD·RAW, Philips XRDML, Rigaku, GSAS, FullProf, CIF, TIFF, HDF5, ILL D1B/D20/D19, HIPPO, INEL, MDI, etc.)
| Change | Path | Description |
|---|---|---|
| maud_mcp Python package | src/maud_mcp/ |
Complete MCP server (core / server / ai / tests) |
| Java bridge | core/java_bridge.py |
subprocess call to Maud.jar |
| PAR editor | core/par_editor.py |
Parse and edit CIF-format .par files |
| Data manager | core/data_manager.py |
Format conversion + CIF parsing |
| Result parser | core/result_parser.py |
Rwp / GOF / cell parameter extraction |
| AI modules | ai/ |
Parameter recommendations, diagnostics, report generation |
| MCP server | server/mcp_server.py |
12 MCP tools |
| Test suite | tests/ |
6 files, 64 cases |
| Legacy implementation | _legacy/ |
Backups of the early maud_api.py / maud_mcp_server.py |
Java sources,
libs/,ImageJ/,build.xml, etc. are all kept as upstream, unmodified.
cd /path/to/MAUD-MCP
python -m pytest src/maud_mcp/tests/ -v| Test file | Cases |
|---|---|
test_java_bridge.py |
7 |
test_par_editor.py |
13 |
test_result_parser.py |
10 |
test_data_manager.py |
8 |
test_mcp_server.py |
11 |
test_ai_modules.py |
15 |
| Total | 64 |
| Project | Description | Repository |
|---|---|---|
| Profex-MCP | Profex / BGMN XRD analysis and refinement MCP server | FullPatt/Profex-MCP |
| FullProf-App-MCP | FullProf Rietveld refinement MCP server | FullPatt/FullProf-App-MCP |
| GSAS2-MCP | GSAS-II engine packaging (Rietveld refinement runtime foundation) | FullPatt/GSAS2-MCP |
BSD 3-Clause License (consistent with upstream MAUD)
This repository is a fork of luttero/maud; all copyrights of upstream contributors are retained.
- Luca Lutterotti — MAUD author, University of Trento
- Advanced Photon Source / Argonne National Lab — GSAS-II development team
- Bruker AXS / Rigaku / PANalytical — XRD data format standards
MAUD homepage: https://maud.radiographema.com MAUD upstream repository: https://github.com/luttero/maud