mcp_output/README_MCP.md

MatDeepLearn MCP Service

这是 MatDeepLearn 的 MCP (Model Context Protocol) 服务封装，用于通过 AI 助手进行材料属性预测的图神经网络训练和推理。

功能概述

MatDeepLearn MCP 服务提供以下工具：

🔧 环境与模型信息

工具名称	描述
check_environment	检查环境配置和 GPU 可用性
list_available_models	列出所有可用的 GNN 模型
get_model_config	获取特定模型的默认配置

📁 会话管理（新增）

工具名称	描述
create_session	创建新工作会话
get_session_info	获取会话信息
list_sessions	列出所有会话
delete_session	删除会话

📤 数据上传（新增）

工具名称	描述
upload_structure_file	上传单个结构文件
upload_structure_files_batch	批量上传多个结构文件
upload_targets	上传 targets.csv 目标属性文件
upload_binary_file	上传二进制文件（如预训练模型）

🔬 结构分析

工具名称	描述
quick_structure_analysis	推荐 快速分析结构文件内容
analyze_structure	分析原子结构文件

🏋️ 模型训练（新增）

工具名称	描述
process_session_data	处理会话中的结构数据为图格式
train_session_model	在会话数据上训练 GNN 模型
run_cross_validation_session	执行 k 折交叉验证

📊 预测与评估（新增）

工具名称	描述
predict_with_session_model	使用训练好的模型进行预测
list_session_models	列出会话中的所有模型
compare_session_models	比较多个模型的性能
download_model	下载训练好的模型（base64 编码）

📁 数据集信息

工具名称	描述
get_dataset_info	获取数据集信息
process_structure_data	处理结构数据为图格式（传统方式）

---

🚀 完整工作流程示例

步骤 1: 创建会话

请创建一个名为 "my_materials" 的新会话

返回的 session_id 将用于后续所有操作。

步骤 2: 上传结构文件

单个文件：

使用 upload_structure_file 上传以下 CIF 文件到会话 session_xxx：
文件名：NaCl.cif
内容：
data_NaCl
_cell_length_a   5.64
...

批量上传：

使用 upload_structure_files_batch 批量上传结构文件到会话 session_xxx：
{
  "NaCl.cif": "data_NaCl...",
  "ZnO.cif": "data_ZnO...",
  "TiO2.cif": "data_TiO2..."
}

步骤 3: 上传目标属性

使用 upload_targets 上传以下 targets.csv 到会话 session_xxx：
NaCl,1.5
ZnO,2.3
TiO2,3.1

步骤 4: 处理数据

使用 process_session_data 处理会话 session_xxx 中的数据

步骤 5: 训练模型

使用 train_session_model 在会话 session_xxx 上训练 CGCNN_demo 模型，训练 100 个 epoch

步骤 6: 评估与预测

使用 list_session_models 查看会话 session_xxx 中的所有模型

使用 predict_with_session_model 对新结构进行预测

步骤 7: 下载模型

使用 download_model 下载会话 session_xxx 中的模型 CGCNN_demo_xxx.pth

---

🌟 远程 MCP 使用指南（在 Cursor 中使用）

当 MCP 服务部署在远程服务器（如 HuggingFace Space）时，您需要直接传入文件内容而不是文件路径。

分析结构文件（推荐方法）

使用 quick_structure_analysis 工具，直接传入文件内容：

请分析这个 CIF 文件的结构：
[在这里粘贴 CIF 文件的完整内容]

或者在 Cursor 中，您可以这样使用：

使用 quick_structure_analysis 分析以下 CIF 文件：

data_NaCl
_cell_length_a   5.64
_cell_length_b   5.64
_cell_length_c   5.64
_cell_angle_alpha   90.0
_cell_angle_beta    90.0
_cell_angle_gamma   90.0
...

工具参数说明

quick_structure_analysis（推荐用于远程分析）

{
  "file_content": "完整的文件内容字符串",
  "file_format": "cif",  // 支持: cif, xyz, vasp, poscar, json, extxyz
  "include_positions": false,
  "include_distances": true
}

create_session

{
  "session_name": "my_project"  // 可选，会话名称
}

upload_structure_files_batch

{
  "session_id": "session_xxx",
  "files": {
    "struct1.cif": "CIF 内容...",
    "struct2.cif": "CIF 内容..."
  }
}

