Kongnitive Edge MCP

Kongnite EdgeMCP

语言： 英语 | 中文（简体）

认识Kongnive EdgeMCP

Kongnitive =孔+认知。

在ESP32上运行的MCP基础层，将硬件功能暴露给AI。AI直接通过MCP工具读取日志、推送脚本、交换驱动程序和迭代设备逻辑。基础层保持稳定，人工智能带来智能。

Kongnitive EdgeMCP 是一个带有嵌入式Lua 5.4运行时的ESP32 MCP服务器。

• AI代理可以在运行时通过向SPIFFS编写Lua脚本来更新逻辑。
• 仅逻辑更改不需要固件重建、刷新或OTA。
• 固件仍然是稳定的运行时平台（MCP、传输、VM、驱动程序）。

简单地说：AI自我迭代

graph LR
    A[get_system_prompt] --> B[lua_get_script]
    B --> C[lua_push_script]
    C --> D[lua_restart]
    D --> E[sys_get_logs]
    E -->|"verify & repeat"| C

固件可以理解为稳定的基础，而Lua脚本形成了可热更新的业务层。AI通过MCP工具在连续的闭环中迭代，而无需重复刷新。

运作原理

运行期模型

graph TD
    Agent["AI Agent (Claude, Codex, OpenClaw ...)"]
    subgraph ESP32["Kongnitive EdgeMCP (ESP32)"]
        MCP[MCP Server]
        LuaVM[Lua VM]
        SPIFFS[SPIFFS Scripts]
        MCP --> LuaVM --> SPIFFS
    end
    Agent -- "MCP tools/call" --> MCP
    MCP -- "MCP response" --> Agent

推荐AI循环

1. get_system_prompt -加载项目级操作提示
2. lua_list_scripts / lua_get_script -检查当前脚本状态
3. lua_push_script 或 lua_bind_dependency -应用逻辑/配置更新
4. lua_restart -如果需要，重新启动Lua VM
5. sys_get_logs -验证运行时日志的结果

DI注射

• di_container.lua 提供提供商注册(provide)和接口绑定(bind/resolve).
• bindings.lua 存储接口到提供者映射以及提供者选项。
• 提供者模块（例如 provider_ssd1306.lua, provider_mock_display.lua)揭露工厂。
• main.lua 解析接口（例如 display)在运行时从容器中删除。

DI热开关

• 使用 lua_bind_dependency 重写 /spiffs/bindings.lua 远程。
• 默认行为是 restart=true，因此新绑定立即生效。
• 为了更安全地推出，请致电 restart=false，然后验证并运行 lua_restart 手动。
• 通过以下方式确认活动提供商 sys_get_logs （例如 display provider=ssd1306).

内置MCP工具（14）

• 系统： control_led, get_status, get_system_prompt, sys_get_logs, sys_ota_push, sys_ota_status, sys_ota_rollback, sys_reboot
• 卢： lua_push_script, lua_get_script, lua_list_scripts, lua_exec, lua_bind_dependency, lua_restart

快速开始

1） 先决条件

• ESP-IDF v5.0+
• ESP32开发板
• 手机数据线系列
• 已验证硬件：Seeed Studio XIAO ESP32S3
• 已验证的I2C引脚（OLED/MPU6050）：SDA=GPIO5，SCL=GPIO6

2） 配置Wi-Fi

编辑 sdkconfig.defaults:

CONFIG_MCP_WIFI_SSID="YOUR_WIFI_SSID"
CONFIG_MCP_WIFI_PASSWORD="YOUR_WIFI_PASSWORD"

3） 构建和闪存

. $HOME/esp/esp-idf/export.sh
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor

4） 首次MCP呼叫

{"method":"tools/call","params":{"name":"get_status","arguments":{}}}
{"method":"tools/call","params":{"name":"lua_list_scripts","arguments":{}}}
{"method":"tools/call","params":{"name":"sys_get_logs","arguments":{"lines":20}}}

5） DI热开关示例（OLED）

{"method":"tools/call","params":{"name":"lua_bind_dependency","arguments":{"provider":"ssd1306","interface":"display","opts":{"addr":60,"sda":5,"scl":6,"freq":400000},"restart":true}}}

常见问题解答

这个项目解决了什么问题？

该项目提供了一个稳定的ESP32 MCP平台，使AI和开发人员能够快速迭代设备行为，而无需重复刷新。

• 通过MCP工具展示硬件功能。
• 在将快速变化的逻辑转移到Lua脚本的同时保持固件稳定。
• 支持远程脚本更新、重启和基于日志的验证。

为什么这个项目使用Lua？Lua是强制性的吗？

Lua不是严格强制性的，但它是快速迭代的默认设计选择：

• 固件保持稳定的平台责任（MCP、传输、驱动程序、OTA、安全）。
• Lua脚本包含热的可更新行为逻辑。
• 许多行为变化可以通过MCP应用(lua_push_script + lua_restart)无需重新刷新固件。

您可以直接在C固件中实现逻辑，但迭代速度和远程调试便利性通常较低。

Lua运行时使用多少内存？我如何验证它？

这取决于正在运行的脚本。在默认示例中，它通常在数十KB的范围内（例如大约50 KB），但当脚本分配大型表/缓冲区或保持全局引用活动时，它可能会增长。

如何验证：

• 使用 get_status 检查 Lua Heap Used 和 Lua Heap Peak.
• 使用 sys_get_logs 检查运行时行为和内存相关日志。
• 使用 lua_list_scripts 和 lua_get_script 检查设备上当前运行的内容。
• 检查中的默认脚本示例 main/default_scripts/ （例如 main/default_scripts/default_main.lua).

开发商

代码布局

• main/ -MCP服务器、协议、工具、运行时、OTA、Wi-Fi
• components/lua/ -Lua 5.4组件
• doc/CONTRIBUTION.md -贡献规则和PR检查表
• MCP_AGENT_CONFIG.md -项目级代理行为与MCP工作流
• doc/TODO.md -开放式技术TODO

配置

• main/Kconfig.projbuild 定义可配置密钥(MCP_WIFI_*、消息大小、OTA URL等）
• sdkconfig.defaults 是共享基线配置
• sdkconfig 故意在当地（被忽视）

开发者期望

• 用英语保存代码/文档
• 更喜欢运行时Lua+MCP更新以进行行为更改
• 工具/工作流更改时更新文档
• 在设备上验证 sys_get_logs

许可证

Apache许可证2.0。看 LICENSE 了解详情。