MCP 使用指南

概述

MCP（Model Context Protocol） 是 Anthropic 推出的开放标准协议，让 AI Agent 安全地与外部工具、数据源和工作流连接。 通过 MCP，AI Agent 不再只是给出建议——它可以直接执行操作。Claude Code、Cline、Continue、Roo Code 等主流 AI Agent 均可使用。

Ameba 提供两套 MCP 服务，分工明确，协同形成"查文档 → 改代码 → 编译 → 烧录 → 观察现象"的自动化迭代闭环：

• 文档查询 MCP（知识层） ——云端 MCP 服务器，让 AI Agent 通过 HTTP 查询 Ameba 官方文档，了解 API 用法和示例代码。

• SDK 开发 MCP（执行层） ——本地 MCP 服务器，由 AI 客户端（Claude Code）在本机直接启动并通过标准输入/输出通信，无需联网或额外认证；可直接修改工程配置、编译、烧录并验证代码运行结果。

文档查询 MCP 与 AI 聊天机器人 共享知识源，但面向不同的使用场景：聊天机器人服务于开发者本人手动提问；文档查询 MCP 则服务于 AI Agent，让其在 SDK 实际开发过程中实时、自动化地查询文档，辅助代码决策——这是它的核心价值。

下图展示了开发板、PC、AI Agent、两套 MCP 服务与 Ameba SDK 之间的关系，以及典型开发工作流：

1. 编辑代码：Agent 根据 SDK 具体代码以及文档 MCP 知识，在编辑器中修改 SDK 源码；

2. 编译固件：Agent 调用 build_firmware 工具，触发 cmake/ninja 编译，并自动同步烧录布局配置到 project_info.json5 ；

3. 烧录固件：Agent 调用 flash_firmware_tool 工具，通过 AmebaFlash.py 将固件烧入开发板；

4. 串口验证：Agent 调用 serial_expect_tool 等工具，等待 boot 日志或执行交互命令，验证运行结果。

文档查询 MCP

Ameba AIoT 文档提供 MCP 服务器，与 AI 聊天机器人 共享知识源。AI Agent 安装 Ameba 文档查询 MCP 服务器后可以直接查询和检索 Ameba AIoT 官方文档内容。

获取 MCP 服务器地址

获取 MCP 服务器地址步骤如下：

1. 打开 RealMCU AIOT 网页

2. 页面右下角点击 AI 图标打开 RealMCU AI 聊天机器人

3. 在弹出的对话框中找到 使用 MCP 下拉框

4. Claude Code 选择点击 添加到 Claude Code ，复制 CLI 命令

5. 其他 AI Agent 如 Roo Code、Cline、Continue 等，点击 复制 MCP 链接 获取 MCP 服务器地址

备注

MCP 服务器地址：

https://ameba-aiot.mcp.kapa.ai

获取到 MCP 服务器地址后，按照下方对应 AI Agent 的 tab 完成接入。

安装与认证

通用步骤：1. 获取 MCP 服务地址（见上节）；2. 配置 MCP 客户端；3. 完成认证（通常通过 GitHub OAuth）；4. 开始使用。

Claude CodeClineRoo CodeContinue

Claude Code:

步骤 1 ：添加 MCP 服务

在终端中运行如下命令，为 Claude Code 添加 Ameba 文档查询 MCP 服务：

claude mcp add --transport http realmcu-ask-ai-docs https://ameba-aiot.mcp.kapa.ai

参数说明：

• --transport http ：使用 HTTP 传输协议

• realmcu-ask-ai-docs ：MCP 服务器名称（可自定义）

• https://ameba-aiot.mcp.kapa.ai ：MCP 服务地址

步骤 2 ：完成认证

1. 打开 Claude Code

2. 在对话框中输入 /mcp 命令，查看 realmcu-ask-ai-docs 认证状态:

   realmcu-ask-ai-docs · △ needs authentication
   

3. 按回车键确认认证，按照 Claude 的提示完成认证流程

4. 认证成功后，返回 Claude 界面继续对话

5. 再次输入 /mcp 命令查看认证状态

   realmcu-ask-ai-docs · ✔ connected
   

