# Vissim MCP

把已打开的 **VISSIM 4.30** 连接到支持 MCP 的 AI 客户端。Windows x64 单文件 EXE，自带 Python 运行环境；双击打开接入面板，使用 `--stdio` 启动 MCP 服务。

**[下载 EXE](https://github.com/zbwdashygo/vissim-mcp/releases/latest)** · [MIT 许可证](LICENSE) · [English](README.en.md)

## 使用

1. 下载发布页的 `VissimMCP-0.3.0-Windows-x64.exe`，放到固定目录。
2. 正常打开你已安装的 Vissim 4.30。
3. 双击本 EXE，点击“运行自检”和“复制接入配置”。
4. 把配置粘贴到 MCP 客户端；客户端通过 `--stdio` 参数启动同一个 EXE。

配置示例（改成自己的 EXE 路径）：

```json
{
  "mcpServers": {
    "vissim430": {
      "command": "C:/Tools/VissimMCP.exe",
      "args": ["--stdio"]
    }
  }
}
```

Codex 可使用：

```powershell
codex mcp add vissim430 -- "C:\Tools\VissimMCP.exe" --stdio
```

先调用 `vissim_status`、`vissim_connect`，再读取工程。服务启动和自检均不会自动启动 Vissim、载入工程或修改底图。

## 15 个操作

| 范围 | 工具 |
|---|---|
| 连接 | `vissim_connect`、`vissim_status`、`vissim_disconnect` |
| 读取 | `vissim_list_objects`、`vissim_get_attributes` |
| 属性修改 | `vissim_set_attributes` |
| 工程和布局 | `vissim_load_network`、`vissim_save_network_as`、`vissim_load_layout` |
| 仿真 | `vissim_configure_simulation`、`vissim_step`、`vissim_run_start`、`vissim_stop` |
| 评价 | `vissim_enable_evaluations`、`vissim_result_files` |

支持读取路段、连接器、流量输入、路径、车辆、信号及检测器。允许修改部分流量和固定配时属性，并回读核对；失败时尝试恢复原值。转向时段权重写作 `RELATIVEFLOW(1)`，括号内为从 1 开始的时段索引。

加载显示设置前会保存当前布局快照，并跳过已加载的同名底图，避免旧版 Vissim 弹出重复图片提示。

## 文件与运行约定

- EXE 运行时的持久数据默认位于 `%LOCALAPPDATA%\VissimMCP`；不会写到单文件解压临时目录。
- 工作副本在其 `projects` 子目录，操作记录在 `logs` 子目录。可以通过 `VISSIM_MCP_DATA_DIR` 和 `VISSIM_MCP_WORK_ROOT` 覆盖。
- 仿真前先调用 `vissim_save_network_as` 另存工作副本。默认拒绝覆盖已有文件，明确指定覆盖时先备份。
- 载入 INP 会替换当前内存工程，调用前应保存用户当前工作。
- 采用一个 STA 线程处理 COM；同一 Vissim 实例请只让一个客户端修改。
- 后台任务以原生单步推进，可查询和停止。它不按 `Speed` 设置进行墙钟限速。
- 目标时间必须小于 `Period`，例如验证 3600 秒时设置 `period=3601`。
- 评价文件存在不代表已完整运行；必须检查原生仿真时钟、检测器配置和警告。
- 固定配时属性修改不自动保证交通冲突消除或全局效率最优。

## 命令行

```powershell
.\VissimMCP.exe --version
.\VissimMCP.exe --diagnose
.\VissimMCP.exe --self-test
.\VissimMCP.exe --print-config
.\VissimMCP.exe --stdio
```

`--self-test` 使用真实 MCP 协议启动本 EXE 的子进程，验证初始化、15 个工具发现和状态读取；不修改 Vissim 工程。

## 从源码构建

需要 Windows x64 和 Python 3.12（含 Tkinter）。

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-build.txt
.\.venv\Scripts\python.exe scripts\collect_notices.py
.\.venv\Scripts\python.exe -m PyInstaller VissimMCP.spec --noconfirm
.\dist\VissimMCP.exe --self-test
```

源代码模式可用 `python launcher.py` 打开面板，或用 `python launcher.py --stdio` 启动服务。

## 验证范围与依赖

已在 VISSIM 4.30-01 实机验证流量、固定配时和转向权重的修改/恢复、原生 10 秒短仿真、长任务停止、重复底图加载及输出保护。短测试不等同于 3600 秒交通性能评价。

本项目是独立的互操作适配器，**仍需要用户安装可正常运行且提供 COM 接口的 Vissim 4.30**。不包含 Vissim、授权文件、课程工程或底图；不修改 Vissim 二进制或许可检查。与 PTV Group 无隶属关系。较新 Vissim 版本未经过本项目验证。

适配器源码采用 MIT 许可。EXE 内第三方组件的许可证保留在 `THIRD_PARTY_NOTICES.txt`，并随二进制一并嵌入。CPython、Tk、pywin32、MCP SDK 和 PyInstaller 各自的许可继续适用。