# ModelSim L MCP Server

> ModelSim/QuestaSim 自动化 MCP 服务器 — 为 AI 助手提供完整的 FPGA 仿真能力。
>
> An MCP server exposing local ModelSim/QuestaSim CLI tools via the Model Context Protocol.

---

## 概述 / Overview

**modelsim-Lmcp-server** 将本机 ModelSim/QuestaSim 命令行工具暴露为 **57 个 MCP 工具**，覆盖从建库编译、仿真运行、波形分析、覆盖率收集、门级仿真、UVM 到批量自动化的全流程。

与 [QuartusMCP](https://github.com/L-YvY-L/quartus-Lmcp-server) 互补：QuartusMCP 管理工程/编译/下载流程，ModelSimMCP 专注于仿真验证。

-   **自动发现** — 启动时扫描 C/D/E/F 盘及 WSL 挂载点，自动找到 `modelsim_ase` / `modeltech` 安装
-   **独立于 Quartus** — 不需要 Quartus 环境，可单独使用 ModelSim SE / QuestaSim
-   **支持所有版本** — ModelSim 10.x、QuestaSim 2020+、各 Quartus 随附版本

---

## 安装 / Installation

```bash
git clone https://github.com/L-YvY-L/modelsim-Lmcp-server.git
cd modelsim-Lmcp-server
pip install -r requirements.txt
```

**环境要求：**
-   Windows 10/11
-   Python 3.10+
-   `mcp>=1.0.0`
-   本机安装 ModelSim / ModelSim-Altera / QuestaSim（任意版本）

---

## MCP 配置 / Configuration

### WorkBuddy

编辑 `~\.workbuddy\mcp.json`：

```json
{
  "mcpServers": {
    "modelsim": {
      "command": "python",
      "args": ["E:/.workbuddy/mcp-servers/modelsim-Lmcp-server/modelsim_mcp_server.py"],
      "env": {
        "MODELSIM_BIN": "E:/intelFPGA_lite/18.1/modelsim_ase/win32aloem"
      }
    }
  }
}
```

### Claude Code

编辑项目目录下的 `.mcp.json` 或用户目录 `~/.mcp.json`：

```json
{
  "mcpServers": {
    "modelsim": {
      "command": "python",
      "args": ["path/to/modelsim_mcp_server.py"],
      "env": {
        "MODELSIM_BIN": "path/to/modelsim_ase/win32aloem"
      }
    }
  }
}
```

### Cursor

编辑 `.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "modelsim": {
      "command": "python",
      "args": ["path/to/modelsim_mcp_server.py"]
    }
  }
}
```

### Continue

编辑 `~/.continue/config.json`：

```json
{
  "modelsim": {
    "command": "python",
    "args": ["path/to/modelsim_mcp_server.py"]
  }
}
```

> 修改配置后请重启对应的 MCP 客户端。环境变量 `MODELSIM_BIN` 通常不需要手动设置 — 服务器会自动发现。

### 可选环境变量

| 变量 | 说明 | 默认值 |
|---|---|---|
| `MODELSIM_BIN` | ModelSim bin 目录 | 自动扫描 C/D/E/F 盘 |
| `MODELSIM_ROOT` | ModelSim 安装根目录 | 自动扫描 |

自动发现支持的路径模式：
- `{drive}:/intelFPGA_lite/*/modelsim_ase/win32aloem`
- `{drive}:/intelFPGA_lite/*/modelsim_ase/win32`
- `{drive}:/modeltech*/win64` 或 `win32`

---

## 功能概览 / Features

| 分类 | 工具数 | 说明 |
|---|---|---|
| **环境与发现** | 3 | 自动发现安装、许可证检查、版本查询 |
| **库管理** | 5 | 创建/删除/映射库、列出库与设计单元 |
| **编译** | 3 | Verilog/SystemVerilog 编译、VHDL 编译、批量编译 |
| **仿真执行** | 5 | 启动/运行/重启仿真、六步完整流程、最简一键仿真 |
| **波形操作** | 7 | 波形布局保存/加载、图片导出、WLF 比较、VCD 互转、离线查看 |
| **信号操作** | 4 | Force 信号、检查信号值、Log 信号、添加到波形 |
| **覆盖率** | 3 | 覆盖率仿真、UCDB 合并、排除项管理 |
| **批量自动化** | 4 | DO 文件生成、批处理脚本、DO 执行、Makefile 生成 |
| **高级仿真** | 7 | 门级仿真、时序仿真、并行仿真、UVM、回归测试、条件断点、Watchpoint |
| **断言** | 1 | SVA 断言仿真 |
| **仿真库编译** | 1 | 编译 Altera/Intel 器件仿真库 |
| **工具集** | 7 | 错误码查询、源码查看、WLF 信息、WLF 恢复/转日志、加密、Tcl 执行 |
| **内存与调试** | 5 | 内存检查、虚拟信号、断点、Transcript 录制、WLF 检查点 |
| **快捷入口** | 2 | 快速仿真、最简参数版 |

---

## 完整工具目录 / Complete Tool Catalog

### 环境与发现
| 工具 | 说明 |
|---|---|
| `discover_modelsim` | 自动发现本机 ModelSim 安装路径与工具 |
| `check_modelsim_license` | 检查许可证状态 |
| `get_modelsim_version` | 获取版本号 |

### 库管理
| 工具 | 说明 |
|---|---|
| `create_library` | 创建设计库 (vlib) |
| `delete_library` | 删除设计库 (vdel) |
| `map_library` | 映射逻辑库到物理路径 (vmap) |
| `list_libraries` | 列出所有已映射的库 |
| `list_design_units` | 列出库中已编译的设计单元 (vdir) |

### 编译
| 工具 | 说明 |
|---|---|
| `compile_verilog` | 编译 Verilog/SystemVerilog (vlog) |
| `compile_vhdl` | 编译 VHDL (vcom) |
| `compile_project` | 批量编译整个目录树 |

### 仿真执行
| 工具 | 说明 |
|---|---|
| `start_simulation` | 启动仿真会话 (vsim) |
| `run_simulation` | 完整六步流程：建库→编译→启动→加波形→运行→保存 |
| `simulation_flow_advanced` | 高级仿真：自定义信号、force、运行后操作 |
| `restart_simulation` | 重启当前仿真 |
| `quick_simulation` | 快速一键仿真 |
| `quick_verilog_sim` | 最简参数版仿真（4 参数） |

### 波形操作
| 工具 | 说明 |
|---|---|
| `save_wave_format` | 保存波形布局 (.do) |
| `load_wave_format` | 加载波形布局 |
| `export_wave_image` | 导出波形图片 (BMP/PNG/JPG) |
| `compare_waveforms` | 比较两个 WLF 文件 (wlfcmp) |
| `convert_wlf_to_vcd` | WLF → VCD 转换 |
| `convert_vcd_to_wlf` | VCD → WLF 转换 |
| `view_waveform` | 离线查看 WLF 波形 (GUI) |

### 信号操作
| 工具 | 说明 |
|---|---|
| `force_signals` | 批量 force 信号值 |
| `examine_signals` | 检查信号当前值 |
| `log_signals` | Log 信号到 WLF |
| `add_wave_signals` | 添加信号到波形（支持分组、分隔线、进制） |

### 覆盖率
| 工具 | 说明 |
|---|---|
| `run_coverage_simulation` | 运行覆盖率仿真 + 生成报告 |
| `merge_coverage` | 合并 UCDB 覆盖率数据 |
| `coverage_exclude` | 排除/恢复覆盖率检查项 |
| `generate_coverage_report` | 生成覆盖率报告 |

### 批量自动化
| 工具 | 说明 |
|---|---|
| `generate_do_file` | 生成可复用 DO 文件（含完整注释模板） |
| `generate_batch_script` | 生成 Windows .bat 一键仿真脚本 |
| `execute_do_file` | 执行已有 DO 文件 |
| `create_makefile` | 生成 ModelSim Makefile (vmake) |

### 高级仿真
| 工具 | 说明 |
|---|---|
| `run_gate_level_simulation` | 门级时序仿真（SDF 反标注） |
| `run_full_timing_simulation_flow` | 完整时序仿真流程 |
| `run_parallel_simulation` | 并行仿真执行 |
| `run_uvm_simulation` | UVM 仿真运行 |
| `run_regression_test` | 回归测试批量运行 |
| `run_assertion_simulation` | SVA 断言仿真 |
| `add_conditional_breakpoint` | 设置条件断点 |

### 仿真库
| 工具 | 说明 |
|---|---|
| `compile_simulation_library` | 编译 Altera/Intel 器件仿真库 |

### 工具集
| 工具 | 说明 |
|---|---|
| `check_error` | 查询错误代码含义 (verror) |
| `view_source_file` | 显示源代码带行号 (vcat) |
| `view_wlf_info` | WLF 文件元信息 (wlfman) |
| `recover_wlf` | 恢复损坏的 WLF (wlfrecover) |
| `wlf_to_log` | WLF 波形 → 文本日志 |
| `encrypt_verilog` | 加密 Verilog 源文件 (vencrypt) |
| `run_tcl_commands` | 在 ModelSim 上下文中执行任意 Tcl 命令 |

### 内存与调试
| 工具 | 说明 |
|---|---|
| `inspect_memory` | 查看仿真中内存实例内容 |
| `create_virtual_signal` | 创建虚拟信号/总线/函数 |
| `set_breakpoint` | 设置断点 (when) |
| `record_transcript` | 录制/停止 Transcript 到 DO 文件 |
| `add_watchpoint` | 添加 Watchpoint 监控 |
| `save_wlf_checkpoint` | 保存 WLF 检查点 |

---

## 使用示例 / Usage Examples

### 一键仿真
```
quick_verilog_sim
  rtl: "../rtl/mux4to1.sv"
  tb: "../tb/mux4to1_tb.sv"
  top_name: "mux4to1_tb"
  work_dir: "D:/project/mux4to1/sim"
```

### 覆盖率仿真
```
run_coverage_simulation
  top_module: "alu_tb"
  rtl_files: "../rtl/*.sv"
  tb_files: "../tb/alu_tb.sv"
  coverage_types: "bcesxf"
  save_ucdb: "alu_cov.ucdb"
```

### 编译器件仿真库
```
compile_simulation_library
  quartus_root: "E:/intelFPGA_lite/18.1/quartus"
  device_family: "cycloneive"
```

### 生成可复用脚本
`generate_do_file` → 编辑 `run.do` → `generate_batch_script` → 双击 `run.bat`

---

## 与 QuartusMCP 分工

| 流程 | 工具 |
|---|---|
| 项目管理、管脚分配、综合/布局布线 | **QuartusMCP** |
| 功能仿真、时序仿真、覆盖率 | **ModelSimMCP** |
| SignalTap 调试、JTAG 下载 | **QuartusMCP** |
| 波形分析、VCD 转换、DO 脚本 | **ModelSimMCP** |

---

## 注意事项 / Notes

-   仿真需要有效许可证
-   本项目只调用本机命令行工具，不包含 ModelSim/器件库文件
-   `run_tcl_commands` 会执行任意 Tcl，请只运行可信命令

---

## CQUPT

---

## 许可证 / License

MIT — 详见 [LICENSE](LICENSE)