IAMF Sentinel

iamf-sentinel-mcp

一个 MCP 服务，向 MCP 客户端——Claude Desktop、 Claude Code 以及任何支持该协议的 Agent 运行时——提供 iamf-sentinel（IAMF 一致性验证器）和 iamf-loom（IAMF 打包器）。

IAMF 是开放媒体联盟的沉浸式音频模型与格式（v1.1.0）。此服务背后的验证器也能读取 IAMF v2.0.0 流， 识别其六种配置文件并检查相关限制，还能读取基于对象的元素及 v2.0.0 渲染设置并进行检查；时间变化的位置 和参数块仍未经验证。此服务让 Agent 能根据规范的一致性规则验证 IAMF 文件，并将打包清单编译为可检查、确定性的计划——且不会执行任何操作（执行是每次启动时单独选择加入的选项，详见下文）。

各处代码注释均引用内部编号设计文档集（doc NN）、ADR 和预先注册的预期标签——DESIGN-NOTES.md 解释了这些标记的含义，并为所有引用的文档编制索引。

工具

工具	功能	需要工具链
iamf_validate	对 .iamf / IAMF-in-MP4 文件生成完整的一致性报告：包含带严重级别的 S 代码问题、摘要和流信息。strict 会将 WARN 提升为失败。	否
iamf_inspect	结构概览：配置文件、编解码器配置（包括 Opus 预跳过）、元素/演示/帧计数、OBU 剪裁总量、MP4 edts/elst 是否存在。	否
loom_compile	将 Loom 清单（YAML/JSON）编译为打包计划——仅验证。按目标进行后端/复用器路由并提供理由，或生成 M 代码诊断。	否
loom_explain	以文本形式运行 loom explain：将已编译的计划作为其自身的说明。	否
loom_run	编译并执行清单：编码、复用、测量，并通过 Sentinel 验证器对每个输出进行门控。返回各目标的输出（sha256）、门控判定、测得的响度和运行记录路径。只有在启动服务时使用 --enable-run 才会注册。	是

资源

• checks://catalog — 验证器可能生成的所有 S 代码检查项：严重级别、 层、标题、描述和相关 F 注册表条目。
• mcodes://catalog — 打包器可能报告的所有 M 代码编译诊断及其稳定摘要（已弃用代码也会保留记录）。
• fregister://catalog — 失效模式注册表（F_TO_CHECK.md）：将 WP1/WP3 失效目录映射到 Sentinel 检查项，并以 Markdown 格式提供。

已验证的平台。 每次推送都会在 Linux、macOS 和 Windows 上，使用 Python 3.11 和 3.12 运行此服务的测试套件——ci.yml 是 声明，矩阵是证据。这也有两个边界。首先，此软件包只是一个 薄封装：此处矩阵通过只说明服务在这些平台上的行为正常，而非一致性逻辑正常——后者由 iamf-sentinel 和 iamf-loom 各自的矩阵验证。 其次，CI 中未安装任何编码器工具链，因此 loom_run 的执行路径 仅通过其失败行为进行测试——缺少二进制文件时会提供可执行的错误信息，而非回溯信息。其子进程部分按设计未在此处验证；相关声明由 iamf-loom 负责。矩阵还包含一个没有同级源码检出的 wheel-only 测试项，这正是实际运行 pip install iamf-sentinel-mcp 时会得到的环境。在该环境中，样本门控测试按设计跳过。这里不对未通过测试的任何平台作出声明。

运行

pip install iamf-sentinel-mcp
iamf-sentinel-mcp                # stdio transport, read-only (default)
iamf-sentinel-mcp --enable-run   # additionally registers loom_run (executes)

Claude Desktop / Code 配置：

{ "mcpServers": { "iamf-sentinel-mcp": { "command": "iamf-sentinel-mcp" } } }

范围与立场

• 默认只读。 未启用 --enable-run 时，工具只会解析和编译；不会执行任何内容、写入文件或访问网络。
• 执行需在每次启动时主动启用。 --enable-run 会注册 loom_run，它会将编码工具链作为子进程运行并写入文件；loom run 内部的 Sentinel 门禁默认仍处于启用状态。缺少工具链时，会显示可操作的错误，并指出预期的二进制文件路径。Sentinel L3 渲染响度 QC 仍未开放。
• 该服务是对产品公共 API 的轻量封装；一致性逻辑位于产品内部，并受其各自的测试门禁保护。

与 iamf-sentinel / iamf-loom 堆栈中的其他所有内容一样，采用 Apache-2.0 许可证（参见 LICENSE / NOTICE）。支持政策：参见核心代码库的 SUPPORT.md。

相关项目

• Inseglet — 面向创作端的配套项目：用于沉浸式创作（床声道、Ambisonics、ADM）的原生 REAPER MCP 扩展，其 spatial.export_loom_manifest 会写入清单，供此服务的 loom_compile / loom_run 接受。在同一个 Agent 会话中同时运行两个服务，即可完成作者 → 打包 → 验证的流程。