upload_targets

{
  "session_id": "session_xxx",
  "targets_content": "struct1,1.5\nstruct2,2.3",
  "validate": true
}

train_session_model

{
  "session_id": "session_xxx",
  "model_name": "CGCNN_demo",
  "epochs": 100,
  "batch_size": 32,
  "learning_rate": 0.002
}

支持的模型

• CGCNN_demo: Crystal Graph Convolutional Neural Network
• MPNN_demo: Message Passing Neural Network
• SchNet_demo: SchNet 连续滤波卷积神经网络
• MEGNet_demo: MatErials Graph Network
• GCN_demo: Graph Convolutional Network
• SOAP_demo: Smooth Overlap of Atomic Positions 描述符方法
• SM_demo: Sine Matrix 描述符方法

本地运行

安装依赖

cd MatDeepLearn
pip install -r mcp_output/requirements.txt

启动 STDIO 模式（用于本地 AI 助手）

python mcp_output/start_mcp.py

启动 HTTP 模式（用于远程访问）

export MCP_TRANSPORT=http
export MCP_PORT=7860
python mcp_output/start_mcp.py

部署到 HuggingFace Space

1. 创建 HuggingFace Space

1. 登录 HuggingFace
2. 点击 "New Space"
3. 选择 "Docker" 作为 SDK
4. 填写 Space 名称（如 matdeeplearn-mcp）

2. 上传代码

方法一：通过 Git

# 克隆你的 Space 仓库
git clone https://huggingface.co/spaces/YOUR_USERNAME/matdeeplearn-mcp
cd matdeeplearn-mcp

# 复制 MatDeepLearn 代码
cp -r /path/to/MatDeepLearn/* .

# 提交并推送
git add .
git commit -m "Initial MatDeepLearn MCP deployment"
git push

方法二：通过 HuggingFace Web 界面

1. 在 Space 页面点击 "Files" 标签
2. 上传所有 MatDeepLearn 文件
3. 确保包含 Dockerfile、mcp_output/ 目录和所有源代码

3. 配置 Space

确保你的 Space 设置中：

• SDK: Docker
• Hardware: CPU Basic（免费）或 GPU（付费，更快）

4. 等待构建

Space 会自动构建 Docker 镜像并启动服务。构建完成后，你可以通过以下 URL 访问：

https://YOUR_USERNAME-matdeeplearn-mcp.hf.space

在 AI 助手中使用

Claude Desktop 配置

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "matdeeplearn": {
      "command": "python",
      "args": ["/path/to/MatDeepLearn/mcp_output/start_mcp.py"]
    }
  }
}

使用远程 HTTP 服务

如果部署到 HuggingFace Space，可以通过 HTTP 调用：

{
  "mcpServers": {
    "matdeeplearn": {
      "url": "https://YOUR_USERNAME-matdeeplearn-mcp.hf.space/mcp"
    }
  }
}

使用示例

检查环境

请检查 MatDeepLearn 环境是否正常

列出可用模型

列出 MatDeepLearn 中所有可用的图神经网络模型

训练模型

使用 CGCNN 模型在 data/test_data 目录上训练 100 个 epoch

预测属性

使用 trained_model.pth 模型预测 new_structures/ 目录中结构的属性

分析结构

分析 structure.cif 文件的原子结构信息

数据格式要求

目录结构

data_directory/
├── targets.csv          # 必需：包含结构ID和目标属性
├── atom_dict.json       # 可选：原子特征字典
├── structure1.json      # 结构文件（支持 json, cif, xyz, POSCAR 等）
├── structure2.json
└── ...

targets.csv 格式

structure_id,property1,property2
structure1,1.23,4.56
structure2,2.34,5.67

常见问题

Q: GPU 不可用怎么办？

A: 服务会自动回退到 CPU 模式。对于大型数据集，建议使用 GPU。

Q: 如何添加自定义模型？

A: 在 matdeeplearn/models/ 目录下添加模型文件，并在 config.yml 中添加配置。

Q: 支持哪些结构文件格式？

A: 支持 ASE 库支持的所有格式，包括：json, cif, xyz, POSCAR, vasp 等。

许可证

本项目遵循 MIT 许可证。

致谢

• MatDeepLearn - Victor Fung 等人开发
• PyTorch Geometric - GNN 框架
• FastMCP - MCP 服务框架