mcp_output/README_MCP.md

# MatDeepLearn MCP Service

这是 [MatDeepLearn](https://github.com/Fung-Lab/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（推荐用于远程分析）
```json
{
  "file_content": "完整的文件内容字符串",
  "file_format": "cif",  // 支持: cif, xyz, vasp, poscar, json, extxyz
  "include_positions": false,
  "include_distances": true
}
```

#### create_session
```json
{
  "session_name": "my_project"  // 可选，会话名称
}
```

#### upload_structure_files_batch
```json
{
  "session_id": "session_xxx",
  "files": {
    "struct1.cif": "CIF 内容...",
    "struct2.cif": "CIF 内容..."
  }
}
```

#### upload_targets
```json
{
  "session_id": "session_xxx",
  "targets_content": "struct1,1.5\nstruct2,2.3",
  "validate": true
}
```

#### train_session_model
```json
{
  "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 描述符方法

## 本地运行

### 安装依赖

```bash
cd MatDeepLearn
pip install -r mcp_output/requirements.txt
```

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

```bash
python mcp_output/start_mcp.py
```

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

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

## 部署到 HuggingFace Space

### 1. 创建 HuggingFace Space

1. 登录 [HuggingFace](https://huggingface.co/)
2. 点击 "New Space"
3. 选择 "Docker" 作为 SDK
4. 填写 Space 名称（如 `matdeeplearn-mcp`）

### 2. 上传代码

方法一：通过 Git

```bash
# 克隆你的 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` 中添加：

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

### 使用远程 HTTP 服务

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

```json
{
  "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 格式

```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](https://github.com/Fung-Lab/MatDeepLearn) - Victor Fung 等人开发
- [PyTorch Geometric](https://pytorch-geometric.readthedocs.io/) - GNN 框架
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP 服务框架