PFC - ITASCA Discrete Element Simulation

itasca-mcp

English | 简体中文

itasca>model new ;now, with LLM.

itasca-mcp 通过 Model Context Protocol 将 AI Agent 连接到 ITASCA 的岩土力学模拟软件——PFC、FLAC、3DEC、MPoint 和 MassFlow。通过自然对话浏览文档、运行模拟并执行代码。

itasca>model solve ;LLM solves.

工具（10 个）

5 个文档工具——浏览和搜索所选引擎的命令、Python API 和参考文档。无需桥接程序。

5 个执行工具——交互式 REPL、任务提交、进度监控、中断和历史记录。需要桥接程序。

示例提示词

• “对密实试样进行双轴压缩测试并绘制应力–应变曲线”
• “在 FLAC3D 中构建边坡模型并求出安全系数”
• “使用 3DEC 模拟节理岩体中的隧道开挖，并检查开挖口周围的块体位移”
• “使用 MPoint 模拟滑坡运移，并报告最终堆积剖面”
• “模拟仍在运行，检查当前不平衡力，但不要停止模拟”
• “查阅文档中的 plot 命令，然后绘制当前模型的接触力链”
• “我刚在控制台输入的命令似乎不对，帮我看看”

首次设置

前提条件

• 已安装 ITASCA 引擎——PFC、FLAC、3DEC、MPoint 或 MassFlow。建议使用 9.0+；同时也支持 PFC 6.0 / 7.0、FLAC 7.0 和 3DEC 7.0。
• 已安装 uv（用于 uvx）
• AI Agent——Claude Code、Codex CLI、Gemini CLI 或任何支持 MCP 的客户端

Agent 设置（推荐）

将以下内容复制给你的 AI Agent，让它自动完成配置：

Fetch and follow this bootstrap guide end-to-end:
https://raw.githubusercontent.com/yusong652/itasca-mcp/main/docs/agentic/itasca-mcp-bootstrap.md

手动设置

1. 在 Agent 中注册 MCP 服务。

大多数 Agent 只需一条命令即可完成注册：

# Claude Code
claude mcp add itasca-mcp -- uvx itasca-mcp

# Codex / Codex-cli
codex mcp add itasca-mcp -- uvx itasca-mcp

# Gemini CLI
gemini mcp add itasca-mcp uvx itasca-mcp

或者手动填写 MCP 配置文件：

{
  "mcpServers": {
    "itasca-mcp": {
      "command": "uvx",
      "args": ["itasca-mcp"]
    }
  }
}

2. 在 ITASCA 引擎内部启动桥接程序：

下载 addon.py，然后在引擎 GUI（PFC、FLAC、3DEC 等）中通过以下任一方式启动：

• 将文件内容复制到引擎的 IPython 控制台并运行
• 或下载文件并在引擎 GUI 中执行

验证

重启 AI Agent，并让它调用 itasca_execute_code 以验证连接。

日常启动

完成首次设置后，每次启动新的引擎会话时，只需重新启动桥接程序——在引擎的 IPython 控制台运行以下内容即可重新连接：

import itasca_mcp_bridge
itasca_mcp_bridge.start()

start() 会检查 PyPI 上是否有更新的桥接程序版本，并在启动前自动升级。MCP 客户端配置会保留。

功能

• 多引擎、多版本语料库 - 提供 PFC、FLAC、3DEC、MPoint 和 MassFlow 的命令、Python API 和参考文档，涵盖多个引擎版本（PFC：6.0/7.0/9.0，FLAC：7.0/9.0，3DEC：7.0/9.0），通过 software 和 version 参数进行选择
• 文档 Agent 可浏览导航 - Agent 可浏览引擎命令树，了解功能和边界，减少幻觉命令；绘图项目参考文档可补充官方文档
• 与运行中的任务并行使用实时 REPL - 在模拟运行时执行代码：检查模型状态和中间结果，无需停止任务；也可用于编写完整脚本前快速迭代
• 任务生命周期管理 - 提交长时间运行的模拟、监控进度、中断正在运行的任务，以及浏览任务历史记录
• 可感知你在 GUI 中的操作 - 你在引擎 IPython 窗格中运行的单元格、在其提示符中输入的命令、打开、关闭或切换查看的绘图和数据文件、添加到绘图中的项目，以及从编辑器执行的数据文件，都会在 Agent 下次调用时传达给它，因此你可以同时在 GUI 中和 Agent 协作
• 由 Agent 启动的桥接程序 - AI Agent 可通过引擎的 console.exe 自行启动桥接程序
• 兼容多个客户端 - 支持 Claude Code、Codex CLI、Gemini CLI、GitHub Copilot CLI、OpenCode、toyouro-nagisa 及其他 MCP 客户端

故障排除

请参阅引导指南中的故障排除。

开发

请参阅开发者指南：从源代码安装并运行。

贡献

欢迎提交 PR 和问题！请参阅 CONTRIBUTING.md，了解更改的归属位置和文档语料库的结构；有关从源代码安装，请参阅开发者指南。

许可证

MIT - 请参阅 LICENSE。