tvOS tool support matrix¶
Support for every MCP tool in schemas/tool-definitions.json when the target is
an Apple TV simulator. Results were measured against an Apple TV 4K (3rd
generation) simulator on tvOS 26.5 and tvOS 27.0, using a probe app with a text
field and a 3×3 button grid.
How the gate works¶
A device-aware tool accepts a tvOS device only when
APPLE_PLATFORM_SUPPORTED_TOOLS.tvos lists it (src/server/applePlatformToolSupport.ts).
Every other device-aware tool fails closed before its handler runs. The server refuses a request
that names platform: "tvos" before target resolution, and it refuses a
resolved Apple TV device at dispatch. Device-management tools that
look up their own target (killDevice and similar) refuse a tvos request by
name unless they are allowlisted. Refusals carry one of three messages. The first is a generic “does not support
tvOS yet”. The second is a “not available on tvOS” message naming the missing runtime
capability (displayConfig, statusBar, clipboard, getAppPermissions). The third is a
focus-navigation hint for touch gestures (tapAt, swipeOn, pinchOn,
multiTouch, dragAndDrop, tapAny).
Observe text policy¶
The single @MainActor router uses TVTextEntryCommands to share a TVKeyboardSettleGate
across hierarchy, append-text and post-press snapshots, using an injected uptime clock. The gate’s only
mutable state is lastKeyboardSeen, initialized to the current uptime so a fresh
runner withholds values for its first window. Any failed hierarchy, append-text or
post-press snapshot stamps the current uptime conservatively before returning.
Hierarchy and append-text propagate the snapshot error; a successful press still succeeds.
Hierarchy, append-text and press requests carry the daemon’s foreground-app hint.
After the runner starts, the foreground restore re-launches that app. It then polls the
hierarchy’s packageName (250 ms interval, 5 s bound) until it names that app, since
simctl launch returns before tvOS finishes the transition. The restore stays best-effort and
cancellable, and the start result’s message reports a bound that expires.
Append-text stamps the known keyboard-present tree again after typing completes.
A type-19 keyboard node anywhere in a snapshot updates that timestamp and
withholds every text-input value (types 45, 49, 50 and 52), regardless of focus
or position in the tree. Withholding continues across snapshots without a
keyboard until two conditions hold. At least settleWindow = 1.0 seconds have elapsed since the last
keyboard snapshot, typing completion or snapshot failure. The current snapshot contains
neither a keyboard nor an anonymous type-45, type-49 or type-52 input. Anonymous means identifier, label
and placeholder are all empty after trimming whitespace and newlines; a nil
placeholder is empty. Only then does the gate clear the timestamp. Backward or non-finite
clock readings fail closed; a non-finite stored timestamp also prevents release
until it is replaced with a finite timestamp.
Nodes retain their snapshot identifier, class and focus; withheld field nodes
emit only their labels, and placeholders appear only as keyboard prompt nodes.
As a second guard, anonymous type-45, type-49 and type-52 nodes never emit values,
even with no gate state. After the gate releases, a named plain field’s value is
readable through observe on its own node, joined with its label when distinct. Whitespace-only
values and values equal to the placeholder count as empty; a whitespace-only
label counts as empty when joining. Secure fields, including type-50 nodes and
fields identified by secure metadata, always redact their values.
Status values¶
- pass: allowlisted and verified working on an Apple TV simulator.
- refused-by-design: fails closed because the capability does not exist on tvOS. Either tvOS has no touch surface, orientation, telephony or keyguard, the tvOS simulator runtime lacks the simctl service, or the tool is Android-, Wear OS- or watchOS-only.
- not-supported: fails closed today although tvOS could support it. The linked issue tracks enabling it; tools with no linked issue have none filed.
- host-only: does not target a device, so the tvOS gate does not apply.
Matrix¶
| Tool | Status | Notes |
|---|---|---|
accessibility |
not-supported | Needs runner work. |
accessibilityAction |
refused-by-design | Android-only (TalkBack and Switch Access actions). |
accessibilityAudit |
not-supported | Needs runner work. |
accessibilityFocus |
not-supported | Needs runner work. |
ambient |
refused-by-design | Wear OS only. |
appLifecycle |
not-supported | |
backgroundWork |
refused-by-design | Android-only. |
barrier |
not-supported | Plan-only multi-device primitive. |
biometricAuth |
refused-by-design | Apple TV has no biometric sensor. |
captureAudio |
not-supported | |
captureTrace |
not-supported | Needs runner work. |
changeLocalization |
not-supported | |
clearKeyValueFile |
not-supported | |
clearMockNetwork |
not-supported | |
clipboard |
refused-by-design | The tvOS simulator runtime has no pasteboard service; the refusal says so. |
compareScreenshot |
pass | Record and compare via simctl io screenshots. |
crashApp |
pass | simctl spawn launchctl kill in the system/ domain (tvOS app services are not under user/<uid>/). |
criticalSection |
not-supported | Plan-only multi-device primitive. |
deleteDevice |
pass | Destroy with verified inventory absence. |
deleteKeychainItem |
not-supported | |
deviceSnapshot |
not-supported | |
displayConfig |
refused-by-design | The tvOS simulator runtime has no appearance or content-size service; the refusal says so. |
displayProfile |
refused-by-design | Android-only. |
dragAndDrop |
refused-by-design | No touch surface. |
dragPath |
refused-by-design | No touch surface. |
executePlan |
pass | |
explore |
pass | Moves focus and selects. Only works when the embedded-SDK tool set is enabled; otherwise the call fails with Unknown tool: explore (#17528). |
exportPlan |
host-only | |
focusNavigate |
pass | |
getAndroid |
host-only | Android AVD discovery. |
getApple |
host-only | iOS Simulator discovery. |
getAppPermissions |
refused-by-design | simctl has no permission read verb; the refusal says so. setAppPermissions covers the write side. |
getDataStore |
refused-by-design | Android-only (Jetpack DataStore). |
getDeepLinks |
pass | |
getDeviceState |
not-supported | |
getLogs |
pass | simctl spawn log show; appId is required and Android-only filters are ignored with a warning. |
getNavigationGraph |
not-supported | |
getNetworkGraph |
not-supported | |
getNotificationPolicy |
not-supported | |
getPreference |
not-supported | |
heapDump |
refused-by-design | Android-only. |
highlight |
not-supported | |
hitTest |
refused-by-design | No touch surface. |
homeScreen |
pass | Presses the Siri Remote home button (same press as pressButton home); the result reports the press, not a checked home screen. |
hoverAt |
refused-by-design | No stylus or pointer. |
identifyInteractions |
not-supported | Also behind the debug flag. |
injectAudioInput |
not-supported | |
inspectPackageSigning |
not-supported | |
installApp |
pass | |
keyboard |
not-supported | |
killDevice |
pass | |
killProfile |
refused-by-design | Android-only. |
launchApp |
pass | |
listApps |
pass | |
listDataStores |
refused-by-design | Android-only (Jetpack DataStore). |
listDeviceImages |
pass | |
listDevices |
pass | Filters with platform: "tvos". |
manufacturerProfile |
refused-by-design | Android-only. |
measureStartup |
refused-by-design | Android-only. |
mediaSession |
refused-by-design | Android-only. |
mockNetwork |
not-supported | |
multiTouch |
refused-by-design | No touch surface. |
navigateTo |
not-supported | |
network |
not-supported | |
observe |
pass | Reports focusedElement. Typed values are withheld while the keyboard is open; see the observe text policy. |
openLink |
pass | Opens declared app schemes. A web URL or an undeclared scheme fails with the documented error. |
performanceAudit |
not-supported | Needs runner work. |
performanceTrace |
not-supported | Needs runner work. |
phoneCall |
refused-by-design | No telephony. |
pinchOn |
refused-by-design | No touch surface. |
portReverse |
refused-by-design | Android-only. |
postNotification |
pass | simctl push to the app named by appId (required). |
pressButton |
pass | Any remote button long-presses with durationMs (100–10000 ms) if the runner lists press_button_hold. No steps or touch-surface swipes. |
prototype |
not-supported | |
provisionDevice |
pass | Boots with readiness none; readiness automation also starts the runner, as startDevice does. |
putAppFile |
not-supported | |
recentApps |
not-supported | |
reconcileDeviceResources |
not-supported | |
recordDeviceGestures |
not-supported | |
recordToolCalls |
host-only | |
removeKeyValue |
not-supported | |
resetAppLogs |
not-supported | |
resetKeychain |
not-supported | |
rotaryScroll |
refused-by-design | Wear OS only. |
rotate |
refused-by-design | No orientation. |
rotateCrown |
refused-by-design | watchOS only. |
selectAllText |
not-supported | |
sendBroadcast |
refused-by-design | Android-only. |
sendKeys |
pass | Requires a focused keyboard (pressButton select on the field); otherwise no focused text input. Read plain values after close. |
sendSms |
refused-by-design | No telephony. |
setActiveDevice |
pass | |
setAppLinks |
refused-by-design | Android-only. |
setAppPermissions |
pass | simctl privacy grant, revoke or reset; changes are not read back (verified: false). |
setDeviceResources |
not-supported | |
setDeviceState |
not-supported | |
setKeyValue |
not-supported | |
setNotificationPolicy |
not-supported | |
setPosture |
refused-by-design | No foldable posture. |
setPreference |
not-supported | |
setSensor |
refused-by-design | Android-only. |
setToolEnabled |
host-only | |
setUIState |
not-supported | Also behind the debug flag. |
shake |
refused-by-design | No motion gesture. |
siri |
not-supported | |
snapshotOf |
not-supported | |
sqlQuery |
not-supported | |
statusBar |
refused-by-design | The tvOS simulator runtime has no status bar override; the refusal says so. |
stopAudioInput |
not-supported | |
swipeAt |
refused-by-design | XCUITest does not expose touch-surface swipes on tvOS; use directional presses and focus navigation. |
swipeOn |
refused-by-design | XCUITest does not expose touch-surface swipes on tvOS; use directional presses and focus navigation. |
systemAlerts |
not-supported | |
systemTray |
refused-by-design | No notification shade. |
tapAny |
refused-by-design | No touch surface; use tapOn or focusNavigate. |
tapAt |
refused-by-design | No touch surface. |
tapOn |
pass | Moves focus to the element by text or elementId and selects it. |
terminateApp |
pass | |
uninstallApp |
pass | |
videoRecording |
pass | simctl io recordVideo, HEVC MP4. |
wakeAndUnlock |
refused-by-design | No keyguard. |
windowMode |
refused-by-design | Android-only. |
Totals: 27 pass, 49 not-supported, 40 refused-by-design, 6 host-only. The tvOS
allowlist also holds startDevice, which is not in the published tool
definitions; it boots the simulator and connects the runner.