# ultra-mcp-ss (lab)

SmartScreen MCP adapter for external MCP clients.

Lab placement: `u22`, exposed as
`https://ultra-mcp.u22.ypcloud.com/mcp/ss`.

## Endpoints

- `POST /mcp/ss`: standard MCP Streamable HTTP JSON-RPC endpoint.
- `GET /mcp/ss`: optional Streamable HTTP server event stream.
- `GET /sse/ss`: legacy MCP SSE transport when `MCP_TRANSPORT=http+sse`.
- `POST /api/ss`: native `{to,data}` HTTP ingress for diagnostics; downstream
  delivery still uses MoteBus only.
- `GET /ping`: process health.

Every SmartScreen operation uses this downstream route:

- Read `ultra_ss_app_lab_mma` from `u22/comm/comm-app` on
  `map://ultra-map-dev`.
- Validate the selected `ultra-map` source and resolved
  `u22/ss/ss-srv-app` owner.
- Send the native `{to,data}` screen command through MoteBus xmsg on
  `ss://mms`. Do not add reserved transport markers to the command body.
- Fail visibly if map resolution, MoteChat, the owner, or its reply is
  unavailable. There is no HTTP or alternate-transport fallback.

An MCP client must initialize the session before listing or calling tools. For
Hermes, register the public MCP URL, reload MCP discovery, and expect tools
such as `ss_notify`, `ss_drop`, `ss_go`, and `ss_text`. `ss_go` is the
first-class MCP form of `/ss go <qname-or-page-route>`; for example, `101.tv`
dispatches the native WebOS route `page://board?type=dock&q=101.tv`. The
constrained `ss_command` tool lets the canonical SS skill carry SS-owned native
command data through a standard MCP `tools/call` request; it does not change
the MoteBus-only downstream route.

DNS-rebinding protection remains enabled. The Lab Compose configuration allows
only the Lab public hostname plus local/container names. PD independently
allows `mcp-ss.ypcloud.com` and the shared `ultra-mcp.ypcloud.com` gateway; PD
and Lab aliases are not interchangeable.

MoteChat startup identity and gateway settings are held only in the locked
`ultra-mcp-ss-mchat.env` topology contract. The selected UltraMap tier is
declared separately by Compose through `ULTRA_MCP_SS_MAP_TIER`.