小技巧

• 查看已添加的 MCP 列表： claude mcp list

• 移除 MCP 服务： claude mcp remove realmcu-ask-ai-docs

查询示例

以 Claude Code 为例，以下是实际查询 Ameba 文档的示例：

示例 1 ：查询 OTA 压缩功能概述

示例 2 ：查询 GPIO 使用方法

MCP 功能列表

文档查询 MCP 服务器基于 HTTP 协议，向 AI Agent 提供以下工具：

工具	描述
search_realtek_knowledge_sources(query)	对 Realtek 的文档及其他知识库执行语义检索，返回与查询最相关的文本片段和来源链接，为 AI Agent 提供官方参考资料。

常见问题排查

现象 / 问题	解决方法
MCP 服务连接失败	确认网络可访问 ameba-aiot.mcp.kapa.ai ；确认认证的 Token 是否正确
认证后能持续使用多久	认证有效期取决于 Token 类型，通常长期有效。如需重新认证，告诉 AI Agent "重新进行 MCP 认证"
能否同时配置多个 MCP 服务	可以。在同一配置文件中添加多个 MCP 服务器条目，使用不同的 server 名称即可
AI Agent 没有主动调用 MCP 服务	当前对话上下文未触发调用条件。明确告诉 AI 使用 MCP 查询，例如 "请通过 realmcu-ask-ai-docs MCP 服务查询 Ameba 的 OTA 功能"

SDK 开发 MCP

SDK 开发 MCP 在本机将 MCP server 作为子进程启动，通过标准输入/输出与 AI 客户端直接交互，无需网络连接或额外认证。AI 可以直接修改工程配置，以及编译、烧录、读写串口，并根据返回结果继续决策，实现自动化闭环开发。

该 MCP 针对嵌入式开发场景做了深度优化：工具组合、参数设计、返回值的结构等，均以 Agent 易用为第一优先级。 编译、烧录日志专门做了精简处理，比直接调用 CLI 命令节约大量上下文，且保留关键错误信息和丰富提示，帮助 Agent 准确判断下一步动作。

软件环境与安装注册

步骤一：初始化环境与安装依赖

Linux / macOS / WSL2Windows

Linux / macOS / WSL2:

将 <SDK_ROOT> 替换为 SDK 的实际绝对路径（如 /home/user/ameba-sdk），在 SDK 根目录执行以初始化 Python 虚拟环境与工具链，并完成首次编译：

cd <SDK_ROOT>
source env.sh
ameba.py build

步骤二：注册 MCP

将 SDK 开发 MCP 注册到 AI 客户端。配置作用于当前 SDK 工作区，不同 SDK checkout 互不干扰。

Claude CodeTraeCline

Claude Code:

在 SDK 根目录执行注册命令（配置写入 ~/.claude.json 或 %APPDATA%\Claude\claude.json 的 workspace 层级）：

# Linux / macOS / WSL2
claude mcp add ameba-dev -- <SDK_ROOT>/tools/ameba/ameba_dev_mcp/launcher.sh

# Windows
claude mcp add ameba-dev -- <SDK_ROOT>\tools\ameba\ameba_dev_mcp\launcher.bat

验证：

claude mcp list
# 应出现：ameba-dev: ✓ Connected

卸载：

claude mcp remove ameba-dev

备注

MCP server 依赖 .venv 存在才能启动。如果在注册 MCP 时 .venv 尚未建立，AI 客户端会显示连接失败。完成步骤一后重启 AI 客户端即可自动连上。

配置开发板

首次使用前，在 Claude Code 对话框中执行：

/ameba-setup-boards

AI 会引导填写开发板型号、串口端口等信息，并自动完成只读环境自检，全程无需手动编辑 JSON 文件。完成后在 SDK 根目录生成两个配置文件：

文件	说明
board_info.json5	板子配置：alias → SoC 型号 + 串口端口 + 连接方式（本地/远端）
project_info.json5	烧录布局：各 SoC 的固件文件与地址表，首次 build_firmware 后自动填充

