microbit-claude-mcp

MCP server for micro:bit v2 CODAL projects. It exposes a small REST API plus an MCP stdio bridge so agents can read and write source/main.cpp, list sources, validate a project, and run build.py to generate MICROBIT.hex.

Features

• Validate a CODAL project layout
• Read and write source files (defaults to source/main.cpp)
• List C/C++ source files
• Run build.py to build firmware
• REST + MCP stdio transport

Requirements

• A micro:bit v2 CODAL project (for example microbit-v2) with build.py and source/
• Python 3 available as python (or set MICROBIT_PYTHON)
• The micro:bit toolchain required by your CODAL project
• Node.js 18+

Installation

Global install:

npm install -g microbit-claude-mcp

Local dev:

npm install
npm run build
npm run build:mcp

Usage

Run the REST server

microbit-claude-mcp

Defaults to port 3040. Override with:

$env:PORT=3041
microbit-claude-mcp

Run the MCP stdio server

node build/mcp.js

If your REST server is not on the default port, set one of:

• MICROBIT_API_URL (full URL, for example http://localhost:3041)
• MICROBIT_API_PORT (port only, for example 3041)

MCP client config

{
  "mcpServers": {
    "microbit-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/build/mcp.js"]
    }
  }
}

Tutorial (10 minutes)

1. Start the REST server.
2. Validate the project:
   • POST /validate
   • Body: { "projectRoot": "/path/to/microbit-v2" }
3. Read the main source:
   • POST /read_source
   • Body: { "projectRoot": "/path/to/microbit-v2" }
4. Write a small change:
   • POST /write_source
   • Body: { "projectRoot": "/path/to/microbit-v2", "content": "// your code" }
5. Build (optional):
   • POST /build
   • Body: { "projectRoot": "/path/to/microbit-v2" }

Environment variables

• PORT: REST server port (default 3040)
• MICROBIT_API_URL: REST base URL for the MCP bridge
• MICROBIT_API_PORT: REST port for the MCP bridge
• MICROBIT_PYTHON: Python executable for build.py
• MICROBIT_BUILD_TIMEOUT_MS: Build timeout in ms (default 120000)

REST API

Health

• GET /health -> { status: "ok" }

Validate

• POST /validate body: { projectRoot: string }
• Returns { valid, missing, projectRoot }

List sources

• POST /list_sources body: { projectRoot: string }
• Returns { files: string[] }

Read source

• POST /read_source body: { projectRoot: string, relativePath?: string }
• Returns { path, content }

Write source

• POST /write_source body: { projectRoot: string, relativePath?: string, content: string }
• Returns { success, path, bytes }

Append source

• POST /append_source body: { projectRoot: string, relativePath?: string, content: string }
• Returns { success, path, bytes }

Build

• POST /build body: { projectRoot: string, timeoutMs?: number }
• Returns { success, exitCode, stdout, stderr, hexPath, hexExists }

Clawdbot / Moltbot compatibility

This repo ships a skill at skills/microbit-mcp/SKILL.md.

Enable it in Moltbot:

{
  "skills": {
    "load": {
      "extraDirs": ["~/.clawdbot/skills"],
      "watch": true,
      "watchDebounceMs": 250
    },
    "entries": {
      "microbit-mcp": {
        "enabled": true,
        "env": {}
      }
    }
  }
}

Example prompts

• "Open this micro:bit project and add a scrolling LED message that says HELLO."
• "Read source/main.cpp and explain what the program currently does."
• "Add a button A handler that toggles the LED matrix, then build the firmware."

Testing

npm test

The tests focus on REST behavior. The build endpoint is not exercised unless a working CODAL toolchain is installed.

Publishing

1. Update package.json version
2. Build:

   npm run build
   npm run build:mcp

3. Publish:

   npm publish --access public

4. Tag and push to trigger .github/workflows/publish.yml

Project structure

• src/index.ts REST API
• src/mcp.ts MCP stdio bridge
• skills/microbit-mcp/SKILL.md agent skill
• server.json MCP registry metadata

Contributing

PRs welcome. Please keep changes small and include tests where possible.

License

MIT