NVSentinel Lab

nvidia-nvsentinel-mcp

用于在实验室集群上测试 NVIDIA NVSentinel（在 Kubernetes 上检测并修复 GPU 故障）的 MCP 服务。它与 NVSentinel 本身一样，使用 Go 编写。Claude Code 等 MCP 客户端可以读取 NVSentinel 的报告、在模拟 GPU 中注入故障，并检查 NVSentinel 是否隔离节点并驱逐其上的工作负载。

此仓库包含服务和示例测试结果，不负责安装 NVSentinel：安装由 omerfsen.aicr 完成，运行环境可以是来自 omerfsen.nvke 的集群或 kind。此项目未来计划贡献给上游：详见 docs/upstream.md。

测试结果

通过此服务和 MCP，在 kind 上运行 NVSentinel v1.30.0 得到的实际输出：docs/test-results。这些结果证明的是 NVSentinel 的流水线能够处理模拟的 DCGM，而非真实 GPU 的健康状况。

标准

此服务遵循以下标准。每项要求、对应状态、证明该要求的测试以及一个已知差距，均列于 docs/mcp-standards.md，其中也包含用于检查更新版本的链接。

标准	版本
Model Context Protocol	2026-07-28，以及更早的 2024-11-05
MCP Registry server.json	2025-12-11，有效且已发布（0.5.1）
AGENTS.md	AGENTS.md，由 CLAUDE.md 导入
Agent Skills	skills/nvsentinel-lab

此服务尚未通过官方一致性测试套件进行测试，该套件仅测试 HTTP 服务。MCP 没有书面文档的标准，因此 docs/tools.md 按惯例根据服务生成。

工具

工具	是否会更改实验室	功能
lab_status	否	节点（隔离状态、NVSentinel 状态、失败的 GPU 检查）、Pod、工作负载
list_scenarios	否	场景、阶段、允许的 XID、日志来源
wait_for_stage	否	轮询直至满足某个阶段条件，例如 cordoned
component_logs	否	NVSentinel 组件日志的末尾若干行
node_events	否	GPU 节点上的近期事件
inject_fault	是	向模拟 GPU 注入 XID 95
clear_fault	是	重启模拟的 hostengine，从而清除故障
reset_lab	是	撤销 DCGM 中断和已注入的故障
run_test_scenario	是	端到端运行一个场景并报告每个步骤

场景	检查内容
xid95	注入 XID 95：检测到故障、隔离节点、驱逐工作负载、成功完成驱逐。清除故障：节点恢复健康、解除隔离、工作负载恢复
dcgm_outage	停止 hostengine：监控器报告 DCGM 连接丢失。恢复 hostengine：故障状态清除

除非设置 NVSENTINEL_MCP_ALLOW_CHANGES=true，否则会禁用会更改任何内容的工具；启用后，这些工具也只能在 kind 集群上运行。详情见：docs/security.md。

每个工具的输入、输出和注释见：docs/tools.md，该文档根据服务对 tools/list 的响应生成；原始数据见 docs/tools.json。如果两者不再与服务匹配，测试就会失败；运行 make docs 可重新生成文档。

安装

该服务需要一个 kubeconfig。对于 kind 实验环境，make lab-token 会生成一个（参见 在 kind 上运行测试）。它通过 stdio 使用 MCP，因此任何 MCP 客户端 都可以启动它。以下所有命令都不会产生更改；只有在客户端应当更改实验环境时，才添加 -e NVSENTINEL_MCP_ALLOW_CHANGES=true。

1. 安装服务。 从最新版本下载适用于你平台的二进制文件：

平台	文件
Linux，x86-64	nvidia-nvsentinel-mcp-linux-amd64
Linux，Arm	nvidia-nvsentinel-mcp-linux-arm64
macOS，Intel	nvidia-nvsentinel-mcp-darwin-amd64
macOS，Apple 芯片	nvidia-nvsentinel-mcp-darwin-arm64
Windows，x86-64	nvidia-nvsentinel-mcp-windows-amd64.exe
Windows，Arm	nvidia-nvsentinel-mcp-windows-arm64.exe

在 Linux 和 macOS 上，将 FILE 设为对应的文件：

FILE=nvidia-nvsentinel-mcp-linux-amd64
BASE=https://github.com/omerfsen/nvidia-nvsentinel-mcp/releases/latest/download
curl -fsSLO "$BASE/$FILE"
curl -fsSL "$BASE/checksums.txt" | grep " $FILE\$" | sha256sum -c -   # macOS: shasum -a 256 -c -
gh attestation verify "$FILE" --repo omerfsen/nvidia-nvsentinel-mcp    # optional: who built it
install -m 755 "$FILE" ~/.local/bin/nvidia-nvsentinel-mcp

在 Windows 上，使用 PowerShell，将 kubeconfig 保存在只有你能读取的位置，因为服务无法在此处检查权限：

$File = "nvidia-nvsentinel-mcp-windows-amd64.exe"
$Base = "https://github.com/omerfsen/nvidia-nvsentinel-mcp/releases/latest/download"
Invoke-WebRequest "$Base/$File" -OutFile "$HOME\bin\nvidia-nvsentinel-mcp.exe"

