Port OS Smart Home MCP Server

Stop watching by cancelling one Port OS event subscription using its exact ID from subscription_list or subscription_inspect. Cancellation is idempotent. Select the intended subscription by name, source endpoint and catalog event; names are not cancellation keys. A stopped monitor requires a new subscription to watch again.

Inspect one Port OS event subscription by its exact ID returned by subscription_list. Returns its safe query, source endpoint, catalog name and lifecycle status. A retained active subscription establishes registration; it does not prove that any client has received or acted on a camera event.

Change only the display name of one Port OS event subscription by exact ID. Use a PLAIN name-value object. The event, endpoint, filter and destination are immutable; to change what is watched, establish a replacement monitor and cancel the old ID.

Enumerate the user's Port OS event subscriptions, including their exact IDs, names, source endpoint, catalog event and status. For requests to stop watching a camera, list subscriptions and follow every nextCursor, select the intended monitor, then use subscription_cancel with its exact ID. Creating a monitor uses the host's events/subscribe capability after discovering supported camera events; these tools never accept callback URLs or signing keys.

Manage the names, types and registry entries of your devices and connected services. Send the complete name, type and enablement document for every metadata replacement, with etag from the read and a stable idempotencyKey. Choose one operation: RENAME, SET_TYPE, SET_ENABLEMENT, MERGE_INTO, or DELETE. Use endpoint_query first and copy the returned endpoint ID. Rename and type changes are durable across provider rediscovery. Disabled endpoints stay available for explicit metadata reads, but cannot receive messages; rediscovery preserves the disabled state. DELETE removes the registry entry, though a provider may rediscover it later. MERGE_INTO retains the source endpoint as disabled and moves supported references to the target; it does not create a source-ID alias, a simulator endpoint can merge only into a target without a simulator route (two simulator endpoints return 409 CONFLICT; disable or delete the duplicate instead), and the target's enablement remains in effect. Before MERGE_INTO or DELETE, identify the actual endpoint and explain the effect to the user; never assume two endpoints are duplicates because their names match. This tool changes registry metadata only and never performs physical control.

Find connected devices and services, discover their controls, and read their state. Start with a focused name, room or category query; follow paginationContext.nextToken. Results include resource references, device types, provider routes, capabilities and accepted message references. An endpoint is a device or connected service, including a filesystem or media library. Copy IDs verbatim into control. For a known device, use endpointId; inspect its declared capabilities, commands and outbound message IDs. Use group_query for rooms and endpoint_manage for requested inventory cleanup. To read state, set expand to the declared capabilities you need, for example ["power","connectivity"] or ["battery"]. expand adds observations; it does not discover more devices or send controls. Add forceDeviceAttributeQuery=true to refresh selected attributes from the provider; otherwise readings may come from cache. Only FRESH observations establish the current state. A FRESH value is the current state; a STALE value is the last known state, reported with its sampledAt and never as live or unknown (a forced read may refresh it). Errored, missing or invalid values are unknown, not OFF or a dead battery, and a STALE value alone must not support a safety claim such as locked or off. An attribute with error.code PROVIDER_NO_STATE (forced reads only) means the provider answered but has no value for it: state is unknown and retrying will not help until the provider reports one. FRESH UNREACHABLE means offline even if a power value is present; STALE UNREACHABLE is the last known connectivity. An ID-only lookup retrieves metadata without requesting fresh state. Supported discovery includes: - Lights, switches and plugs: select by name and power/brightness capabilities as well as type; a light may be typed SWITCH or PLUG. - Thermostats and sensors: read temperature-sensor for ambient temperature; a setpoint is not room temperature. Clarify indoor versus outdoor temperature when ambiguous. - Cameras, locks, appliances, vacuums, pet appliances, sprinklers and water sensors: inspect declared controls and observations. - Phones, Apple Watch and trackers: read battery, charging, connectivity or location capabilities; use control for a declared ring command. - Speakers, TVs and media services: discover playback, volume, search and playlist commands. Alexa devices may be VOICE_ASSISTANT. - Filesystems, photos, calendars and reminders: choose a concrete route-backed service, rather than a generic plugin catalog or an old unrouted record. Read portos://guides/index or the bundled Port OS skill references for device workflows. Keep the account with every ID; check relevant authorized accounts before reporting a device missing. Names alone do not prove identity. Port OS selects routes for logical targets. Establish identity before merging records. By default lists contain enabled devices; enablement=DISABLED selects disabled devices and enablement=* includes both. Exact endpointId lookup can read metadata regardless of enablement. With group:read, controllableGroups lists rooms a device can act on. Simulator state does not establish household device state.

