ESP32 MCP C SDK 测试应用全解析91 个用例覆盖 API、协议合规与内存安全【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution导读本文基于 components/mcp-c-sdk/test_apps/README.md 展开系统讲解乐鑫 IoT 解决方案仓库中 MCP C SDKModel Context Protocol C SDK配套测试应用的设计与使用。该测试应用以 Unity 测试框架为底座覆盖 SDK 全部公共 API、JSON-RPC 2.0 协议语义、MCP 2024/2025 版本特性、线程安全与内存泄漏检测共 91 个用例53 个 API/集成用例 38 个协议合规用例。读完本文你将掌握如何构建、烧录并运行这套测试理解其测试分组组织方式学会用pytest自动化矩阵与一键脚本高效完成回归验证。一、测试应用定位与运行环境mcp-c-sdk是 ESP32 平台上一套完整的 MCP 协议 C SDK它让设备能够以标准化方式暴露工具tools、资源resources、提示词prompts供 AI 代理发现与调用。测试应用位于 components/mcp-c-sdk/test_apps其角色是对该组件的单元测试与协议合规性验证载体而非一个可演示的业务示例。运行环境有两个硬性前提ESP-IDF v5.0 或更高版本工程通过 test_apps/CMakeLists.txt 引入$ENV{IDF_PATH}/tools/unit-test-app/components与$ENV{IDF_PATH}/examples/common_components/protocol_examples_common并注册了mcp-c-sdk组件Unity 测试框架由 ESP-IDF 内置携带测试主程序 main/test_mcp_c_sdk.c 通过PRIV_REQUIRES unity mcp-c-sdk test_utils cjson esp_http_client声明依赖见 main/CMakeLists.txt。测试既可在真实硬件上运行也可在 QEMU 上运行其中线程安全用例使用 FreeRTOS 任务模拟并发访问而 MCP Transport Manager 的测试则依赖一个mock transport 实现无需真实 HTTP 服务器。二、测试覆盖全景从公共 API 到端到端工作流2.1 MCP Transport Manager APIesp_mcp_mgr.hTransport Manager 是 SDK 三层体系管理/路由层 → 传输层 → 协议语义层中的管理/路由层测试覆盖esp_mcp_mgr_init()/esp_mcp_mgr_deinit()esp_mcp_mgr_start()/esp_mcp_mgr_stop()esp_mcp_mgr_register_endpoint()/esp_mcp_mgr_unregister_endpoint()esp_mcp_mgr_req_handle()—— 以 JSON-RPC 消息为输入的请求处理esp_mcp_mgr_req_destroy_response()—— 响应缓冲区清理各类错误路径NULL 参数、非法句柄、非法 transport以 test_mcp_c_sdk.c 中的test_mcp_init_deinit、test_mcp_start_stop为例可看到标准生命周期测试模式先esp_mcp_create创建引擎实例再以esp_mcp_mgr_config_t配置.transport指向 mock transport、.config指向任意配置、.instance指向引擎实例调用esp_mcp_mgr_init随后验证 start/stop 往返最后按先 stop 再 deinit的顺序清理。非法参数路径则断言返回ESP_ERR_INVALID_ARG如test_mcp_start_invalid_handle、test_mcp_deinit_invalid_handle。端点注册测试test_mcp_register_unregister_endpoint还验证了关键状态机重复注册同一端点返回ESP_ERR_INVALID_STATE重复注销返回ESP_ERR_NOT_FOUND。2.2 MCP Engine APIesp_mcp_engine.h引擎层负责协议语义与工具调度测试覆盖esp_mcp_create()/esp_mcp_destroy()、esp_mcp_add_tool()/esp_mcp_remove_tool()。其中test_server_add_remove_tool验证了同名工具重复添加返回ESP_ERR_INVALID_STATE、重复移除失败的约束NULL 参数路径返回ESP_ERR_INVALID_ARG。2.3 Tool APIesp_mcp_tool.h与 Property APIesp_mcp_property.hTool API 测试覆盖esp_mcp_tool_create()/esp_mcp_tool_destroy()、esp_mcp_tool_add_property()/esp_mcp_tool_remove_property()并验证了 name/description/callback 任一为 NULL 时创建失败。Property API 则逐一测试全部属性创建函数创建函数说明测试用例示例esp_mcp_property_create_with_bool布尔属性test_property_create_boolesp_mcp_property_create_with_int整数属性test_property_create_intesp_mcp_property_create_with_float浮点属性test_property_create_floatesp_mcp_property_create_with_string字符串属性test_property_create_stringesp_mcp_property_create_with_array数组属性test_property_create_arrayesp_mcp_property_create_with_object对象属性test_property_create_objectesp_mcp_property_create_with_range带范围约束属性test_property_create_with_rangeesp_mcp_property_create_with_int_and_range默认值 范围test_property_create_with_int_and_range2.4 Value APIesp_mcp_data.hValue 是工具回调的返回值载体测试验证esp_mcp_value_create_bool/int/float/string的类型标记ESP_MCP_VALUE_TYPE_*与数据字段如test_value_create_string同时断言销毁后string_value被置空test_value_create_string_null验证 NULL 入参返回ESP_MCP_VALUE_TYPE_INVALID。2.5 集成测试集成用例覆盖 Server Tool、Tool Property、多属性单工具、MCP Transport Manager Server 组合以及完整的端到端工作流——创建 server → 添加带属性的工具 → 注册端点 → 处理请求 → 清理。从源码可见完整协议交互test_mcp_full_workflow_with_server依次发送initialize、notifications/initialized、tools/listtest_mcp_tools_call_integration则发送tools/call{name:test_tool,arguments:{enabled:true}}验证工具回调链路覆盖了 MCP 协议消息的 initialize / tools/list / tools/call 三件套。三、MCP 协议合规性测试2025 重点这是本测试应用中技术含量最高的部分共 38 个用例聚焦 MCP 2025 协议栈每一类都有精确的断言逻辑使用 cJSON 逐字段校验响应结构3.1 initialize 方法4 类协议版本协商请求protocolVersion: 2024-11-05时响应须回显2024-11-05请求未知版本如2026-01-01返回-32602 Invalid Params且错误data.field精确指向params.protocolVersion必填字段校验缺失protocolVersion、clientInfo、capabilities、clientInfo.name、clientInfo.version均返回-32602且data.field分别定位到对应字段路径见 test_mcp_c_sdk.c重复 initialize同一会话重复发送返回-32600 Invalid Request错误信息包含 only be sent once会话作用域initialize是会话级操作test_initialize_is_session_scoped验证 sess-a/sess-b 互不干扰清除会话状态后可重新初始化test_clear_session_state_resets_initialize_lifecyclecapabilities 结构响应包含tools.listChanged、tasks.list/cancel/requests.tools.call注册 completion provider 后额外出现completionsserverInfo包含 name 与 version 字段。3.2 JSON-RPC 2.0 规范4 类所有请求/响应携带jsonrpc: 2.0请求/响应id必须匹配result与error字段互斥客户端 capabilities 解析含 vision 子能力。3.3 tools/list 完整测试4 类游标cursor参数分页支持工具较多时返回nextCursor非法游标返回空列表多工具分页验证。3.4 tools/call 深度测试9 类覆盖参数类型校验、范围检查min/max 约束、越界参数、float、string、stackSize 参数、不存在工具、缺失必填参数、非法 stackSize 等 9 个维度。stackSize 对应 Kconfig 中的MCP_TOOLCALL_STACK_SIZE范围 4096–16384默认 8192是控制工具调用任务栈大小的关键配置。3.5 错误码与响应解析错误处理 6 类完整覆盖 JSON-RPC 标准错误码错误码含义触发场景-32700Parse Error非法 JSON-32600Invalid Request错误 jsonrpc 版本-32601Method not found未注册的方法-32602Invalid params参数校验失败-32001 ~ -32003自定义错误应用级错误—错误响应格式code/message 字段存在响应解析 4 类成功响应result 字段、错误响应error 字段、应用级错误isError 字段、非法 JSON 处理。ping 方法 1 类验证 ping 响应格式MCP 2025 中返回{}。3.6 MCP 2025 新特性测试6 类resources/list与resources/read测试回调返回 MIME 类型与文本内容如device://status返回application/jsonprompts/list与prompts/get渲染回调生成 messages JSONcompletion/completeprovider 返回补全候选值tasks 工作流tools/call配合 task 模式、tasks/get、tasks/result断言_meta.io.modelcontextprotocol/related-task.taskId、RFC3339 格式时间戳、ttl 字段tasks/cancel未知任务错误路径logging/setLevel。四、线程安全与内存泄漏测试线程安全test_server_thread_safety创建 4 个 FreeRTOS 任务THREAD_TEST_THREADS 4每个任务循环 100 次THREAD_TEST_ITERATIONS 100并发执行工具添加/移除用互斥量保护计数器最终断言总迭代数为 400。源码中thread_test_task还对并发添加同名工具的场景做了容错返回ESP_ERR_INVALID_STATE时销毁对象而非断言失败体现了 SDK 链表操作 mutex 保护的线程安全设计详见 README_CN.md 线程安全章节。内存泄漏test_memory_leak_server/tool/property/value/full_workflow五个用例分别循环执行对象的创建-销毁配合 Unity 的内存泄漏检测TEST_MEMORY_LEAK_THRESHOLD验证资源正确回收full_workflow 覆盖创建 server → 建工具 → 加属性 → 注册 → 移除 → 销毁的完整生命周期。五、测试结构Unity 分组标签体系测试按 API 类别组织为 Unity 分组标签这是运行筛选的核心机制标签含义[mcp]MCP Transport Manager API 测试[server]Server API 测试[tool]Tool API 测试[property]Property API 测试[value]Value API 测试[integration]多 API 组合集成测试[thread_safety]线程安全测试[memory]内存泄漏测试[protocol]MCP 协议合规测试JSON-RPC MCP 方法[initialize]initialize 方法测试[jsonrpc]JSON-RPC 2.0 规范测试[tools][list]tools/list 方法测试[tools][call]tools/call 方法测试[error]错误处理测试[response]响应解析测试[ping]ping 方法测试[2025]MCP 2025 特性测试单个用例可挂多个标签如[mcp][protocol][initialize][session]标签支持 AND 语义[tools][list]与分组嵌套。六、构建与运行6.1 构建cd components/mcp-c-sdk/test_apps idf.py build6.2 运行全部测试idf.py -p PORT flash monitor6.3 按分组筛选运行# 仅运行 server 测试 idf.py -p PORT flash monitor --filter server # 仅运行 tool 测试 idf.py -p PORT flash monitor --filter tool # 线程安全测试 idf.py -p PORT flash monitor --filter thread_safety # 内存泄漏测试 idf.py -p PORT flash monitor --filter memory # MCP 协议合规测试 idf.py -p PORT flash monitor --filter protocol # initialize 方法测试 idf.py -p PORT flash monitor --filter initialize # tools/list 测试 idf.py -p PORT flash monitor --filter tools/list # tools/call 测试 idf.py -p PORT flash monitor --filter tools/call # 错误处理测试 idf.py -p PORT flash monitor --filter error # 响应解析测试 idf.py -p PORT flash monitor --filter response # MCP 2025 特性测试 idf.py -p PORT flash monitor --filter 2025七、推荐执行顺序从单元矩阵到 HTTP 集成为减少误报、加快问题定位官方推荐的执行顺序分两步7.1 第一步单元矩阵pytest_mcp.py验证 SDK 核心 API、协议处理以及各sdkconfig.ci.*矩阵配置。从仓库根目录执行python -m pytest components/mcp-c-sdk/test_apps/pytest_mcp.py \ --target esp32c3 \ --port /dev/ttyUSB0pytest_mcp.py 通过 pytest-embedded 与 DUT 交互等待 Unity 菜单输出、解析测试菜单、支持UNITY_TEST_FILTER环境变量做用例级筛选。其config参数化覆盖了 16 种构建配置见下节矩阵目标芯片支持 esp32c3 / esp32s3。7.2 第二步HTTP 集成矩阵pytest_mcp_http_integration.py验证 HTTP transport 行为及 auth/session/JWT 相关 profile。该脚本复用 examples/mcp/mcp_server/test_kconfig_matrix.sh 的端到端矩阵需要先导出环境变量export MCP_HTTP_HOSTDUT_IP export MCP_HTTP_ENDPOINTmcp_server export MCP_AUTH_TOKENGOOD_TOKEN # 仅 scope profile 需要 # export MCP_AUTH_LOW_SCOPE_TOKENLOW_SCOPE_TOKEN运行命令python -m pytest components/mcp-c-sdk/test_apps/pytest_mcp_http_integration.py -v其 profile 与矩阵用例的对应关系见 pytest_mcp_http_integration.pyprofile矩阵用例defaultbaseline_hs1_sse1_auth0_meta1_hc1sse_offhs1_sse0_auth0_meta1_hc1_get405auth_onhs1_sse1_auth1_jwt0_scope0_meta1_hc1auth_scope_onhs1_sse1_auth1_jwt0_scope1_meta1_hc1auth_jwt_claimshs1_sse1_auth1_jwt1_sig0_kid1_meta1_hc1auth_jwt_sighs1_sse1_auth1_jwt1_sig1_jwks_valid_meta1_hc1oauth_meta_offhs1_sse1_auth1_meta0_hc1session_ttl_shorths1_sse1_auth1_ttl_short_meta1_hc1提示矩阵用例名中的缩写含义可从 Kconfig 推导——hsHTTP server、sseSSE 开关、authBearer 鉴权、jwtJWT 校验、scopescope 检查、metaOAuth 元数据、hcHTTP client、ttl会话 TTL。未设置MCP_HTTP_HOST时脚本自动 skip。运行技巧固件与目标二进制一致时可追加--skip-autoflash y跳过烧录仅跑部分 Unity 用例时在执行pytest_mcp.py前设置UNITY_TEST_FILTER分组示例UNITY_TEST_FILTER[gate]用例名示例UNITY_TEST_FILTERtest_a|test_b|为 OR 语义[a][b]为 AND 语义八、一键自动化脚本run_test_apps.shrun_test_apps.sh 将构建 pytest 日志收集合为一条命令./components/mcp-c-sdk/test_apps/run_test_apps.sh --port /dev/ttyUSB0常用选项选项说明--target esp32c3\|esp32s3芯片目标默认 esp32c3--skip-build跳过 build_apps.py 构建阶段--skip-autoflash传递--skip-autoflash y给 pytest--skip-port-probe跳过串口写探针预检--unity-filter [protocol]设置UNITY_TEST_FILTER--pytest-k default or api_testpytest-k表达式筛选参数/用例--log-dir DIR日志/JUnit 输出目录默认.cache/mcp-test-logs脚本内部流程校验--port与IDF_PATHsourceexport.sh→ 串口预检探针Unity 菜单交互需要双向串口读写能力→ 调用tools/build_apps.py构建依赖 Python 模块idf_build_apps缺失时报错并提示pip install idf-build-apps→ 组装 pytest 命令并以tee同时输出控制台与日志文件生成带时间戳的.log与 JUnit.xml报告。若已备好二进制加--skip-build即可跳过构建阶段。九、构建配置矩阵sdkconfig.ci.*解读test_apps目录下的 15 个sdkconfig.ci.*文件对应 pytest 的参数化配置从命名即可看出验证重点均可对照 Kconfig 中的开关项default/api_test基线配置与 API 测试专用配置toolcall_min/toolcall_maxMCP_TOOLCALL_STACK_SIZE上下限4096 / 16384toollist_min/toollist_maxMCP_TOOLLIST_MAX_SIZE上下限1024 / 16384no_http_server/no_http_clientMCP_TRANSPORT_HTTP_SERVER/MCP_TRANSPORT_HTTP_CLIENT关闭路径sse_offMCP_HTTP_SSE_ENABLE关闭GET 返回 405auth_on/auth_scope_onMCP_HTTP_AUTH_ENABLE scope 检查矩阵auth_jwt_claims/auth_jwt_sigJWT claims 校验与签名验证JWKSoauth_meta_offOAuth 元数据端点关闭session_ttl_minMCP_HTTP_SESSION_TTL_MS最小值1000msprotocol_default_2024默认协议版本回退到2024-11-05legacy 传输。这些矩阵与 HTTP 集成测试中的 profile 一一呼应覆盖了 SDK 绝大多数 Kconfig 开关组合。十、结语与验证要点回顾这份测试应用其设计思路对嵌入式组件测试具有直接参考价值三层解耦通过 mock transportmock_transport/mock_transport_with_request两组函数表见 test_mcp_c_sdk.c把协议引擎与真实 HTTP 网络解耦使 91 个用例中的绝大多数可以在无网络环境下稳定复现协议优先38 个协议合规用例覆盖 MCP 2024/2025 两代版本、JSON-RPC 2.0 全错误码、分页游标与任务工作流是 SDK 兼容性的契约测试可靠性保障线程安全4 任务 × 100 次并发与内存泄漏5 个生命周期用例共同保证 SDK 在真实多任务环境下的健壮性可自动化pytest_mcp.pypytest_mcp_http_integration.pyrun_test_apps.sh构成从构建、烧录、执行到日志归档的完整 CI 链路。运行时的三条实用建议优先按单元矩阵 → HTTP 集成矩阵的顺序执行利用UNITY_TEST_FILTER与--filter精确定位失败分组固件不变时使用--skip-autoflash加速迭代。【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考