# PDM MCP Server

AI 驱动的 FPGA 功耗评估助手 — 将 Xilinx Power Design Manager (PDM) 的 Python API 封装为 MCP (Model Context Protocol) 服务，供 AI Agent 通过自然语言进行功耗建模与分析。

## 前置条件

- **Python** ≥ 3.10
- **Xilinx PDM** (Power Design Manager) 已安装
  - PDM 的 Python API (`xv_pdm_pytasks`) 必须可用
  - 安装路径会被自动检测（详见下方「PDM 路径配置」）

## 安装

### 从源码安装

```bash
git clone <repo-url>
cd pdm_mcp
pip install .
```

安装后可使用 `pdm-mcp` 命令：

```bash
pdm-mcp version   # 显示版本
pdm-mcp serve     # 启动 MCP server
```

### PDM 路径配置

MCP Server 启动时会按以下优先级自动查找 PDM 安装路径：

1. `PDM_HOME` 环境变量 → `$PDM_HOME/pdm.bat`
2. 项目根目录的 `path.txt` 文件（格式：`PDM：H:\path\to\PDM\bin`）
3. 系统 `PATH` 中的 `pdm.bat` / `pdm`
4. 默认安装路径回退（`C:/Xilinx/*/PDM/bin/pdm.bat` 等）

若自动检测失败，可创建 `path.txt` 指定路径，或设置环境变量：

```bash
set PDM_HOME=H:\AMDDesignTools\PDM_2026.1\PDM\bin
```

## MCP 客户端配置

在 AI 客户端（如 Kimi Code、Claude Desktop 等）中添加 MCP Server 配置：

```json
{
  "mcpServers": {
    "pdm-mcp": {
      "command": "pdm-mcp",
      "args": ["serve"]
    }
  }
}
```

如果未安装到系统 PATH，指定完整路径：

```json
{
  "mcpServers": {
    "pdm-mcp": {
      "command": "python",
      "args": ["-m", "pdm_mcp", "serve"],
      "cwd": "H:/path/to/pdm_mcp"
    }
  }
}
```

## 使用

MCP Server 提供 **10 个工具**，每个工具通过 `action` 参数选择具体操作。

---

### 1. `session` — 会话管理

| action | 参数 | 说明 |
|---|---|---|
| `start` | `session_id` (默认 `"default"`), `mode` (默认 `"py"`), `pdm_path`, `timeout` | 启动 PDM 子进程会话 |
| `stop` | `session_id` | 关闭指定会话 |
| `list` | 无 | 列出所有活跃会话 |

```python
session(action="start")
session(action="list")
session(action="stop", session_id="my_session")
```

---

### 2. `project` — 项目管理

| action | 关键参数 | 说明 |
|---|---|---|
| `open` | `path` | 打开 .pdm 项目文件 |
| `create` | `name`, `part` | 创建新项目 |
| `close` | 无 | 关闭当前项目 |
| `save` | `save_path` (可选) | 保存/另存为 |
| `info` | 无 | 项目基本信息 |
| `list_blocks` | 无 | 列出所有 Block |
| `list_architectures` | 无 | 列出可用 FPGA 架构 |
| `list_parts` | `architecture`, `package_filter` | 筛选器件型号 |
| `list_processes` | 无 | 列出工艺角 (Maximum/Typical) |
| `select_part` | `part`, `process` | 更换器件 |
| `import_xpe` | `file`, `append` | 导入 XPE 文件 |
| `export_xdc` | `file`, `thermal`, `rails`, `overwrite` | 导出 XDC 约束 |
| `export_power_design` | `file`, `overwrite` | 导出 Power Design XML |
| `reset` | 无 | 重置项目数据 |

```python
project(action="open", path="my_design.pdm")
project(action="save")
project(action="info")
project(action="list_parts", architecture="Artix-7", package_filter="csg324")
```

---

### 3. `power` — 功耗查询

