内容
# Quartus MCP 服务
## 简介
本项目是一个面向 Intel/Altera Quartus 的 MCP 服务，可让 Claude Code 调用本机 Quartus/ModelSim 命令行工具，完成工程创建、HDL 文件管理、编译、仿真、时序分析、报告读取和 JTAG 下载等流程。
## 功能概览
- 创建、打开、查看、归档和枚举 Quartus 工程。
- 添加或移除 HDL、SDC、MIF 和仿真文件。
- 设置全局约束、管脚约束、时钟和器件信息。
- 运行 map、fit、assembler、完整编译、STA、DRC 和功耗分析。
- 读取 flow、map、fit、asm、STA、power 和 QSF 报告。
- 自动生成 Verilog testbench，并调用 ModelSim 批处理仿真。
- 编译 Quartus 仿真库，支持 LPM、megafunction、Intel IP 和器件 atom 联合仿真。
- 检测 JTAG 线缆/器件，并下载生成的 SOF。
- 提供 Claude Code 项目级 FPGA skills 和 agents。
## 环境要求
| 依赖 | 版本 / 说明 |
| --- | --- |
| Quartus 命令行工具 | 已用 Quartus Prime Lite 23.1std.0 Build 991 测试 |
| ModelSim 命令行工具 | 已用 ModelSim SE-64 2020.4 测试 |
| Python | 3.10 或更高版本 |
| MCP Python 包 | `mcp>=1.0.0` |
| Claude Code | 当前版本 |
## 安装
```powershell
git clone https://github.com/<your-name>/quartus_mcp_server.git
cd quartus_mcp_server
python -m pip install -r requirements.txt
```
## 工具链发现
Quartus 的查找顺序如下：
1. `QUARTUS_MCP_ROOT`
2. `QUARTUS_ROOTDIR`
3. `QUARTUS_ROOTDIR_OVERRIDE`
4. `QUARTUS_BIN`
5. 常见 Windows/WSL 安装目录：
`C:\intelFPGA_lite`、`C:\intelFPGA`、`C:\altera`、
`/mnt/c/intelFPGA_lite`、`/mnt/c/intelFPGA`、`/mnt/c/altera`
ModelSim 的查找顺序如下：
1. `QUARTUS_MCP_MODELSIM_BIN`
2. `MODELSIM_BIN`
3. 常见 Windows ModelSim 目录，例如 `C:\modeltech*\win64`
4. Intel 自带的 `modelsim_ase` 目录
可以调用 `get_quartus_installation` 确认当前使用的可执行文件路径和可用状态。
## 本地验证
运行以下检查：
```powershell
python scripts\validate_claude_skills.py
python scripts\validate_claude_agents.py
python -m unittest discover -s tests
python scripts\smoke_test_tools.py
```
`smoke_test_tools.py` 会直接调用所有 MCP tool 函数，包括 ModelSim 仿真。依赖硬件的下载器相关工具在没有开发板时可能返回结构化的 no-cable/no-device 结果；这仍然能验证 MCP tool 本身不会崩溃，并且 Quartus 命令可被调用。
## 项目技能
本仓库在 `.claude/skills` 下提供项目级 Claude Code skills。这些 skills 位于 MCP tools 之上，用来决定调用哪些 Quartus/ModelSim 工具、读取哪些证据，以及什么时候切换到更具体的 FPGA 工作流。
| 技能 | 用途 |
| --- | --- |
| `quartus-project-bringup` | 创建或导入工程，设置顶层实体，注册 HDL/SDC，并运行首次编译检查 |
| `quartus-constraints-board` | 管理 QSF/SDC、管脚、I/O 标准、时钟约束和板级配置 |
| `quartus-compile-debug` | 根据报告和消息定位 map/fit/assembler/DRC 问题 |
| `modelsim-rtl-simulation` | 创建或注册 testbench，并运行 ModelSim RTL 仿真 |
| `intel-ip-cosimulation` | 使用 Quartus 仿真库、IP 脚本、LPM 和器件 atom 运行联合仿真 |
| `quartus-timing-closure` | 基于时钟、路径和报告证据推进时序收敛 |
| `quartus-qor-power-review` | 汇总资源、DRC、流程状态、警告和功耗报告 |
| `fpga-board-programming` | 检测 JTAG 线缆和器件，确认 SOF 并下载到开发板 |
| `quartus-flow-signoff` | 运行编译、仿真、时序、DRC、功耗和归档验收 |
| `quartus-mcp-maintainer` | 维护 MCP tools、README、测试、smoke 检查和 skill 引用一致性 |
## 项目代理
本仓库还在 `.claude/agents` 下提供项目级 Claude Code subagents。
| 代理 | 职责 |
| --- | --- |
| `fpga-spec-architect` | 需求、接口、复位/时钟约定、延迟、验证计划和交接约定 |
| `fpga-rtl-engineer` | 可综合 RTL、顶层一致性、源文件注册和编译检查 |
| `fpga-verification-engineer` | testbench、激励/检查器、通过/失败标记、ModelSim 日志和仿真产物 |
| `fpga-ip-cosim-engineer` | Intel IP、LPM、megafunction 和器件 atom 仿真配置与调试 |
| `quartus-integration-engineer` | 维护 QSF/SDC、源文件、map/fit/asm/STA 和报告的一致性 |
| `fpga-signoff-reviewer` | 最终编译、仿真、时序、DRC、QoR、功耗、归档和开发板下载准备 |
| `quartus-mcp-maintainer` | MCP 服务、README、测试、smoke、skills、agents 和工具发现行为 |
## 可用工具（43）
### 安装
| 工具 | 说明 |
| --- | --- |
| `get_quartus_installation` | 显示 Quartus 路径、版本和可执行文件状态 |
### 项目管理
| 工具 | 说明 |
| --- | --- |
| `create_project` | 创建新工程并设置 family 和 device |
| `open_project` | 打开并验证现有工程后关闭 |
| `close_project` | 说明无状态 close 行为 |
| `get_project_info` | 读取 family、device、revision 和顶层实体 |
| `list_projects` | 递归查找 `.qpf` 工程 |
| `archive_project` | 将工程归档为 `.qar` |
### 编译
| 工具 | 说明 |
| --- | --- |
| `compile_project` | 运行完整或部分流程 |
| `run_analysis_synthesis` | 通过 `quartus_map` 运行分析综合 |
| `run_fitter` | 通过 `quartus_fit` 运行 Fitter |
| `run_assembler` | 通过 `quartus_asm` 运行 Assembler |
| `get_compilation_status` | 查看最近编译状态和产物 |
| `get_compilation_messages` | 提取错误、警告和关键警告 |
### 时序分析
| 工具 | 说明 |
| --- | --- |
| `run_timing_analysis` | 通过 `quartus_sta` 运行静态时序分析 |
| `get_timing_summary` | 读取最新 `.sta.summary` 报告 |
| `get_clock_summary` | 从 STA 输出提取时钟名和周期 |
| `get_timing_paths` | 查询两个节点模式之间的时序路径 |
### 管脚分配和器件
| 工具 | 说明 |
| --- | --- |
| `get_device_families` | 列出支持的器件 family |
| `get_devices` | 列出指定 family 的器件型号 |
| `get_pin_assignments` | 读取管脚分配 |
| `set_pin_assignment` | 给信号分配管脚和可选 I/O 标准 |
| `remove_pin_assignment` | 移除某信号的管脚和 I/O 标准 |
| `get_global_assignments` | 读取全局分配 |
| `set_global_assignment` | 写入全局分配 |
### JTAG 和下载器
| 工具 | 说明 |
| --- | --- |
| `detect_jtag_devices` | 检测 JTAG 器件 |
| `get_programmer_cables` | 列出可用下载线 |
| `program_device` | 通过 JTAG 下载最新 `.sof` |
### 报告和分析
| 工具 | 说明 |
| --- | --- |
| `get_flow_summary` | 读取 flow summary 报告 |
| `get_resource_usage` | 提取资源利用率 |
| `read_report_file` | 读取指定报告类型 |
| `get_power_report` | 运行 `quartus_pow` 并返回功耗报告 |
| `run_design_rule_check` | 运行 `quartus_drc` |
### 文件管理
| 工具 | 说明 |
| --- | --- |
| `list_project_files` | 列出 `.qsf` 中注册的 HDL/SDC/MIF 文件 |
| `add_file_to_project` | 向工程添加文件分配 |
| `remove_file_from_project` | 从 `.qsf` 移除文件分配 |
| `read_qsf` | 读取原始 `.qsf` 文件 |
### ModelSim 仿真
| 工具 | 说明 |
| --- | --- |
| `create_testbench` | 根据顶层端口创建 Verilog testbench |
| `add_simulation_file` | 注册或创建仅仿真使用的 HDL/Tcl 文件 |
| `run_simulation` | 使用工程 HDL、testbench、Intel 仿真库和 IP 脚本运行 ModelSim 批处理仿真 |
| `read_simulation_log` | 读取仿真日志并提取通过、错误和警告信号 |
| `list_simulation_artifacts` | 列出仿真 manifest、日志、波形和 ModelSim 产物 |
### Tcl 脚本
| 工具 | 说明 |
| --- | --- |
| `run_tcl_script` | 通过 `quartus_sh -t` 运行 `.tcl` 文件 |
| `execute_tcl_command` | 通过临时脚本运行内联 Tcl |
## 注意事项与限制
- Programmer/JTAG 相关工具需要连接 FPGA 开发板和下载线。
- ModelSim 仿真需要可用的 ModelSim license。
- 本项目只调用本机命令行工具，不包含 Quartus、ModelSim、Intel IP 或 Intel 仿真库文件。
- `execute_tcl_command` 会在本机执行任意 Tcl，请只运行可信命令。
## 致谢
本项目基于并扩展了 [irumvag/quartus_mcp_server](https://github.com/irumvag/quartus_mcp_server)。该上游项目在 README 中声明采用 MIT license。
感谢 `@irumvag` 的原始 Quartus MCP server 工作。
## 许可证
MIT。详见 [LICENSE](LICENSE)。
