内容
# surfer-mcp
一个MCP服务器,允许AI助手控制 [Surfer](https://surfer-project.org/),一个用于硬件设计和验证的开源波形查看器。它通过 [波形通信协议(WCP)](https://surfer-project.org/wcp.html) 与Surfer通信,也可以直接通过 [pywellen](https://github.com/ekiwi/pywellen) 读取波形文件。
## 功能
- **加载和重新加载** 波形文件(VCD、FST、GHW等)
- **浏览层次结构** — 列出设计中的作用域和信号
- **控制查看器** — 添加/删除信号,设置光标位置,缩放,设置视口范围,添加标记,改变信号颜色
- **读取信号数据** — 获取时间戳的值,查找边缘,搜索值,获取时间窗口内的所有转换
- **截图** Surfer窗口(macOS)
## 要求
- Python 3.10+
- [Surfer](https://surfer-project.org/) 已安装并在您的 `PATH` 中
- macOS(截图功能使用Quartz;其他功能跨平台工作,如果您删除 `pyobjc` 依赖)
## 安装
```bash
# 克隆仓库
git clone https://github.com/PaoloRondot/surfer-mcp.git
cd surfer-mcp
# 使用 uv 安装(推荐)
uv pip install -e .
# 或使用 pip
pip install -e .
```
## 与 Claude Code 一起使用
将以下内容添加到您的 Claude Code MCP 设置(`~/.claude/settings.json` 或项目 `.mcp.json`):
```json
{
"mcpServers": {
"surfer": {
"command": "uv",
"args": ["run", "--directory", "/path/to/surfer-mcp", "surfer-mcp"]
}
}
}
```
或如果您已全局安装:
```json
{
"mcpServers": {
"surfer": {
"command": "surfer-mcp"
}
}
}
```
## 与其他 MCP 客户端一起使用
服务器通过 **stdio** 运行。启动它:
```bash
surfer-mcp
```
或在不安装的情况下:
```bash
uv run --directory /path/to/surfer-mcp surfer-mcp
```
## 可用工具
| 工具 | 描述 |
|------|-------------|
| `load_waveform` | 将波形文件加载到 Surfer 中 |
| `reload_waveform` | 重新加载当前波形 |
| `list_scopes` | 列出层次结构中的所有作用域(模块/实例) |
| `list_signals` | 列出作用域内的信号 |
| `add_signals` | 按名称将信号添加到查看器 |
| `add_scope` | 添加作用域中的所有信号 |
| `add_items` / `remove_items` | 添加或删除项目,路径/ID |
| `get_item_list` / `get_item_info` | 查询显示的项目 |
| `set_cursor` | 将光标移动到时间戳 |
| `set_viewport_range` / `set_viewport_to` | 控制可见的时间范围 |
| `zoom_to_fit` | 缩放以适应所有数据 |
| `add_markers` | 添加命名的时间标记 |
| `focus_item` | 滚动到项目 |
| `set_item_color` | 更改信号显示颜色 |
| `get_signal_values` | 读取时间戳的信号值 |
| `find_rising_edge` / `find_falling_edge` | 查找信号的下一个边缘 |
| `find_value` | 查找特定值的下一个出现 |
| `get_transitions` | 获取时间窗口内的所有转换 |
| `get_time_range` | 获取仿真时间范围和时间尺度 |
| `screenshot` | 捕获 Surfer 窗口(macOS) |
| `clear` | 从查看器中清除所有项目 |
| `shutdown_surfer` | 关闭 Surfer |
## 工作原理
当工具第一次调用时,服务器会自动:
1. 启动 Surfer 并启用 WCP
2. 连接 TCP 并执行 WCP 握手
3. 发送命令并返回结果
Surfer 进程在工具调用之间保持运行,以便您可以交互式地探索波形。
## 许可证
MIT