# vivadoer

**Repository Path**: johnzchgrd/vivadoer

## Basic Information

- **Project Name**: vivadoer
- **Description**: Yet another MCP for vivado
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-08
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vivadoer

Vivado MCP 服务器，基于官方 MCP Python SDK 实现，通过 stdio 与 IDE 交互，经 TCP 与 Vivado Tcl 服务通信。

## 功能

- **连接**: 测试连接、扫描/切换 Vivado 实例、版本查询、许可证状态、任意 Tcl 执行 (`eval_tcl`)
- **项目**: 创建、打开、关闭、获取信息
- **源文件**: 添加/移除 RTL/XDC、设置顶层、宏定义管理
- **IP**: 目录查询、参数查看、创建/删除/配置
- **综合/实现**: 同步/异步运行、策略设置、Run 诊断、日志与报告
- **报告**: 资源利用率、时序、拥塞、路由状态、DRC
- **约束**: 时钟/IO 约束、保存约束文件
- **硬件**: JTAG 目标扫描、器件编程
- **调试**: ILA 触发/捕获/CSV 导出、VIO 读写

## 安装

```bash
pip install -e .
```

## 使用

### 1. 启动 Vivado Tcl 服务

在 Vivado Tcl Console 执行：

```tcl
set port 9999
socket -server {apply {
    if {[catch {puts $sock "OK"; flush $sock}]} return
    while {[gets $sock cmd] >= 0} {
        if {[catch {set result [eval $cmd]} err]} { puts $sock "ERROR: $err" } { puts $sock $result }
        puts $sock "<<<END>>>"; flush $sock
    }
    close $sock
}} $port
puts "Tcl server started on port $port"
```

服务端逐行读取，用 `;` 串联多句 Tcl。返回值为最后一条命令的 Tcl 返回值，非 `puts` 输出。需返回多行文本时，让最后一条表达式产生该字符串。

### 2. IDE 配置

仓库提供 `.cursor/mcp.json`，以本仓库为工作区根目录时自动生效。也可放在用户全局配置 `%USERPROFILE%\.cursor\mcp.json`。

配置要点：

| 项 | 说明 |
|---|---|
| 入口 | `vivadoer/server.py`，自动检测 Content-Length / NDJSON，无需区分 IDE |
| 工作区 | 打开仓库根目录（含 `setup.py`），确保 `${workspaceFolder}` 和 `PYTHONPATH` 正确 |
| Python | 建议 `python -u` 无缓冲；若 `PATH` 有误可改用 `py -3 -u` 或写绝对路径 |

可选环境变量（写在 `mcp.json` 的 `env`）：

- `VIVADOER_MCP_LOG`：诊断日志路径
- `VIVADOER_MCP_DEBUG=1`：在日志中记录每条 MCP 方法名
- `VIVADOER_MCP_DEBUG_STDERR=1`：同时输出到 stderr

安装后也可用 `vivadoer-server` 或 `python -m vivadoer` 启动。

配置保存后重载 MCP 或重启 IDE。

## 项目结构

```
vivadoer/
├── vivado_client.py      # Vivado TCP socket 客户端
├── vivado_tools.py       # 工具实现 (~80 接口)
├── server.py             # MCP 服务器 (SDK + 自动协议检测)
├── tools/                # 工具 JSON Schema 定义
└── replay_trace.py       # JSONL trace 重放

tests/                    # unittest
├── test_mcp_server_unit.py
├── test_mcp_stdio_subprocess.py
├── test_ip_tools.py
├── test_hw_debug_tools.py
├── test_hardware_tools.py
└── test_vivado_live.py   # 需真实 Vivado，默认跳过

testcases/
├── water_led/            # 全流程 + Run 诊断 trace
└── ip_demo/              # FIFO + ILA + VIO trace
```

## 接口

### 连接 (6)

