Skip to content

About

FullProf-App-MCP: AI-Agent-Friendly MCP server for FullProf — Rietveld refinement, powder diffraction analysis, and MCP protocol integration

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

FullProf-App-MCP 🧪🦞

Chinese (Simplified) · English

AI-Agent-Friendly MCP Server for FullProf — Rietveld Refinement & Powder Diffraction Analysis

License Python 3.10+ MCP Protocol

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.


Purpose

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

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 runs + dev tests   │
└────────────────────────────────┘

Code Structure

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

Module Dependencies

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

Installation

Prerequisites

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

1️⃣ Get the Code and Dependencies

git clone https://github.com/FullPatt/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 computing
  • 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)

# 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/bin

3️⃣ Verify Installation

python -m fullprof_mcp status

Example 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)

MCP Server Usage

Launch

# 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

Claude Desktop Config

{
  "mcpServers": {
    "fullprof-mcp": {
      "command": "python3",
      "args": ["-m", "fullprof_mcp", "server"],
      "cwd": "/path/to/FullProf-App-MCP"
    }
  }
}

MCP Tool List (16)

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 Templates (4)

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

Resources (3)

  • fullprof://status — System status JSON
  • fullprof://pcr/{path} — PCR file content JSON
  • fullprof://results/{workdir} — Refinement results JSON

Quick Functional Test

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 Capabilities

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)

Changes vs Upstream

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

Testing

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"

Roadmap

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 🔄

Related Projects

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

License

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.


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/

About

FullProf-App-MCP: AI-Agent-Friendly MCP server for FullProf — Rietveld refinement, powder diffraction analysis, and MCP protocol integration

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages