内容
# microbit-claude-mcp
[](https://www.npmjs.com/package/microbit-claude-mcp)
[](https://github.com/eoinjordan/microbit-mcp/actions/workflows/publish.yml)
适用于 micro:bit v2 CODAL 项目的 MCP 服务器。它公开了一个小型 REST API 和一个 MCP stdio 桥接器，以便代理可以读取和写入 `source/main.cpp`，列出源文件，验证项目，并运行 `build.py` 生成 `MICROBIT.hex`。
## 功能
- 验证 CODAL 项目布局
- 读取和写入源文件（默认为 `source/main.cpp`）
- 列出 C/C++ 源文件
- 运行 `build.py` 构建固件
- REST + MCP stdio 传输
## 要求
- 一个 micro:bit v2 CODAL 项目（例如 `microbit-v2`），包含 `build.py` 和 `source/`
- Python 3 可用（或设置 `MICROBIT_PYTHON`）
- CODAL 项目所需的 micro:bit 工具链
- Node.js 18+
## 安装
全局安装:
```sh
npm install -g microbit-claude-mcp
```
本地开发:
```sh
npm install
npm run build
npm run build:mcp
```
## 使用
### 运行 REST 服务器
```sh
microbit-claude-mcp
```
默认为端口 `3040`。覆盖端口：
```sh
$env:PORT=3041
microbit-claude-mcp
```
### 运行 MCP stdio 服务器
```sh
node build/mcp.js
```
如果您的 REST 服务器不在默认端口上，请设置以下之一：
- `MICROBIT_API_URL`（完整 URL，例如 `http://localhost:3041`）
- `MICROBIT_API_PORT`（仅端口，例如 `3041`）
### MCP 客户端配置
```json
{
"mcpServers": {
"microbit-mcp": {
"command": "node",
"args": ["/绝对路径/to/build/mcp.js"]
}
}
}
```
## 教程（10 分钟）
1. 启动 REST 服务器。
2. 验证项目：
- `POST /validate`
- 正文：`{ "projectRoot": "/路径/to/microbit-v2" }`
3. 读取主源：
- `POST /read_source`
- 正文：`{ "projectRoot": "/路径/to/microbit-v2" }`
4. 写入小更改：
- `POST /write_source`
- 正文：`{ "projectRoot": "/路径/to/microbit-v2", "content": "// 您的代码" }`
5. 构建（可选）：
- `POST /build`
- 正文：`{ "projectRoot": "/路径/to/microbit-v2" }`
## 环境变量
- `PORT`：REST 服务器端口（默认为 `3040`）
- `MICROBIT_API_URL`：MCP 桥接器的 REST 基 URL
- `MICROBIT_API_PORT`：MCP 桥接器的 REST 端口
- `MICROBIT_PYTHON`：用于 `build.py` 的 Python 可执行文件
- `MICROBIT_BUILD_TIMEOUT_MS`：构建超时（毫秒）（默认为 `120000`）
## REST API
### 健康检查
- `GET /health` -> `{ status: "ok" }`
### 验证
- `POST /validate` 正文：`{ projectRoot: 字符串 }`
- 返回 `{ valid, missing, projectRoot }`
### 列出源文件
- `POST /list_sources` 正文：`{ projectRoot: 字符串 }`
- 返回 `{ files: 字符串[] }`
### 读取源文件
- `POST /read_source` 正文：`{ projectRoot: 字符串, relativePath?: 字符串 }`
- 返回 `{ path, content }`
### 写入源文件
- `POST /write_source` 正文：`{ projectRoot: 字符串, relativePath?: 字符串, content: 字符串 }`
- 返回 `{ success, path, bytes }`
### 追加源文件
- `POST /append_source` 正文：`{ projectRoot: 字符串, relativePath?: 字符串, content: 字符串 }`
- 返回 `{ success, path, bytes }`
### 构建
- `POST /build` 正文：`{ projectRoot: 字符串, timeoutMs?: 数值 }`
- 返回 `{ success, exitCode, stdout, stderr, hexPath, hexExists }`
## Clawdbot / Moltbot 兼容性
此仓库在 `skills/microbit-mcp/SKILL.md` 处提供了一个技能。
在 Moltbot 中启用它：
```json
{
"skills": {
"load": {
"extraDirs": ["~/.clawdbot/skills"],
"watch": true,
"watchDebounceMs": 250
},
"entries": {
"microbit-mcp": {
"enabled": true,
"env": {}
}
}
}
}
```
## 示例提示
- "打开这个 micro:bit 项目并添加一个滚动的 LED 消息，显示 HELLO。"
- "读取 source/main.cpp 并解释程序当前的作用。"
- "添加一个按钮 A 处理程序，切换 LED 矩阵，然后构建固件。"
## 测试
```sh
npm test
```
测试关注 REST 行为。除非安装了有效的 CODAL 工具链，否则不会测试构建端点。
## 发布
1. 更新 `package.json` 版本
2. 构建：
```sh
npm run build
npm run build:mcp
```
3. 发布：
```sh
npm publish --access public
```
4. 标签并推送以触发 `.github/workflows/publish.yml`
## 项目结构
- `src/index.ts` REST API
- `src/mcp.ts` MCP stdio 桥接器
- `skills/microbit-mcp/SKILL.md` 代理技能
- `server.json` MCP 注册表元数据
## 贡献
欢迎 PR。请保持更改小，并尽可能包含测试。
## 许可证
MIT
