Metadata-Version: 2.4
Name: fpga-testbench-mcp
Version: 0.2.1
Summary: FPGA 测试平台知识库 MCP Server — 为 FPGA 验证工程师提供 Verilog testbench 知识查询、代码模板和验证方法指导
Project-URL: Homepage, https://github.com/courviv/fpga-testbench-knowledge-mcp-server
Project-URL: Repository, https://github.com/courviv/fpga-testbench-knowledge-mcp-server
Project-URL: Issues, https://github.com/courviv/fpga-testbench-knowledge-mcp-server/issues
Author: FPGA Testbench MCP Contributors
License: MIT
License-File: LICENSE
Keywords: eda,fpga,mcp,model-context-protocol,testbench,verification,verilog
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Requires-Python: >=3.13
Requires-Dist: chromadb>=1.5.9
Requires-Dist: mcp[cli]>=1.27.2
Requires-Dist: python-frontmatter>=1.1
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# FPGA Testbench Knowledge MCP Server

为 FPGA 验证工程师服务的 MCP Server —— 让 Agent 在生成 Verilog testbench 代码前，**一次调用即可拿到生成所需的全部上下文**：

1. **编码规范全文**：`coding-standards` 类目下的全部规范条款，每次调用都会原样返回，确保生成代码严格遵循。
2. **向量检索的相关知识片段**：根据待测模块描述，对其余知识文章按二级标题切分后做语义检索，返回 Top-K 最相关的小节。

底层使用 [ChromaDB](https://www.trychroma.com/) 持久化向量库；首次启动会自动下载默认嵌入模型 `all-MiniLM-L6-v2`（约 80 MB，需联网），随后所有查询都是本地计算。

## 暴露的 MCP 工具

| Tool | 入参 | 返回 |
|------|------|------|
| `generate_testbench_context(description, top_k=5)` | `description: str` 待测模块描述；`top_k: int` 检索片段数 | 拼装好的 Markdown 字符串，可直接作为 LLM 生成 testbench 的上下文 |

返回 Markdown 结构：

```
# FPGA Testbench 生成上下文
> 待测模块描述: <description>

## 一、编码规范（必须严格遵循）
<整套 FPGA 编码规范的正文>

## 二、相关知识片段（语义检索 Top-K）
### 1. <文章标题> — <小节标题>
- 来源: knowledge://<category>/<article_id>
- 分类: <category>
- 相似度: 0.812
<chunk 正文>
...
```

## 安装

```bash
git clone <repo-url>
cd fpga-testbench-knowledge-mcp-server
uv sync
```

## 使用

### 开发调试 (MCP Inspector)

```bash
uv run mcp dev src/fpga_testbench_mcp/server.py
```

在 Inspector 的 Tools 面板调用 `generate_testbench_context`，输入待测模块描述即可。

### 配置 Claude Desktop

在 `claude_desktop_config.json` 中添加：

```json
{
  "mcpServers": {
    "fpga-testbench-knowledge": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "D:\\527\\fpga-testbench-knowledge-mcp-server",
        "fpga-testbench-mcp"
      ]
    }
  }
}
```

## 知识库内容

| 类别 | 用途 |
|------|------|
| `coding-standards` | 每次调用全文返回；FPGA RTL 编码规范、命名/注释/状态机/目录结构等 |
| `methodology` | 参与向量检索；定向测试方法、代码覆盖率基础 |
| `bus-protocols` | 参与向量检索；AXI4 / Avalon-MM 协议与 BFM |
| `components` | 参与向量检索；时钟复位、BFM、结果检查等 testbench 组件设计 |
| `assertions` | 参与向量检索；SystemVerilog Assertion 入门 |
| `tools` | 参与向量检索；ModelSim / Vivado XSim 使用指南 |

## 开发

```bash
# 运行测试（首次会下载嵌入模型，需联网）
uv run python -m pytest tests/ -v
```

## 项目结构

```
src/fpga_testbench_mcp/
├── server.py                      # FastMCP 入口，注册唯一 Tool
├── resources/
│   ├── loader.py                  # index.yaml 解析、文章加载、编码规范拼装
│   └── vector_store.py            # ChromaDB 持久化索引与查询
└── knowledge_base/
    ├── index.yaml                 # 知识库总索引
    ├── coding-standards/          # 始终全文返回
    ├── methodology/               # 参与向量检索
    ├── bus-protocols/
    ├── components/
    ├── assertions/
    ├── tools/
    └── .chroma/                   # ChromaDB 持久化目录（git-ignored，按需重建）
```

> 重建索引：删除 `src/fpga_testbench_mcp/knowledge_base/.chroma/` 后重启 server 即可。