之后若需增减开发板或更换端口，重新执行 /ameba-setup-boards 或直接编辑 board_info.json5 即可。 如需手工指定烧录的 .bin 文件与 Flash 地址，参考 附录：project_info.json5 手动模式 。

典型 Agent 开发流程

在 Claude Code 中告诉 AI 你的开发目标，AI 会依次调用 build_firmware → flash_firmware_tool → serial_connect_tool → serial_expect_tool → serial_disconnect_tool 完成一轮验证：

# 在 Claude Code 中告诉 AI：
帮我修改 main 函数的打印日志，加入工程版本号。编译烧录 RTL8720E_COM20，等开发板 boot 完成后把 boot log 给我看

AI 串行调用示例：

build_firmware(alias="RTL8720E_COM20")
flash_firmware_tool(alias="RTL8720E_COM20")
serial_connect_tool(alias="RTL8720E_COM20")
serial_expect_tool(alias="RTL8720E_COM20",
                   patterns=["KM4 START SCHEDULER", "Crash Dump"],
                   timeout=20.0)
serial_disconnect_tool(alias="RTL8720E_COM20")

MCP 功能列表

SDK 开发 MCP 向 AI Agent 提供三类功能：

• 工具（Tools） 是 AI 可直接调用的操作（如编译、烧录、串口读写）；

• 提示词（Prompts） 是预置的引导流程，Agent 据此完成多步交互任务；

• 资源（Resources） 是 AI 可读取的只读数据（如设备信息、配置文件）。

工具（Tools）

工具	说明
set_target	切换当前编译目标 SoC
build_firmware	编译当前 SoC 固件；成功后自动同步 project_info.json5
flash_firmware_tool	按 board/project 配置烧录固件到开发板
list_serial_ports_tool	列出本机或指定开发板的可用串口
scan_remote_ports_tool	扫描远端 AmebaRemoteService 上的可用串口（无需 board_info.json5）
apply_board_config_tool	写入或合并 board_info.json5 板子配置
env_pre_check_tool	只读环境自检：验证 JSON 配置、串口可见性及远端 TCP 连通性
kconfig_get	读取 Kconfig 符号当前值
kconfig_set	写入 Kconfig 符号值并重新生成头文件
kconfig_search	按名称或提示文本搜索 Kconfig 符号（支持正则）
serial_connect_tool	打开串口，默认复位开发板并清空缓冲区
serial_disconnect_tool	关闭串口连接，释放端口
serial_command_tool	发送命令并等待响应（含清缓冲 + 写入 + 模式匹配）
serial_expect_tool	阻塞等待指定关键字匹配、空闲或超时
serial_read_tool	非阻塞快照当前缓冲区内容

提示词（Prompts）

提示词	说明
/ameba-setup-boards	引导完成开发板配置初始化，一次交互生成 board_info.json5 ，并自动调用 env_pre_check_tool 完成验证

资源（Resources）

资源 URI	说明
device://profiles	列出所有支持的设备 profile 及内存类型
device://{device_name}/info	获取指定设备的 Flash 布局、RAM 地址、固件列表等详细信息
device://{device_name}/{memory_type}/info	获取指定设备与内存类型（nor/nand）的详细 profile
board://list	列出 board_info.json5 中已配置的所有开发板 alias
board://{alias}	获取单块开发板的已解析配置（密码已脱敏）
config://project_info	完整 project_info.json5 内容（烧录布局）
config://board_info	完整 board_info.json5 内容（密码已脱敏）
debug://hardware	硬件故障排查参考（驱动、自动下载电路、常见错误码）

常见问题排查

在 Claude Code 中按 Ctrl+O 可展开 MCP 工具调用的详细参数与返回值，查看具体错误码。提醒：

• 远端场景：开发板接在 Windows PC 上时，需运行 AmebaRemoteService.exe 做串口 TCP 转发（端口 58916）。

• 自动下载电路：开发板需要支持硬件自动下载电路，否则自动下载和自动 reset 将不能工作。（自动下载电路要求详见 <SDK_ROOT>/tools/ameba/ameba_dev_mcp/hardware_debug.md）