| 接口 | 说明 |
|------|------|
| `test_connection` | 测试连接状态 |
| `eval_tcl` | 执行任意 Tcl，返回 eval 结果。仅用于可信输入 |
| `list_vivado` | 扫描运行中的 Vivado 实例 |
| `switch_vivado` | 切换实例 |
| `vivado_version` | 版本信息 |
| `get_license_status` | 许可证状态 |

### 项目 (4)

| 接口 | 说明 |
|------|------|
| `create_project` | 创建项目 |
| `open_project` | 打开项目 |
| `close_project` | 关闭项目 |
| `get_project_info` | 项目详情 |

### 源文件 (6)

| 接口 | 说明 |
|------|------|
| `add_source_file` | 添加 RTL |
| `add_constraint_file` | 添加 XDC |
| `set_top_module` | 设置顶层 |
| `list_source_files` | 列出源文件 |
| `list_constraint_files` | 列出约束文件 |
| `remove_file` | 移除文件 |

### IP (5)

| 接口 | 说明 |
|------|------|
| `list_ip_catalog` | 列出 IP 目录，`pattern` 建议收窄 |
| `get_ipdef_parameters` | 按 VLNV 查参数及默认值 |
| `create_ip` | 创建 IP 实例，可选 `config` |
| `remove_ip` | 移除实例 |
| `get_ip_config` | 读取实例当前配置 |

### 综合 (6)

| 接口 | 说明 |
|------|------|
| `run_synthesis` | 同步运行 |
| `run_synthesis_async` | 异步启动 |
| `get_run_status` | 运行状态 |
| `get_synthesis_report` | 综合报告 |
| `get_synthesis_warnings` | 综合警告 |
| `set_synthesis_strategy` | 设置策略 |
| `open_synthesized_design` | 打开综合后设计 |

### Run 诊断 (2)

| 接口 | 说明 |
|------|------|
| `get_run_messages` | 读取 STATUS/PROGRESS/ERRORS/WARNINGS |
| `get_run_log` | 读取日志，支持 severity 过滤与截断 |

### 实现 (5)

| 接口 | 说明 |
|------|------|
| `run_implementation` | 同步运行 |
| `run_implementation_async` | 异步启动 |
| `run_full_flow` | 综合→实现→比特流 |
| `set_implementation_strategy` | 设置策略 |
| `open_implemented_design` | 打开实现后设计 |

### 比特流与导出 (2)

| 接口 | 说明 |
|------|------|
| `generate_bitstream` | 生成比特流 |
| `export_hardware` | 导出 XSA |

### 报告 (9)

| 接口 | 说明 |
|------|------|
| `report_congestion` | 拥塞报告 |
| `report_route_status` | 路由状态 |
| `get_implementation_warnings` | 实现警告 |
| `report_utilization` | 资源利用率 |
| `report_utilization_hierarchical` | 分层利用率 |
| `report_timing_summary` | 时序摘要 |
| `report_timing_detail` | 详细时序 |
| `report_worst_timing_paths` | 最差路径 |
| `report_drc` | DRC 报告 |

### 约束 (5)

| 接口 | 说明 |
|------|------|
| `create_clock_constraint` | 时钟约束 |
| `create_io_constraint` | IO 约束 |
| `get_all_clocks` | 列出时钟 |
| `get_clock_info` | 时钟信息 |
| `save_constraints` | 保存约束 |

### 文件操作 (6)

| 接口 | 说明 |
|------|------|
| `create_source_file` | 创建源文件 |
| `create_constraint_file` | 创建约束文件 |
| `read_file` | 读文件 |
| `list_all_files` | 列出文件 |
| `append_to_file` | 追加内容 |
| `read_file_lines` | 读指定行范围 |

### 设备编程 (8)

| 接口 | 说明 |
|------|------|
| `open_hardware_manager` | 打开 Hardware Manager |
| `connect_hardware_server` | 连接 hw_server |
| `list_hardware_targets` | 列出 JTAG 目标 |
| `open_hardware_target` | 打开目标，不传时取第一个 |
| `list_hardware_devices` | 列出设备 |
| `program_device` | 下载比特流 |
| `disconnect_hardware` | 断开 |

