STM32 RAG MCP

一个以 Claude Code 插件 形式交付的 STM32 文档知识库。它从本地 datasheet 和 reference manual 中检索原文证据，通过 MCP 返回文档、revision、PDF 页码、章节、寄存器和 source SHA-256，再由 Claude 基于证据回答或生成代码。

当前版本是 evidence-first、lexical-first RAG：本地检索无需 embedding 模型或远程向量库；Claude Code 仍负责最终自然语言回答。证据不足时系统明确 abstain，不猜寄存器、地址或页码。

当前语料

本地验证语料合计 4 份 PDF、3,174 页、42,839,844 bytes。download_manifest.csv 保存 SHA-256、实际镜像来源和 ST 官方文档页面。当前 PDF 来自公开镜像，索引不会把它们描述成“自动同步的最新版”；更新文档后必须重新校验 revision、SHA 和 citation。

仓库语料说明： 当前公开仓库已经包含上述 4 份 PDF，方便首次安装直接构建索引。PDF 仍应视为 ST 文档的再分发内容；更新或替换文件前请确认其来源和再分发许可。SQLite 索引是可再生构建产物，不提交到仓库。

Related MCP server: MCP Manuels

架构

STM32 PDF
  -> SHA/provenance registry
  -> PyMuPDF page/block parser
  -> TOC + model-scope propagation
  -> section/register-aware chunks
  -> SQLite metadata + FTS5 BM25
  -> exact technical-token rerank + abstention
  -> MCP evidence tools
  -> Claude Code answer with citations

核心特点：

• page-first：保留 physical PDF page、PDF label、可见页脚和异常标记；

• scope-aware：区分 RM0090 的 F42/F43 RCC 章节与 F405/F407 RCC 章节；

• register-aware：支持 GPIO_MODER / GPIOA_MODER 到 GPIOx_MODER 的规范化，同时区分 F1 的 GPIOx_CRL/CRH；

• deterministic：SQLite FTS5 unicode61 tokenchars '_'、固定重排和 index fingerprint；

• fail loud：PDF、schema、parser、chunker 或 corpus fingerprint 变化时拒绝旧索引；

• read-only MCP：运行时不下载、不建库、不修改 PDF。

安装依赖

项目使用 uv.lock 固定依赖。已验证运行时：CPython 3.13.13、PyMuPDF 1.28.2、MCP 2.1.1。

uv sync --frozen --extra dev

准备 PDF 与构建索引

克隆仓库后，4 份验证语料位于 reference_manual/，可先校验路径、大小和 SHA-256：

uv run stm32-rag doctor --corpus reference_manual --manifest download_manifest.csv --json

预期输出 ok: true，包含 4 documents、3,174 pages 和 42,839,844 bytes。manifest 中的 source 是原始镜像地址，official_page 是 ST 官方文档页；它们用于 provenance 记录，不会在正常启动时自动访问网络。

如果需要重新下载或替换 PDF，下载器只会在显式执行时联网，并将结果写入被 .gitignore 排除的 download_results.csv：

uv run python download_stm32_docs.py

下载完成后必须重新校验 manifest 中记录的文件路径、字节数和 SHA-256；下载器报告 failed 时会以非零状态退出。确认语料完整后，构建本地 SQLite FTS5 索引：

uv run stm32-rag index \\
  --corpus reference_manual \\
  --manifest download_manifest.csv \\
  --db assets/stm32-index.sqlite3 \\
  --index-manifest assets/index-manifest.json \\
  --json

索引构建会在临时数据库中完成 integrity check 和 fingerprint 校验，成功后才原子替换 assets/stm32-index.sqlite3。索引不会提交到 GitHub；更新 PDF、parser、chunker 或 retrieval policy 后都应重新构建。

构建完成后再次检查索引：

uv run stm32-rag doctor \\
  --corpus reference_manual \\
  --manifest download_manifest.csv \\
  --db assets/stm32-index.sqlite3 \\
  --json

CLI 查询

uv run stm32-rag search --db assets/stm32-index.sqlite3 --corpus reference_manual --manifest download_manifest.csv --chip STM32F407 --query GPIO_MODER --json