现象 / 错误码	解决方法
BOARD_CONFIG_MISSING / PROJECT_CONFIG_MISSING	重新执行 /ameba-setup-boards 生成配置文件；或参照 envelope 中的 template_path 手动填写
PORT_NOT_VISIBLE	确保开发板已插上
REMOTE_UNREACHABLE	在远端 Windows PC 启动 AmebaRemoteService.exe，检查 58916 端口防火墙
RESET_FAILED 或烧录卡在进入下载模式	满足 <SDK_ROOT>/tools/ameba/ameba_dev_mcp/hardware_debug.md 硬件下载电路要求
ALIAS_REQUIRED / ALIAS_NOT_FOUND	错误提示中已列出可用 alias，选择正确的开发板别名重试
ameba-dev 在 claude mcp list 显示未连接	确认已执行 source env.sh 并完成首次编译；之后重启 Claude Code。确保 MCP 注册命令里 <SDK_ROOT> 是有效的绝对路径
server 启动失败（import 错误）	手动运行 <SDK_ROOT>/tools/ameba/ameba_dev_mcp/launcher.sh （Windows 同名 .bat ）查看完整 stderr 输出

附录：project_info.json5 手动模式

project_info.json5 中每个 SoC 条目支持两种模式：

模式	images 由谁管理	build_firmware 后会覆盖 images 字段内容？
auto	MCP 自动写入	会 （每次编译成功后自动更新）
manual	用户手工填写	不会 （MCP 永不修改此条目）

手动模式适合以下场景：

• 需要固定烧录指定地址的 .bin ，不让编译结果覆盖配置；

• 烧录与编译分离（例如烧录预编译好的 release bin）；

• 需要自定义哪些 image 参与烧录（增删条目）。

配置方法

将 flash_layout_setting_mode 改为 "manual" ，并手工填写 build_dir 和 images[] ：

"RTL8721F": {
  "flash_layout_setting_mode": "manual",
  "build_dir": "/home/me/sdk/build_RTL8721F",
  "memory_type": "nor",
  "images": [
    {
      "path": "/home/me/sdk/build_RTL8721F/boot.bin",
      "start_addr": "0x08000000",
      "end_addr": "0x0803FFFF"
    },
    {
      "path": "/home/me/sdk/build_RTL8721F/app.bin",
      "start_addr": "0x08040000"
      /* end_addr 可省略，省略时按实际文件大小推算，用于区段重叠校验 */
    },
    {
      /* optional=true：文件不存在时只警告，不阻断烧录 */
      "path": "/home/me/sdk/build_RTL8721F/vfs.bin",
      "start_addr": "0x083C0000",
      "optional": true
    }
  ]
}

字段说明：

字段	必填	说明
flash_layout_setting_mode	是	固定为 "manual"
build_dir	是	绝对路径，指向 build_<SOC>/ 目录
memory_type	否	"nor" / "nand" / "ram" ，缺省继承 defaults.memory_type
images[].path	是	.bin 文件绝对路径
images[].start_addr	是	Flash 起始地址，格式 0x...
images[].end_addr	否	结束地址（含）；省略时按文件大小推算，仅用于区段重叠校验
images[].optional	否	true 时文件缺失只警告不报错（适合 VFS 等可选 image）

从 auto 迁移到 manual

1. 找到当前 project_info.json5 中该 SoC 的 auto 条目，将 generated by build 注释块内的 images 数据复制出来；

2. 将 flash_layout_setting_mode 改为 "manual" ；

3. 删除 /* === generated by build, do not edit === */ 注释；

4. 按需调整 images[] 内容。

此后 build_firmware 编译成功也不会覆盖此条目，flash 地址由你全权掌控。

注意事项

• 所有 path 必须是绝对路径 ，相对路径会被校验拒绝；

• images[] 至少填一项，否则报 MANUAL_IMAGES_EMPTY ；

• 烧录前 MCP 会做区段重叠校验 （当 end_addr 已知时）；

• 手动模式下 MCP 不会 重新解析 SDK flash layout，用户负责保证地址与 SDK 一致。