Show Port OS devices with their supported controls. To show a device, always call this tool: the widget it opens is the device's UI, so never render a second card, map or controls for it; answer in a sentence or two. Uses the same selection, expansion and pagination arguments as endpoint_query. A single matching device opens its full view with now playing, transport, volume and other controls; several matches open only a list of names to choose from, so pass one returned endpoint ID (or a query matching one device) to control a device. Showing a device does not start live video or send a control command. Pass primary to choose which card leads, one of the device's card ids (every result lists them as cardIds; an unknown id is rejected with the available ones). The device's usual card and every other card stay behind the details toggle. Examples: "what's the battery on the vacuum" -> primary battery; "turn the thermostat fan on" -> primary fan; "how open are the blinds" -> primary closure; "show me the camera on the roborock" -> primary camera. "where is my phone" or "show its location" -> primary location; "show the roborock's map" or "pick a room to clean" -> primary house-map. Every result already includes the cached readings of the cards it lists (cardIds), so you can answer without a second call; pass expand to choose different capabilities. primary refreshes that card's readings from the device, so the answer is current. Always state the value in words: a FRESH reading is current; a STALE reading is the last known value, so say it is last known and give its age.

Organize rooms and device groups: create, rename, change members, enable, disable, merge or delete them. Create, delete, add/remove members, MOVE_MEMBER and rename default to providerSync BEST_EFFORT: send supported native group changes first, verify provider readback, then save Port OS intent. A provider failure falls back locally and is PARTIALLY_APPLIED. PORTOS_ONLY sends nothing; FAIL_ON_PROVIDER_ERROR fails customer intent if a required provider change fails, while retaining received provider facts. Native effects cannot be rolled back. Undeclared support is NOT_SUPPORTED with reason NOT_DECLARED and does not by itself make the result partial. OUTSIDE_PRINCIPAL means native changes are not attempted through another principal's account; the authorized Port OS change can still apply. Read group IDs and etags with group_query first. Every reference to one group in a batch uses the same starting etag. MOVE_MEMBER takes memberEndpointId plus source and target group references with both etags; a lone add cannot implicitly displace another exclusive native group. Contradictory edits return 400; list position is not a procedural ordering mechanism. MERGE_INTO and aggregate/route enablement accept only PORTOS_ONLY. Rename does not automatically merge groups. DELETE_GROUP can delete provider groups. Routes not confirmed retired are disabled and orphaned, so rediscovery cannot resurrect the deleted group. SET_ENABLEMENT can hide an aggregate without deleting it; SET_GROUP_ROUTE_ENABLEMENT changes one provider route's contribution locally; its etag is the native route version and groupEtag is also required when the route belongs to a group. Obtain explicit user authorization for the exact MERGE_INTO or DELETE_GROUP targets and effects before calling. Hue supports native group creation, deletion, membership and rename. Roborock supports room rename only; membership changes do not reshape robot maps. Sonos native group mutations are not implemented. Declared support is authoritative. Use control for device actions such as power, playback or cleaning. Customer intent commits as one batch. Set validateOnly=true to report PLANNED or NOT_SUPPORTED dispatches without sending or writing. idempotencyKey is required otherwise: use one unique key per intended change, and reuse it only for the identical request after a lost or uncertain response. A stale etag returns PRECONDITION_FAILED; re-read and resolve the change before a new request. Inspect status COMMITTED, PARTIALLY_SUCCEEDED or FAILED, each result's APPLIED, PARTIALLY_APPLIED or NOT_APPLIED status, and providerDispatches. Failed batches retain provider facts and report operations whose messages were sent as NOT_APPLIED without group etags; errors identify failing operations. Do not report a partial save as fully synchronized or automatically repeat native writes.

Find rooms, floors, zones, homes and device groups, with their members and supported controls. Returns resource references, names, etags, spatial roles, parent paths, children, members, controllers and providers. For a named room use a focused name query; list without a query for an inventory request. Follow pagination only as needed for the requested scope. Controllers list endpoints and messages accepting this group: room cleaning targets the controller with payload {"groupIds":[<group ID>]}, not the group itself. Messages target the logical group ID through control. Port OS selects compatible native or equivalent member delivery for the complete effective membership, including scenes/media. Native interfaces and membershipComplete do not establish aggregate coverage. Disabled routes cannot control. For ambiguous names ask which parentPath the user means. Read one group with id; merged IDs resolve to the survivor with redirectedFrom. Show room maps with endpoint_show on the vacuum controller, primary house-map; never draw spatial geometry yourself. Expand uses capability names as in endpoint_query; forceDeviceAttributeQuery refreshes observations. Omitted or failed fresh route attributes are unavailable. membershipComplete is provider-declared: false means incomplete/unreported, absent means unknown. members lists resolved endpoints; empty does not prove a native group empty. Disabled groups are hidden unless enablement is DISABLED or * and cannot be targeted; re-enable with group_manage SET_ENABLEMENT. Copy IDs and etags verbatim.

