# Quartus II 9.1 MCP Server

用 agent 直接控制 Quartus II 9.1 的本地 MCP server。它把 Quartus 9.1 自带的命令行工具封装成 MCP tools，让 Codex 或其他 MCP client 可以创建工程、解析工程、锁引脚、生成 `.vwf` 仿真波形、运行仿真、编译、读取报告和烧录器件。

这个仓库只包含 MCP server、安装脚本、示例配置和 Codex skill。它不包含 Quartus II 9.1 软件本体，也不包含许可证。使用前需要你已经在自己的电脑上安装了合法可用的 Quartus II 9.1。

## 功能

- 检测 Quartus II 9.1 安装、版本、命令行工具和许可证环境变量。
- 查找并解析 `.qpf/.qsf` 工程。
- 用 Quartus Tcl 创建或更新工程。
- 从已有工程提取可复用模板。
- 通过直接 pin assignment 或 board preset 批量锁引脚。
- 内置 `MAX II EPM1270T144C5` 数字实验板 preset，覆盖 LCM12864 液晶版常用模块。
- 根据结构化或自然语言仿真需求生成 `.vwf` 文件。
- 运行功能仿真、时序仿真、全流程编译或单 stage 编译。
- 读取 report/summary 文件并提取错误、警告、资源和时序摘要。
- 查询 JTAG 硬件并通过 `quartus_pgm` 烧录 `.sof/.pof`。
- 附带 `quartus91-vhdl-flow` Codex skill，让 agent 更稳定地完成“写 VHDL -> 建工程 -> 生成 VWF -> 仿真 -> 编译 -> 锁引脚”的完整流程。

## 前置条件

- Windows，推荐与 Quartus II 9.1 同机运行。
- Node.js 18 或更新版本。
- Quartus II 9.1 已安装，例如：

```text
C:\altera\91\quartus
D:\altera\91\quartus
```

- 如果你的 Quartus 功能需要 license，先在系统或 MCP client 环境里配置 `LM_LICENSE_FILE` 或 `ALTERAD_LICENSE_FILE`。
- Codex 或其他支持 stdio MCP server 的 MCP client。

## 快速安装

Clone 仓库并安装 Node 依赖：

```powershell
git clone https://github.com/<your-github-user>/quartus91-mcp.git
cd quartus91-mcp
npm install
```

检查 server 能否找到 Quartus：

```powershell
$env:QUARTUS91_ROOT = "C:\altera\91\quartus"
npm run smoke
```

如果你是 Codex 用户，可以直接写入 `~\.codex\config.toml`：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install-codex-mcp.ps1 `
  -QuartusRoot "C:\altera\91\quartus"
```

安装配套 Codex skill：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install-codex-skill.ps1
```

然后重启 Codex，让 MCP server 和 skill 生效。

如果已经有旧的 `quartus91` 配置或旧 skill，可以加 `-Force` 覆盖：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install-codex-mcp.ps1 `
  -QuartusRoot "C:\altera\91\quartus" `
  -Force

powershell -ExecutionPolicy Bypass -File .\scripts\install-codex-skill.ps1 -Force
```

## 手动 MCP 配置

Codex `config.toml` 示例：

```toml
[mcp_servers.quartus91]
command = 'node'
args = ['C:\path\to\quartus91-mcp\src\server.js']
startup_timeout_sec = 30
tool_timeout_sec = 1800

[mcp_servers.quartus91.env]
QUARTUS91_ROOT = 'C:\altera\91\quartus'
```

通用 MCP JSON 示例：

```json
{
  "mcpServers": {
    "quartus91": {
      "command": "node",
      "args": [
        "C:\\path\\to\\quartus91-mcp\\src\\server.js"
      ],
      "env": {
        "QUARTUS91_ROOT": "C:\\altera\\91\\quartus"
      }
    }
  }
}
```

如果 `node` 不在 PATH 里，把 `command` 改成 `node.exe` 的绝对路径，例如：

```toml
command = 'C:\Program Files\nodejs\node.exe'
```

## MCP Tools

| Tool | 用途 |
|---|---|
| `quartus_info` | 检测 Quartus 安装路径、版本、bin/bin64 路径、命令行工具和 license 环境。 |
| `quartus_list_projects` | 递归查找 `.qpf` 工程并读取 revisions。 |
| `quartus_inspect_project` | 解析 `.qpf/.qsf`，返回器件、top entity、source files、SDC、pin assignments 等。 |
| `quartus_extract_project_template` | 从已有工程提取可复用的基础设置、source、VWF 和 pins。 |
| `quartus_create_project` | 通过 Quartus Tcl 创建或更新工程/revision。 |
| `quartus_list_board_presets` | 列出内置板级 preset 和可绑定资源。 |
| `quartus_set_pins` | 对已有工程设置直接引脚或 board preset 资源引脚。 |
| `quartus_generate_vwf` | 从信号、时钟、脉冲、事件、bus sequence 生成 `.vwf`。 |
| `quartus_simulate_vwf` | 用 `.vwf/.cvwf/.vec/.tbl/.scf/.vcd` 运行功能或时序仿真。 |
| `quartus_run_flow` | 运行 `quartus_sh --flow`，例如 `compile`。 |
| `quartus_run_stage` | 运行单个 stage，例如 map、fit、asm、sta、tan、sim。 |
| `quartus_run_tcl` | 执行 Quartus Tcl 命令、inline script 或脚本文件。 |
| `quartus_read_report` | 读取并摘要 Quartus report/summary。 |
| `quartus_list_hardware` | 调用 `quartus_pgm -l` 和 `jtagconfig --enum` 列出下载器/JTAG 链。 |
| `quartus_program_device` | 调用 `quartus_pgm` 通过 CDF 或 operation 烧录。 |
| `quartus_open_gui` | 打开 Quartus GUI，可选打开指定工程。 |

