MCP ersatztv_update_channel omits graphicsElementIds — cannot set the On Now/Next overlay, and silently strips it #754

Closed
opened 2026-08-06 20:41:12 +02:00 by timothy · 2 comments
Owner

ToolCatalog.ChannelFields() (ErsatzTV.Mcp/ToolCatalog.cs:263) declares 27 of the 28 properties on
UpdateChannelRequest. The missing one is graphicsElementIds — the field that attaches
channel-level graphics elements, including the built-in On Now/Next overlay (#74,
graphics.channel-level-attachment).

Two consequences, the second worse than the first:

  1. The overlay cannot be enabled via MCP at all. ToolArgumentValidator enforces
    additionalProperties:false, so passing graphicsElementIds is rejected before a request is built.
  2. Calling the tool on a channel that has the overlay silently removes it. PUT /api/v1/channels/{id}
    is a full replace, and the tool's own description says "Send the full desired state" — but the schema
    cannot express the full state. An agent that faithfully GETs a channel, edits one field and calls
    ersatztv_update_channel drops every attached graphics element. Nothing errors; the overlay just
    stops rendering at the next transition.

This is the same shape as the optional-parameter-on-shared-primitive-is-opt-out class: the omission
is invisible at the call site and only shows up as missing pixels on a stream.

Note ChannelFields() is shared by ersatztv_create_channel and ersatztv_update_channel, and
CreateChannelRequest does not have graphicsElementIds. So the field must be added to the update
tool only, not to the shared helper as-is, or create calls will start sending an unknown property.

Found while enabling the overlay across all prod channels from media-management.

Done-when

  • ersatztv_update_channel accepts graphicsElementIds (int array) and round-trips it
  • ersatztv_create_channel does not send graphicsElementIds (not on CreateChannelRequest)
  • A test asserts the update tool's declared fields match UpdateChannelRequest, so the next added
    property cannot drift silently
  • docs/mcp.md updated if the tool surface description changes
  • Adversarial review passed