Control devices/services and retrieve results or camera snapshots. Target exactly one id (endpoint/group) or field-first query as in endpoint_query. Queries freeze all authorized matches across every page in one request; zero or over 100 fails before delivery. Report any narrowing or splitting of requested whole-house coverage. Prefer one query control for whole-home lights; avoid loops and copied ID lists. If the established home scope identifies LIGHT and SWITCH as physical lighting only, use {"idempotencyKey":"<action key>","query":{"type":{"in":["LIGHT","SWITCH"]}},"message":"power/turn-off","payload":{},"waitForResult":false}. Otherwise combine LIGHT with known lamp-switch predicates; do not include arbitrary switches/plugs, simulators, provider SELF records or duplicate physical devices. Discover missing scope only. A group-only search can miss ungrouped lights. A separate action needs a new key. Copy returned target/message references from endpoint_query or group_query, preserving the account and declared payload ({} if fieldless). Compact and full IDs are accepted. Clarify ambiguous scope. Port OS selects compatible routes and native or equivalent member delivery for the complete target. Provider ambiguity requires resolving the intended logical target before another control. Use waitForResult=false for ordinary response-less power, cleaning, lock and playback commands. Report accepted/pending, then stop; do not automatically poll, fresh-read or call endpoint_show. Use true when the requested result needs a reply: snapshots/pixels, SDP, searches, queue reads, scene creation and authorization challenges. QUEUED/IN_PROGRESS remain pending even with empty lists. A requested verification or diagnosis uses a fresh query; acceptance alone never proves physical completion. Live music queue recipe: "set up a playlist and play it on my Sonos" means an active queue, not a saved library playlist unless requested. 1. Discover the Spotify library and target speaker/native group. Search via declared media-search/search-media with {"query":"<artist or mood>","type":"track"}, waitForResult=true. Copy returned playable canonical IDs; never invent IDs or play search phrases. 2. Check the target's declared media-queue support, supportedMediaResources/maxItemsPerPlay. Send play-queue once with {"mediaIds":["<track ID>","<track ID>"]} to the logical speaker or group; Port OS selects the compatible provider. No queueVersion here, and no repeated play-media emulation. 3. Ordinary play-queue uses waitForResult=false: acknowledge acceptance and stop. If the user asks for queue contents or verification, read get-queue with {}, waitForResult=true, and request fresh playback on the same target. queue-contents has currentMediaId, upcoming mediaIds, complete and optional queueVersion; complete=false is only a window. 4. Append without restarting using add-to-queue once with {"mediaId":"<track ID>"}. If requiresQueueVersion=true, get-queue first and copy its exact queueVersion into the append; omit it for Spotify Connect. Read a new queueVersion only before a subsequent append that requires it. Inspect conflicts/uncertain writes; never automatically retry or replace the queue. Failed search proves neither stopped playback nor a broken connection. Preserve playback and report the failure. Search type is lowercase "track", not configuration label "TRACK". Room lighting scenes: group_query with expand:["scene"], forceDeviceAttributeQuery:true; select the requested logical group and declared messages. Recall scene/activate with {"sceneId":"<returned scene ID>"}; Port OS resolves the provider. To save, first set member states, then scene/create-scene with {"name":"<scene name>"}, waitForResult=true. This snapshots settings without activation; activate using returned scene-created.sceneId. Inspect fresh available-scenes after uncertain creation. Ordinary recall uses waitForResult=false: acknowledge acceptance and stop. Read fresh state only for requested verification or an uncertain outcome; acceptance/scene labels prove no physical state. Preserve the requested room and scene. Use declared commands; consult portos://guides/index for unfamiliar workflows. Inventory edits belong in endpoint_manage/group_manage. Inspect partial/unknown outcomes before acting. TIMED_OUT is unknown; fresh-read state. Read known receipts via authorized GET /message-requests/{id}. control is a write: after ambiguous transport failure (including HTTP 404), never automatically repeat it, even with the same key; no receipt means possible new dispatch. Recover the receipt or read state first. An authorized retry retains key/all arguments, including waitForResult. MESSAGE_UNSUPPORTED/MESSAGE_AMBIGUOUS means nothing sent; correct from discovery. Unreachable devices rejected delivery. Conflicting observations cannot establish success.