JADE Research MCP

Windows MCP server for local MDI JADE 9 GUI control and independent, reproducible powder XRD calculations. 32 tools · MIT license · Python 3.11+

面向材料研究的本地 MCP：通过对话控制已安装的 JADE，并完成谱图处理、峰拟合、晶格和尺寸/应变计算。已在 Windows、JADE 9 中文版、Python 3.12 环境验证；其他版本和语言需要适配。

本项目是独立开发的界面桥接工具，不是 JADE 官方产品，不提供 JADE 软件、许可证、ICDD/ICSD 数据库或厂商示范数据。使用者需要自行安装并合法使用相应软件和数据库。

能做什么

jade_* 由已安装的 JADE 执行。真实菜单可进入背景、定相、PDF 检索、分峰、晶格、WPF/Rietveld、定量和宏处理；需要逐步观察和设置参数，不能把“菜单已发送”当成分析成功。相关模块受安装版本、授权与数据库配置限制。

xrd_* 由 NumPy/SciPy/pymatgen 独立计算，结果不是 JADE 的内部计算。独立引擎没有实现 Rietveld、物相定量、Kα₂ 剥离或残余应力分析。

Related MCP server: crystallography-mcp

安装

需要 Windows、Python 3.11+（已测 3.12），以及使用 JADE 界面控制时所需的 JADE 安装。桌面需要保持解锁。安装脚本使用 uv。

git clone https://github.com/bojinLi/jade-research-mcp.git
cd jade-research-mcp
.\install.ps1

也可以使用 Python 自带环境管理：

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.lock.txt

锁定文件记录验证环境的依赖版本。需要另行解析依赖时，可使用 pip install ".[test]"；这会安装满足 pyproject.toml 的版本，不等同于已验证的锁定环境。

连接 MCP 客户端

服务器采用 stdio。客户端启动 run_server.py，不需要手动开启网页或额外的模型 API Key。

将下面示例中的路径替换为本机实际位置。注意 command 指向本项目虚拟环境中的 Python。

{
  "mcpServers": {
    "jade": {
      "command": "C:/path/to/jade-research-mcp/.venv/Scripts/python.exe",
      "args": ["C:/path/to/jade-research-mcp/run_server.py"],
      "env": {
        "PYTHONUTF8": "1",
        "JADE_EXE": "C:/path/to/JADE/jade9c.exe",
        "JADE_RESULTS_DIR": "C:/path/to/jade-research-mcp/results"
      }
    }
  }
}

Codex 可以使用项目脚本注册；先把 --jade-exe 改为实际路径。脚本会备份配置并校验其他设置保持一致；遇到不同的既有 jade 条目会停止，不覆盖它。

.\.venv\Scripts\python.exe scripts\register_codex.py --jade-exe "C:\path\to\JADE\jade9c.exe" --backup-dir ".\work\config-backups"

重载客户端的 MCP 连接后，先调用 jade_capabilities 和 jade_state 检查。环境变量 JADE_EXE 指定 JADE 程序位置；JADE 启动时自动使用其安装目录作为工作目录。若使用默认路径，请先确认它适用于你的电脑。

在对话中使用

用 JADE MCP 打开这份 XRD 文件，先核对波长、扫描范围和数据点数，再扣背景、寻峰与拟合。保留原文件，保存新报告。

对这个文件夹的样品使用相同参数处理，导出峰表和对比图。

用我提供的 Mg、MgH₂ 和 MgO CIF 对比候选物相，列出匹配及未匹配峰。

用已归属的同相孤立峰做 Scherrer 和 Williamson–Hall，注明仪器展宽和峰型假设。

典型界面调用顺序：

1. jade_launch 启动或连接，并恢复最小化的主窗口。

2. jade_state 取得当前窗口、控件及 observation_token。

3. jade_open_file 原生打开文件；再检查文件标签、范围、截图或导出结果。

4. jade_workflows / jade_menus 读取真实菜单，jade_menu 进入分析窗口。

