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 处于哪种模式。若只想让端口 8100 不在宿主机上发布，请用 lager box-config env set 设置 LAGER_MCP_NO_PUBLISH=1 并应用。其他端口照常发布。请参阅 lager box-config。

要求令牌

默认情况下，MCP 服务器不要求任何凭据。凡是能访问端口 8100 的一方，都能读取实验台上下文。您可以让服务器要求一个 Bearer 令牌：

lager box-config mcp-token enable --box <BOX>

该命令只显示一次令牌，同时打印一段带有该令牌的客户端配置：

{
  "mcpServers": {
    "lager": {
      "url": "http://<box-ip>:8100/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

令牌立即生效，容器不会重启。不带令牌的请求会得到 401 Unauthorized。关于 status、rotate 和 disable，请参阅 lager box-config。启用之后，每个客户端都必须发送该令牌，其中也包括直接连接该 Box 的控制平面 MCP 客户端。启用令牌之前，请确认每个客户端都能发送这个请求头。如果某个客户端无法发送自定义请求头，请保持令牌关闭，并让端口 8100 远离不受信任的网络。

令牌不会加密连接。端口 8100 是普通 HTTP，因此令牌以明文在网络上传输。请把 Box 放在您信任的网络上。令牌只属于这台 Box。它不是网关凭据，做认证的网关也不得转发端口 8100。

智能体能看到什么

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

资源

资源	它给智能体提供什么
`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 及其 `purpose`、`tags`、`dut_connection` 和 `test_hints`，以及 Box 上检测到的各台仪器及其通道和能力。带 Net 名称调用时，返回该 Net 的完整元数据、能力、所属子系统、相关文档引用，以及 `metadata_sources`（每个字段由哪个文件写入）。如果该 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 类型、模式或关键字查找示例。每个匹配项都带有其 Net 类型的精选代码片段，以及指向 lager 仓库中完整脚本的链接；这些脚本并不在 Box 上。
`box_manage(action)`	`health` 健康检查，或从磁盘 `reload` 实验台配置。

每个工具的回复都带有 box_id，下面受开关控制的工具也不例外，因此通过一个会话与多台 Box 对话的客户端可以区分它们。

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

可选的工具开关

有两个环境变量，两者默认都关闭，除非显式设置。设置之后， Box 的 MCP 服务器在启动时会注册额外的工具。每一个都会扩大已接入智能体对该 Box 的操作范围，因此请把它们当作部署决策，而不是便利设置。请在设置任何一个变量之前先启用令牌。如果开关已打开而没有令牌，服务器会在启动时记录一条警告。在这种状态下，凡是能访问端口 8100 的一方都能使用新增的工具。

`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)`	检查实验台是否具备某个所描述测试所需的能力。

实验台清单

上面的工具一次只回答一个问题。保存着多台 Box 副本的客户端（控制平面、面向整个机群的 MCP 主机，或者您自己）可以改为用一个请求获取完整的描述：

curl http://<box-ip>:9000/bench

回复是实验台清单，一个 JSON 文档。它包含：

schema_version 和 box_id；
实验台本身：各个 Net 及其元数据、Box 上检测到的仪器、DUT 槽位、接口、以 capability_bindings 表示的能力图，以及 metadata_sources；
reference_keys，即每个 Net 对应的 lager://reference/{net_type} 条目。

它由 MCP 工具所读取的同一份已加载状态构建，因此两者永远不会不一致。 ETag 头就是清单的 content_hash。把它作为 If-None-Match 发回去。只要清单没有变化，Box 就返回不带正文的 304，因此每分钟轮询一次的客户端不会给 Box 带来任何开销。/status 通过 capabilities.benchManifest 声明这个路由；早于该路由的 Box（lager 0.50.0 之前）不会带这个标志。在 CLI 中，lager bench export 获取的是同一份文档。

上下文来自哪里

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

每个 Net 的 purpose —— 在 Net 管理器 TUI（lager nets tui）中设置，或用 lager nets describe NAME --purpose "..." 设置。用一句话描述每根线在被测设备上做什么。
每个 Net 的 dut_connection 和 test_hints —— 用 lager nets describe NAME --dut-connection "J3 pin 4" --test-hint "hold nRST low while flashing" 设置。前者说明该 Net 落在被测设备的哪个位置，后者是给编写测试的人的一行提示。为每个 Net 保存这两个字段的控制平面会把它们同步到 Box。
DUT 上下文 —— 用 lager dut 设置：这台 Box 的用途、MCU、子系统，以及原理图和数据手册的引用。

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

​接入智能体

​要求令牌

​智能体能看到什么

​资源

​工具

​可选的工具开关

​LAGER_MCP_ALLOW_CONTROL

​LAGER_MCP_ALLOW_EXEC

​提示（Prompts）

​推荐的智能体工作流程

​实验台清单

​上下文来自哪里

接入智能体

要求令牌

智能体能看到什么

资源

工具

可选的工具开关

`LAGER_MCP_ALLOW_CONTROL`

`LAGER_MCP_ALLOW_EXEC`

提示（Prompts）

推荐的智能体工作流程

实验台清单

上下文来自哪里