uv run stm32-rag search --db assets/stm32-index.sqlite3 --corpus reference_manual --manifest download_manifest.csv --chip STM32F407 --query "USART_CR1 TE bit" --json

不存在或跨系列不兼容的寄存器会返回 abstained: true，不会静默取消 chip filter。

重建索引

更新 PDF、parser 或 chunker 后运行：

uv run stm32-rag index --corpus reference_manual --manifest download_manifest.csv --db assets/stm32-index.sqlite3 --index-manifest assets/index-manifest.json --json

index builder 在临时 SQLite 中完成事务、integrity check 和 fingerprint 校验后再原子替换目标文件；失败不会破坏旧索引。

Claude Code 插件

插件组件：

• .claude-plugin/plugin.json

• .mcp.json

• skills/stm32-docs/SKILL.md

• MCP tools：search_stm32_docs、get_register、search_peripheral

验证插件：

claude plugin validate C:/Users/Administrator/rag_embedding --strict

本地开发加载：

claude --plugin-dir C:/Users/Administrator/rag_embedding

启动后在 Claude Code 中检查 /mcp，技能命令为：

/stm32-rag:stm32-docs

.mcp.json 使用 ${CLAUDE_PLUGIN_ROOT} 定位只读 corpus/index，使用 ${CLAUDE_PLUGIN_DATA} 保存 uv 环境/cache。首次在新安装位置启动时，uv 可能从 lockfile 安装 Python 依赖；它不会自动下载 STM32 PDF、生成 SQLite 索引或下载 embedding 模型。公开仓库中的 .mcp.json 需要在本地语料和索引准备完成后使用。

MCP 工具

search_stm32_docs

综合查询，可传：query、chip、family、document_type、peripheral、register、top_k。

get_register

精确寄存器查询，必须传 chip 和 register。适合地址 offset、reset value、bit field 和清除语义。

search_peripheral

外设范围查询，必须传 chip 和 peripheral，可附加具体问题。

三个工具都只返回 evidence/citations，不返回一个伪装成权威的本地生成答案。

Citation 语义

每条 evidence 包含：

• document / DocID / revision / type / family；

• source path、SHA-256、mirror URL、ST official page；

• physical PDF pages、PDF labels、source footers；

• section path、register、chip scope；

• warnings 和 page anomalies。

RM0008 p.67–80 是重要异常：PDF physical/page label 仍为 67–80，但可见页脚错误写成 67/80…80/80。系统保留 canonical page 与 source footer，并标记 embedded_total_mismatch。

评测与测试

uv run pytest -q

当前测试覆盖：

• corpus 路径、SHA、页数和 downloader 无副作用 import；

• RM0008 页码异常；

• RM0090 scope 与无效 TOC anchor；

• F4 datasheet 横向页；

• register chunk 跨页与确定性 ID；

• SQLite schema、FTS5、只读和 stale-index 防护；

• CLI、MCP in-memory client 和真实 stdio 子进程；

• eval/golden_queries.json 的 20 个正例 + 5 个负例 hard gate。

正例要求 Recall@5 / citation hit 至少 90%；当前 20/20 正例首条命中定义页，5/5 负例 abstain。

已知限制

• 当前检索模式为 lexical，未打包 embedding 模型或 learned reranker；接口扩展点已保留，但响应不会谎称 hybrid。

• F4 datasheet p.14–15、62–70 为旋转横向表格。系统保留原文/rotation 并标记 table_layout_degraded；精确 pin/Alternate Function 查询会优先匹配非降级 pinout 表，无法建立可靠映射时显式 abstain。

• 尚未加入 SVD 结构化寄存器数据库、Errata、Application Note、HAL/LL、示例代码或其他 STM32 family。

• download_stm32_docs.py 只在显式执行时联网，并写 download_results.csv；它不会覆盖 verified corpus manifest。MVP 正常运行不调用 downloader。

项目计划

完整背景和后续路线见 STM32_RAG_MCP_Project_Plan.md。本版优先兑现计划中的核心目标：从 STM32 文档找到可靠证据、保留页码和来源，并通过 MCP 供 Claude 主动查询。