Vensim MCP

把结构化的系统动力学规格生成成真正可打开的 Vensim .mdl，同时提供布局、SVG 预览、静态审计和本机 Vensim 交接。项目既能作为 MCP server 使用，也能直接从命令行运行。

Vensim PLE 实机运行证据

以下图片不是 SVG 预览或设计稿，而是 2026-07-20 在本机 Vensim PLE 10.5.1 中打开本仓库生成的 examples/market_adoption.mdl 后直接截取的运行界面。

原生检查均通过：

Model Check	Units Check

SyntheSim 能实际启动，常量被转换为滑杆，库存、流率和辅助变量显示仿真曲线：

完整验收步骤、环境和边界见 docs/native-validation.md。

为什么需要它

现有开源方案通常只覆盖其中一段：PySD 和 SDEverywhere 擅长跨平台仿真，VenPy/VST 面向 Windows DLL 或 DSS 命令文件，一些 .mdl 美化脚本只重排已有坐标。这个项目把 macOS 上实际可用的路径连起来：

1. 用 JSON 明确库存、流率、变量、单位和因果连接；
2. 生成包含正确库存、阀门、源汇云和信息箭头的 Vensim Sketch；
3. 用确定性分层布局与碰撞评分选择弧线控制点；
4. 从真实 Sketch 记录渲染 SVG，而不是画一张与模型无关的示意图；
5. 静态审计后直接在本机 Vensim 中打开，完成权威的 Check Model 和 Units Check。

能力边界

能力	macOS Vensim PLE	Vensim DSS	无 Vensim
生成和审计 .mdl	支持	支持	支持
SVG 预览	支持	支持	支持
打开原生模型	支持	支持	不支持
.cmd 无头批处理	官方不支持	支持	不支持
Vensim DLL	macOS 不提供	Windows 可用	不支持

PLE 可以被可靠地调用来打开模型，但不能被包装成并不存在的 DSS 批处理能力。vensim-mcp doctor 会报告当前机器的真实版本和边界。

快速开始

需要 Python 3.10+；推荐使用 uv。

git clone https://github.com/Cybing521/vensim-mcp.git
cd vensim-mcp
uv sync

uv run python -m vensim_mcp.cli doctor
uv run python -m vensim_mcp.cli generate examples/market_adoption.json \
  --output examples/market_adoption.mdl
uv run python -m vensim_mcp.cli validate examples/market_adoption.mdl
uv run python -m vensim_mcp.cli render examples/market_adoption.mdl \
  --output examples/market_adoption.svg
uv run python -m vensim_mcp.cli open examples/market_adoption.mdl

在 Vensim 中依次执行：

• Model > Check Model
• Model > Units Check
• 运行一次仿真，确认库存曲线和边界行为符合预期

静态审计结果不会冒充这三项原生检查。

MCP 配置

安装后运行 stdio server：

uv run python -m vensim_mcp.server

Codex/兼容客户端可使用以下命令配置本地 server（把目录换成你的绝对路径）：

{
  "mcpServers": {
    "vensim": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/vensim-mcp",
        "run",
        "python",
        "-m",
        "vensim_mcp.server"
      ]
    }
  }
}

暴露的 MCP tools：

• vensim_doctor
• generate_vensim_model
• inspect_vensim_model
• validate_vensim_model
• render_vensim_preview
• open_vensim_model
• create_vensim_dss_script

JSON 规格

最小规格由四部分组成：

{
  "name": "simple_model",
  "title": "Simple Model",
  "levels": [
    {"name": "Population", "equation": "INTEG ( Births - Deaths, 1000 )", "unit": "Person"}
  ],
  "flows": [
    {"name": "Births", "equation": "Population * Birth Fraction", "unit": "Person/Month", "target": "Population"}
  ],
  "variables": [
    {"name": "Birth Fraction", "equation": "0.02", "unit": "1/Month", "kind": "constant"}
  ],
  "links": [
    {"source": "Population", "target": "Births", "polarity": "+"},
    {"source": "Birth Fraction", "target": "Births", "polarity": "+"}
  ]
}

完整例子见 examples/market_adoption.json。生成器不会猜测研究数据、方程或单位；这些必须由建模者明确提供。

布局原则

• 库存和物理流率构成水平主骨架；
• 常量均匀分布在上层，计算型辅助变量靠近其作用目标；
• 无障碍的短连接优先保持直线，只有避让节点、物理管道或相邻路线时才使用单控制点弧线；
• 对多个曲率和两个弯曲方向同时评分，节点碰撞的惩罚高于路线交叉，避免为了少一次交叉而穿过变量；
• 变量名按实际字符宽度调整节点尺寸；
• 物理管道与信息箭头使用不同样式；
• 过长连接、重叠节点、路线穿节点、路线交叉和断裂对象引用都会进入审计报告。

当前主示例的静态审计为：节点重叠 0、路线穿节点 0；13 条信息连接中仍有 7 对相交，另有 4 个交点涉及库存—流率物理管道。密集反馈图不承诺数学意义上的零交叉，但路由器会在保持 Vensim 单控制点兼容性的前提下尽量减少交叉，并如实报告残留值。

测试

uv run python -m unittest discover -s tests -v

测试覆盖 JSON 校验、模型生成、Sketch 引用、物理管道、直线/曲线混合路由、节点与路径碰撞指标、SVG 预览、DSS 脚本边界，以及本机 Vensim PLE 检测。

研究依据

公开方案对比和官方能力边界见 docs/research.md。核心文件格式依据 Vensim 官方 File Formats 与 Sketch Format。

License

MIT。Vensim 是 Ventana Systems, Inc. 的产品；本项目不包含或重新分发 Vensim 软件、DLL 或专有二进制格式。