5. 每次操作前重新观察；修改参数后核对进度、残差、结果和实际输出文件。

每个界面操作要求单次使用、90 秒有效的观察令牌；界面结构改变后旧令牌失效。工具只接受配置 JADE 程序的窗口，物理点击还会检查边界与遮挡。窗口文字、截图和数据库内容始终作为数据处理，不作为执行授权。

数据交换和精度

• jade_open_file 默认使用原生 File Read 对话框，支持 JADE 能识别的文件。已测试 RD 和 MDI；未知仪器格式仍由 JADE 决定是否可读。返回 verified_loaded=false 提醒客户端继续核对，不能只凭对话框关闭就断言成功。

• 可选 import_mode="clipboard" 将文本数值列导入 JADE，暂存并恢复原剪贴板；检测到其他应用更新剪贴板时保留其新内容。此路径可能丢失辐射、计数时间等元数据，实测 JADE 9 会将强度取整，须核对适用性。

• 二进制谱先经 JADE 读入，再用 jade_export_pattern 导出给独立引擎。XY/XYE/CSV/TXT/DAT/MDI ASCII 可以直接独立分析。

• 旧 MDI 支持声明点数后的 -1 结束标记、受限零填充和文件末尾 Ctrl-Z；其他点数或范围不一致会拒绝，不默默截断。

• 计算产物写入唯一 results/ 子目录，保留输入 SHA-256、参数及适用的 JSON/CSV/HTML/PNG/SVG/PDF。原输入不覆盖。

服务器本身不监听网络端口，也不主动上传文件。MCP 客户端可能把工具返回的数据或截图发给其模型服务；请按客户端的隐私设置使用。

科学边界

• 输入角度为 2θ（度），波长及 d 为 Å，Q 定义为 2π/d，Scherrer 输出为 nm。

• 寻峰的表观半高宽不是严格精修峰宽。尺寸计算应使用可靠拟合值及仪器标准；相干衍射畴尺寸不等同颗粒直径。

• 高斯仪器展宽按平方差扣除，洛伦兹按差值扣除；混合峰型需要专门仪器模型。W–H 采用均匀形变近似，至少三条同相孤立峰；负斜率或截距会标记。

• 独立晶格计算是在 1/d² 空间按已知 hkl 的最小二乘，未拟合零点误差；不是全谱精修。

• 峰拟合使用无权最小二乘。XYE 第三列不参与加权；形式误差不能代替完整系统不确定度。

• CIF 对比是给定候选集合内的一对一峰匹配。分数不是概率、质量分数或物相确认结论。

• 自带演示与收敛结果不能替代标准物质对含量、检出限、仪器展宽及残余应力的准确度验证。

验证

已完成 35 项自动测试，并在一套 JADE 9 中文版环境中实际调用全部 32 工具。已验证自带样例的定相、单/多相 WPF 收敛、晶胞精修、两文件原生宏处理和报告导出。公开摘要见 validation/VALIDATION.md；原始界面日志、截图和厂商数据不公开。

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe scripts\acceptance_mcp.py

第一条自动测试不要求 JADE 已安装；第二条实际调用独立工具，并在 JADE 已运行时读取界面状态，生成本地验收记录。scripts/smoke_mcp.py --ui 会加载人工测试谱、打开和退出背景对话框，会改变当前 JADE 工作状态。

examples/ 仅含程序生成的两峰测试谱和取整晶格参数的示范 CIF，不是实验数据或标准卡片。厂商自带样例需从使用者自己的合法安装获取；scripts/inspect_bundled_samples.py --sample-dir "C:\path\to\samples" 可以只读检查。

许可证与贡献

桥接程序原创代码使用 MIT。JADE、数据库和依赖保留各自许可证，本仓库没有授予它们的使用权。

欢迎提交 Issue 或 Pull Request。报告问题时附上 JADE 版本/语言、Windows 版本、显示缩放和最小复现步骤；请使用匿名人工数据，不上传个人配置、授权文件或保密实验数据。详见 CONTRIBUTING.md。