| action | 关键参数 | 说明 |
|---|---|---|
| `summary` | 无 | 总功耗摘要（自动保存快照） |
| `block_power` | `block_name` | 指定 Block 功耗分解 |
| `rails` | 无 | 电源轨电压/电流/功耗 |
| `thermal` | 无 | 热分析（结温/θ-JA/裕量） |
| `clock_power` | 无 | 各时钟域功耗 |
| `export_report` | `output_path` | 导出功耗报告 |

```python
power(action="summary")
power(action="block_power", block_name="logic")
power(action="export_report", output_path="report.txt")
```

---

### 4. `scenario` — 场景配置

| action | 关键参数 | 说明 |
|---|---|---|
| `set_environment` | `temp`, `airflow`, `heatsink` | 温度/风流量/散热器 |
| `set_clock_frequency` | `name`, `freq_mhz` | 修改时钟频率 |
| `set_toggle_rate` | `block`, `pct` | 修改翻转率 |
| `set_resource_util` | `block`, `lut`, `ff`, `bram`, `dsp` | 修改资源用量（绝对数量） |
| `recalculate` | 无 | 触发功耗重算 |
| `compare` | 无 | 对比两次功耗快照 |

```python
scenario(action="set_environment", temp=85, airflow=250, heatsink="medium")
scenario(action="set_clock_frequency", name="clk_main", freq_mhz=200)
scenario(action="set_resource_util", block="logic", lut=50000, ff=60000, bram=80, dsp=100)
scenario(action="recalculate")
scenario(action="compare")
```

---

### 5. `clock` — 时钟管理

| action | 关键参数 | 说明 |
|---|---|---|
| `list` | 无 | 列出所有时钟 |
| `create` | `name`, `freq`, `io_type`, `io_standard`, `is_gated`, `min_freq` | 创建时钟 |
| `delete` | `name` | 删除时钟 |
| `edit` | `name`, `freq`, `io_type`, ... | 编辑时钟参数 |
| `settings` | `name` | 获取时钟设置 |
| `sample_settings` | 无 | 获取示例设置模板 |
| `replace` | `name`, `other`, `blocks` | 替换时钟引用 |
| `mgr_types` | 无 | 列出时钟管理器类型 |
| `mgr_list` | 无 | 列出现有时钟管理器 |
| `mgr_create` | `name`, `type`, `input_clock`, `vco_range` | 创建时钟管理器 |
| `mgr_delete` | `name` | 删除时钟管理器 |
| `mgr_settings` | `name` | 获取时钟管理器设置 |

```python
clock(action="create", name="clk_200", freq=200, io_type="HD")
clock(action="mgr_create", name="mmcm1", type="MMCM", input_clock="clk_200")
```

---

### 6. `ip` — IP 核管理

| action | 关键参数 | 说明 |
|---|---|---|
| `types` | 无 | 列出可用 IP 类型 |
| `list` | `ip_type` | 列出指定类型的 IP 实例 |
| `create` | `ip_type`, `ip_name` | 创建 IP |
| `delete` | `ip_type`, `ip_name` | 删除 IP |
| `settings` | `ip_type`, `ip_name` | 获取 IP 当前设置 |
| `sample_settings` | `ip_type` | 获取 IP 设置模板 |

```python
ip(action="types")
ip(action="list", ip_type="GTH")
ip(action="create", ip_type="GTH", ip_name="gth_0")
```

---

### 7. `power_design` — 电源设计

| action | 关键参数 | 说明 |
|---|---|---|
| `info` | 无 | 电源域/电源名称概览 |
| `rail_characteristics` | 无 | 电源轨特性详情 |
| `delivery_design` | 无 | 电源交付设计汇总 |
| `set_consolidation` | `mode` | 设置电源轨整合模式 |

```python
power_design(action="info")
power_design(action="rail_characteristics")
power_design(action="set_consolidation", mode="Consolidated")
```

