<div align="center">

![Repo Traffic](https://komarev.com/ghpvc/?username=mcp-docs-server&label=Repo+Traffic&color=blue&style=flat-square)

</div>

# AK Active Kernel documentation MCP server

| EN | [VN](README_VN.md) |

A free, public **[Model Context Protocol](https://modelcontextprotocol.io) server** that gives AI coding tools accurate, queryable knowledge base for the **AK (Active Kernel)** event-driven MCU framework (firmware: [`ak-base-kit-stm32l151`](https://github.com/the-ak-foundation/ak-base-kit-stm32l151)).

It lets an AI assistant:

- Understand the AK kernel core (scheduler, message pools, timers, FSM/TSM),
- Look up exact **API signatures and arguments** (extracted straight from the headers, so they never drift),
- Follow the **rules & format** for creating tasks, drivers, and screens,
- Design new tasks/drivers **without touching** the kernel, boot, sys, networks, or common code.

**(*) Deeply understanding your product is the root of automation success !**

[<img src="images/ak-active-kernel-documentation-mcp-server-1280-640-px.png" width="960"/>](<https://epcb.vn/products/ak-embedded-base-kit-lap-trinh-nhung-vi-dieu-khien-mcu>)

## How it works

This repo is **standalone** - the kernel headers are vendored (committed) under
`vendor/ak-inc/`, so nothing else needs to be cloned to build it.

```
vendor/ak-inc/*.h  ──────────────► scripts/extract.mjs ─┐   (snapshot of the kernel
  ▲ refreshed by                                          │    headers; refresh with
  scripts/fetch-headers.mjs (GitHub)                      ├─►  npm run fetch-headers)
corpus/ (hand-written guides,        scripts/build-corpus ┘─► generated/corpus.json
         guardrails, enrichment) ───────────────────────────►      (docs + BM25 index)
                                                                      │
                                          src/core (resources + tools + prompts)
                                          ├── src/worker  ->  Cloudflare Worker (remote HTTP)
                                          └── src/cli     ->  npx ak-mcp (stdio, local)
```

Signatures come from the vendored kernel headers; semantics/examples are layered on per symbol (`corpus/enrichment/`). A CI **drift check** fails if any cross-reference points at a symbol the headers no longer define.

## What it exposes

**Tools**

| Tool | Purpose |
| --- | --- |
| `start_ak_project(project_name?, ref?)` | resolve the **latest** base-kit release and return download/extract commands + a customization plan |
| `search_ak_docs(query, section?, limit?)` | BM25 search across everything |
| `get_ak_api(symbol)` | exact signature, params, returns, semantics, examples, FATAL codes |
| `list_ak_api(module?)` | browse the API by module (task/message/timer/fsm/tsm/ak/port) |
| `get_ak_guide(topic)` | recipes: start-project, create-task, create-driver, create-screen, use-timer, isr-bridge, tune-pools, **debug-uart-shell**, **kernel-task-log**, **agent-workflow** |
| `get_ak_guardrails()` | do-not-modify zones + kernel invariants |
| `analyze_ak_log(log, context?)` | paste raw UART output -> structured diagnosis: FATAL cause/fix, timing (run-to-completion/starvation), reboot loops, next shell commands |
| `decode_ak_lcd(dump, scale?, invert?)` | paste a `lcd d` framebuffer dump -> the OLED screen rendered as text art **and a PNG image**, with blank/bounding-box stats |

**Prompts:** `ak-new-project`, `ak-new-task`, `ak-new-driver`, `ak-debug` - guided scaffolding/debugging that enforces conventions and guardrails.

**Debugging loop:** the board's only debug surface is its 115200 UART console (leveled printf

- an interactive shell). Agents capture it non-interactively with
[`examples/ak-console.py`](examples/ak-console.py) (pyserial; destructive shell commands are
blocked unless `--allow-destructive`), then feed the text to `analyze_ak_log`.

**Resources:** `ak://index`, and `ak://{section}/{id}` for every concept, guide, guardrail, and API entry.

## Kernel headers (vendored)

The build reads the AK kernel's public headers, which are **committed** under `vendor/ak-inc/`
(a snapshot of a firmware release tag - see `vendor/ak-inc/SOURCE.txt`). Cloning this repo is
enough to build it: **no firmware checkout required.**

Refresh the snapshot when the kernel changes:

```sh
npm run fetch-headers            # pinned default tag (v1.3)
npm run fetch-headers v1.4       # a specific release tag
```

then `npm run build:corpus` and commit `vendor/ak-inc/`. Header resolution order (first
existing wins) - override only if you want to build against a live firmware checkout:

1. `$AK_INC_DIR` - exact path to `.../application/sources/ak/inc`
2. `$AK_FIRMWARE_DIR/application/sources/ak/inc` - a firmware repo root
3. `vendor/ak-inc/` - the committed snapshot (default)

Once `generated/corpus.json` is built, the running server (stdio or Worker) needs **nothing**
external - the corpus is self-contained.

## Develop

```sh
npm install
npm run build:corpus     # generate generated/corpus.json from the headers + corpus/
npm run drift            # build + fail on broken cross-references
npm test                 # extractor, corpus integrity, and search ranking (no deps needed)
npm run typecheck        # core + cli
```

The corpus pipeline (`scripts/*.mjs`) and tests are **zero-dependency** and run on plain Node ≥ 20 - no install required for `npm run build:corpus` / `node --test` (only the firmware headers must be reachable as above).

## Run locally (stdio)

```sh
npm run build            # build:corpus + tsc -> dist/
node dist/cli/bin.js     # or, after publishing: npx -y ak-mcp
```

Inspect it with the MCP Inspector:

```sh
npx @modelcontextprotocol/inspector node dist/cli/bin.js
```

Client config (Claude Desktop / Cursor):

```json
{ "mcpServers": { "ak": { "command": "npx", "args": ["-y", "ak-mcp"] } } }
```

## Deploy (remote, public)

The Worker bundles `corpus.json` at build time, so it needs no database.

```sh
npm run dev              # local Streamable HTTP at http://localhost:8787/mcp
npm run deploy           # build:corpus + wrangler deploy
```

Endpoints: `/mcp` (Streamable HTTP), `/sse` (legacy), `/` (landing page).

Remote client config:

```json
{ "mcpServers": { "ak": { "url": "https://ak-mcp.<your-account>.workers.dev/mcp" } } }
```

**Using it in VS Code (vibe coding):** see [docs/vscode-vibe-coding.md](docs/vscode-vibe-coding.md)
for step-by-step setup (Copilot Agent mode, Cursor, Cline, Claude Code), a copy-paste
[`.vscode/mcp.json`](examples/vscode-mcp.json) template, and a project steering file
([`examples/copilot-instructions.md`](examples/copilot-instructions.md)).

CI (`.github/workflows/ak-mcp.yml`) builds from the vendored headers (no firmware checkout):
`verify` runs build + drift + tests + typecheck on every change, and `deploy` ships from `main`
when `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` secrets are set. A `refresh-headers` job
(manual **Run workflow** with an optional `tag`, or a `repository_dispatch` of type
`firmware-updated` from the firmware repo) re-fetches `vendor/ak-inc/`, verifies it, and commits
the update if anything changed.

## Adding knowledge base

- **The kernel released a new version?** Run `npm run fetch-headers [<tag>]` to refresh `vendor/ak-inc/`, then `npm run build:corpus` and commit the snapshot. New/changed signatures are then extracted automatically.
- **A new API needs prose?** Add `corpus/enrichment/<symbol>.md` to give it semantics/examples (the signature is already extracted).
- **A new recipe or concept?** Add a markdown file under `corpus/guides/` or `corpus/concepts/` with frontmatter (`id`, `title`, `tags`, `summary`, optional `apis`).
- Run `npm run drift` to verify all references resolve.

Enrichment / content frontmatter:

```markdown
---
symbol: timer_set            # enrichment only
summary: One-line summary.
fatal_codes: MT:0x30
see_also: timer_remove_attr, timer_tick
tags: timer, periodic
---
Markdown body (semantics, examples) ...
```