Chinese (Simplified) · English
AI-Agent-Friendly MCP Server for FullProf — Rietveld Refinement & Powder Diffraction Analysis
FullProf-App-MCP wraps the classic powder diffraction Rietveld refinement suite FullProf as a standard MCP (Model Context Protocol) server, enabling AI agents and automated workflows to directly invoke Rietveld refinement, PCR editing, data conversion, phase searching, and more.
This repository combines the FullProfAPP sources (PyQt5 + crysfml Fortran, jointly developed by CIC energiGUNE, ICMAB-CSIC, ILL and ALBA Synchrotron) with an added headless MCP layer:
| Feature | Description |
|---|---|
| 🧩 MCP protocol service | Exposes 16 MCP tools + 4 prompts + 3 resources over stdio/SSE |
| 🤖 AI agent interface | AI can directly create PCRs, set parameters, run refinement, and diagnose results |
| ⚙️ Headless operation | PyQt5 GUI dependency removed; runs on pure Python |
| 🧪 Mock mode | Develop, test, and debug even without the FullProf binary |
| 🔍 Smart diagnostics | Automatic Rwp evaluation, error-pattern matching, fix suggestions |
AI Agent (Claude/Copilot)
│ MCP stdio/SSE
▼
┌────────────────────────────────┐ subprocess ┌────────────────────────────────┐
│ fullprof_mcp/ │ ─────────────────→ │ FullProf binary │
│ (MCP protocol + bridge + AI) │ │ (Fortran refinement engine) │
└────────────────────────────────┘ └────────────────────────────────┘
│
▼
┌────────────────────────────────┐
│ MOCK MODE (no FullProf) │
│ Simulated runs + dev tests │
└────────────────────────────────┘
FullProf-App-MCP/
├── src/ # MCP server & FullProfAPP libraries
│ ├── fpfunctions/ # 🟨 FullProfAPP core library
│ ├── fpgui/ # 🟨 PyQt5 GUI code
│ └── fullprof_mcp/ # 💚 MCP server (added in this repo)
│ ├── __init__.py # Version declaration
│ ├── __main__.py # CLI: status / server
│ ├── config.py # FullProf auto-detection + environment variables
│ ├── core/ # Core engine
│ │ ├── api.py # FullProfAPI — high-level AI abstraction interface
│ │ ├── models.py # Data structures: CellParams, RefineResult
│ │ ├── pcr_editor.py # 📄 Full PCR file read/write editing (no PyQt5)
│ │ ├── result_parser.py # 📊 .sum/.mic/.prf/.res parsing
│ │ ├── data_manager.py # 🔄 Format conversion (xye/xys/dat/raw/xrdml) + CIF
│ │ └── fullprof_bridge.py # 🔗 FullProf subprocess bridge + Mock
│ ├── server/mcp_server.py # FastMCP: 16 tools + 4 prompts + 3 resources
│ ├── ai/ # 🤖 AI enhancements
│ │ ├── params.py # Parameter recommendation engine
│ │ ├── diagnostics.py # Diagnostics engine (12+ error patterns)
│ │ └── reporter.py # Report generation (Markdown/HTML/JSON)
│ ├── install_fullprof.sh # FullProf installation script
│ └── tests/ # 🧪 Test suite (10 files)
├── Fortran-Utilities/ # 🔧 Auxiliary Fortran tools
├── Tests/ # 🧪 Upstream test data (EgyptMakeup / LiFePO4 / NMC111)
├── docs/ # 📚 Sphinx docs
├── examples/ # 📘 Examples
├── Documents/ Support-PDF-Documents/ # 📄 Reference materials
├── .mcp.json # MCP host config template
├── requirements.txt # Python dependencies
└── CHANGELOG.rst # Changelog
fullprof_mcp.server.mcp_server (FastMCP, entry point)
│
├── core/api.py (FullProfAPI) — Unified entry point for AI
│ ├── core/pcr_editor.py — PCR file read/write
│ ├── core/result_parser.py — Refinement result parsing
│ ├── core/data_manager.py — Data formats + CIF
│ └── core/fullprof_bridge.py — FullProf subprocess invocation
│ ├── FullProfBridge — Real bridge
│ └── MockFullProfBridge — Mock bridge
├── ai/params.py — Parameter recommendation
├── ai/diagnostics.py — Smart diagnostics
└── ai/reporter.py — Report generation
| Dependency | Purpose | Installation |
|---|---|---|
| Python 3.10+ | MCP server | apt install python3.11 |
| Python packages | MCP / numpy / scipy | pip install -r requirements.txt |
| FullProf | Refinement engine (optional) | Download from the ILL website |
| gfortran | FullProf compilation (optional) | System package manager |
git clone https://github.com/FullPatt/FullProf-App-MCP.git
cd FullProf-App-MCP
pip install -r requirements.txtCore dependencies:
mcp>=1.0.0— MCP protocol frameworknumpy>=1.25.0— Numerical computingscipy>=1.11.0— Peak finding, filtering, fittingfastnumbers>=3.2.0— Fast string→number conversionPyCifRW>=4.4.0— CIF file parsing
# Method A: use the installation script
chmod +x src/fullprof_mcp/install_fullprof.sh
./src/fullprof_mcp/install_fullprof.sh
# Method B: set the environment variable manually
export FULLPROF_HOME=/path/to/FullProf
# Method C: add to PATH
export PATH=$PATH:/path/to/FullProf/binpython -m fullprof_mcp statusExample of normal output:
FullProf-MCP Configuration
Platform: Linux
Python: 3.11.2
FullProf Home: /opt/fullprof
FullProf Binary: /opt/fullprof/bin/fullprof
FullProf Ready: Yes
FullProf-MCP v0.1.0
Dependencies:
✓ numpy ✓ scipy ✓ fastnumbers ✓ PyCifRW ✓ mcp
Even without FullProf, it can run in Mock mode:
python -m fullprof_mcp status
# FullProf Ready: No (Mock mode enabled automatically)# stdio mode (default, for Claude Desktop / Cursor / VS Code)
python -m fullprof_mcp server
# SSE HTTP mode (for remote access)
python -m fullprof_mcp server --transport sse --port 8910{
"mcpServers": {
"fullprof-mcp": {
"command": "python3",
"args": ["-m", "fullprof_mcp", "server"],
"cwd": "/path/to/FullProf-App-MCP"
}
}
}| Category | Tool | Description |
|---|---|---|
| Basics | get_status |
System status, version, FullProf availability |
read_pcr |
Read a PCR file and return structured JSON content | |
edit_pcr |
Modify PCR parameters (unit cell, atoms, background, flags) | |
create_pcr_from_cif |
Automatically create a PCR from CIF + data file + IRF | |
| Data processing | load_data |
Load diffraction data and return a summary (point count, 2θ range) |
convert_data |
Convert data file formats | |
detect_format |
Auto-detect the data format | |
find_peaks |
Automatic peak finding (position, intensity, d-spacing) | |
estimate_background |
Chebyshev polynomial background fitting | |
| Refinement | run_refinement |
Run FullProf Rietveld refinement |
get_results |
Parse results (Rwp, GOF, unit-cell parameters) | |
| Database | search_phase_cod |
Search the COD crystallography database |
read_cif |
Read a CIF and return unit cell / space group / atomic positions | |
| AI enhancements | auto_diagnose |
One-click diagnostics: Rwp evaluation + error matching + fix suggestions |
suggest_best_strategy |
Recommend an incremental refinement strategy | |
generate_report |
Generate a refinement report (Markdown/HTML/JSON) |
| Prompt | Function |
|---|---|
refine_xrd |
Guide the XRD Rietveld refinement workflow |
search_match |
Search-Match phase identification workflow |
full_refinement_workflow |
Full refinement pipeline (data→CIF→IRF→PCR→refinement→report) |
diagnose_refinement |
Guidance for diagnosing refinement results |
fullprof://status— System status JSONfullprof://pcr/{path}— PCR file content JSONfullprof://results/{workdir}— Refinement results JSON
import sys
sys.path.insert(0, "/path/to/FullProf-App-MCP/src")
from fullprof_mcp.core.api import FullProfAPI
api = FullProfAPI()
print(api.get_status())
# → {'fullprof': {'available': False}, 'mock_mode': True}
from fullprof_mcp.core.pcr_editor import PcrEditor
editor = PcrEditor("/path/to/pcr_dir", "jobname")
editor.read()
result = api.refine(editor)
print(f"Rwp={result.rwp}, GOF={result.gof}")FullProf is an open-source powder diffraction refinement software suite developed by Juan Rodríguez-Carvajal (ILL, Grenoble, France), written in FORTRAN 77/95.
| Capability | Description |
|---|---|
| Rietveld refinement | Whole-pattern fitting of powder diffraction, supporting multiple phases and multiple diffraction patterns |
| Le Bail fitting | Extract structure factors; peak-shape fitting without a structural model |
| Pawley fitting | Peak-shape fitting under constraints |
| Unit-cell parameter refinement | Precise determination of unit-cell parameters after indexing |
| Profile Matching | Diffraction pattern matching |
| Fourier synthesis | Fourier mapping of nuclear and magnetic scattering densities |
| Maximum Entropy Method (MEM) | Reconstruct scattering density with the maximum entropy method |
| Simulated annealing | Ab initio structure solution |
| Sequential refinement | Batch refinement of time-resolved / temperature-series data |
| Magnetic structure refinement | Simultaneous refinement of nuclear + magnetic structures (Shubnikov groups) |
Supported diffraction types: X-rays (laboratory sources, synchrotron radiation), neutrons (constant wavelength, TOF), electron diffraction
File Formats
- Input: PCR (
*.pcr), data (*.xye/*.xys/*.dat/*.raw/*.xrdml), instrument parameters (*.irf), CIF - Output:
*.sum(refinement log),*.prf(fitted data),*.mic(microstructure),*.res(results),*.fst(structure factors)
| Change | Path | Description |
|---|---|---|
| fullprof_mcp Python package | src/fullprof_mcp/ |
Complete MCP server |
| Headless design | — | PyQt5 / crysfml runtime dependencies removed |
| API abstraction layer | core/api.py |
FullProfAPI — unified entry point for AI |
| PCR editor | core/pcr_editor.py |
PCR read/write without PyQt5 dependency |
| Result parser | core/result_parser.py |
.sum / .mic / .prf / .res parsing |
| Data manager | core/data_manager.py |
Format conversion + CIF |
| FullProf bridge | core/fullprof_bridge.py |
Subprocess invocation + Mock mode |
| MCP server | server/mcp_server.py |
FastMCP: 16 tools / 4 prompts / 3 resources |
| AI diagnostics | ai/ |
Parameter recommendation, diagnostics engine, report generation |
| Test suite | tests/ |
10 test files |
cd /path/to/FullProf-App-MCP
# All tests
python -m pytest src/fullprof_mcp/tests/ -v| Test file |
|---|
test_ai.py |
test_api.py |
test_config.py |
test_data_manager.py |
test_fullprof_bridge.py |
test_mcp_server.py |
test_pcr_editor.py |
test_pcr_editor_phase2.py |
test_phase3.py |
test_result_parser.py |
# Verify no GUI dependencies
python -c "from fullprof_mcp.core.pcr_editor import PcrEditor; print('✅ Headless OK')"
python -c "from fullprof_mcp.core.api import FullProfAPI; print('✅ API OK')"
python -c "from fullprof_mcp.server.mcp_server import mcp; print('✅ MCP Server OK')"
# Confirm no PyQt5 contamination
grep -rn "PyQt5\|crysfml" src/fullprof_mcp/core/ src/fullprof_mcp/server/ || echo "✅ No GUI dependency leaks"| Stage | Component | Status |
|---|---|---|
| 1 | Core infrastructure (PcrEditor / ResultParser / DataManager) | ✅ |
| 2 | FullProf bridge (FullProfBridge + Mock) | ✅ |
| 3 | Data management (format conversion, CIF validation, peak finding, background) | ✅ |
| 4 | MCP server (FastMCP, 16 tools, resources, prompts) | ✅ |
| 5 | AI enhancements (parameter recommendation, diagnostics, report generation) | ✅ |
| 6 | COD online search integration | ✅ |
| — | Official release + documentation | 🔄 |
| Project | Description | Repository |
|---|---|---|
| Profex-MCP | Profex / BGMN XRD analysis and refinement MCP server | FullPatt/Profex-MCP |
| MAUD-MCP | MAUD combined diffraction analysis MCP server | FullPatt/MAUD-MCP |
| GSAS2-MCP | GSAS-II engine packaging (Rietveld refinement runtime foundation) | FullPatt/GSAS2-MCP |
GNU Affero General Public License v3.0 (AGPL-3.0)
The LICENSE file consists of the upstream FullProfAPP license header (Copyright (C) 2022 FullProfAPP's Authors) and the full text of GNU AGPL v3; the included FullProfAPP sources are governed by that license, and all upstream contributor copyrights are retained.
FullProf itself is developed and maintained by Juan Rodríguez-Carvajal (ILL), under its own distribution terms.
- Juan Rodríguez-Carvajal — FullProf author, Institut Laue-Langevin
- CIC energiGUNE, ICMAB-CSIC, ILL, ALBA Synchrotron — FullProfAPP joint development team
- EU Horizon 2020 — BATTERY 2030+ project funding (Grant No. 957189)
FullProf homepage: https://www.ill.eu/sites/fullprof/