---

### 8. `vivado` — Vivado 数据导入

| action | 关键参数 | 说明 |
|---|---|---|
| `import_report` | `report_path`, `label` | 导入 Vivado 功耗报告 |
| `compare` | `label` | 与 PDM 结果逐项对比 |
| `import_utilization` | `util_report_path`, `block_name` | 导入利用率报告 |

```python
vivado(action="import_report", report_path="post_route_power.rpt")
vivado(action="compare", label="vivado_import")
vivado(action="import_utilization", util_report_path="utilization.rpt")
```

---

### 9. `estimate` — 快速估算（无需 PDM 会话）

| action | 关键参数 | 说明 |
|---|---|---|
| `quick` | `part`, `clock_mhz`, `lut_pct`, ... | 快速功耗估算 (±40%) |
| `recommend` | `budget`, `logic_cells`, `family` | 根据预算推荐器件 |
| `families` | 无 | 列出支持的 FPGA 系列 |

```python
estimate(action="quick", part="xc7a100tcsg324-1", clock_mhz=200, lut_pct=60)
estimate(action="recommend", budget=3.0, logic_cells=50000, family="7series")
estimate(action="families")
```

---

### 10. `explore` — 属性探索

| action | 关键参数 | 说明 |
|---|---|---|
| `block_resources` | `block` | 列出 Block 的资源名 |
| `block_summaries` | `block` | 列出 Block 的汇总表名 |
| `resource_info` | `block`, `resource` | 获取资源字段名/记录名 |
| `resource_defaults` | `block`, `resource` | 获取资源默认值 |
| `resource_valid_values` | `block`, `resource`, `fields` | 获取字段有效值范围 |
| `summary_info` | `target`, `summary` | 获取汇总表详情 |
| `list_property` | `target` | 列出对象属性名 |
| `report_property` | `target`, `pattern`, `all_props`, `detail` | 报告对象属性 |
| `reset_property` | `target`, `prop` | 重置属性为默认值 |

```python
explore(action="block_resources", block="logic")
explore(action="resource_defaults", block="logic", resource="logic_config")
explore(action="report_property", target="project", pattern="*", all_props=True)
```

---

## 使用模板

以下是常见场景的操作模板。直接将这些指令告诉 AI Agent 即可。

---

### 模板 A：设计前期最大功耗快速评估（无 PDM 项目）

> 器件尚未确定，需要快速估算最坏情况功耗，给出电源设计余量。

```
1. 调用 estimate(action="families")，了解有哪些 FPGA 系列可选。
2. 用 estimate(action="quick") 做粗估。关键参数：
   - part: 候选器件，如 "xc7a100tcsg324-1"
   - clock_mhz: 主时钟频率
   - lut_pct / ff_pct / bram_pct / dsp_pct: 设为预期的最大值（如 80-90）
   - io_count / io_standard / io_toggle: IO 数量和翻转率
   - temp / airflow / heatsink: 环境条件
3. 多选几个候选器件重复 quick 估算，比较结温。
4. 用 estimate(action="recommend")，传入功耗预算和资源需求，验证选型。
5. 电源余量建议：总功耗 × 1.3 ~ 1.5 作为电源设计目标。
```

**示例对话**：
```
用户: 我在设计一个 200MHz 主频、占用约 70% LUT 的逻辑，用 xc7a100t，
      想知道最大功耗大概多少，电源要留多少余量。
      (AI 自动调用 estimate quick → 返回总功耗和结温 → 建议余量)
```

---

### 模板 B：精确功耗评估（基于 PDM 项目）

> 已有 RTL / Vivado 工程，需要精确评估并导出约束到 PCB 设计。

