Content
# FullProf-App-MCP
**AI-Agent-Friendly MCP Server for FullProf — Rietveld Refinement & Powder Diffraction Analysis**
[](LICENSE)
[]()
[](https://modelcontextprotocol.io)
FullProf-App-MCP wraps the classic powder diffraction Rietveld refinement suite [FullProf](https://www.ill.eu/sites/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.
## Purpose
This repository is a **FullProfAPP fork + MCP wrapper**. FullProfAPP was jointly developed by CIC energiGUNE, ICMAB-CSIC, ILL, and ALBA Synchrotron, providing a PyQt5 + crysfml Fortran-based graphical Rietveld refinement tool. This fork makes fundamental changes:
| Feature | Description |
|------|------|
| 🧩 **MCP Protocol Service** | Exposes 16+ FullProf operations as MCP tools via stdio/SSE |
| 🤖 **AI Agent Interface** | AI can directly create PCR, set parameters, execute refinement, and diagnose results |
| ⚙️ **Headless Operation** | Stripped of all PyQt5 GUI dependencies, runs in pure Python |
| 🧪 **Mock Mode** | Allows development, testing, and debugging without FullProf binary |
| 🔍 **Intelligent Diagnostics** | Automatic Rwp assessment, error pattern matching, and repair suggestions |
### Architecture
```
AI Agent (Claude/Copilot)
│ MCP stdio/SSE
▼
┌──────────────────────────┐ subprocess ┌─────────────────────┐
│ fullprof_mcp/ │ ─────────────────→ │ FullProf binary │
│ (MCP Protocol + Bridge + AI) │ │ (Fortran Refinement Engine) │
└──────────────────────────┘ └─────────────────────┘
│
▼
┌──────────────────────────┐
│ MOCK MODE (No FullProf) │
│ Simulated Execution + Development Testing │
└──────────────────────────┘
```
## Code Structure
```
FullProf-App-MCP/
├── src/ # MCP Server & FullProf Library
│ ├── fpfunctions/ # 🟨 FullProfAPP Core Library (unchanged)
│ ├── fpgui/ # 🟨 PyQt5 GUI Code (unchanged)
│ └── fullprof_mcp/ # 💚 MCP Server (this fork's additions)
│ ├── __init__.py # Version Declaration (v0.1.0)
│ ├── __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 # 📄 PCR File Complete Read/Write/Edit (without PyQt5)
│ │ ├── result_parser.py # 📊 .sum/.mic/.prf/.res Parsing
│ │ ├── data_manager.py # 🔄 Data Format Conversion (xye/xys/dat/raw/xrdml) + CIF
│ │ └── fullprof_bridge.py # 🔗 FullProf Subprocess Bridge + Mock
│ ├── server/ # MCP Protocol Layer
│ │ └── mcp_server.py # FastMCP: 16+ Tools + Resources + Prompts
│ ├── ai/ # 🤖 AI Enhancement Modules
│ │ ├── params.py # Parameter Recommendation Engine
│ │ ├── diagnostics.py # Diagnostic Engine (12+ Error Patterns)
│ │ └── reporter.py # Report Generation (Markdown/HTML/JSON)
│ ├── install_fullprof.sh # FullProf Installation Script
│ └── tests/ # 🧪 Test Suite (10+ files)
│ ├── test_pcr_editor.py # PCR Read/Write Tests
│ ├── test_api.py # FullProfAPI Tests
│ ├── test_mcp_server.py # MCP Protocol Tests
│ └── ...
├── Fortran-Utilities/ # 🔧 Auxiliary Fortran Tools
├── Tests/ # 🧪 Upstream Test Data (EgyptMakeup, LiFePO4, NMC111)
├── docs/ # 📚 Sphinx Documentation
├── .mcp.json # MCP Host Configuration Template
├── requirements.txt # Python Dependencies
└── CHANGELOG.rst # Change Log
```
### Module Dependencies
```
fullprof_mcp.server.mcp_server (FastMCP, entry point)
│
├── core/api.py (FullProfAPI) — Unified AI Interface
│ ├── core/pcr_editor.py — PCR File Read/Write
│ ├── core/result_parser.py — Refinement Result Parsing
│ ├── core/data_manager.py — Data Format + CIF
│ └── core/fullprof_bridge.py — FullProf Subprocess Call
│ ├── FullProfBridge — Real Bridge
│ └── MockFullProfBridge — Mock Bridge
├── ai/params.py — Parameter Recommendation
├── ai/diagnostics.py — Intelligent Diagnostics
└── ai/reporter.py — Report Generation
```
## Installation
### Prerequisites
| Dependency | Purpose | Installation Method |
|------|------|----------|
| **Python 3.10+** | MCP Server | `apt install python3.11` |
| Python Package | MCP/numpy/scipy | `pip install -r requirements.txt` |
| **FullProf** | Refinement Engine (optional) | Download from ILL website |
| **gfortran** | FullProf Compilation (optional) | System Package Manager |
### 1️⃣ Install Python Dependencies
```bash
git clone https://github.com/XRDFPSR/FullProf-App-MCP.git
cd FullProf-App-MCP
pip install -r requirements.txt
```
Core dependencies:
- `mcp>=1.0.0` — MCP Protocol Framework
- `numpy>=1.25.0` — Numerical Computation
- `scipy>=1.11.0` — Peak Finding, Filtering, Fitting
- `fastnumbers>=3.2.0` — Fast String→Number Conversion
- `PyCifRW>=4.4.0` — CIF File Parsing
### 2️⃣ Install FullProf (optional — for actual refinement)
```bash
# Method A: Use installation script
chmod +x src/fullprof_mcp/install_fullprof.sh
./src/fullprof_mcp/install_fullprof.sh
# Method B: Manual environment variable setup
export FULLPROF_HOME=/path/to/FullProf
# Method C: Add to PATH
export PATH=$PATH:/path/to/FullProf/bin
```
### 3️⃣ Verify Installation
```bash
python -m fullprof_mcp status
```
Example 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, you can run in Mock mode:
```bash
python -m fullprof_mcp status
# FullProf Ready: No (automatically enables Mock mode)
```
## MCP Server Usage
### Start Server
```bash
# 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
```
### MCP Host Configuration / Claude Desktop Config
```json
{
"mcpServers": {
"fullprof-mcp": {
"command": "python3",
"args": ["-m", "fullprof_mcp", "server"],
"cwd": "/path/to/FullProf-App-MCP"
}
}
}
```
### MCP Tool List (16+ tools)
| Category | Tool | Function |
|------|------|------|
| **Basic Tools** | `get_status` | Get system status, version, FullProf availability |
| | `read_pcr` | Read PCR file, return JSON structured content |
| | `edit_pcr` | Modify PCR parameters (cell, atoms, background, flags) |
| | `create_pcr_from_cif` | Automatically create PCR from CIF + data file + IRF |
| **Data Processing** | `load_data` | Load diffraction data, return summary (number of points, 2θ range) |
| | `convert_data` | Convert data file formats |
| | `detect_format` | Automatically detect data format |
| | `find_peaks` | Automatic peak finding (position, intensity, d-spacing) |
| | `estimate_background` | Chebyshev polynomial fitting of background |
| **Refinement Execution** | `run_refinement` | Execute FullProf Rietveld refinement |
| | `get_results` | Parse results (Rwp, GOF, cell parameters) |
| **Database** | `search_phase_cod` | Search COD crystallography database |
| | `read_cif` | Read CIF, return cell/space group/atom positions |
| **AI Enhancement** | `auto_diagnose` | One-click diagnosis: Rwp assessment + error matching + repair suggestions |
| | `suggest_best_strategy` | Recommend incremental refinement strategy |
| | `generate_report` | Generate refinement report (Markdown/HTML/JSON) |
### Prompt Templates / Prompts
| Prompt | Function |
|--------|------|
| `refine_xrd` | Guide XRD Rietveld refinement workflow |
| `search_match` | Search-Match phase identification workflow |
| `full_refinement_workflow` | Complete refinement pipeline (data→CIF→IRF→PCR→refinement→report) |
| `diagnose_refinement` | Refinement result diagnosis guide |
### Resource Protocol / Resource Protocol
- `fullprof://status` — System status JSON
- `fullprof://pcr/{path}` — PCR file content JSON
- `fullprof://results/{workdir}` — Refinement result JSON
### Quick Functional Test
```python
import sys, os
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}
# Run refinement in Mock mode
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 Capabilities Overview
[FullProf](https://www.ill.eu/sites/fullprof/) is an open-source powder diffraction refinement software suite developed by **Juan Rodríguez-Carvajal** (ILL, Grenoble, France), written in FORTRAN 77/95.
### Core Features
| Feature | Description |
|------|------|
| **Rietveld Refinement** | Powder diffraction full-spectrum fitting, supporting multi-phase multi-pattern |
| **Le Bail Fitting** | Extract structure factors, peak shape fitting without structural model |
| **Pawley Fitting** | Constrained peak shape fitting |
| **Cell Parameter Refinement** | Precise determination of cell parameters after indexing |
| **Profile Matching** | Diffraction pattern matching |
| **Fourier Synthesis** | Calculation of nuclear and magnetic scattering density Fourier maps |
| **Maximum Entropy Method (MEM)** | Maximum entropy method for scattering density reconstruction |
| **Simulated Annealing** | _Ab initio_ structural solution |
| **Sequential Refinement** | Batch refinement of time-resolved/temperature-resolved data |
| **Magnetic Structure Refinement** | Simultaneous refinement of nuclear and magnetic structures (Shubnikov groups) |
### Supported Diffraction Types
- X-ray (lab X-ray sources, synchrotron)
- Neutron (constant wavelength, time-of-flight 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 Factor)
## Changes vs Upstream
| Change | Path | Description |
|------|------|------|
| fullprof_mcp Python Package | `src/fullprof_mcp/` | Complete MCP Server |
| Headless Design | — | Stripped all PyQt5/crysfml dependencies |
| API Abstraction Layer | `core/api.py` | FullProfAPI — Unified Entry for AI |
| PCR Editor | `core/pcr_editor.py` | PyQt5-free PCR Read/Write (1700+ lines) |
| Result Parser | `core/result_parser.py` | .sum/.mic/.prf/.res Parsing (900+ lines) |
| Data Manager | `core/data_manager.py` | Format Conversion + CIF (1000+ lines) |
| FullProf Bridge | `core/fullprof_bridge.py` | Subprocess Call + Mock Mode |
| MCP Server | `server/mcp_server.py` | FastMCP: 16+ Tools |
| AI Diagnosis | `ai/` | Parameter Recommendation, Diagnosis Engine, Report Generation |
| Test Suite | `tests/` | 10+ Test Files |
| Renaming | — | fullprof-app → FullProf-App-MCP |
## Testing
```bash
cd /path/to/FullProf-App-MCP
# All Tests
python -m pytest src/fullprof_mcp/tests/ -v
# By Module
python -m pytest src/fullprof_mcp/tests/test_pcr_editor.py -v
python -m pytest src/fullprof_mcp/tests/test_api.py -v
python -m pytest src/fullprof_mcp/tests/test_mcp_server.py -v
# 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 Leaks
grep -rn "PyQt5\|crysfml" src/fullprof_mcp/core/ src/fullprof_mcp/server/ || echo "✅ No GUI dependency leaks"
```
## Development
### Code Inspection
```bash
# Syntax Check
python -m py_compile src/fullprof_mcp/core/pcr_editor.py
```
### Roadmap
| Phase | 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 Enhancement (Parameter Recommendation, Diagnosis, Report Generation) | ✅ |
| 6 | COD Online Search Integration | ✅ |
| — | Official Release + Documentation | 🔄 |
## Related Projects
| Project | Description | Repository |
|------|------|------|
| **GSAS2-MCP** | GSAS-II Rietveld Refinement MCP Server | [XRDFPSR/GSAS2-MCP](https://github.com/XRDFPSR/GSAS2-MCP) |
| **Profex-MCP** | Profex/BGMN XRD Analysis MCP Server | [XRDFPSR/Profex-MCP](https://github.com/XRDFPSR/Profex-MCP) |
| **MAUD-MCP** | MAUD Combined Diffraction Analysis MCP Server | [XRDFPSR/MAUD-MCP](https://github.com/XRDFPSR/MAUD-MCP) |
## License
**GNU General Public License v3.0 (GPL-3.0)**
This repository is a fork of [FullProfAPP](https://github.com/XRDFPSR/fullprof-app) (GPLv3), retaining all upstream contributors' copyrights. FullProf was developed and maintained by Juan Rodríguez-Carvajal (ILL).
## Acknowledgements
- **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/*
*FullProfAPP Upstream: https://github.com/XRDFPSR/fullprof-app*
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available