内容
<p align="center">
<img src="assets/Driverge-lockup.svg" alt="Driverge" width="360">
</p>
<p align="center"><em>数据表 PDF → 嵌入式 C/C++ 驱动程序，来自任何 MCP 客户端。</em></p>
<p align="center">
<a href="https://www.npmjs.com/package/driverge-mcp"><img alt="npm (beta)" src="https://img.shields.io/npm/v/driverge-mcp/beta"></a>
<a href="https://github.com/MehmetTopuz/driverge-mcp/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/MehmetTopuz/driverge-mcp/actions/workflows/ci.yml/badge.svg"></a>
<a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-blue"></a>
<img alt="status" src="https://img.shields.io/badge/status-closed%20beta-orange">
<img alt="mcp" src="https://img.shields.io/badge/MCP-server-black">
</p>
> 🧪 **封闭测试** — 使用 **`npm i driverge-mcp@beta`** 或直接使用 `npx -y driverge-mcp@beta` 运行。生成的驱动程序是**草稿**，不是硬件认证的固件，JSON 模式在稳定版本 **v0.1.0** 之前可能会更改 — 请参阅 [成熟度和状态](#成熟度和状态)，以及 [BETA.md](BETA.md) 如果您正在测试。
---
**目录：** [什么是 Driverge？](#什么是Driverge) ·
[快速开始](#快速开始) · [为什么选择 Driverge？](#为什么选择Driverge) ·
[它的功能](#它的功能) · [成熟度和状态](#成熟度和状态) ·
[概念](#Driverge背后的概念) · [安装](#安装) ·
[用法](#用法) · [故障排除](#故障排除) · [路线图](#路线图)
## 什么是 Driverge？
**Driverge 是一个与客户端无关的 [MCP](https://modelcontextprotocol.io) 服务器**，它将 IC 数据表 PDF 转换为嵌入式 C/C++ 驱动程序。它可以与任何支持 MCP 的主机连接 — Claude Desktop、Claude Code（VS Code）、Cursor 等。
其指导原则是：**确定性的代码解析和验证；主机 AI 推理。** Driverge 包含 **没有内部 LLM，不需要 API 密钥** — TypeScript 管道提取芯片的**已验证、结构化 JSON 模型**，而您已经在使用的主机 AI 则负责填入推理部分（初始化序列、供应商特殊性、文档）。您的数据表永远不会离开您的机器。
<p align="center">
<img src="assets/driverge-flow.png" alt="Driverge 工作原理：数据表 PDF 流经确定性分析 → 冻结 JSON → 生成 → 验证管道；主机 AI 填入 TODO(driverge) 差距，循环重复，直到验证通过，生成 driver.c/.h" width="760">
</p>
## 快速开始
在您的 MCP 客户端配置中添加一个条目（Claude Desktop、Claude Code、Cursor — [安装](#安装) 中的客户端路径）：
```json
{
"mcpServers": {
"driverge": { "command": "npx", "args": ["-y", "driverge-mcp"] }
}
}
```
重启客户端，然后询问：
> "使用 driverge 分析位于 `C:/ds/bme280.pdf` 的数据表，然后生成一个可移植的驱动程序。"
就是这样 — 不需要克隆，不需要构建，不需要 API 密钥。详细信息请参阅 [安装](#安装) 和 [用法](#用法)。
## 为什么选择 Driverge？
为新的传感器或 IC 带来一个新的驱动程序意味着从 40 页的 PDF 中手动转录数十个寄存器地址、位域掩码和命令代码 — 工作效率低下，而且是静默错误的一个经典来源（一个错误的掩码，驱动程序“正常工作”但读取错误的数据）。Driverge 确定性地完成机械部分，并将判断留给您已经在使用的 AI。
- **没有幻觉的寄存器映射。** 地址、掩码和命令代码是从数据表中**提取并验证**的 — 而不是猜测的。无效或不完整的数据在可以成为代码之前被拒绝。
- **自带客户端 — 私有设计。** 一个普通的 MCP 服务器，没有嵌入式 LLM：它与您已经付费的模型一起推理，并且数据表在本地解析，永远不会上传 — 对 NDA 部件安全。
- **确定性和可复制。** 相同的数据表始终产生相同的 JSON 和相同的驱动程序骨架 — 可审查、可差异化、可测试。
- **通过构造可移植。** 一个驱动程序核心通过一个小的每总线薄 HAL 接缝针对任何平台；本地目标（STM32、ESP32）预填充它。AI 只完成标记的 `TODO(driverge)` 差距，而 `validate_driver` 检查结果。
**适合：** 快速评估新的传感器、原型设计、将现有的驱动程序移植到不同的 MCU，或只是学习不熟悉的芯片的寄存器映射。
## 它的功能
1. **分析** 数据表 PDF → 检测格式、制造商和接口类型（寄存器映射 vs. 命令集），然后提取寄存器 / 位域（或命令 + CRC）和总线协议到一个**冻结的 JSON 契约**，由验证器控制。
2. **生成** 针对目标平台的驱动程序，C 或 C++：一个确定性的**薄 HAL 骨架** — 寄存器/位域常量、每总线缝隙、函数存根 — 每个推理间隙标记 `TODO(driverge)` 加上一个 `fill_in_brief`，告诉主机 AI 需要完成什么。
3. **验证** 完成的驱动程序：薄 HAL 纯度，没有剩余的 TODO，寄存器引用存在，位域掩码与 JSON 匹配。
### 支持的目标
每个目标都专门为相同的可移植 **[薄 HAL](https://en.wikipedia.org/wiki/Hardware_abstraction_layer)** 接缝进行定制 — 驱动程序核心在所有平台上相同；只有接缝实现不同。
| 目标 | 总线绑定 | 总线 | 语言 | 成熟度 |
| --- | --- | --- | --- | --- |
| **可移植（薄 HAL）** | 用户实现 `<part>_hal_*` 接缝 | I²C、SPI、UART、CAN | C / C++ | **测试中** — 主机测试，CI 中 gcc 编译；尚未在硬件上测试 |
| **ESP32** | ESP-IDF（`i2c_master_*`、`spi_master`、`uart`、`TWAI`） | I²C、SPI、UART、CAN | C / C++ | **实验性** — 非正式的 I²C 启动；SPI/UART/CAN 从未在硬件上测试 |
| **STM32** | CubeHAL（`HAL_I2C_*`、`HAL_SPI_*` + GPIO CS、`HAL_UART_*`） | I²C、SPI、UART | C / C++ | **实验性** — 3 个硬件现场测试（NUCLEO-G474RE，手动完成）；没有自动编译门控 |
| **Arduino** | `Wire` / `SPI` | — | C++ | 未实现 |
STM32 CAN 正在计划中（bxCAN/FDCAN 家族需要自己的通道），下一波原生目标 — RP2040/RP2350、TI MSPM0、NXP MCX/i.MX RT、Nuvoton NuMicro、Microchip PIC，以及最终的 Zephyr — 正在 [路线图](#路线图) 中。要求目标不支持的 bus 会快速失败，并带有明确的 `UnsupportedBusError` 错误。
## 成熟度和状态
Driverge 处于 **封闭测试** 状态（`0.1.0-beta.x`，npm `beta` 分发标签）。
**今日已证明（主机级别）：**
- 完整的确定性测试套件在干净的 TypeScript 构建上是绿色的（超过 540 个测试），并且**可移植**驱动程序在 CI 中由真正的 `gcc` 门控编译（包括多驱动程序链接门控）。
- 提取管道针对 **14 个真实数据表** 进行回归测试，并诚实地报告其覆盖率 — 7 个完全提取，4 个部分提取，3 个延迟（参见 [覆盖率记分卡](tests/scorecard/scorecard.snap.md)）。
**尚未证明 — 这是测试版到 v0.1.0 的门控：**
- **硬件行为未被 CI 门控。** STM32 现已在真实硬件上运行 — 3 个 NUCLEO-G474RE 现场测试（手动完成并反馈到生成器），以及 ESP32 的非正式 I²C 启动（MPU-9250）。仍然没有干净、可重复的自动化硬件通过，因此每个生成的驱动程序在闪存之前都需要审查。
- 原生 ESP32/STM32 接缝尚未由自动化编译门控构建（ESP-IDF / CubeIDE）— 只有可移植目标构建。
- 只有一个 MCP 客户端已进行端到端测试。
> ⚠️ 将每个生成的驱动程序视为**审查草稿**：在闪存之前，请使用数据表检查寄存器地址、初始化序列和任何补偿数学运算。Driverge 未经过安全认证。
**测试测试版？** [BETA.md](BETA.md) 有身份寄存器烟雾测试要运行，以及如何发送现场报告。
## Driverge 背后的概念
Driverge 将驱动程序编写分为两种工作：**机械部分**（寄存器地址、掩码、命令表 — 提取并由确定性代码检查）和**判断部分**（初始化排序、时序特殊性、补偿数学运算 — 由主机 AI 完成）。以下所有内容都旨在保持这一边界清晰；页面顶部的图表显示了各个部分如何连接。
### 确定性核心，边缘推理
寄存器几何是机械的：地址要么正确，要么错误；掩码要么与数据表匹配，要么不匹配。Driverge 使用纯 TypeScript 处理这部分 — 没有采样，因此输出在每次运行时都相同。真正需要判断的部分（以什么顺序操作寄存器，哪个时序特殊性适用）留给主机 AI。
### 冻结的 JSON 契约
`analyze_datasheet` 运行一个五阶段的管道（L1-L5）：检测 PDF 类型，映射关键字页，识别制造商和接口类型，提取寄存器表（或命令集 + CRC），并根据冻结的 draft-07 [JSON 模式契约](schemas/datasheet.schema.json) 验证结果 — 也作为 `driverge://schema` 资源公开。任何验证失败的内容都会在代码生成之前被拒绝，因此错误的提取永远不会静默地成为错误的驱动程序。
## 安装
**先决条件：** Node.js LTS（≥ 18；CI 在 Node 20 和 22 上测试）。
使用 npm 安装测试版：
```bash
npm i driverge-mcp@beta
```
或者直接跳过安装 — 下面的配置通过 [npx](https://docs.npmjs.com/cli/commands/npx) 启动 Driverge，它在第一次运行时从 npm 下载，在缓存中，并自动启动（`-y` 跳过 npx 的安装提示）。在您的 MCP 客户端配置中添加一个条目：
```json
{
"mcpServers": {
"driverge": { "command": "npx", "args": ["-y", "driverge-mcp"] }
}
}
```
| 客户端 | 配置文件 |
| --- | --- |
| Claude Desktop | `claude_desktop_config.json` |
| Claude Code（VS Code） | 工作区根目录下的 `.mcp.json` |
| Cursor | `.cursor/mcp.json` |
| 其他（Codex、Gemini CLI、…） | 相同的 `command` + `args` 对在它们自己的 MCP 配置中 |
> **测试版测试人员：** 显式地使用 `["-y", "driverge-mcp@beta"]` 作为 `args` 锁定测试版通道。普通的 `driverge-mcp` 解析 npm 的 `latest` 标签，在封闭测试期间故意落后于测试版。
您永远不会手动运行服务器 — 为了确认它已连接，请让您的客户端运行 `ping` 工具，该工具会回复 `pong`。在 Windows 上，直接编写配置文件比使用 `claude mcp add` 更方便 — 请参阅 [故障排除](#故障排除)。克隆存储库（如下）仅用于开发。
### 配置
| 环境变量 | 默认值 | 目的 |
| --- | --- | --- |
| `DRIVERGE_OUT_ROOT` | 服务器工作目录 | `generate_driver` 的 `out_dir` 写入被限制在此根目录下。任何解析到此根目录外部的 `out_dir` 都会被拒绝（`out_dir "…"` 跳出允许的根目录）。将其设置为要写入驱动程序的目录。 |
| `DRIVERGE_MAX_PDF_BYTES` | `67108864`（64 MiB） | `analyze_datasheet` 将读取的最大 PDF 大小。较大的文件将被拒绝，并带有明确的“PDF 太大”错误，在进行任何解析之前 — 以限制对敌对或意外巨大输入的内存使用。 |
在 MCP 配置的 `env` 块中设置，例如：
```json
{
"mcpServers": {
"driverge": {
"command": "npx",
"args": ["-y", "driverge-mcp"],
"env": { "DRIVERGE_OUT_ROOT": "C:/work/drivers" }
}
}
}
```
如果没有 `out_dir`，生成的 文件仅在工具结果中返回 — 无磁盘写入，无需配置。
### 从源代码运行（开发）
要贡献或运行最新的未发布更改：
```bash
git clone https://github.com/MehmetTopuz/driverge-mcp.git
cd driverge-mcp
npm install
npm run build
```
然后将您的客户端指向已构建的入口点：
```json
{
"mcpServers": {
"driverge": { "command": "node", "args": ["/absolute/path/to/dist/server.js"] }
}
}
```
## 用法
给您的 MCP 客户端一个数据表，并要求它构建一个驱动程序。典型的流程：
1. **`analyze_datasheet`** — `{ "pdf_path": "/abs/path/bme280.pdf" }` → 返回一个紧凑的摘要和一个 `ref` 句柄；完整的 JSON 作为资源可用。如果自动检测选择错误的供应商或接口样式，则可选的 `manufacturer_hint`（自由文本）和 `interface_kind_hint`（`"register_map"` | `"command_set"`）参数会引导它。
2. **`generate_driver`** — `{ "ref": "…", "target": "portable" }` → 返回驱动程序文件 + 一个 `fill_in_brief`。（`out_dir` 还会将它们写入磁盘；`language: "cpp"` 呈现一个基于类的 `.hpp`/`.cpp` 驱动程序，而不是默认的 C。）
3. 主机 AI 使用简介和 `driverge://datasheet/<ref>` 资源完成 `TODO(driverge)` 标记。
4. **`validate_driver`** — `{ "ref": "…", "files": [...] }` → 静态检查；循环直到通过。
重用相同的 `ref` 和不同的 `target` **无需重新解析**。
**完成延迟的数据表。** 当 `analyze_datasheet` 报告 `extraction: deferred` 时，主机 AI 会从 `driverge://datasheet/<ref>` 资源重建寄存器映射，并使用 `validate_datasheet({ "ref": "…", "json": { … } })` 持久化回缓存的该 `ref` 下的 `ref`，从而在下一个 `generate_driver` 呈现真正的寄存器而不是 TODO 存根。
### BME280 → 可移植驱动程序的示例
> "使用 driverge 分析位于 `C:/ds/bme280.pdf` 的数据表，然后生成一个可移植的驱动程序。"
Driverge 解析 BME280 内存映射（16 个寄存器，19 个位域，I²C 地址），验证它，并生成 `bme280.h` / `bme280.c` — 寄存器 `#define`，位域 `MASK` / `SHIFT` 宏，薄 HAL 接缝，以及 `bme280_init/read_register/write_register` 存根：
```c
/* bme280.h — 由 Driverge 生成（摘录） */
#define BME280_I2C_ADDR 0x76
#define BME280_REG_CTRL_MEAS 0xF4
#define BME280_REG_STATUS 0xF3
/* … */
#define BME280_TEMP_XLSB_TEMP_XLSB_MASK 0xF0
#define BME280_TEMP_XLSB_TEMP_XLSB_SHIFT 4
```
```c
/* bme280.c — 每个推理间隙都是一个标记的 TODO（摘录） */
int bme280_init(bme280_t *dev) {
/* … */
/* TODO(driverge): 实现电源开启/重置初始化序列 — 正确的寄存器写入顺序和值，以及任何必需的启动延迟。参见 fill_in_brief.init_sequence_todo。 */
return 0;
}
```
主机 AI 然后从数据表文本中填充初始化序列和文档，`validate_driver` 检查结果。
### MCP 接口
| 类型 | 名称 | 用途 |
|---|---|---|
| 工具 | `analyze_datasheet` | PDF → 验证的 JSON，缓存在 `ref` 下 |
| 工具 | `generate_driver` | `ref` + `target` → 驱动程序骨架 + `fill_in_brief` |
| 工具 | `validate_driver` | 静态检查已完成的驱动程序与其 `ref` |
| 工具 | `validate_datasheet` | 重新运行验证器检查 `ref` 或 JSON；**两者**都通过则在该 `ref` 下持久化已完成的 datasheet |
| 工具 | `ping` | 健康检查 — 确认服务器正在运行 |
| 资源 | `driverge://datasheet/<ref>` | 分析后的 datasheet 的完整解析 JSON |
| 资源 | `driverge://schema` | 冻结的 datasheet JSON-Schema 契约 |
| 提示 | `generate-driver` | 有指导的分析 → 生成 → 填写 → 验证流程 |
## 故障排除
- **服务器是否正在运行？** 请您的客户端运行 `ping` 工具 — 它会回复 `pong`。如果 npx 无法启动，请检查 `node --version`（需要 ≥ 18）。
- **扫描的 / 仅图像 PDF。** Driverge 解析基于文本的 PDF；检测到扫描或混合 PDF 会报告明确的警告，解析将不完整（OCR 延迟到未来的版本）。
- **`extraction: partial` 或 `deferred` 不是失败。** `partial` 表示寄存器已找到但详细信息（例如位域）不完整；`deferred` 表示寄存器/命令部分已检测到但未自动提取。在这两种情况下，生成的骨架都告诉主机 AI 从 datasheet 资源中精确地完成什么。只有 `none` 是真正的解析失败。
- **`out_dir "…" 超出允许的根目录`。** 磁盘写入被限制在 `DRIVERGE_OUT_ROOT`（默认：服务器的工作目录）下 — 参见 [配置](#配置)。
- **原生目标上的 `UnsupportedBusError`。** 目标当前不支持该部件的 bus（目前意味着 STM32 上的 CAN，或解析器无法识别的 bus）。改为生成 **可移植** 目标并实现其缝隙。
- **Windows：优先编辑配置文件而不是 `claude mcp add` CLI。** `claude mcp add … -- npx -y driverge-mcp` 会消耗 `-y` 自身（`unknown option '-y'`），并且 PowerShell 5.1 会破坏 `claude mcp add-json` 中的嵌套引号。将 JSON 块直接写入 `.mcp.json` / `claude_desktop_config.json` 可以避免两者。
- **Windows：从您自己的脚本中启动服务器。** 从 Node 启动 `npx.cmd` 需要 `shell: true`（否则 `spawn EINVAL`）。MCP 客户端为您处理此问题；它只会影响自定义测试脚本。
- **`claude mcp list` 中的“Pending approval”**。项目范围的 `.mcp.json` 可能在单独的 `claude mcp list` 进程中显示为 `⏸ Pending approval`，而 `driverge` 工具在您的活动会话中已经可调用 — 该列表滞后于运行会话。
## 路线图
- **v0.x** — 一个参考传感器（BME280），可移植的薄 HAL 核心，MCP 接口，多个客户端。✅
- **v0.y** — 原生代码生成：ESP32 ✅，STM32 ✅（硬件验证是 beta → v0.1.0 的门槛），Arduino（下一个）；多制造商提取 ✅（12 个供应商 — 参见 [已验证的部件](#verified-parts)）；多 bus 缝隙家族（I²C，SPI，UART，CAN）✅；C 或 C++ 输出 ✅。（当前）
- **v1.0** — 更广泛的供应商/部件覆盖，STM32 CAN（bxCAN/FDCAN），以及稳定的、版本化的 JSON 模式。
- **探索中，无承诺时间表** — 下一代原生目标：RP2040/RP2350，TI MSPM0，NXP MCX/i.MX RT，Nuvoton NuMicro，Microchip PIC，以及最终的 Zephyr。在此处命名，以便 [支持的目标](#supported-targets) 注释指向“路线图”有一个指向的对象 — 不是承诺这些功能会在任何日期发布。
- **v1.x** — 新的原生 MCU 目标（相同的可移植薄 HAL 核心，每个平台一个缝隙文件；按 beta 测试者需求优先）：**RP2040/RP2350**（pico-sdk），**TI MSPM0**（DriverLib），**NXP MCX / i.MX RT**（MCUXpresso `fsl_lpi2c`/`fsl_lpspi`），**Nuvoton NuMicro**（BSP 标准驱动程序），以及 **Microchip PIC**（MCC Melody 用于 8/16 位；Harmony v3 用于 PIC32）。
- **稍后** — 一个 **Zephyr** 元目标（基于 devicetree 的 `i2c`/`spi` API）：一个缝隙覆盖 Nordic nRF 和所有其他 Zephyr 支持的供应商。
每天的进度在 [CHANGELOG](CHANGELOG.md) 中跟踪。
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取开发设置、提交约定和测试驱动的工作流程。问题和 PR 欢迎。
## 安全和免责声明
生成的驱动程序是草稿，旨在供人类审查，而不是认证的固件 — 参见 [SECURITY.md](SECURITY.md)。Driverge 在本地运行，不会传输您的 datasheet。
## 许可证
[MIT](LICENSE) © Mehmet Topuz
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器