```
1. session(action="start")
2. project(action="create", name="my_design", part="xc7a100tcsg324-1")
3. 用 explore(action="block_resources", block="logic") 查看可用资源字段。
4. 用 scenario(action="set_resource_util") 填入综合后的 LUT/FF/BRAM/DSP 用量（绝对数量）。
   例如 ``lut=50000, ff=60000, bram=80, dsp=100``。
5. 用 clock(action="create") 创建设计中的时钟，或 scenario(action="set_clock_frequency")
   修改已有时钟。
6. 用 scenario(action="set_environment", temp=85, airflow=250, heatsink="medium")
   设置工作环境。
7. scenario(action="recalculate") 重算功耗。
8. power(action="summary") 查看总功耗，power(action="thermal") 检查结温是否超标。
9. 如结温过高，调整 airflow 或 heatsink，重复步骤 7-8。
10. project(action="export_xdc", file="thermal.xdc") 导出散热约束。
11. power_design(action="rail_characteristics") 查看电源轨特性，确定每路电源需求。
12. project(action="save")
13. session(action="stop")
```

---

### 模板 C：导入 Vivado 结果并验证

> 综合/布线已完成，导入 Vivado 报告验证 PDM 建模精度。

```
1. session(action="start")
2. project(action="open", path="my_design.pdm")
3. vivado(action="import_report", report_path="post_route_power.rpt")
4. vivado(action="import_utilization", util_report_path="utilization.rpt", block_name="logic")
5. scenario(action="recalculate")
6. vivado(action="compare")  → 总功耗和各项逐项对比，>10% 差异标记 WARN。
7. 根据差异调整 PDM 参数（调用 scenario / clock），重复步骤 5-6。
8. project(action="save")
9. session(action="stop")
```

---

### 模板 D：多场景功耗对比

> 同一设计在不同频率、温度下的功耗差异。

```
1. session(action="start")
2. project(action="open", path="my_design.pdm")
3. power(action="summary")                         → 保存快照 A（基准）
4. scenario(action="set_clock_frequency", 
            name="clk_main", freq_mhz=300)         → 调整频率
5. scenario(action="recalculate")
6. power(action="summary")                         → 保存快照 B
7. scenario(action="compare")                      → 对比 A vs B
8. scenario(action="set_environment", 
            temp=85, airflow=0, heatsink="none")   → 调整环境
9. scenario(action="recalculate")
10. power(action="summary")                        → 保存快照 C
11. scenario(action="compare")                     → 对比 B vs C
12. session(action="stop")
```

---

### 模板 E：器件选型与 Part 替换

> 当前器件功耗超标，需要更换器件并重新评估。

```
1. session(action="start")
2. project(action="open", path="my_design.pdm")
3. project(action="list_parts", architecture="Artix-7")  → 查看同架构备选器件
4. power(action="summary")                                → 当前功耗
5. project(action="select_part", part="xc7a200tfbg484-2") → 换更大器件
6. scenario(action="recalculate")
7. power(action="summary")                                → 验证新器件功耗和结温
8. 若不满意，重复步骤 5-7。
9. project(action="save", save_path="my_design_a200t.pdm")
10. session(action="stop")
```

---

### 模板 F：时钟系统规划

> 从零配置复杂时钟网络（含 MMCM/DPLL）。

```
1. session(action="start")
2. project(action="create", name="clock_design", part="xcku3p-ffva676-1-i")
3. clock(action="sample_settings")                           → 了解时钟设置模板结构
4. clock(action="create", name="sys_clk", freq=125, 
         io_type="HD", io_standard="LVCMOS 1.8V")            → 创建系统时钟
5. clock(action="mgr_types")                                 → 查看可用的时钟管理器
6. clock(action="mgr_create", name="mmcm_sys",
         type="MMCM", input_clock="sys_clk", vco_range="Low") → 创建 MMCM
7. clock(action="mgr_settings", name="mmcm_sys")             → 查看 MMCM 产生的输出时钟
8. scenario(action="recalculate")
9. project(action="save")
10. session(action="stop")
```

---

### 模板 G：电源轨设计与原理图检查

