Update mcp_output/README_MCP.md

mcp_output/README_MCP.md

@@ -1,205 +1,265 @@
-# 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` | 获取特定模型的默认配置 |
-| `process_structure_data` | 将原子结构数据处理为图格式 |
-| `train_model` | 训练 GNN 模型 |
-| `predict_properties` | 使用训练好的模型预测新结构的属性 |
-| `cross_validation` | 执行 k 折交叉验证 |
-| `analyze_structure` | 分析原子结构文件 |
-| `compare_models` | 比较不同 GNN 模型的性能 |
-| `get_dataset_info` | 获取数据集目录信息 |
-
-## 支持的模型
-
-- **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 服务框架
+# 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` | 获取特定模型的默认配置 | - |
+| `quick_structure_analysis` | **推荐** 快速分析结构文件 | ✅ |
+| `analyze_structure` | 分析原子结构文件 | ✅ |
+| `process_structure_data` | 将原子结构数据处理为图格式 | ✅ |
+| `get_dataset_info` | 获取数据集信息 | ✅ |
+| `train_model` | 训练 GNN 模型 | - |
+| `predict_properties` | 使用训练好的模型预测新结构的属性 | - |
+| `cross_validation` | 执行 k 折交叉验证 | - |
+| `compare_models` | 比较不同 GNN 模型的性能 | - |
+
+## 🌟 远程 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
+}
+```
+
+#### analyze_structure
+```json
+{
+  "file_content": "完整的文件内容字符串",
+  "file_format": "cif"
+}
+```
+
+#### process_structure_data（处理多个结构）
+```json
+{
+  "structure_contents": {
+    "struct1.cif": "CIF 内容...",
+    "struct2.cif": "CIF 内容..."
+  },
+  "targets_csv": "struct1,1.5\nstruct2,2.3"
+}
+```
+
+## 支持的模型
+
+- **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 服务框架