FullProf-App-MCP 🧪🦞

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

FullProf-App-MCP 将经典的粉末衍射 Rietveld 精修软件 FullProf 封装为标准的 MCP (Model Context Protocol) 服务器，使 AI 智能体（Claude、Copilot、Cursor 等）和自动化工作流可以直接调用 Rietveld 精修、PCR 编辑、数据转换、物相检索等全部功能。

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

本仓库是 FullProfAPP 的 fork + MCP 包装。FullProfAPP 由 CIC energiGUNE、ICMAB-CSIC、ILL 和 ALBA Synchrotron 联合开发，提供了一套基于 PyQt5 + crysfml Fortran 的图形化 Rietveld 精修工具。本 fork 在此基础上做了根本性改动：

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:

特性	说明
🧩 MCP 协议服务	通过 stdio/SSE 将 16+ FullProf 操作暴露为 MCP 工具
🤖 AI 智能体接口	AI 可直接创建 PCR、设置参数、执行精修、诊断结果
⚙️ Headless 运行	剥离所有 PyQt5 GUI 依赖，纯 Python 可运行
🧪 Mock 模式	无 FullProf 二进制时也可以开发、测试和调试
🔍 智能诊断	自动 Rwp 评估、错误模式匹配、修复建议

架构 / Architecture

AI Agent (Claude/Copilot)
        │ MCP stdio/SSE
        ▼
┌──────────────────────────┐     subprocess     ┌─────────────────────┐
│   fullprof_mcp/          │ ─────────────────→  │  FullProf binary    │
│   (MCP 协议 + 桥接 + AI)  │                    │  (Fortran 精修引擎)   │
└──────────────────────────┘                    └─────────────────────┘
        │
        ▼
┌──────────────────────────┐
│   MOCK MODE (无 FullProf) │
│   模拟运行 + 开发测试     │
└──────────────────────────┘

代码结构 / Code Structure

FullProf-App-MCP/
├── src/                                    # MCP 服务器 & FullProf 库
│   ├── fpfunctions/                        # 🟨 FullProfAPP 核心库 (未修改)
│   ├── fpgui/                              # 🟨 PyQt5 GUI 代码 (未修改)
│   └── fullprof_mcp/                       # 💚 MCP 服务器 (本 fork 新增)
│       ├── __init__.py                     #    版本声明 (v0.1.0)
│       ├── __main__.py                     #    CLI: status / server
│       ├── config.py                       #    FullProf 自动检测 + 环境变量
│       ├── core/                           #    核心引擎
│       │   ├── api.py                      #    FullProfAPI — 高层 AI 抽象接口
│       │   ├── models.py                   #    数据结构: CellParams, RefineResult
│       │   ├── pcr_editor.py               #    📄 PCR 文件完整读写编辑 (无 PyQt5)
│       │   ├── result_parser.py            #    📊 .sum/.mic/.prf/.res 解析
│       │   ├── data_manager.py             #    🔄 数据格式转换 (xye/xys/dat/raw/xrdml) + CIF
│       │   └── fullprof_bridge.py          #    🔗 FullProf 子进程桥接 + Mock
│       ├── server/                         #    MCP 协议层
│       │   └── mcp_server.py               #    FastMCP: 16+ 工具 + 资源 + 提示词
│       ├── ai/                             #    🤖 AI 增强模块
│       │   ├── params.py                   #    参数推荐引擎
│       │   ├── diagnostics.py              #    诊断引擎 (12+ 错误模式)
│       │   └── reporter.py                 #    报告生成 (Markdown/HTML/JSON)
│       ├── install_fullprof.sh             #    FullProf 安装脚本
│       └── tests/                          #    🧪 测试套件 (10+ 文件)
│           ├── test_pcr_editor.py          #    PCR 读写测试
│           ├── test_api.py                 #    FullProfAPI 测试
│           ├── test_mcp_server.py          #    MCP 协议测试
│           └── ...
├── Fortran-Utilities/                      # 🔧 辅助 Fortran 工具
├── Tests/                                  # 🧪 上游测试数据 (EgyptMakeup, LiFePO4, NMC111)
├── docs/                                   # 📚 Sphinx 文档
├── .mcp.json                               # MCP 宿主配置模板
├── requirements.txt                        # Python 依赖
└── CHANGELOG.rst                           # 变更日志

模块依赖关系 / Module Dependencies

fullprof_mcp.server.mcp_server (FastMCP, 入口)
    │
    ├── core/api.py (FullProfAPI)      — 面向 AI 的统一入口
    │   ├── core/pcr_editor.py         — PCR 文件读写
    │   ├── core/result_parser.py      — 精修结果解析
    │   ├── core/data_manager.py       — 数据格式 + CIF
    │   └── core/fullprof_bridge.py    — FullProf 子进程调用
    │       ├── FullProfBridge         — 真实桥接
    │       └── MockFullProfBridge     — 模拟桥接
    ├── ai/params.py                   — 参数推荐
    ├── ai/diagnostics.py              — 智能诊断
    └── ai/reporter.py                 — 报告生成

