IntelligentMat/apex-mcp

APEX MCP Tools

This package wraps the APEX workflow system as MCP tools using FastMCP. It exposes endpoints to submit APEX workflows, list/query their status, control lifecycle, and retrieve artifacts.

Quick start

1. Install deps (uv recommended):

uv venv --python=3.12
uv sync

2. Run the MCP server:

uv run python deploy.py

The server listens on port 8792 by default.

Available tools

• apex_submit(parameters, config_file, work_dirs, flow?, name?, submit_only?, debug?, labels?)
• apex_list(config_file, label?)
• apex_get(config_file, workflow_id)
• apex_getkeys(config_file, workflow_id)
• apex_control(config_file, workflow_id, action, step_ids?)
• apex_retrieve(config_file, workflow_id, work_dir)

Payload examples

Submit relaxation:

{
  "parameters": ["/path/param_relax.json"],
  "config_file": "/path/global_bohrium.json",
  "work_dirs": ["/path/to/work"],
  "flow": "relax",
  "name": "demo-relax",
  "submit_only": true
}

List workflows:

{ "config_file": "/path/global_bohrium.json" }

Retrieve artifacts:

{
  "config_file": "/path/global_bohrium.json",
  "workflow_id": "<WF_ID>",
  "work_dir": "/path/to/work"
}

将 MCP 添加到 Cursor

要在 Cursor 中使用此 APEX MCP 工具，需要将其配置为 MCP 服务器。以下是详细步骤：

1. 安装和启动 MCP 服务器

首先确保已安装并启动 APEX MCP 服务器：

# 安装依赖
uv venv --python=3.12
uv sync

# 启动 MCP 服务器
uv run python deploy.py

服务器默认在 http://localhost:8792 上监听。

2. 配置 Cursor MCP 设置

在 Cursor 中，需要将此 MCP 服务器添加到配置中：

方法一：通过 Cursor 设置界面

1. 打开 Cursor
2. 进入 Settings (设置)
3. 找到 MCP Servers 或 Model Context Protocol 部分
4. 添加新的 MCP 服务器配置：

{
  "name": "apex-mcp",
  "url": "http://localhost:8792",
  "description": "APEX workflow management tools"
}

方法二：通过配置文件

编辑 Cursor 的 MCP 配置文件（通常位于用户配置目录）：

{
  "mcpServers": {
    "apex-mcp": {
      "command": "uv",
      "args": ["run", "python", "deploy.py"],
      "cwd": "/Users/siyuliu/Downloads/apex_mcp",
      "env": {}
    }
  }
}

或者使用 HTTP 连接方式：

{
  "mcpServers": {
    "apex-mcp": {
      "url": "http://localhost:8792",
      "transport": "http"
    }
  }
}

3. 验证 MCP 连接

配置完成后，在 Cursor 中你应该能够：

1. 看到 APEX MCP 工具在可用工具列表中
2. 使用以下工具：
   • apex_submit - 提交 APEX 工作流
   • apex_list - 列出工作流
   • apex_get - 获取工作流详情
   • apex_getkeys - 获取步骤键
   • apex_control - 控制工作流生命周期
   • apex_retrieve - 检索结果文件

4. 使用示例

配置成功后，你可以在 Cursor 中使用自然语言来操作 APEX 工作流：

• "提交一个弛豫计算工作流"

  submit job to apex
  {
    "parameters": ["absolute_path_to/examples/vasp_demo/param_relax.json"],
    "config_file": "absolute_path_to/examples/vasp_demo/global_bohrium.json",
    "work_dirs": ["absolute_path_to/examples/vasp_demo/confs/std-fcc"],
    "flow": "relax",
    "name": "demo-relax",
    "submit_only": true
  }
  

• "列出所有正在运行的工作流"
• "检索工作流 ABC123 的结果"
• "停止工作流 XYZ789"

Cursor 会自动调用相应的 APEX MCP 工具来执行这些操作。

故障排除

如果遇到连接问题：

1. 确保 MCP 服务器正在运行：curl http://localhost:8792/health
2. 检查防火墙设置
3. 验证 Cursor 的 MCP 配置语法
4. 查看 Cursor 和 MCP 服务器的日志输出

注意事项

• 确保 APEX 环境已正确配置
• MCP 服务器需要访问 APEX 配置文件和工作目录
• 某些操作可能需要适当的权限和网络访问