`ToolCatalog.ChannelFields()` (`ErsatzTV.Mcp/ToolCatalog.cs:263`) declares 27 of the 28 properties on `UpdateChannelRequest`. The missing one is **`graphicsElementIds`** — the field that attaches channel-level graphics elements, including the built-in On Now/Next overlay (#74, `graphics.channel-level-attachment`). Two consequences, the second worse than the first: 1. **The overlay cannot be enabled via MCP at all.** `ToolArgumentValidator` enforces `additionalProperties:false`, so passing `graphicsElementIds` is rejected before a request is built. 2. **Calling the tool on a channel that has the overlay silently removes it.** `PUT /api/v1/channels/{id}` is a full replace, and the tool's own description says *"Send the full desired state"* — but the schema cannot express the full state. An agent that faithfully GETs a channel, edits one field and calls `ersatztv_update_channel` drops every attached graphics element. Nothing errors; the overlay just stops rendering at the next transition. This is the same shape as the `optional-parameter-on-shared-primitive-is-opt-out` class: the omission is invisible at the call site and only shows up as missing pixels on a stream. Note `ChannelFields()` is shared by `ersatztv_create_channel` and `ersatztv_update_channel`, and `CreateChannelRequest` does **not** have `graphicsElementIds`. So the field must be added to the update tool only, not to the shared helper as-is, or create calls will start sending an unknown property. Found while enabling the overlay across all prod channels from `media-management`. ## Done-when - [x] `ersatztv_update_channel` accepts `graphicsElementIds` (int array) and round-trips it - [x] `ersatztv_create_channel` does **not** send `graphicsElementIds` (not on `CreateChannelRequest`) - [x] A test asserts the update tool's declared fields match `UpdateChannelRequest`, so the next added property cannot drift silently - [x] `docs/mcp.md` updated if the tool surface description changes - [x] Adversarial review passed
timothy added the bugpriority: high labels 2026-08-06 20:41:12 +02:00
timothy added the in-progress label 2026-08-06 21:13:03 +02:00
Author
Owner

Claiming this (Claude Code session, 2026-08-06). Will fix the MCP update-tool field drift plus add the drift-proof test.

Claiming this (Claude Code session, 2026-08-06). Will fix the MCP update-tool field drift plus add the drift-proof test.
timothy removed the in-progress label 2026-08-06 22:43:25 +02:00
Author
Owner

Closing record

Outcome: Shipped in PR #760 (squashed to 9881d1ff8). ersatztv_update_channel now declares graphicsElementIds; ScheduleFlags() now declares padToNearestMinute — a second, live instance of the same defect that this issue did not know about. Both are pinned by a new guard tying every MCP write tool's body to the generated OpenAPI contract, name and type.

Root cause: Nothing tied a tool's declared arguments to the contract it wraps. ChannelFields() was hand-maintained against a 28-property DTO and drifted by one. The harm came from the combination: the endpoint is a full replace and the tool's own description says "send the full desired state", so the schema's inability to express a field turned a faithful GET-edit-PUT into a silent clear — 200, no error, missing pixels at the next transition.

Decisions/conventions changed: Added mcp.tool-schema-openapi-parity (active). No supersessions.

Reusable knowledge:

  • A missing field on a full-replace wrapper is not "one field you cannot set" — it is a silent delete of that field on every call. Severity is set by the write's replace semantics, not by the field's importance.
  • Write tools here are not uniform, and one is not uniform with itself: ersatztv_update_playout leaves scheduleFile unchanged but nulls dailyRebuildTime unconditionally. A blanket "every write is a full replace" claim is false and dangerous in the opposite direction (it would imply add-collection-items replaces membership).
  • Verifying a full-replace endpoint live mutates whatever you omit. Snapshot the whole entity first and build probe bodies from that JSON — a hand-built body overwrites real settings. The bug under test is exactly the mechanism that eats your evidence.
  • An older deployed instance ignores a field that does not exist in its build, which reads identically to the field working. Check the deployed /openapi/v1.json before concluding either way.

Verification: 61/61 MCP tests, 441 script tests, dotnet format exit 0, no BOMs, decisions-validate: OK. CI green (Build & test 9m59s — full run, not the docs-only fast path). Live E2E on ersatztv-test with the bug as its own positive control: [1] → update omitting the field → [] (200, isError=false) → update with the field → [1] restored. Guard verified by mutation, not assumption: dropping either field, retyping either, drifting an array element type, and deleting the copied spec each turn the suite red and name the fault.

Deferred: padToNearestMinute has no live round-trip — the deployed test image predates the field entirely (its /openapi/v1.json lacks it), so the API silently ignored it. Environment limitation, not a defect; the field is real on main, which is what the guard asserts against. Follow-ups filed: #758 (GetPagedPlayouts counts before both the query and Channel != null filters — pre-existing, newly reachable, same family as #690) and #759 (query guard ignores a $ref'd parameter where the body guard fails loudly; dormant today).

Docs updated: docs/mcp.md, docs/decisions/records/mcp/tool-schema-openapi-parity.md (new), docs/decisions/README.md (regenerated).

Review: 3 adversarial rounds, cold + worktree-isolated. Rounds 1 and 2 returned BLOCKED — the schedule twin got its schema fix but not its warning; a docs claim was false for four tools; and the guard compared names only (proved by mutation: retyping the field this PR adds stayed green). Round 2 caught update_playout mis-bucketed as safe. Round 3 MERGEABLE, re-confirmed on the merging sha.

## Closing record **Outcome:** Shipped in PR #760 (squashed to `9881d1ff8`). `ersatztv_update_channel` now declares `graphicsElementIds`; `ScheduleFlags()` now declares `padToNearestMinute` — a **second, live instance of the same defect** that this issue did not know about. Both are pinned by a new guard tying every MCP write tool's body to the generated OpenAPI contract, name **and** type. **Root cause:** Nothing tied a tool's declared arguments to the contract it wraps. `ChannelFields()` was hand-maintained against a 28-property DTO and drifted by one. The harm came from the combination: the endpoint is a **full replace** and the tool's own description says *"send the full desired state"*, so the schema's inability to express a field turned a faithful GET-edit-PUT into a silent clear — `200`, no error, missing pixels at the next transition. **Decisions/conventions changed:** Added `mcp.tool-schema-openapi-parity` (active). No supersessions. **Reusable knowledge:** - A missing field on a **full-replace** wrapper is not "one field you cannot set" — it is a silent **delete** of that field on every call. Severity is set by the write's replace semantics, not by the field's importance. - Write tools here are **not uniform**, and one is not uniform with itself: `ersatztv_update_playout` leaves `scheduleFile` unchanged but nulls `dailyRebuildTime` unconditionally. A blanket "every write is a full replace" claim is false and dangerous in the opposite direction (it would imply add-collection-items *replaces* membership). - **Verifying a full-replace endpoint live mutates whatever you omit.** Snapshot the whole entity first and build probe bodies from that JSON — a hand-built body overwrites real settings. The bug under test is exactly the mechanism that eats your evidence. - **An older deployed instance ignores a field that does not exist in its build**, which reads identically to the field working. Check the deployed `/openapi/v1.json` before concluding either way. **Verification:** 61/61 MCP tests, 441 script tests, `dotnet format` exit 0, no BOMs, `decisions-validate: OK`. CI green (Build & test 9m59s — full run, not the docs-only fast path). **Live E2E on ersatztv-test with the bug as its own positive control**: `[1]` → update omitting the field → `[]` (200, `isError=false`) → update with the field → `[1]` restored. Guard verified by **mutation**, not assumption: dropping either field, retyping either, drifting an array element type, and deleting the copied spec each turn the suite red and name the fault. **Deferred:** `padToNearestMinute` has **no live round-trip** — the deployed test image predates the field entirely (its `/openapi/v1.json` lacks it), so the API silently ignored it. Environment limitation, not a defect; the field is real on `main`, which is what the guard asserts against. Follow-ups filed: #758 (`GetPagedPlayouts` counts before both the `query` and `Channel != null` filters — pre-existing, newly reachable, same family as #690) and #759 (query guard ignores a `$ref`'d parameter where the body guard fails loudly; dormant today). **Docs updated:** `docs/mcp.md`, `docs/decisions/records/mcp/tool-schema-openapi-parity.md` (new), `docs/decisions/README.md` (regenerated). **Review:** 3 adversarial rounds, cold + worktree-isolated. Rounds 1 and 2 returned **BLOCKED** — the schedule twin got its schema fix but not its warning; a docs claim was false for four tools; and the guard compared **names only** (proved by mutation: retyping the field this PR adds stayed green). Round 2 caught `update_playout` mis-bucketed as safe. Round 3 MERGEABLE, re-confirmed on the merging sha.
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: timothy/ersatztv#754