### 硬件调试 (12)

前置：Hardware Manager 已打开、hw_server 已连接、目标已打开、已编程且含 Debug Hub。

| 接口 | 说明 |
|------|------|
| `list_hw_ilas` | 列出 ILA |
| `list_hw_vios` | 列出 VIO |
| `list_hw_probes` | 列出探针，`parent`: `ila` / `vio` |
| `ila_arm` | 武装 ILA |
| `ila_wait_capture` | 等待捕获完成 |
| `ila_upload_data` | 上传数据 |
| `ila_export_csv` | 导出 CSV，读回后返回预览 |
| `ila_reset` | 重置 ILA |
| `ila_configure_triggers` | 批量设置触发条件 |
| `ila_capture_to_csv` | upload + 写 CSV，`arm_and_wait` 默认 false |
| `vio_set_probe_values` | 设 OUTPUT_VALUE 并 commit |
| `vio_get_probe_values` | 读 INPUT_VALUE / OUTPUT_VALUE，可选 refresh |

### 其他 (2)

| 接口 | 说明 |
|------|------|
| `get_help` | Tcl 命令帮助 |
| `list_fpga_parts` | 列出器件型号，可选 `regexp_pattern` |

## 测试

```bash
python -m unittest discover -s tests -p "test_*.py" -v
```

| 模块 | 说明 |
|------|------|
| `test_mcp_server_unit` | 进程内工具加载与 VivadoTools 方法检查 |
| `test_mcp_stdio_subprocess` | 子进程 Content-Length / NDJSON 双链路 |
| `test_ip_tools` | Mock IP 相关接口 |
| `test_hw_debug_tools` | Mock ILA/VIO |
| `test_hardware_tools` | Mock 硬件目标 |
| `test_vivado_live` | 真实 Vivado TCP，默认跳过 |

联调环境变量：

| 变量 | 说明 |
|------|------|
| `VIVADOER_LIVE=1` | 运行 `test_vivado_live` |
| `VIVADOER_IP_INTEGRATION=1` | 运行 IP 集成测试 |

单文件运行：

```bash
python -m unittest tests.test_ip_tools -v
```

## Trace 重放

将 IDE 录制的 `vivadoer-trace/v1` JSONL 按 MCP `tools/call` 方式调用 `VivadoTools`，用于复现与排障。

内置用例：
- `testcases/water_led/vivadoer.trace.jsonl` — 全流程 + Run 诊断
- `testcases/ip_demo/vivadoer.trace.jsonl` — FIFO + ILA + VIO

常用命令：

```bash
# dry-run，仅打印
python -m vivadoer.replay_trace testcases/water_led/vivadoer.trace.jsonl

# 列出 scenario
python -m vivadoer.replay_trace testcases/water_led/vivadoer.trace.jsonl --list-scenarios

# 执行指定 scenario（需 Vivado Tcl 服务在 --port 指定端口）
python -m vivadoer.replay_trace testcases/water_led/vivadoer.trace.jsonl --scenario from_scratch --execute --port 9999

# 映射到其它目录
python -m vivadoer.replay_trace testcases/water_led/vivadoer.trace.jsonl --workspace D:/path/to/testcases

# 字符串替换
python -m vivadoer.replay_trace testcases/water_led/vivadoer.trace.jsonl --replace C:/old=C:/new
```

默认 dry-run，避免误操作。执行需显式加 `--execute`。

## 添加新工具

1. `vivadoer/tools/<name>.json` — JSON Schema
2. `vivadoer/vivado_tools.py` — 实现方法
3. `tests/` — 补充 unittest

示例：

```json
{
  "name": "my_tool",
  "description": "...",
  "inputSchema": {
    "type": "object",
    "properties": {
      "param": {"type": "string"}
    },
    "required": ["param"]
  }
}
```

```python
def my_tool(self, param: str, **kwargs) -> Dict[str, Any]:
    client = self._get_client()
    ...
    return {"success": True}
```

## License

MIT