内容
# Zephyr RTOS MCP 服务器
一个 MCP（模型上下文协议）服务器，为大型语言模型提供 Zephyr RTOS 文档的可靠访问 — Kconfig 符号、设备树绑定和 API 签名。不再有虚构的驱动程序结构体或编造的 Kconfig 选项。
## 快速开始
### 选项 1：npx（无需安装）
```json
{
"mcpServers": {
"zephyr": {
"command": "npx",
"args": ["-y", "@aarav-j/zephyr-mcp-server"]
}
}
}
```
首次启动时自动下载服务器和预构建索引（8.5 MB）。无需设置。
### 选项 2：从 GitHub 克隆
```bash
git clone https://github.com/Aarav-J/zephyr-mcp-server.git
cd zephyr-mcp-server
npm install
npm run build
```
将以下内容添加到您的 MCP 客户端配置中（例如 `~/.cursor/mcp.json`）：
```json
{
"mcpServers": {
"zephyr": {
"command": "node",
"args": ["/path/to/zephyr-mcp-server/dist/index.js"]
}
}
}
```
## 工具
### `get_function_signature`
查找精确的 C 函数或宏签名、参数、返回类型和头文件位置。
```
参数：
name — 函数或宏名称（例如 k_sem_take, GPIO_DT_SPEC_GET）
version? — Zephyr 版本标签。默认为最新缓存版本。
返回：
- signature — 带有类型的精确 C 签名
- brief — 单行描述
- params — 带描述的键入参数列表
- return_type — 返回类型
- return_desc — 返回值描述
- header — 声明头文件
- section — Doxygen 组/章节
```
> 需要索引 Doxygen XML 输出（参见构建完整索引）。
### `find_kconfig`
按名称或描述搜索 Zephyr Kconfig 符号。
```
参数：
pattern — 搜索字符串（例如 GPIO, CONFIG_I2C, USB）
limit? — 最大结果数。默认为 10，最大 50。
version? — Zephyr 版本标签。
返回：
- name — 符号名称（CONFIG_*）
- type — bool, string, int, hex, tristate
- prompt — 用户可见的提示文本
- default — 默认值
- depends_on — 依赖符号链
- path — Zephyr 树中的文件路径
```
### `get_dt_binding`
按兼容字符串查找设备树绑定。
```
参数：
compatible — 兼容字符串（例如 st,stm32-i2c, arm,cortex-m4）
version? — Zephyr 版本标签。
返回：
- compatible — 兼容字符串
- description — 绑定描述
- properties — 带有类型、必填/可选状态、默认值的架构
- child_binding — 子绑定架构（如果有）
- bus — 此绑定提供的总线类型
- on_bus — 此绑定所在的总线
- path — Zephyr 树中的 YAML 文件路径
```
### `search_docs`
跨索引文档域进行全文搜索。
```
参数：
query — 搜索查询（例如 "semaphore", "i2c stm32", "gpio interrupt"）
domain? — 作用域："api", "kconfig", "dt"，或省略所有
limit? — 最大结果数。默认为 10，最大 30。
version? — Zephyr 版本标签。
返回：
- query — 原始查询
- count — 找到的总结果数
- results — { domain, title, snippet, path } 的排名列表
```
## 索引
### 预构建索引（自动下载）
服务器在首次启动时自动从 GitHub Releases 下载预构建索引。当前索引涵盖：
| 数据 | 数量 |
|---|---|
| Kconfig 符号 | 24,118 |
| 设备树绑定 | 3,553 |
| 索引大小 | 8.5 MB |
这足以让 `find_kconfig`、`get_dt_binding` 和 `search_docs` 工具立即工作。
### 构建完整索引（带有 API 签名）
要索引函数签名，您需要 Zephyr 文档构建的 Doxygen XML 输出：
```bash
# 选项 1：自己构建 Zephyr 文档
# （需要完整的 Zephyr 构建环境）
cd /path/to/zephyr
west build -t doxygen
# Doxygen XML 将位于 build/zephyr-doc/xml/
# 选项 2：使用预构建的文档源
npx tsx scripts/build-index.ts v4.4.1 \
--source /path/to/zephyr \
--doxygen /path/to/zephyr/build/zephyr-doc/xml/
```
### 从源代码构建
如果您想从特定的 Zephyr 版本构建索引：
```bash
# 下载并索引 Zephyr 源代码中的 Kconfig + DT 绑定
npx tsx scripts/build-index.ts v4.4.1 --source /path/to/zephyr
```
CLI 接受本地 Zephyr 源代码目录。在针对新版本运行首次时，它将自动下载 Zephyr 源代码 tarball。
## 版本管理
服务器在启动时检查新的 Zephyr 版本并记录一条消息，当有新版本可用时：
```
[update] 新的 Zephyr 版本：v4.5.0（缓存：v4.4.1）
[update] 运行：cd zephyr-mcp-server && npm run build-index v4.5.0
```
## 架构
```
zephyr-mcp-server/
├── src/
│ ├── index.ts # MCP 服务器 + 工具处理程序
│ ├── db.ts # SQLite FTS5 数据库层
│ └── parsers/
│ ├── doxygen.ts # Doxygen XML → FunctionRow[]
│ ├── kconfig.ts # Kconfig → KconfigRow[]
│ └── dt-bindings.ts # YAML 绑定 → DtBindingRow[]
├── scripts/
│ └── build-index.ts # 索引构建 CLI
├── dist/ # 编译输出
└── test/
└── fixtures/ # 测试fixtures
```
## 开发
```bash
npm run build # 编译 TypeScript
npm run start # 在stdio上启动MCP服务器
npm run build-index <version> --source <path> # 构建索引
```
## 贡献
欢迎提交PR。主要改进领域：
- **Doxygen XML 获取** — 自动化下载或构建用于预构建索引版本的 Doxygen XML
- **Kconfig 解析器质量** — 当前解析器基于正则表达式；切换到 kconfiglib（Python）将提高准确性
- **RST 文档分块** — 解析 Zephyr 的 RST 文档以获取更丰富的文档搜索结果
- **CI 流水线** — GitHub Action 自动构建新 Zephyr 版本的索引
## 许可证
MIT
