内容
# AK Active Kernel 文档 MCP 服务器
免费的公开 **[模型上下文协议](https://modelcontextprotocol.io)** 服务器，为 AI 编码工具提供准确、可查询的 **AK（Active Kernel）** 事件驱动 MCU 框架（固件：[`ak-base-kit-stm32l151`](https://github.com/the-ak-foundation/ak-base-kit-stm32l151)）的文档。
它让 AI 助手能够：
- 了解 AK 内核核心（调度器、消息池、定时器、FSM/TSM），
- 查询确切的 **API 签名和参数** （直接从头文件提取，确保准确），
- 遵循创建任务、驱动程序和屏幕的 **规则和格式**，
- 在不触及内核、启动、系统、网络或公共代码的情况下，设计新的任务/驱动程序。
## 工作原理
本仓库是 **独立的** - 内核头文件被 Vendored（提交）到 `vendor/ak-inc/` 下，因此无需克隆其他仓库即可构建。
```markdown
vendor/ak-inc/*.h ──────────────► scripts/extract.mjs ─┐ (内核头文件的快照)
▲ 定期刷新 │ （刷新内核头文件）
scripts/fetch-headers.mjs (GitHub) ├─► npm run fetch-headers)
corpus/（手动编写的指南、 scripts/build-corpus ┘─► 生成的/corpus.json
规则、补充） ───────────────────────────► （文档 + BM25 索引）
│
src/core（资源 + 工具 + 提示）
├── src/worker → Cloudflare Worker（远程 HTTP）
└── src/cli → npx ak-mcp（标准输入/输出，本地）
```
签名来自 Vendored 的内核头文件；语义/示例按符号分层（`corpus/enrichment/`）。CI **漂移检查** 如果任何交叉引用指向一个符号，而该符号不再由头文件定义，则检查失败。
## 提供的内容
**工具**
| 工具 | 用途 |
| --- | --- |
| `start_ak_project(project_name?, ref?)` | 解析 **最新** 的基础开发套件版本并返回下载/解压命令 + 自定义计划 |
| `search_ak_docs(query, section?, limit?)` | 对所有内容进行 BM25 搜索 |
| `get_ak_api(symbol)` | 确切的签名、参数、返回值、语义、示例、致命错误代码 |
| `list_ak_api(module?)` | 按模块浏览 API（任务/消息/定时器/FSM/TSM/AK/端口） |
| `get_ak_guide(topic)` | 配方：启动项目、创建任务、创建驱动程序、创建屏幕、使用定时器、ISR 网桥、调整池、 **调试 UART Shell** 、 **内核任务日志** 、 **代理工作流** |
| `get_ak_guardrails()` | 不修改区域 + 内核不变性 |
| `analyze_ak_log(log, context?)` | 粘贴原始 UART 输出 → 结构化诊断：致命错误原因/修复、时间（运行完成/饥饿）、重启循环、下一步 Shell 命令 |
| `decode_ak_lcd(dump, scale?, invert?)` | 粘贴 `lcd d` 缓冲区转储 → 以文本艺术和 PNG 图片形式渲染的 OLED 屏幕，带有空白/边界框统计 |
**提示：** `ak-new-project`、`ak-new-task`、`ak-new-driver`、`ak-debug` - 引导式脚手架/调试，强制执行约定和规则。
**调试循环：** 开发板的唯一调试界面是其 115200 UART 控制台（分级 printf + 交互式 Shell）。代理捕获它，非交互式地使用 [`examples/ak-console.py`](examples/ak-console.py)（pyserial；破坏性 Shell 命令被阻止，除非 `--allow-destructive`），然后将文本输入到 `analyze_ak_log`。
`start_ak_project` 在调用时查询 GitHub 的“最新版本”API（如果 API 无法访问，则回退到固定的 `v1.3`），因此新项目始终从最新标签开始。
**资源：** `ak://index`，和 `ak://{section}/{id}`，适用于每个概念、指南、规则和 API 条目。
## 内核头文件（Vendored）
构建过程读取 AK 内核的公共头文件，这些头文件被 **提交** 到 `vendor/ak-inc/` 下（固件版本标签的快照 - 参见 `vendor/ak-inc/SOURCE.txt`）。克隆此仓库就足够构建它：**不需要固件检查**。
当内核更改时，刷新快照：
```sh
npm run fetch-headers # 默认固定标签（v1.3）
npm run fetch-headers v1.4 # 特定版本标签
```
然后 `npm run build:corpus` 并提交 `vendor/ak-inc/`。头文件解析顺序（首先存在的赢家）- 仅当您想针对实时固件检查构建时才覆盖：
1. `$AK_INC_DIR` - 到 `.../application/sources/ak/inc` 的确切路径
2. `$AK_FIRMWARE_DIR/application/sources/ak/inc` - 固件仓库根目录
3. `vendor/ak-inc/` - 提交的快照（默认）
一旦 `generated/corpus.json` 构建完成，运行的服务器（标准输入/输出或 Worker）需要 **没有任何** 外部依赖 - corpus 是自包含的。
## 开发
```sh
npm install
npm run build:corpus # 从头文件 + corpus/ 生成 generated/corpus.json
npm run drift # 构建 + 失败于损坏的交叉引用
npm test # 提取器、corpus 完整性和搜索排名（无需依赖）
npm run typecheck # 核心 + CLI
```
Corpus 管道（`scripts/*.mjs`）和测试是 **零依赖** 的，并且在普通 Node ≥ 20 上运行 - 无需安装即可运行 `npm run build:corpus` / `node --test`（只需要固件头文件可访问）。
## 本地运行（标准输入/输出）
```sh
npm run build # build:corpus + tsc -> dist/
node dist/cli/bin.js # 或发布后：npx -y ak-mcp
```
使用 MCP 检查器检查：
```sh
npx @modelcontextprotocol/inspector node dist/cli/bin.js
```
客户端配置（Claude Desktop / Cursor）：
```json
{ "mcpServers": { "ak": { "command": "npx", "args": ["-y", "ak-mcp"] } } }
```
## 部署（远程，公开）
Worker 在构建时捆绑 `corpus.json`，因此它不需要数据库。
```sh
npm run dev # 本地 Streamable HTTP，位于 http://localhost:8787/mcp
npm run deploy # build:corpus + wrangler deploy
```
端点：`/mcp`（Streamable HTTP），`/sse`（旧版）， `/`（登录页面）。
远程客户端配置：
```json
{ "mcpServers": { "ak": { "url": "https://ak-mcp.<your-account>.workers.dev/mcp" } } }
```
**在 VS Code 中使用它（vibe coding）：** 参见 [docs/vscode-vibe-coding.md](docs/vscode-vibe-coding.md)，了解逐步设置（Copilot Agent 模式，Cursor，Cline，Claude Code），复制粘贴 [`.vscode/mcp.json`](examples/vscode-mcp.json) 模板，和项目导航文件 [`examples/copilot-instructions.md`](examples/copilot-instructions.md)。
CI（`.github/workflows/ak-mcp.yml`）从 Vendored 头文件（无需固件检查）构建 `verify` 运行构建 + 漂移 + 测试 + 类型检查每次更改，并在 `CLOUDFLARE_API_TOKEN` 和 `CLOUDFLARE_ACCOUNT_ID` 机密设置时从 `main` 部署。`refresh-headers` 作业（手动 **运行工作流**，带有可选的 `tag`，或来自固件仓库的 `repository_dispatch` 类型 `firmware-updated`）重新获取 `vendor/ak-inc/`，验证它，并在有更改时提交更新。
## 添加文档
- **内核发布了新版本？** 运行 `npm run fetch-headers [<tag>]` 刷新 `vendor/ak-inc/`，然后 `npm run build:corpus` 并提交快照。新/更改的签名随后自动提取。
- **新 API 需要正文？** 添加 `corpus/enrichment/<symbol>.md` 以提供语义/示例（签名已经提取）。
- **新配方或概念？** 在 `corpus/guides/` 或 `corpus/concepts/` 下添加带有 frontmatter（`id`、`title`、`tags`、`summary`，可选 `apis`）的 Markdown 文件。
- 运行 `npm run drift` 以验证所有引用是否解析。
补充/内容 frontmatter：
```markdown
---
symbol: timer_set # 仅补充
summary: 一行摘要。
fatal_codes: MT:0x30
see_also: timer_remove_attr, timer_tick
tags: timer, periodic
---
Markdown 正文（语义，示例）...
```
