1. Arcs-mini 上跑通 MCP 控制 GPIO 到底难在哪
Arcs-mini 是聆思科技推出的一块面向语音交互与边缘 AI 的开发板，板载麦克风阵列、屏幕和若干可编程 GPIO，出厂固件里已经内置了 AIUI 语音链路。它最吸引嵌入式开发者的地方，是官方例程里带了一套 MCP（Model Context Protocol）服务框架——也就是说，大模型不只是"聊天"，而是能通过标准协议回调板子上的本地函数，去开关 LED、调屏幕亮度、显示表情，甚至驱动你外接的风扇。
MCP 在这里扮演的角色，可以理解成"大模型和硬件之间的翻译官"。大模型本身不知道 GPIOA 第 4 脚是高电平还是低电平，它只知道"用户想开灯"。MCP 把这句自然语言意图，翻译成一份结构化的 JSON 工具调用请求，通过串口/网络下发到开发板；板子上的 MCP 集成层解析这份 JSON，找到注册过的 handler，执行真正的 GPIO 写操作，再把结果打包回传。整条链路跑通之后，你对着板子说一句"把灯打开"，LED 就亮了。
这套东西适合谁？一类是做智能硬件的嵌入式工程师，想给自己的产品加一层"自然语言控制"；另一类是玩 AI 工具链的开发者，想验证大模型调用本地工具（tool calling）在资源受限设备上的可行性。Arcs-mini 的算力不算强，但胜在官方把 MCP 注册、消息分发、参数校验这些脏活都封装好了，你只需要写业务 handler。
不过实际动手时会遇到几个坎：一是 MCP 的注册宏和消息格式官方文档讲得比较散，得对着源码啃；二是大模型侧要有一个稳定的 API 通道来发起 tool call，本地直连往往卡在网络和鉴权上；三是自定义 MCP 工具时，参数定义、GPIO 初始化、CMake 挂载任何一环漏了，都会表现为"大模型说调用了但灯不亮"。这篇就按"先跑通官方 LED 例程，再自己加一个风扇 MCP"的顺序，把每一步的配置和验证动作写清楚，中间用统一的 Key/API 通道（https://taotoken.net/?utm_source=taotoken_aicg_blog_end）来承接大模型侧的调用请求，避免在鉴权上反复折腾。
我试过把官方例程原封不动烧进去，语音唤醒后说"开灯"，串口日志里能看到Processing MCP tool call，但 LED 没反应——后来发现是唤醒词没替换成功，板子还在等"小聆小聆"。这类"链路通了但动作没执行"的问题，后面第 5 节会逐条对照排查。
2. 前置准备：统一 Key/API 通道与 Arcs-mini 环境
在动 MCP 代码之前，得先把两端的"地基"打好：开发板侧要能编译烧录，大模型侧要有一个能发起 tool call 的稳定入口。很多人卡在第二步——本地直连模型服务时，要么鉴权头拼错，要么网络抖动导致 tool call 请求半路断掉，日志里只留下一句local proxy failed，根本看不出是模型侧还是板子侧的问题。
统一 Key/API 通道的价值就在这里：它把模型调用收敛到一个 Base URL 加一个 Key，板子固件里只需要配置这两个值，不用关心背后是哪个模型、走什么协议。TaoToken 的 API 入口是https://taotoken.net/api，控制台在https://taotoken.net/console，Key 在https://taotoken.net/api-keys生成。生成后你会拿到一串以sk-开头的密钥，这就是后面配置里要填的api_key。
开发板侧的环境搭建，按官方文档走就行：装好工具链，git clone例程仓库，用 CMake 配置目标板型。Arcs-mini 的例程里，MCP 相关代码集中在aiui_mcp.c和mcp_integration.c两个文件，前者管注册和调用，后者管消息分发。编译命令大致是这样：
mkdir build && cd build cmake -DBOARD=arcs_mini -DCMAKE_BUILD_TYPE=Release .. make -j8烧录用官方提供的下载脚本，串口波特率默认 921600。烧完之后打开串口终端（minicom -D /dev/ttyUSB0 -b 921600或 Windows 下用串口助手），能看到启动日志里打印MCP manager initialized，说明 MCP 框架起来了。
大模型侧的配置，我建议先在电脑上用一个最小的 Python 脚本验证通道是否通，再去改板子固件。这样出问题时能快速定位是通道问题还是固件问题。脚本里把 Base URL 指向https://taotoken.net/api，模型 ID 填你控制台里开通的那个，发一个带 tools 定义的请求，看返回里有没有tool_calls字段。这一步通了，再往板子上搬。
有一点要注意：Arcs-mini 的固件里，模型调用的地址和 Key 通常写在aiui_config.h或类似的配置头文件里，别硬编码在业务代码中，方便后面换环境。如果你用的是 Claude Code 这类工具做辅助开发，可以在~/.claude/settings.json里配好同样的 Base URL 和 Key，让它在帮你写 MCP handler 时也能直接调模型验证逻辑。
3. 可复制配置：MCP 注册片段与 settings 文件
这一节给的是能直接抄的配置。先看板子侧的 MCP 工具注册。官方例程用MCP_REGISTER_TOOL_STATIC宏做静态注册，LED 的两个工具是这样定义的：
// 注册LED开关控制工具 MCP_REGISTER_TOOL_STATIC(led_switch, "控制LED开关状态，可以是开启或关闭", "1.0", led_switch_params, 1, led_switch_handler, false, NULL); // 注册LED闪烁控制工具 MCP_REGISTER_TOOL_STATIC(led_blink, "控制LED闪烁模式，可以是关闭、普通、快速或慢速", "1.0", led_blink_params, 1, led_blink_handler, false, NULL);宏的参数依次是：工具名、给大模型看的描述、版本、参数定义数组、参数个数、handler 函数、是否异步、用户数据。描述这一栏很关键，大模型就是靠它判断"用户说开灯时该调哪个工具"，所以别写得太抽象，把"开启或关闭"这种枚举值写进去，模型选错工具的概率会低很多。
参数定义用MCP_PARAM_DEF宏，比如 LED 开关的action参数：
static mcp_param_def_t led_switch_params[] = { MCP_PARAM_DEF("action", MCP_PARAM_STRING, true, "LED开关操作，可以是 'on'、'turn_on'、'off' 或 'turn_off'", NULL), MCP_PARAM_DEF_END };第三个参数true表示必填，第四个是描述，同样要写清楚可选值。handler 里解析参数时，遍历ctx->params找到action，比对字符串后调用 GPIO 写函数。
再看大模型侧的 settings 配置。如果你用 Claude Code 做开发辅助，~/.claude/settings.json里这样写：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的Key", "ANTHROPIC_MODEL": "你的模型ID" } }这三件套——Base URL、Key、Model ID——缺一不可。Base URL 不带 UTM 参数，就是干净的https://taotoken.net/api。Key 从控制台生成，Model ID 在模型列表里选。配好之后重启 Claude Code，它发起的请求就会走这条通道。
如果你用的是 Cline 或类似的 VS Code 插件，配置项名字不同但逻辑一样：找Base URL、API Key、Model三个字段填进去。Cline 的 MCP 配置在cline_mcp_settings.json里，格式是：
{ "mcpServers": { "arcs-mini": { "command": "python", "args": ["-m", "arcs_mcp_bridge"], "env": { "ARCS_SERIAL_PORT": "/dev/ttyUSB0", "ARCS_BAUD": "921600" } } } }这个 bridge 的作用是把电脑上的 MCP 请求转发到串口，板子收到后执行。注意ARCS_SERIAL_PORT要换成你实际的串口设备名，Linux 下是/dev/ttyUSB0，Windows 下是COM3这种。
Codex 用户如果走auth.json配置，文件在~/.codex/auth.json，里面填api_key和base_url两个字段，值同上。不管哪个工具，核心就这三件套，配错任何一个都会在请求阶段报 401。
4. 验证请求：从连接测试到引脚读写确认
配置填完，别急着说"开灯"，先做三步验证，每步都有明确的成功标志。
第一步，连接测试。在电脑上跑一个最小请求，确认通道通。用 curl 发一个带 tools 的请求：
curl https://taotoken.net/api/v1/messages \ -H "x-api-key: sk-你的Key" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "你的模型ID", "max_tokens": 256, "tools": [{ "name": "led_switch", "description": "控制LED开关状态", "input_schema": { "type": "object", "properties": { "action": {"type": "string", "enum": ["on", "off"]} }, "required": ["action"] } }], "messages": [{"role": "user", "content": "把灯打开"}] }'成功标志：返回 JSON 里stop_reason是tool_use，content数组里有一个type为tool_use的块，name是led_switch，input里action是on。这说明模型正确理解了意图并选择了工具。如果返回的是普通文本，说明 tools 定义没被识别，检查input_schema格式。
第二步，板子侧连接测试。串口终端里，板子启动后应该打印 MCP 初始化日志。然后手动往串口发一条模拟的 MCP 请求，格式参考mcp_integration_process_message里解析的结构：
{ "action": "mcp", "method": "tools/call", "data": { "id": "test-001", "name": "led_switch", "arguments": {"action": "on"} } }成功标志：串口打印Calling tool: led_switch with 1 parameters，紧接着Tool call completed successfully，同时板子上的 LED 点亮。如果只打印了Processing MCP tool call但没有后续，说明mcp_integration_extract_tool_call解析失败，检查 JSON 字段名是否和代码里cJSON_GetObjectItem取的一致。
第三步，端到端语音测试。唤醒板子（默认"小聆小聆"，替换后是你设的词），说"把灯打开"。串口日志应该依次出现：语音识别结果、MCP 消息分发、工具调用、执行成功。LED 亮起，屏幕如果有表情也会同步变化。这一步的成功标志最直观——灯真的亮了。
引脚读写确认，可以在 handler 里加一行日志，打印 GPIO 寄存器的值：
LISA_LOGI(TAG, "GPIOA pin4 value: %d", GPIO_PinRead(GPIOA(), 0x01 << 4));执行led_switch后，这行日志应该从 0 变 1（或反过来，取决于你的电路是高电平点亮还是低电平点亮）。如果日志里值变了但灯不亮，那就是硬件接线或限流电阻的问题，不是软件问题。
5. 常见报错排查：401、local proxy failed 与 OAuth
这一节对照真实会遇到的报错，逐条给排查路径。
401 Unauthorized。最常见，出现在大模型侧请求阶段。原因通常是 Key 填错、Key 过期、或者 Base URL 写成了带路径的地址。检查三点：Key 是不是从https://taotoken.net/api-keys生成的完整字符串；Base URL 是不是干净的https://taotoken.net/api，后面不要跟/v1之类的后缀（有些工具会自动拼）；请求头字段名对不对，Anthropic 协议用x-api-key，OpenAI 协议用Authorization: Bearer。如果三件套里 Model ID 填了一个没开通的模型，也会返回 401 或 403，去控制台确认模型状态。
local proxy failed。这个报错通常出现在板子固件里配置了本地代理地址，但代理进程没起来，或者端口被占。Arcs-mini 的例程如果走串口转发，检查 bridge 进程是否在跑，ps aux | grep arcs_mcp_bridge看有没有。如果是网络转发，检查板子和电脑是否在同一网段，ping一下。还有一种情况是防火墙拦了本地端口，临时关掉防火墙测试。
reading choices 报错。这个一般出现在用 OpenAI 兼容协议调模型时，返回体里没有choices字段。原因可能是模型返回了错误结构，或者请求被中间层改写。先看完整返回体，如果里面有error字段，按 error 信息排查；如果返回体是空的，检查max_tokens是不是设得太小导致截断。还有一种可能是 tools 定义里input_schema写成了parameters（OpenAI 格式），协议不匹配导致解析失败。
OAuth 相关报错。如果你用的工具走 OAuth 流程（比如某些 IDE 插件），报OAuth token expired或invalid_grant，说明 token 过期了。重新走一遍授权流程，或者在设置里换成 API Key 模式。Claude Code 的settings.json里如果同时配了 OAuth 和 API Key，可能会冲突，建议只保留 API Key 三件套。
工具调用了但 handler 没执行。串口日志有Processing MCP tool call但没有Calling tool，说明mcp_integration_extract_tool_call返回了错误。检查 JSON 里data.name字段是否和注册的工具名完全一致（大小写敏感），arguments里的参数名是否和MCP_PARAM_DEF里定义的一致。参数类型也要对，定义的是MCP_PARAM_STRING，传进来的是数字，校验会失败。
GPIO 无输出。handler 执行了，日志也打印成功，但引脚没电平变化。检查GPIO_Initialize有没有调用，IOMuxManager_PinConfigure有没有把引脚复用成 GPIO 功能，GPIO_SetDir有没有设成输出。这三步漏任何一步，引脚都不会动。另外确认你操作的端口和引脚号跟实际接线一致，GPIOA和GPIOB别搞混。
6. 自定义 MCP 工具：加一个风扇控制并接入 GPIO
官方 LED 例程跑通后，自己加一个风扇 MCP 工具，是验证整套框架可扩展性的最好方式。思路和 LED 一样：写 handler、定义参数、注册工具、接 GPIO、挂 CMake。
先写风扇的业务层。新建fan_control.c，里面定义状态和 handler：
#include "fan_control.h" #include "aiui_mcp.h" #include "lisa_log.h" #include "cJSON.h" #include <string.h> #define TAG "fan_control" static int fan_state = 0; static mcp_result_t fan_switch_handler(const mcp_context_t *ctx, mcp_response_t *response) { if (!ctx || !response) return MCP_RESULT_INVALID_PARAM; const char *action = NULL; for (uint32_t i = 0; i < ctx->param_count; i++) { if (strcmp(ctx->params[i].name, "action") == 0 && cJSON_IsString(ctx->params[i].value)) { action = ctx->params[i].value->valuestring; } } if (!action) { response->content = cJSON_CreateString("错误：缺少 action 参数"); return MCP_RESULT_INVALID_PARAM; } int new_state = -1; if (strcmp(action, "on") == 0 || strcmp(action, "turn_on") == 0) new_state = 1; else if (strcmp(action, "off") == 0 || strcmp(action, "turn_off") == 0) new_state = 0; else { response->content = cJSON_CreateString("错误：action 只能是 on/off"); return MCP_RESULT_INVALID_PARAM; } fan_state = new_state; if (fan_state) app_fan_on(); else app_fan_off(); char msg[64]; snprintf(msg, sizeof(msg), "风扇已%s", fan_state ? "开启" : "关闭"); response->content = cJSON_CreateString(msg); return MCP_RESULT_SUCCESS; } static mcp_param_def_t fan_switch_params[] = { MCP_PARAM_DEF("action", MCP_PARAM_STRING, true, "风扇开关操作，可以是 'on'、'turn_on'、'off' 或 'turn_off'", NULL), MCP_PARAM_DEF_END }; MCP_REGISTER_TOOL_STATIC(fan_switch, "控制风扇开关状态，可以是开启或关闭", "1.0", fan_switch_params, 1, fan_switch_handler, false, NULL);再写硬件层fan.c，把 GPIO 初始化封装好：
#include "fan.h" #include "Driver_GPIO.h" #include "IOMuxManager.h" #include "lisa_log.h" #define TAG "fan" #define FAN_GPIO_PORT GPIOA #define FAN_PIN_NUM 4 #define FAN_PIN_MASK (0x01 << FAN_PIN_NUM) #define FAN_IOMUX_PAD CSK_IOMUX_PAD_A #define FAN_IOMUX_FUNC CSK_IOMUX_FUNC_DEFAULT static void fan_hw_control(bool state) { GPIO_PinWrite(FAN_GPIO_PORT(), FAN_PIN_MASK, state ? 1 : 0); } void fan_hw_init(void) { GPIO_Initialize(FAN_GPIO_PORT(), NULL, NULL); IOMuxManager_PinConfigure(FAN_IOMUX_PAD, FAN_PIN_NUM, FAN_IOMUX_FUNC); GPIO_SetDir(FAN_GPIO_PORT(), FAN_PIN_MASK, CSK_GPIO_DIR_OUTPUT); GPIO_PinWrite(FAN_GPIO_PORT(), FAN_PIN_MASK, 0); } void app_fan_init(void) { fan_hw_init(); LISA_LOGI(TAG, "Fan service initialized"); } void app_fan_on(void) { LISA_LOGI(TAG, "Turning fan ON"); fan_hw_control(true); } void app_fan_off(void) { LISA_LOGI(TAG, "Turning fan OFF"); fan_hw_control(false); }注意FAN_PIN_NUM和FAN_IOMUX_PAD要按你实际接线的引脚改。我一开始照抄例程用了 GPIOA 第 4 脚，结果那个脚被屏幕占用了，风扇纹丝不动，换成 GPIOB 第 2 脚才正常。所以接线前先查板子的引脚复用表。
最后挂 CMake。在CMakeLists.txt里把新文件加进源文件列表：
set(APP_SOURCES ${APP_SOURCES} src/fan_control.c src/fan.c )编译烧录，串口里应该能看到Fan service initialized。然后对着板子说"把风扇打开"，日志里出现Calling tool: fan_switch，风扇转起来。如果模型没选对工具，把fan_switch的描述改得更具体一点，比如加上"用于控制散热风扇"，模型区分度会更高。
整套跑下来，你会发现 MCP 的扩展成本很低——业务逻辑、硬件操作、注册声明三块分开写，互不干扰。后面想加什么设备，照这个模板复制一份就行。真正花时间的不是写代码，而是排查"模型选了工具但硬件没动"这类链路问题，把第 5 节的排查清单存下来，下次遇到直接对照。
