Skip to content
XinProfPublic
forked from luttero/maud

About

MAUD-MCP: AI-Agent-Friendly MCP server for MAUD — Combined diffraction analysis, Rietveld refinement, texture/stress/structure analysis

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

MAUD-MCP 🧪🤖

Chinese (Simplified) · English

AI-Agent-Friendly MCP Server for MAUD — Combined Analysis of Diffraction Data

License Python 3.10+ MCP Protocol Java 21+

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.


Purpose

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

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.

Architecture

AI Agent (Claude/Copilot)
        │ MCP stdio
        ▼
┌───────────────────────┐     subprocess     ┌───────────────────────┐
│   src/maud_mcp/       │ ─────────────────→  │  Maud.jar (Java)      │
│  (MCP protocol/bridge) │                     │  (Rietveld engine)     │
└───────────────────────┘                     └───────────────────────┘

Code Structure

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

Module Dependencies

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

Installation

⚠️ About the MAUD runtime

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

Prerequisites

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)

1️⃣ Get the code and Python dependencies

git clone https://github.com/FullPatt/MAUD-MCP.git
cd MAUD-MCP
pip install mcp>=1.0 numpy scipy PyCifRW

2️⃣ Install Java 21

wget -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 -version

3️⃣ Deploy Maud.jar

See "About the MAUD runtime" above.

4️⃣ Verify

python -m src.maud_mcp

Sample 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

5️⃣ Minimal run test

python -m src.maud_mcp --test-ins
# → ✅ INS executed successfully

Environment Variables

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

MCP Server Usage

Launch

python -m src.maud_mcp --server

Claude Desktop Config

{
  "mcpServers": {
    "maud-mcp": {
      "command": "python3",
      "args": ["-m", "src.maud_mcp", "--server"],
      "cwd": "/path/to/MAUD-MCP"
    }
  }
}

MCP tool list (12)

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() in server/mcp_server.py one by one. The parameter recommendation (params.py) and report generation (reporter.py) modules under ai/ are currently internal modules and not yet registered as standalone MCP tools.

Quick functional test

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 Capabilities

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
PDF 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.)


Changes vs Upstream

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.


Testing

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

Related Projects

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

License

BSD 3-Clause License (consistent with upstream MAUD)

This repository is a fork of luttero/maud; all copyrights of upstream contributors are retained.


Acknowledgements

  • 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

About

MAUD-MCP: AI-Agent-Friendly MCP server for MAUD — Combined diffraction analysis, Rietveld refinement, texture/stress/structure analysis

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages