内容
# FullProf-App-MCP 🧪🦞
**AI-Agent-Friendly MCP Server for FullProf — Rietveld Refinement & Powder Diffraction Analysis**
[](LICENSE)
[]()
[](https://modelcontextprotocol.io)
FullProf-App-MCP 将经典的粉末衍射 Rietveld 精修软件 [FullProf](https://www.ill.eu/sites/fullprof/) 封装为标准的 **MCP (Model Context Protocol)** 服务器，使 AI 智能体（Claude、Copilot、Cursor 等）和自动化工作流可以直接调用 Rietveld 精修、PCR 编辑、数据转换、物相检索等全部功能。
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
本仓库是 **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 依赖
```bash
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 (可选 — 用于实际精修)
```bash
# 方式 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️⃣ 验证安装
```bash
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 模式下运行：
```bash
python -m fullprof_mcp status
# FullProf Ready: No (自动启用 Mock 模式)
```
---
## MCP 服务器使用 / MCP Server Usage
### 启动服务器
```bash
# 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
```json
{
"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
### 快速功能测试
```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}
# 在 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](https://www.ill.eu/sites/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
```bash
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
### 代码检查
```bash
# 语法检查
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 在线搜索集成 | ✅ |
| — | 正式发布 + 文档 | 🔄 |
---
## 相关项目 / Related Projects
| 项目 | 说明 | 仓库 |
|------|------|------|
| **GSAS2-MCP** | GSAS-II Rietveld 精修 MCP 服务器 | [XRDFPSR/GSAS2-MCP](https://github.com/XRDFPSR/GSAS2-MCP) |
| **Profex-MCP** | Profex/BGMN XRD 分析 MCP 服务器 | [XRDFPSR/Profex-MCP](https://github.com/XRDFPSR/Profex-MCP) |
| **MAUD-MCP** | MAUD 组合衍射分析 MCP 服务器 | [XRDFPSR/MAUD-MCP](https://github.com/XRDFPSR/MAUD-MCP) |
---
## 许可证 / License
**GNU General Public License v3.0 (GPL-3.0)**
本仓库是 [FullProfAPP](https://github.com/XRDFPSR/fullprof-app) (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*
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器