编译与安装 / Installation

前置条件 / Prerequisites

依赖	用途	安装方式
Python 3.10+	MCP 服务器	`apt install python3.11`
Python 包	MCP/numpy/scipy	`pip install -r requirements.txt`
FullProf	精修引擎 (可选)	从 ILL 网站下载
gfortran	FullProf 编译 (可选)	系统包管理器

1️⃣ 安装 Python 依赖

git clone https://github.com/XRDFPSR/FullProf-App-MCP.git
cd FullProf-App-MCP
pip install -r requirements.txt

核心依赖：

mcp>=1.0.0 — MCP 协议框架
numpy>=1.25.0 — 数值计算
scipy>=1.11.0 — 寻峰、滤波、拟合
fastnumbers>=3.2.0 — 快速字符串→数字转换
PyCifRW>=4.4.0 — CIF 文件解析

2️⃣ 安装 FullProf (可选 — 用于实际精修)

# 方式 A：使用安装脚本
chmod +x src/fullprof_mcp/install_fullprof.sh
./src/fullprof_mcp/install_fullprof.sh

# 方式 B：手动设置环境变量
export FULLPROF_HOME=/path/to/FullProf

# 方式 C：加入 PATH
export PATH=$PATH:/path/to/FullProf/bin

3️⃣ 验证安装

python -m fullprof_mcp status

正常输出示例：

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

即使没有 FullProf，也可以在 Mock 模式下运行：

python -m fullprof_mcp status
# FullProf Ready: No  (自动启用 Mock 模式)

MCP 服务器使用 / MCP Server Usage

启动服务器

# stdio 模式 (默认，用于 Claude Desktop / Cursor / VS Code)
python -m fullprof_mcp server

# SSE HTTP 模式 (用于远程访问)
python -m fullprof_mcp server --transport sse --port 8910

MCP 宿主配置 / Claude Desktop Config

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

MCP 工具清单 (16+ 个)

类别	工具	功能
基础工具	`get_status`	获取系统状态、版本、FullProf 可用性
	`read_pcr`	读取 PCR 文件，返回 JSON 结构化内容
	`edit_pcr`	修改 PCR 参数 (晶胞、原子、背底、标志位)
	`create_pcr_from_cif`	从 CIF + 数据文件 + IRF 自动创建 PCR
数据处理	`load_data`	加载衍射数据，返回摘要 (点数、2θ 范围)
	`convert_data`	转换数据文件格式
	`detect_format`	自动检测数据格式
	`find_peaks`	自动寻峰 (位置、强度、d-spacing)
	`estimate_background`	Chebyshev 多项式拟合背底
精修执行	`run_refinement`	执行 FullProf Rietveld 精修
	`get_results`	解析结果 (Rwp, GOF, 晶胞参数)
数据库	`search_phase_cod`	搜索 COD 晶体学数据库
	`read_cif`	读取 CIF，返回晶胞/空间群/原子位置
AI 增强	`auto_diagnose`	一键诊断：Rwp 评估 + 错误匹配 + 修复建议
	`suggest_best_strategy`	推荐增量精修策略
	`generate_report`	生成精修报告 (Markdown/HTML/JSON)

提示词模版 / Prompts

提示词	功能
`refine_xrd`	引导 XRD Rietveld 精修工作流
`search_match`	Search-Match 物相鉴定工作流
`full_refinement_workflow`	完整精修管线 (数据→CIF→IRF→PCR→精修→报告)
`diagnose_refinement`	精修结果诊断引导

资源协议 / Resource Protocol

fullprof://status — 系统状态 JSON
fullprof://pcr/{path} — PCR 文件内容 JSON
fullprof://results/{workdir} — 精修结果 JSON

快速功能测试

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}

# 在 Mock 模式下运行精修
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 能力概述 / FullProf Capabilities

FullProf 是由 Juan Rodríguez-Carvajal（ILL, 法国格勒诺布尔）开发的开源粉末衍射精修软件套件，采用 FORTRAN 77/95 编写。

核心功能

功能	说明
Rietveld 精修	粉末衍射全谱拟合，支持多相多谱图
Le Bail 拟合	提取结构因子，无结构模型时进行峰形拟合
Pawley 拟合	约束条件下的峰形拟合
晶胞参数精修	指数化后的晶胞参数精确确定
Profile Matching	衍射花样匹配
傅立叶合成	计算核散射密度和磁散射密度的傅立叶映射
最大熵法 (MEM)	最大熵方法重建散射密度
模拟退火	Ab initio 结构解析
序列精修	时间分辨/温度序列数据的批量精修
磁结构精修	核 + 磁结构的同步精修 (Shubnikov 群)

支持的衍射类型

X 射线 (实验室 X 射线源、同步辐射)
中子 (恒定波长、飞行时间 TOF)
电子衍射

文件格式

