AK Active Kernel documentation MCP server

| EN | VN |

A free, public Model Context Protocol server that gives AI coding tools accurate, queryable knowledge base for the AK (Active Kernel) event-driven MCU framework (firmware: 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 !

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.

Related MCP server: jlink-mcp

What it exposes

Tools

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 (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:

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

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)

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:

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

Client config (Claude Desktop / Cursor):

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

Deploy (remote, public)

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

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:

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

Using it in VS Code (vibe coding): see docs/vscode-vibe-coding.md for step-by-step setup (Copilot Agent mode, Cursor, Cline, Claude Code), a copy-paste .vscode/mcp.json template, and a project steering file (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:

---
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) ...