MCP 服务器概述

每一台 Lager Box 都运行一个 MCP（Model Context Protocol）服务器。它让 AI 智能体理解实验台、理解被测设备（DUT），并规划硬件在环测试。它运行在 Box 上，通过 Box 的本地 IP 访问。默认情况下，MCP 服务器是只读的：它描述实验台和被测设备，但不驱动硬件、也不运行代码。有两个需要显式开启的环境变量可以改变这一点，请参阅可选的工具开关。智能体通过另一条通道执行测试 —— 也就是 lager CLI。

MCP-compatible AI agent
    |  MCP (streamable-http via box IP)     ← discovery + planning (read-only)
    v
Lager MCP Server (on-box, port 8100)
    |  reads /etc/lager bench config (nets, DUT context, instruments)
    v
Bench / DUT metadata

AI agent  ──  lager python path/to/test.py --box <box-ip>  ──▶  Hardware
              (execution happens over the CLI, not MCP)

接入智能体

把任意兼容 MCP 的客户端指向该 Box：

{
  "mcpServers": {
    "lager": {
      "url": "http://<box-ip>:8100/mcp"
    }
  }
}

开箱即用时，MCP 服务器只用于发现和规划 —— 它不运行代码，也不驱动硬件。有两个需要显式开启的环境变量可以扩展它，请参阅可选的工具开关。若要执行测试，智能体先在本地写一个 Python 文件，然后用 lager python path/to/test.py --box <box-ip> 运行它，该命令会把项目同步到 Box 并带着完整的项目上下文运行。请把 Box 的 IP 地址传给 --box —— 就是您连接 MCP 服务器时用的那个 IP。本地的 Box 名称只是客户端侧的别名，因此 IP 是双方都能依赖的唯一标识。为了让这一点更具体，discover_bench() 会把您实际连接所用的地址作为 box_address 回显出来，并给出一条可以直接运行的 lager python … --box <that-address> 命令。

上面的 URL 假设该 Box 会发布它的端口，这是默认行为。用 start_box.sh --no-publish （或 LAGER_NO_PUBLISH=1）启动的 Box 不会在宿主机上发布端口 8100。 MCP 服务器仍然运行，并在容器内绑定 0.0.0.0:8100，但只能在内部的 lagernet Docker 网络上访问 —— 宿主机端口由反向代理拥有。在这样的 Box 上，请把客户端指向容器的 lagernet 地址，因为 <box-ip>:8100 连不上。请不要把端口 8100 经由该代理对外暴露，因为 MCP 服务器不做任何认证。该模式通过 /etc/lager/no_publish 在重启之间保留，start_box.sh --publish 会清除它。每次运行结束时，start_box.sh 都会报告该 Box 处于哪种模式。

智能体能看到什么

服务器对外提供两类东西：资源（智能体读取的只读上下文）和工具（可调用的函数）。

资源

资源	它给智能体提供什么
`lager://dut/overview.md`	请先读这个。一份叙述性简介：这台 Box 测试什么、被测设备的 MCU/外设、子系统，以及应该获取哪些文档。
`lager://dut/context`	以结构化 JSON 表示的完整 DUT 上下文。
`lager://bench/identity`	Box ID、主机名、版本，以及每个 DUT 的摘要（用途、MCU）。
`lager://bench/netlist`	每个 Net 及其类型、角色、仪器和元数据。
`lager://bench/interfaces`	协议接口（SPI、I2C、UART）及其对应的 Net。
`lager://guide/overview`	Lager 是什么，以及”Net”是什么。
`lager://guide/workflow`	推荐的”定位 → 发现 → 规划 → 编写 → 运行”循环。
`lager://guide/rtt-defmt`	固件日志的核心工作流程：串流 RTT 并解码 `defmt`。涵盖 `dbg.session()` 作用域、能感知重连的 RTT 读取器，以及会自愈的 `reset()`/`read_memory()`（这样您就不必自己写烧录/复位的变通代码），还有 DA1469x 烧录后重连这一例外。
`lager://reference/{net_type}`	某一种 Net 类型的完整 API 参考，以 JSON 表示（例如 `lager://reference/Debug`）—— 方法、注意事项，以及一段可直接运行的示例代码。
`lager://guide/api-quick-reference`	按 Net 类型整理的 `lager.Net` API 速查表。
`lager://guide/docs`	指向完整在线文档（`docs.lagerdata.com`）以及 `llms.txt` 页面索引的链接，供查阅 Box 上未涵盖的内容。

工具