输入：PCR (*.pcr)、数据 (*.xye, *.xys, *.dat, *.raw, *.xrdml)、仪器参数 (*.irf)、CIF
输出：*.sum (精修日志)、*.prf (拟合数据)、*.mic (微观结构)、*.res (结果)、*.fst (结构因子)

本 Fork 的变更 / Changes vs Upstream

变更	路径	说明
fullprof_mcp Python 包	`src/fullprof_mcp/`	完整的 MCP 服务器
Headless 设计	—	剥离所有 PyQt5/crysfml 依赖
API 抽象层	`core/api.py`	FullProfAPI — 面向 AI 的统一入口
PCR 编辑器	`core/pcr_editor.py`	无 PyQt5 依赖的 PCR 读写 (1700+ 行)
结果解析器	`core/result_parser.py`	.sum/.mic/.prf/.res 解析 (900+ 行)
数据管理器	`core/data_manager.py`	格式转换 + CIF (1000+ 行)
FullProf 桥接	`core/fullprof_bridge.py`	子进程调用 + Mock 模式
MCP 服务器	`server/mcp_server.py`	FastMCP: 16+ 工具
AI 诊断	`ai/`	参数推荐、诊断引擎、报告生成
测试套件	`tests/`	10+ 测试文件
重命名	—	fullprof-app → FullProf-App-MCP

测试 / Testing

cd /path/to/FullProf-App-MCP

# 全部测试
python -m pytest src/fullprof_mcp/tests/ -v

# 按模块
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

# 验证无 GUI 依赖
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')"

# 确认无 PyQt5 污染
grep -rn "PyQt5\|crysfml" src/fullprof_mcp/core/ src/fullprof_mcp/server/ || echo "✅ No GUI dependency leaks"

开发 / Development

代码检查

# 语法检查
python -m py_compile src/fullprof_mcp/core/pcr_editor.py

项目路线图 / Roadmap

阶段	组件	状态
1	核心基础设施 (PcrEditor, ResultParser, DataManager)	✅
2	FullProf 桥接 (FullProfBridge + Mock)	✅
3	数据管理 (格式转换、CIF 验证、寻峰、背底)	✅
4	MCP 服务器 (FastMCP, 16+ 工具, 资源, 提示词)	✅
5	AI 增强 (参数推荐、诊断、报告生成)	✅
6	COD 在线搜索集成	✅
—	正式发布 + 文档	🔄

许可证 / License

GNU General Public License v3.0 (GPL-3.0)

本仓库是 FullProfAPP (GPLv3) 的 fork，所有上游贡献者的版权均保留。FullProf 由 Juan Rodríguez-Carvajal（ILL）开发并维护。

致谢 / Acknowledgements

Juan Rodríguez-Carvajal — FullProf 作者，Institut Laue-Langevin
CIC energiGUNE, ICMAB-CSIC, ILL, ALBA Synchrotron — FullProfAPP 联合开发团队
EU Horizon 2020 — BATTERY 2030+ 项目资助 (Grant No. 957189)

FullProf 主页: https://www.ill.eu/sites/fullprof/ FullProfAPP 上游: https://github.com/XRDFPSR/fullprof-app

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
Documents		Documents
Fortran-Utilities		Fortran-Utilities
Support-PDF-Documents		Support-PDF-Documents
Tests		Tests
docs		docs
examples		examples
src		src
.gitignore		.gitignore
.mcp.json		.mcp.json
.readthedocs.yaml		.readthedocs.yaml
CHANGELOG.rst		CHANGELOG.rst
LICENSE		LICENSE
README.md		README.md
requirements.txt		requirements.txt

项目	说明	仓库
GSAS2-MCP	GSAS-II Rietveld 精修 MCP 服务器	XRDFPSR/GSAS2-MCP
Profex-MCP	Profex/BGMN XRD 分析 MCP 服务器	XRDFPSR/Profex-MCP
MAUD-MCP	MAUD 组合衍射分析 MCP 服务器	XRDFPSR/MAUD-MCP

Folders and files

Latest commit

History

Repository files navigation

FullProf-App-MCP 🧪🦞

项目目的 / Purpose

架构 / Architecture

代码结构 / Code Structure

模块依赖关系 / Module Dependencies

编译与安装 / Installation

前置条件 / Prerequisites

1️⃣ 安装 Python 依赖

2️⃣ 安装 FullProf (可选 — 用于实际精修)

3️⃣ 验证安装

MCP 服务器使用 / MCP Server Usage

启动服务器

MCP 宿主配置 / Claude Desktop Config

MCP 工具清单 (16+ 个)

提示词模版 / Prompts

资源协议 / Resource Protocol

快速功能测试

FullProf 能力概述 / FullProf Capabilities

核心功能

支持的衍射类型

文件格式

本 Fork 的变更 / Changes vs Upstream

测试 / Testing

开发 / Development

代码检查

项目路线图 / Roadmap

相关项目 / Related Projects

许可证 / License

致谢 / Acknowledgements

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages