# Vensim MCP

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

![Market adoption example](examples/market_adoption.svg)

## Vensim PLE 实机运行证据

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

![Generated model opened in Vensim PLE](docs/images/vensim-native-model.png)

原生检查均通过：

| Model Check | Units Check |
|---|---|
| ![Vensim reports Model is OK](docs/images/vensim-model-check.png) | ![Vensim reports Units are OK](docs/images/vensim-units-check.png) |

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

![SyntheSim running in Vensim PLE](docs/images/vensim-synthesim.png)

完整验收步骤、环境和边界见 [`docs/native-validation.md`](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](https://docs.astral.sh/uv/)。

```bash
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：

```bash
uv run python -m vensim_mcp.server
```

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

```json
{
  "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 规格

最小规格由四部分组成：

```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`](examples/market_adoption.json)。生成器不会猜测研究数据、方程或单位；这些必须由建模者明确提供。

## 布局原则

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

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

## 测试

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

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

## 研究依据

公开方案对比和官方能力边界见 [`docs/research.md`](docs/research.md)。核心文件格式依据 Vensim 官方 [File Formats](https://www.vensim.com/documentation/refad.html) 与 [Sketch Format](https://www.vensim.com/documentation/ref_sketch_format.html)。

## License

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