Content
# FPGA Pilot MCP Server
> 🤖 AI-Powered Xilinx Vivado Automation — Let AI control your FPGA development workflow via MCP protocol.
[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 |
|----------|-------------|
| **Project Management** | Create/open/close projects, add sources & constraints, set top module |
| **Synthesis & Implementation** | Smart launch with state tracking, auto-error extraction, incremental mode |
| **Simulation** | Compile + elaborate + run, waveform probing with time-range sampling |
| **IP Generation** | Clock Wizard, Block Memory, FIFO, ILA, AXI GPIO |
| **Reporting** | Utilization, timing summary, DRC, methodology checks, clock networks |
| **Smart Workflow** | File change detection (MD5), auto re-run on source changes, state-aware launch |
### Requirements
- Windows (tested on Windows 11)
- Xilinx Vivado (2019.1+)
- Python 3.10+
- Claude Code (or any MCP-compatible AI agent)
### Quick Start
```bash
# 1. Clone
git clone https://github.com/YJ559/fpga-pilot.git
cd fpga-pilot
# 2. Install dependencies
python -m venv .venv
.venv\Scripts\activate
pip install mcp
# 3. Configure Claude Code
# Add to .claude/settings.local.json:
{
"mcpServers": {
"fpga-pilot": {
"command": "python",
"args": ["path/to/brain.py"]
}
}
}
# 4. Launch Vivado, then let AI take over
# In Claude Code: "Create a project for xc7z020, add my top module, and run synthesis"
```
### Usage Examples
**Create a project and run full flow:**
```
> Create a Vivado project named "my_design" for xc7z020clg400-2
> Add touch_detector.v, water_light_ctrl.v, and constraints.xdc
> Set top module to touch_led_water
> Run synthesis and implementation
```
**Generate IP cores:**
```
> Create a 100MHz to 50MHz clock wizard
> Create a 1024x32 Block RAM
> Create an ILA with 4 probes for debugging
```
**Run simulation and probe signals:**
```
> Compile and run tb_counter simulation
> Probe counter[7:0] and enable from 0ns to 1us
```
### Project Structure
```
fpga_pilot/
├── brain.py # MCP server entry (21 tools)
├── fpga_pilot_mcp.py # Atomic tool library (28 functions)
├── brain/ # Intelligence layer
│ ├── planner.py # Decision engine
│ ├── executor.py # Workflow orchestrator
│ ├── state_machine.py # 10-state Vivado run manager
│ ├── source_tracker.py # MD5 file change detection
│ ├── ip_factory.py # IP core generators
│ ├── launcher.py # Vivado auto-launch
│ └── atomic_bridge.py # Bridge abstraction
├── vivado/ # Vivado Tcl bridge
│ ├── fpga_pilot_bridge.tcl # TCP server (31 commands)
│ └── auto_start.tcl # Auto-load script
├── test_*.py # Test suite
├── PROJECT_CONTEXT.md # Architecture docs (中文)
└── IMPLEMENTATION_FLOW.md # Implementation history (中文)
```
---
## 中文
**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.**
