MCP 集成

CycBox 提供一个 MCP 服务，将 IoT 调试功能开放给像 Claude 这样的 AI 助手。这允许 AI 助手帮助你配置连接、编写 Lua 脚本、控制引擎并调试协议。

概述

MCP 服务器作为一个实现 Model Context Protocol 的 HTTP 服务运行，使 AI 助手能够：

• 读取和修改连接配置（传输层、编解码器、转换器）
• 编写和验证用于消息处理的 LuaJIT 脚本
• 控制 IoT 引擎（启动、停止、重启）
• 在不中断连接的情况下热重载 Lua 脚本
• 获取调试日志

要求

• Premium 许可证：MCP 服务器功能需要有效的 CycBox 专业版许可证，您可以通过注册用户获取一个月试用
• 网络访问：服务器在可配置的主机/端口上监听（默认：127.0.0.1:8654）

配置 MCP 服务器

1. 打开 MCP 服务器设置

在 CycBox UI 中，导航到 MCP 服务器配置对话框（可从配置页面或者脚本页面中访问）。

2. 配置服务器设置

• Host (主机)：绑定的网络接口（默认：127.0.0.1）

  • 使用 127.0.0.1 仅允许本地访问（出于安全考虑，推荐使用）
  • 使用 0.0.0.0 以允许网络访问（请谨慎使用）

• Port (端口)：TCP 端口号（默认：8654）

  • 确保该端口未被其他应用程序占用
  • 如果更改了此端口，请记住在添加到 Claude Code 时使用新端口

3. 设置 AI 助手权限

控制 AI 助手可以执行的操作：

• 允许 AI 助手控制启停：允许 AI 启动、停止和重启 IoT 引擎

  • 如果你想让 AI 协助管理引擎生命周期，请启用此项
  • 对于只读协助（配置审查、脚本编写），请禁用此项

• 允许 AI 助手重新加载 Lua 脚本：允许 AI 热重载 Lua 脚本

  • 如果你想让 AI 立即测试脚本更改，请启用此项
  • 脚本在重载前会进行验证以防止错误

4. 启动服务器

点击 Start (启动) 按钮运行 MCP 服务器。运行时，你将看到：

• 显示“Running”的服务器状态指示器
• 服务器 URL（例如：http://127.0.0.1:8654）
• 用于关闭服务器的 Stop (停止) 按钮

自动启动行为：如果 MCP 服务器在上次关闭 CycBox 时处于运行状态，则在重新打开应用程序时，它将使用相同的配置自动启动。

注意：AI 助手连接期间，服务器必须保持运行。停止服务器将导致断开连接。

添加到 Claude Code

MCP 服务器运行后，使用以下命令将其添加到 Claude Code：

claude mcp add CycBox --transport http http://localhost:8654

重要提示：如果你更改了默认值，请将 localhost:8654 替换为你配置的主机和端口。

验证连接

添加服务器后，Claude Code 现在可以：

• 使用 claude mcp get CycBox 获取有关 CycBox 的详细信息
• 在你寻求 IoT 调试帮助时自动使用 CycBox 工具

你可以尝试的示例提示词：

• “显示当前的连接配置”
• “帮我写一个 Lua 脚本来解析 Modbus RTU 消息”
• “启动引擎并检查是否有任何错误”
• “将串口配置更新为使用 115200 波特率”

添加到 VSCode (GitHub Copilot)

如果你在 VSCode 中使用 GitHub Copilot，可以通过 VSCode 界面添加 MCP 服务器：

1. 打开命令面板

   • Windows/Linux：按下 Ctrl+Shift+P
   • Mac：按下 Cmd+Shift+P

2. 运行 MCP 命令

   • 输入 MCP: Add Server 并从列表中选择它

3. 选择连接类型

   • 选择 HTTP 作为传输类型

4. 输入服务器 URL

   • 输入你的 MCP 服务器 URL（例如：http://localhost:8654）
   • 使用在 CycBox UI 中配置的主机和端口

5. 输入服务器名称

   • 为服务器提供一个名称（例如：CycBox）

添加后，GitHub Copilot 在 VSCode 中协助你处理 IoT 调试任务时，将能够访问所有 CycBox 工具和资源。

可用工具

MCP 服务器向 AI 代理开放了以下工具：

工具	描述	需要权限
get_config_schema	发现组件组的可用配置字段。先使用 group_names=["app"] 调用，然后使用具体组件名称获取其字段 Schema	无
get_configs	以结构化 JSON 形式检索当前的传输层/编解码器/转换器配置	无
set_configs	更新连接配置（结构化 JSON，由 Schema 验证）。请先使用 get_config_schema 了解可用字段	无
get_lua_script	检索当前的 Lua 脚本源代码（LuaJIT / Lua 5.1）	无
set_lua_script	更新并验证 Lua 脚本（保存前进行语法检查）。必须使用 LuaJIT（Lua 5.1）语法	无
reload_lua_script	在不停止引擎的情况下热重载 Lua 脚本（创建新的 Lua VM）。返回重载状态和日志	允许 AI 助手重载 Lua
start_engine	使用当前配置启动 IoT 引擎，等待 3 秒获取初始日志。返回启动状态、连接 ID 和日志	允许 AI 助手控制引擎
stop_engine	停止正在运行的 IoT 引擎	允许 AI 助手控制引擎
restart_engine	停止并使用当前配置重启引擎，等待 3 秒获取初始日志。返回启动状态、连接 ID 和日志	允许 AI 助手控制引擎
get_logs	检索最近的 Lua 脚本日志和钩子错误（最多 100 条）	无

可用资源

MCP 服务器还提供以下资源供 AI 助手读取参考：

资源 URI	描述
cycbox://api/lua-api	完整的 Lua 脚本 API 参考（钩子、辅助函数、模块）
cycbox://example/{name}	包含嵌入式 JSON 配置块的示例脚本

AI 助手可以列出所有可用资源并读取它们，以便在编写脚本或配置之前了解 Lua API 和查看工作示例。