> 导出电源设计数据，提供给硬件工程师做原理图检查。

```
1. session(action="start")
2. project(action="open", path="my_design.pdm")
3. scenario(action="set_environment", temp=85,
            airflow=250, heatsink="medium")
4. scenario(action="recalculate")
5. power_design(action="info")                               → 查看电源域和电源名称
6. power_design(action="rail_characteristics")               → 查看每路电压/电流
7. power_design(action="delivery_design")                    → 查看电源交付方案
8. power_design(action="set_consolidation", 
               mode="Consolidated")                          → 尝试整合模式
9. power_design(action="delivery_design")                    → 对比整合后的方案
10. project(action="export_power_design", 
            file="power_design.xml")                         → 导出 XML 供原理图检查
11. project(action="export_xdc", file="thermal.xdc",
            thermal="Ambient")                               → 导出环境温度约束
12. project(action="save")
13. session(action="stop")
```

---

### 模板 H：导入 XPE 快速起步

> 已有 Vivado XPE 文件，直接导入作为起点。

```
1. session(action="start")
2. project(action="create", name="from_xpe", part="xc7a100tcsg324-1")
3. project(action="import_xpe", file="baseline.xpe")          → 导入 XPE 数据
4. power(action="summary")                                    → 查看导入后的功耗
5. explore(action="block_resources", block="logic")           → 查看 XPE 填充了哪些资源
6. scenario(action="set_environment", temp=85, airflow=250,
            heatsink="medium")
7. scenario(action="recalculate")
8. power(action="summary")
9. project(action="save")
10. session(action="stop")
```

---

### 模板 I：同设计跨器件功耗对比（基于 PDM）

> 同一套设计参数（资源、时钟、环境），在不同 FPGA 型号上的功耗和结温差异。

```
1. session(action="start")
2. project(action="open", path="my_design.pdm")

   # ---- 器件 A ----
3. scenario(action="set_resource_util", block="logic",
            lut=50000, ff=60000, bram=80, dsp=100)
4. clock(action="create", name="clk_main", freq=200)
5. scenario(action="set_environment", temp=85, airflow=250, heatsink="medium")
6. scenario(action="recalculate")
7. power(action="summary")                                → 保存快照（器件 A）

   # ---- 器件 B ----
8. project(action="select_part", part="xc7a200tfbg484-2") → 切换到更大器件
9. scenario(action="recalculate")
10. power(action="summary")                               → 保存快照（器件 B）
11. scenario(action="compare")                            → 对比 A vs B

    # ---- 器件 C ----
12. project(action="select_part", part="xcku3p-ffva676-1-i") → 切换到 UltraScale
13. scenario(action="recalculate")
14. power(action="summary")                               → 保存快照（器件 C）
15. scenario(action="compare")                            → 对比 B vs C

16. session(action="stop")
```

> **说明**：`compare` 对比的是最近两次 `power(summary)` 的快照。三器件以上需两两依次对比，每次 `compare` 后记录输出即可。

---

### 模板 J：纯快速估算跨器件对比（无需 PDM）

> 连 PDM 项目都不需要，直接用 `estimate quick` 快速比较多个器件。

```
1. estimate(action="quick", part="xc7a35tcsg324-1", clock_mhz=200,
            lut_pct=70, temp=85, airflow=250, heatsink="medium")
   → 记录: A35T → 功耗 X.XW, 结温 YY°C

2. estimate(action="quick", part="xc7a100tcsg324-1", clock_mhz=200,
            lut_pct=70, temp=85, airflow=250, heatsink="medium")
   → 记录: A100T → 功耗 X.XW, 结温 YY°C

3. estimate(action="quick", part="xc7a200tfbg484-2", clock_mhz=200,
            lut_pct=70, temp=85, airflow=250, heatsink="medium")
   → 记录: A200T → 功耗 X.XW, 结温 YY°C

4. estimate(action="quick", part="xcku3p-ffva676-1-i", clock_mhz=200,
            lut_pct=70, temp=85, airflow=250, heatsink="medium")
   → 记录: KU3P → 功耗 X.XW, 结温 YY°C

5. 横向比较四个器件的总功耗和结温，选择最优性价比型号。
```