## MAX II 实验板 Preset

内置 preset：

```text
maxii_epm1270t144c5_lab
```

默认器件设置：

```text
Family: MAX II
Device: EPM1270T144C5
I/O standard: 3.3-V LVTTL
```

常用资源包括：

- `clock`
- `reset`
- `button`
- `leds`
- `switches`
- `buttons`
- `logic_input_8`
- `logic_output_5`
- `seven_segment_segments`
- `seven_segment_decimal_point`
- `seven_segment_pdf_segments`
- `seven_segment_digits`
- `dot_matrix_rows`
- `dot_matrix_red_cols`
- `dot_matrix_green_cols`
- `buzzer`
- `keypad_rows`
- `keypad_cols`
- `ps2`
- `uart1`
- `uart2`
- `vga`
- `fram`
- `adc_ads7816`
- `dac_tlv5638`
- `i2c_shared`
- `temperature_sensor`
- `eeprom_24lc02`
- `lcd12864_control`
- `lcd12864_data`
- `lcd12864`

完整引脚表在 [skills/quartus91-vhdl-flow/references/maxii-board-preset.md](skills/quartus91-vhdl-flow/references/maxii-board-preset.md)。

## 创建工程示例

```json
{
  "name": "quartus_create_project",
  "arguments": {
    "projectDir": "projects/counter_demo",
    "projectName": "counter_demo",
    "revision": "counter_demo",
    "boardPreset": "maxii_epm1270t144c5_lab",
    "topLevelEntity": "counter_demo",
    "sourceFiles": ["counter_demo.vhd"],
    "resourceBindings": [
      { "resource": "clock", "signal": "clk" },
      { "resource": "reset", "signal": "reset" },
      { "resource": "switches", "signal": "sw", "count": 2 },
      { "resource": "leds", "signal": "led", "count": 8 }
    ]
  }
}
```

## 生成 VWF 示例

```json
{
  "name": "quartus_generate_vwf",
  "arguments": {
    "projectPath": "projects/counter_demo/counter_demo.qpf",
    "outputFile": "counter_demo_stimulus.vwf",
    "attachToProject": true,
    "simulationTime": 500,
    "timeUnit": "ns",
    "requirementsText": "clk 20 ns period; rst_n low for 40 ns then high; din changes every 20 ns starting at 60 ns.",
    "signals": [
      { "name": "clk", "direction": "INPUT" },
      { "name": "rst_n", "direction": "INPUT", "defaultValue": 0 },
      { "name": "din", "width": 8, "direction": "INPUT", "defaultValue": "0x00", "radix": "Hexadecimal" },
      { "name": "done", "direction": "OUTPUT" }
    ],
    "clocks": [
      { "signal": "clk", "period": 20, "dutyCycle": 50 }
    ],
    "events": [
      { "signal": "rst_n", "time": 0, "value": 0 },
      { "signal": "rst_n", "time": 40, "value": 1 }
    ],
    "sequences": [
      { "signal": "din", "width": 8, "start": 60, "step": 20, "values": ["0x01", "0x02", "0x04", "0x08"] }
    ]
  }
}
```

运行功能仿真：

```json
{
  "name": "quartus_simulate_vwf",
  "arguments": {
    "projectPath": "projects/counter_demo/counter_demo.qpf",
    "mode": "functional",
    "timeoutSeconds": 1800
  }
}
```

## Codex Skill

仓库内置 skill：

```text
skills/quartus91-vhdl-flow
```

安装后，Codex 可以在相关请求中自动触发，也可以显式输入：

```text
Use $quartus91-vhdl-flow to create a VHDL project for the MAX II board, generate a .vwf stimulus file, lock pins, and run a functional simulation.
```

这个 skill 会指导 agent：

- 用 Quartus II 9.1 兼容的 VHDL 写法。
- 根据用户的自然语言仿真需求生成 `.vwf`。
- 优先使用 `maxii_epm1270t144c5_lab` preset 锁引脚。
- 避免 VGA/LED、I2C、数码管小数点等共享引脚冲突。
- 先 dry-run 不确定的仿真/编译命令，再实际运行。

## 测试

```powershell
npm run smoke
```

smoke test 会真实启动 MCP server，并检查：

- MCP tools 能否列出。
- `quartus_info` 是否能找到 Quartus。
- 示例工程解析是否可用。
- 临时工程创建是否可用。
- `.vwf` 生成和 QSF 挂载是否可用。
- board preset 引脚展开是否可用。
- 仿真和编译命令 dry-run 是否可用。

## 注意事项

- Quartus II 9.1 很老，现代 SystemVerilog、VHDL-2008、Tcl 或 SDC 特性不一定兼容。
- 编译、仿真和烧录都会启动真实 Quartus 子进程；不确定参数时先使用支持 `dryRun` 的工具。
- 烧录前先调用 `quartus_list_hardware`，确认 cable 和 JTAG 链。
- `QUARTUS91_ROOT` 应指向 Quartus 的 `quartus` 目录，或传给安装脚本一个包含 `quartus` 子目录的安装根目录。
- 这个仓库的 MAX II 引脚 preset 来自历史 Quartus 工程和 MAXII 数字实验板 LCM12864 版资料整理。请以你手头板卡原理图为最终依据。

## License

MIT. See [LICENSE](LICENSE).