MaterialsCodeGraph：计算材料科学智能工作流平台

项目简介

MaterialsCodeGraph是一个用于计算材料科学领域的先进工作流平台，旨在简化复杂的计算任务。它结合了自然语言处理、智能工具编排和全面的计算溯源能力，使用户能够通过简单指令调用各种计算工具（如LAMMPS、kALDo、ASE等），自动化规划并执行多步骤工作流，并跟踪所有计算数据和结果的血缘关系。该平台基于Model Context Protocol (MCP) 构建，通过模块化的MCP服务器提供核心服务，为LLM（大型语言模型）应用提供安全、可扩展的上下文服务框架。

主要功能点

自然语言交互: 用户可以使用日常英语描述计算任务，系统智能理解并执行，无需编写复杂的脚本。
智能工作流编排: 平台能够自动选择合适的计算工具，规划多步骤的计算工作流，并动态验证各个步骤之间的依赖关系，确保任务顺利执行。
全面技能管理: 集中管理所有计算工具及其功能（技能），包括详细的输入、输出和依赖定义，便于系统理解和调用。
计算溯源与知识图谱: 完整追踪所有计算任务的输入数据、输出结果、使用的参数及详细的执行过程，构建可查询的知识图谱，支持科学发现和复现。
结果解释与可视化: 为复杂的计算结果提供人类可读的解释，并生成交互式可视化图表，帮助用户直观理解数据。
参数学习与推荐: 从历史计算数据中学习参数模式和最佳实践，为新任务提供智能参数推荐，提高工作效率和准确性。
多MCP服务器协同: 通过多个专门的MCP服务器（如接口服务器、计算服务器、内存服务器、编排服务器、验证服务器）协同工作，提供模块化、可扩展的服务架构。

安装步骤

请按照以下步骤安装MaterialsCodeGraph及其依赖：

安装 'uv' 包管理器： 'uv' 是一个极快的 Python 包管理器，推荐使用。

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

验证安装:
```
uv --version
```

安装项目依赖：在项目根目录下执行以下命令以安装核心依赖和生产环境（包括主要的计算工具，如ASE、kALDo等）依赖：
```
uv sync --extra production
```

配置环境变量：在项目根目录创建或编辑名为 '.env' 的文件，并填入必要的API Key。这些API Key对于与外部AI服务（如Claude）和材料数据库（如Materials Project）的交互至关重要：

# 必需的 API Keys
ANTHROPIC_API_KEY=your_claude_api_key_here  # 替换为您的Claude API Key
MP_API_KEY=your_materials_project_api_key_here  # 替换为您的Materials Project API Key

# 可选配置
DEBUG=false

服务器配置（供MCP客户端使用）

MaterialsCodeGraph提供了多个专门的MCP服务器，每个服务器负责不同的领域功能。MCP客户端可以通过以下JSON格式的配置信息，来启动并连接到这些MCP服务器。这些配置描述了每个服务器的名称、功能、启动命令和参数，客户端无需理解服务器内部的具体代码实现。

[
  {
    "server_name": "mcg-orchestration",
    "description": "提供智能工作流规划、编排和计算结果解释能力。它是LLM客户端与整个计算工作流交互的核心，负责接收自然语言任务并生成多步执行计划。",
    "command": "uv",
    "args": ["run", "python", "-m", "orchestration_mcp.server"],
    "initialization_options": {
      "capabilities": {
        "tools": true,
        "prompt_templates": false
      }
    }
  },
  {
    "server_name": "mcg-interfaces",
    "description": "处理自然语言交互，将用户请求转化为可执行的计算计划，并为结果生成人类可读的解释。它是用户与平台沟通的桥梁。",
    "command": "uv",
    "args": ["run", "python", "-m", "interfaces_mcp.server"],
    "initialization_options": {
      "capabilities": {
        "tools": true,
        "prompt_templates": false
      }
    }
  },
  {
    "server_name": "mcg-memory",
    "description": "管理知识图谱，存储计算资产、血缘关系，并提供模式学习与查询服务。所有计算的历史数据和关系都存储在此服务器中。",
    "command": "uv",
    "args": ["run", "python", "-m", "memory_mcp.server"],
    "initialization_options": {
      "capabilities": {
        "tools": true,
        "prompt_templates": false
      }
    }
  },
  {
    "server_name": "mcg-validation",
    "description": "负责参数和计算结果的校验，并提供问题诊断与改进建议。确保计算的物理合理性和结果的可靠性。",
    "command": "uv",
    "args": ["run", "python", "-m", "validation_mcp.server"],
    "initialization_options": {
      "capabilities": {
        "tools": true,
        "prompt_templates": false
      }
    }
  },
  {
    "server_name": "mcg-compute",
    "description": "（通用计算执行器）负责代码生成和计算任务的实际执行。它接收来自编排服务器的指令，调用具体的计算工具并返回结果。",
    "command": "uv",
    "args": ["run", "python", "-m", "compute_mcp.server"],
    "initialization_options": {
      "capabilities": {
        "tools": true,
        "prompt_templates": false
      }
    }
  }
]

基本使用方法

MaterialsCodeGraph提供了多种与系统交互的方式，包括直接的命令行工具和MCP客户端连接：

启动可选的Web后端和前端服务器（如果需要访问Web UI）：

终端 1 - 启动后端API服务器：

uv run uvicorn backend.server:app --reload --host 0.0.0.0 --port 8000

终端 2 - 启动前端UI服务器：

python3 -m http.server 3000 -d frontend

访问应用: 前端UI可在 'http://localhost:3000' 访问，后端API文档可在 'http://localhost:8000/docs' 查看。

使用命令行工具 (CLI)： MaterialsCodeGraph提供了丰富的CLI工具，可以作为MCP客户端的替代方案，或进行直接测试。
- 交互式聊天: 通过自然语言与系统互动，例如：“Fetch mp-149 from Materials Project”，“Minimize the structure with ORB”。
```
uv run mcg chat
```
- 扫描代码库: 扫描计算材料科学代码库，构建计算知识图谱。
```
uv run mcg scan /path/to/your/repo
```
- 解释请求: 解释用户请求将被路由到哪个工具和技能。
```
uv run mcg explain "calculate thermal conductivity of silicon"
```
- 描述工具: 获取关于可用工具和技能的详细信息。
```
uv run mcg describe kaldo.thermal_conductivity
```
作为MCP客户端连接: 请使用您偏好的MCP客户端，并根据上方提供的“服务器配置”信息，配置好您希望连接的MCP服务器。连接成功后，您可以通过MCP客户端调用这些服务器提供的工具和功能。例如，调用 'mcg-orchestration' 服务器上的 'create_plan' 工具来生成计算工作流计划。

关键词