内容
# FPGA Pilot MCP 服务器
> 🤖 AI 驱动的 Xilinx Vivado 自动化 — 让 AI 通过 MCP 协议控制你的 FPGA 开发流程。
[English](#english) | [中文](#中文)
---
## English
**FPGA Pilot** is a Model Context Protocol (MCP) server that bridges AI agents (such as Claude) with Xilinx Vivado. It enables autonomous FPGA development — project creation, synthesis, implementation, simulation, and IP core generation — all driven by natural language.
### Architecture
```
Claude Code / AI Agent
│
▼ MCP Protocol (JSON-RPC)
brain.py (21 Tools)
│
▼
Brain Layer (Python)
├── Planner → Decision engine
├── Executor → Workflow orchestration
├── StateMachine → 10-state run manager
├── SourceTracker → MD5 change detection
├── IPFactory → 5 IP core generators
│
▼ TCP (127.0.0.1:10098)
fpga_pilot_bridge.tcl (31 Commands)
│
▼ Tcl API
Xilinx Vivado
```
### Features
| Category | Capabilities |
|----------|-------------|
| **项目管理** | 创建/打开/关闭工程，添加源文件和约束，设置顶层模块 |
| **综合与实现** | 智能启动（带状态追踪），自动提取错误，增量模式 |
| **仿真** | 编译+细化+运行，波形探测（时间范围采样） |
| **IP 核生成** | 时钟向导、Block Memory、FIFO、ILA、AXI GPIO |
| **报告** | 资源利用率、时序摘要、DRC、方法论检查、时钟网络 |
| **智能工作流** | 文件变更检测（MD5），源文件变更自动重跑，状态感知启动 |
### Requirements
- Windows（Windows 11 测试通过）
- Xilinx Vivado 2019.1+
- Python 3.10+
- Claude Code（或任何兼容 MCP 的 AI 代理）
### Quick Start
```bash
# 1. 克隆仓库
git clone https://github.com/YJ559/fpga-pilot.git
cd fpga-pilot
# 2. 安装依赖
python -m venv .venv
.venv\Scripts\activate
pip install mcp
# 3. 配置 Claude Code
# 在 .claude/settings.local.json 中添加:
{
"mcpServers": {
"fpga-pilot": {
"command": "python",
"args": ["path/to/brain.py"]
}
}
}
# 4. 启动 Vivado，然后用自然语言驱动 FPGA 开发
```
### Usage Examples
**创建工程并运行全流程：**
```
> 为 xc7z020clg400-2 创建一个名为 "my_design" 的 Vivado 工程
> 添加 touch_detector.v、water_light_ctrl.v 和 constraints.xdc
> 设置顶层模块为 touch_led_water
> 运行综合和实现
```
**生成 IP 核：**
```
> 创建一个 100MHz 转 50MHz 的时钟向导
> 创建一个 1024x32 的 Block RAM
> 创建一个带 4 个探针的 ILA 用于调试
```
**仿真与波形探测：**
```
> 编译并运行 tb_counter 仿真
> 从 0ns 到 1us 探测 counter[7:0] 和 enable 信号
```
### 项目结构
```
fpga_pilot/
├── brain.py # MCP 服务器入口（21 个工具）
├── fpga_pilot_mcp.py # 原子工具库（28 个函数）
├── brain/ # 智能层
│ ├── planner.py # 决策引擎
│ ├── executor.py # 工作流编排
│ ├── state_machine.py # 10 状态 Vivado 运行管理器
│ ├── source_tracker.py # MD5 文件变更检测
│ ├── ip_factory.py # IP 核生成器
│ ├── launcher.py # Vivado 自动启动
│ └── atomic_bridge.py # 桥抽象
├── vivado/ # Vivado Tcl 桥
│ ├── fpga_pilot_bridge.tcl # TCP 服务器（31 条命令）
│ └── auto_start.tcl # 自动加载脚本
├── test_*.py # 测试套件
├── PROJECT_CONTEXT.md # 架构文档（中文）
└── IMPLEMENTATION_FLOW.md # 实现历史（中文）
```
---
## 中文
**FPGA Pilot** 是一个 MCP（Model Context Protocol）服务器，连接 AI 代理与 Xilinx Vivado，实现 FPGA 开发全流程的 AI 驱动自动化。
### 架构
```
AI 代理 (Claude Code 等)
│
▼ MCP 协议 (JSON-RPC)
brain.py (21 个工具)
│
▼
大脑层 (Python)
├── Planner → 决策引擎
├── Executor → 工作流编排
├── StateMachine → 10 状态运行管理
├── SourceTracker → MD5 变更检测
└── IPFactory → 5 种 IP 核生成器
│
▼ TCP (127.0.0.1:10098)
fpga_pilot_bridge.tcl (31 条命令)
│
▼ Tcl API
Xilinx Vivado
```
### 功能
| 类别 | 能力 |
|------|------|
| **项目管理** | 创建/打开/关闭工程，添加源文件和约束，设置顶层模块 |
| **综合与实现** | 智能启动（带状态追踪），自动提取错误，增量模式 |
| **仿真** | 编译+细化+运行，波形探测（时间范围采样） |
| **IP 核生成** | 时钟向导、Block Memory、FIFO、ILA、AXI GPIO |
| **报告** | 资源利用率、时序摘要、DRC、方法论检查、时钟网络 |
| **智能工作流** | 文件变更检测（MD5），源文件变更自动重跑，状态感知启动 |
### 环境要求
- Windows（Windows 11 测试通过）
- Xilinx Vivado 2019.1+
- Python 3.10+
- Claude Code（或任何兼容 MCP 的 AI 代理）
### 快速开始
```bash
# 1. 克隆仓库
git clone https://github.com/YJ559/fpga-pilot.git
cd fpga-pilot
# 2. 安装依赖
python -m venv .venv
.venv\Scripts\activate
pip install mcp
# 3. 配置 Claude Code
# 在 .claude/settings.local.json 中添加:
{
"mcpServers": {
"fpga-pilot": {
"command": "python",
"args": ["path/to/brain.py"]
}
}
}
# 4. 启动 Vivado，然后用自然语言驱动 FPGA 开发
```
### 使用示例
**创建工程并运行全流程：**
```
> 为 xc7z020clg400-2 创建一个名为 "my_design" 的 Vivado 工程
> 添加 touch_detector.v、water_light_ctrl.v 和 constraints.xdc
> 设置顶层模块为 touch_led_water
> 运行综合和实现
```
**生成 IP 核：**
```
> 创建一个 100MHz 转 50MHz 的时钟向导
> 创建一个 1024x32 的 Block RAM
> 创建一个带 4 个探针的 ILA 用于调试
```
**仿真与波形探测：**
```
> 编译并运行 tb_counter 仿真
> 从 0ns 到 1us 探测 counter[7:0] 和 enable 信号
```
---
## License
MIT © 2025 Yu Jie Zhang
## Contributing
Issues and pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
---
**Made with FPGA passion and AI power.**