每个版本还附带 checksums.txt 和 SBOM 文件 nvidia-nvsentinel-mcp.sbom.cdx.json。目前只在 Linux x86-64 上运行过；其他平台已构建，但尚未测试。也可以使用 Go 1.27 安装： go install github.com/omerfsen/nvidia-nvsentinel-mcp@latest。或者使用镜像 docker.io/omerfsen/nvidia-nvsentinel-mcp，它始终不会以 root 身份运行，大小约为 32 MB。

使用 nvidia-nvsentinel-mcp --version 检查。无标志运行时，它会向 stderr 写入一行日志，然后 等待 stdin 上的 MCP 客户端，因此看起来会处于空闲状态：这是正常的，按 Ctrl-C 可停止它。--help 会列出 标志，--debug 会将每次工具调用和集群详细信息记录到 stderr。

2. 添加到客户端。 对于 Claude Code，假设二进制文件已在你的 PATH 中：

claude mcp add nvsentinel-lab -- nvidia-nvsentinel-mcp

或者提供二进制文件的完整路径，例如 ~/.local/bin/nvidia-nvsentinel-mcp。

使用镜像：

claude mcp add nvsentinel-lab -- docker run --rm -i --read-only --cap-drop=ALL \
  --security-opt=no-new-privileges --user "$(id -u):$(id -g)" --memory=128m --cpus=1 \
  --pids-limit=64 --network=kind \
  --volume "$HOME/.kube/nvsentinel-lab-mcp-docker.yaml:/kube/config:ro" \
  docker.io/omerfsen/nvidia-nvsentinel-mcp@sha256:cb6fba848870580f77d347d476a2a7003cd336cd6f4807a72928013538d7aed9

其他客户端可在其 MCP 配置中使用相同的命令。如果二进制文件不在客户端可见的 PATH 中，请使用完整路径：

{ "mcpServers": { "nvsentinel-lab": { "command": "nvidia-nvsentinel-mcp" } } }

3. 可选：添加技能，让 Agent 学会如何使用这些工具。技能只包含 说明，因此仍需完成步骤 1 和 2。以下任一命令均可：

gh skill install omerfsen/nvidia-nvsentinel-mcp nvsentinel-lab
npx skills add omerfsen/nvidia-nvsentinel-mcp --skill nvsentinel-lab

截至 v2.103.2，GitHub CLI 没有 gh mcp add：gh skill 用于安装技能，MCP 服务 则通过客户端添加。该服务已在官方 MCP Registry 中列出，名称为 io.github.omerfsen/nvidia-nvsentinel-mcp。

在 kind 上运行测试

需要 Go、Docker、kubectl、helm、yq、约 10 GiB 可用内存，以及 omerfsen/aicr 的检出副本，并已运行 make dev（在 https://github.com/omerfsen/aicr/pull/8 合并之前，需使用其 dev/osen/nvsentinel-latest 分支）。

make lab-up           # the kind cluster, with its own kubeconfig
make lab-install      # NVSentinel v1.30.0 through omerfsen.aicr (AICR_DIR=<checkout>)
make lab-fixture      # simulated DCGM, a labelled node, a workload, the server's RBAC
make lab-token        # a kubeconfig for the server: its own identity, valid 8 hours
make e2e              # the tests, through the real binary over MCP; writes docs/test-results
make image e2e-image  # the same, with the server in its container
make lab-down

无需集群即可运行的测试：make lint test。

在 Claude Code 中使用

从代码检出目录开始，如果要开发服务本身：运行 make build lab-token，然后在此目录中重新启动 Claude Code，并在 .mcp.json 中批准该服务。此配置允许更改。

设置

变量	默认值	作用
NVSENTINEL_MCP_KUBECONFIG	~/.kube/nvsentinel-lab-mcp.yaml（镜像：/kube/config）	使用的唯一 kubeconfig。必须设为私有（chmod 600）
NVSENTINEL_MCP_ALLOW_CHANGES	关闭	仅当值恰为 true 时，才允许使用更改工具，且仅限实验环境
NVSENTINEL_MCP_LAB_CONTEXT	kind-nvsentinel-lab	更改操作所需的上下文。必须以 kind- 开头

未测试的内容

• 除 Linux x86-64 以外平台的二进制文件：这些文件是交叉编译的，未实际运行。
• 真实 GPU。RTX 4080 SUPER 不在 NVSentinel 的验证列表中，真实 DCGM 健康状况仍待检查。
• AICR 在 NVKE 上的安装（而非 kind）。
• 修复操作。kind 安装流程止于 cordon 和 drain：AICR 的修复 mixin 需要 metadata-collector，而后者需要 NVML。
• syslog 监控器：它读取 kernel-transport 日志条目，而 kind 节点无法安全地产生这些条目，因此在 kind 上未启用。
• 手动验证镜像的 cosign 签名和 SBOM 证明：它们已附加，且仅验证了构建来源（gh attestation verify）。

所有步骤、失败和碰壁记录都在 docs/build-log.md 中。

许可证

Apache-2.0。lab/gpu-spec.yaml 和 lab/fake-dcgm.yaml 来自 NVSentinel，遵循相同的许可证。