---

### 11. `guide` — 引导式评估向导

只需告诉 AI "我想评估 xxx 的功耗"，AI 会调用本工具一步步询问所需参数，
每步给出可选值，无需记忆任何工具名。

**流程**：器件型号 → 评估模式（quick/pdm/vivado） → 逐步填参 → 自动计算结果。

```python
# 用户: "我想评估 xc7a100t 的功耗"
# AI 自动调用:
guide(step="start")
# → 返回: "请输入 FPGA 器件型号"
guide(step="device", value="xc7a100tcsg324-1")
# → 返回: "选择评估模式: quick / pdm / vivado"
guide(step="mode", value="quick", device="xc7a100tcsg324-1")
# → 返回: "主时钟频率是多少 (MHz)？"
guide(step="quick_clock_mhz", value="200", device="xc7a100tcsg324-1")
# → 返回: "LUT 利用率大约多少 (%)？"
# ... 逐步收集参数 ...
# → 最终返回: 功耗估算结果（含 breakdown、结温）
```

**示例对话**：
```
用户: 我想评估 xc7a100t 的功耗，200MHz 主频，资源用了大概 70%
AI:   (自动调用 guide → 收集参数 → 返回总功耗 1.2W，结温 45°C，建议电源余量 1.8W)
```


## 开发

### 运行测试

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

### 项目结构

```
pdm_mcp/
├── src/pdm_mcp/
│   ├── __main__.py           # CLI 入口 (pdm-mcp serve)
│   ├── server.py             # FastMCP 实例 + 工具注册
│   ├── config.py             # PDM 路径检测
│   ├── analysis/
│   │   ├── estimator.py      # 快速功耗估算模型
│   │   └── power_parser.py   # Vivado 报告解析器
│   ├── session/
│   │   ├── pdm_session.py    # PDM 子进程管理（哨兵协议）
│   │   ├── session_manager.py # 多会话生命周期
│   │   └── base_session.py   # 抽象基类 + PdmResult
│   └── tools/                # 10 个 MCP 工具
│       ├── session_tools.py
│       ├── project_tools.py
│       ├── power_tools.py
│       ├── scenario_tools.py
│       ├── clock_tools.py
│       ├── ip_tools.py
│       ├── power_design_tools.py
│       ├── import_tools.py
│       ├── estimate_tools.py
│       └── exploration_tools.py
├── scripts/mainloop.py       # PDM 子进程 REPL
├── tests/                    # 测试
├── docs/                     # UG1781 参考文档
└── pyproject.toml
```

## Bug 反馈

请通过以下任一方式提交反馈：

- **GitHub Issues**: 在项目仓库提交 Issue，附上以下信息：
  - `pdm-mcp version` 输出
  - 完整的错误信息 / 堆栈跟踪
  - 复现步骤
  - PDM 版本 (`pdm.bat` 所在目录名即为版本号)

- **日志**: 启动 MCP Server 时会输出日志到 stderr，包含 PDM 路径检测信息和运行时错误。如果遇到问题，请附上日志。

- **常见问题排查**:

  | 问题 | 可能原因 | 解决方法 |
  |---|---|---|
  | `PDM 路径检测失败` | PDM 未安装或路径不在默认位置 | 设置 `PDM_HOME` 或创建 `path.txt` |
  | `会话 'xxx' 不存在` | 未调用 `session(action="start")` | 先启动会话再操作 |
  | `No project open` | 未调用 `project(action="open")` | 先打开项目再查询 |
  | 功耗值为 0 | 未设置资源利用率或时钟频率 | 调用 `scenario` 配置参数后 `recalculate` |