工具	用途
`discover_dut()`	一次调用完成定位：被测设备的用途、MCU、外设、子系统和文档引用。
`discover_bench(net_name?)`	枚举硬件 —— 各个 Net，以及各台仪器及其通道、能力和已录入的规格/量程。带 Net 名称调用时，返回该 Net 的完整元数据、能力、所属子系统和相关文档引用（如果该 Net 不存在，则返回可用 Net 名称的列表）。
`cite_schematic(net_name)`	只返回与某个 Net 相关的原理图/数据手册引用和页码提示。
`plan_firmware_test(firmware_description, test_goals)`	生成分阶段的测试计划，限定到相关的 Net，并附上 DUT 上下文和文档引用。
`assess_suitability(test_type)`	检查这个实验台能否运行某一类测试。
`get_test_example(query)`	按 Net 类型、模式或关键字查找可运行的示例脚本。
`box_manage(action)`	`health` 健康检查，或从磁盘 `reload` 实验台配置。

默认情况下，工具接口是只读的。 上面这七个工具不驱动硬件（设置电压、翻转 GPIO、烧录固件），也不改动 Box。这些都发生在智能体编写、并用 lager python 运行的测试脚本里，或者发生在专门的 CLI 命令中。只有当下面两个开关都关闭时，这个默认状态才成立。

可选的工具开关

有两个环境变量，两者默认都关闭，除非显式设置。设置之后， Box 的 MCP 服务器在启动时会注册额外的工具。每一个都会扩大已接入智能体对该 Box 的操作范围，因此请把它们当作部署决策，而不是便利设置。

`LAGER_MCP_ALLOW_CONTROL`

增加三个受限工具。它们读取实验台状态，并可以对集线器端口断电再上电 —— 但不执行任意代码。

工具	用途
`net_status(net)`	某个实验台 Net 的简要只读状态。
`debug_probe_status(net)`	某个调试 Net 的探针是否出现在 USB 总线上。
`power_cycle_hub(hub)`	对一个 USB 集线器端口（Acroname、YKUSH 或 Plugable）断电再上电，使用与 `lager usb` 相同的 `cycle`，端口断电保持 1 秒。结果中带有 `reconnected`：`true`、`false` 或 `null`。只有当 Box 读不到自己的 USB 拓扑时，该工具才会再多等 4 秒。会驱动硬件。

`LAGER_MCP_ALLOW_EXEC`

这个开关会把 Box 上的任意命令执行和文件写入能力，暴露给任何能访问 MCP 端口的智能体。智能体可以运行 Box 服务用户能运行的任何命令，并覆盖它能写入的任何文件。设置它之后，服务器自己会在启动时打印一条警告。请只在您自己掌控的实验台、受信任的网络上启用它，绝不要在共用或生产环境的 Box 上启用。

工具	用途
`box_exec(command, timeout_s, cwd)`	在 Box 上运行任意 shell 命令并捕获结果。
`read_file(path, max_bytes)`	读取 Box 上的文件（配置、源码、日志）。
`write_file(path, content)`	原子地写入文件，并备份此前的版本。
`list_dir(path)`	列出 Box 上某个目录中的条目。

提示（Prompts）

服务器还注册了若干提示。它们是斜杠命令风格的入口，引导客户端（例如 Cursor）走完”发现 → 规划 → 编写 → 运行”的流程。它们本身不做任何工作，每一个都返回一段指令，由智能体用上面的工具去执行。

提示	作用
`write_lager_test(what_to_test)`	引导智能体完成发现实验台/被测设备、规划、编写测试，并通过 CLI 运行它。
`explore_bench()`	帮助定位这台 Box 是什么、它测试什么、它能运行什么。
`assess_test_feasibility(test_description)`	检查实验台是否具备某个所描述测试所需的能力。

上下文来自哪里

上面这一切的质量，都取决于您在搭建实验台时一次性录入的元数据：

每个 Net 的 purpose —— 在 Net 管理器 TUI（lager nets tui）中设置，或用 lager nets describe NAME --purpose "..." 设置。用一句话描述每根线在被测设备上做什么。
DUT 上下文 —— 用 lager dut 设置：这台 Box 的用途、MCU、子系统，以及原理图和数据手册的引用。

完整指南请参阅编写 DUT 上下文。

​接入智能体

​智能体能看到什么

​资源

​工具

​可选的工具开关

​LAGER_MCP_ALLOW_CONTROL

​LAGER_MCP_ALLOW_EXEC

​提示（Prompts）

​推荐的智能体工作流程

​上下文来自哪里

接入智能体

智能体能看到什么

资源

工具

可选的工具开关

`LAGER_MCP_ALLOW_CONTROL`

`LAGER_MCP_ALLOW_EXEC`

提示（Prompts）

推荐的智能体工作流程

上下文来自哪里