# mcppics.local HTTP badge specification

Version: 1  
Status: proposed device-side contract  
Consumer: `https://mcp.pictures` (also `https://www.mcp.pictures`)

## Purpose

Provide a small page that a static HTTPS marketing site can embed to show whether the local MCP service is ready. It must work without CORS because the parent page only embeds the response; it does not read the iframe document.

The badge is loaded only after the visitor clicks **Check local camera**. This makes the browser’s local-network permission request an intentional action.

## Endpoint

Serve this endpoint from the same origin as the device service:

```text
GET http://mcppics.local/badge
```

The endpoint must not redirect to another hostname, scheme, or path. It must return a complete HTML document, not an image or a partial fragment. Ignore unknown query parameters; the static site adds a changing `check` parameter to avoid stale intermediary responses.

### Response headers

```http
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Cache-Control: no-store
Content-Security-Policy: frame-ancestors https://mcp.pictures https://www.mcp.pictures
Referrer-Policy: no-referrer
X-Content-Type-Options: nosniff
```

Do not set `X-Frame-Options: DENY` or `SAMEORIGIN`; either would prevent the intended cross-origin embedding. A CORS `Access-Control-Allow-Origin` header is not required for this iframe design.

## Badge page behavior

- Use a transparent page background and a compact layout that fits a `220 × 50` CSS pixel iframe.
- Include a visible, accessible status label and a link to `http://mcppics.local/` with `target="_top"`, so clicking it opens the device service in the main tab.
- Show a green dot and “mcppics.local ready” only when the MCP service is ready to accept requests.
- If the HTTP service is running but the MCP service is not ready, show a non-green state such as an amber dot and “MCP service not ready.”
- Keep the page self-contained. Do not load scripts, stylesheets, fonts, images, or analytics from third parties.
- Do not include credentials, camera images, user data, or private diagnostics in the page or status message.

The badge endpoint must check the actual MCP readiness state. Serving the badge HTML alone is not sufficient evidence that the MCP service works.

## Readiness message

After rendering the current state, the badge page must send this message to its parent:

```js
window.parent.postMessage(
  { type: "mcppics.badge", version: 1, status: "ready" },
  "*"
);
```

Use `status: "not_ready"` when the device HTTP service responded but the MCP service is not ready. The message contains status only; it must never contain secrets or user data. The wildcard target is acceptable for this non-sensitive signal because the embedding page validates both `event.origin` and `event.source` before acting on it.

The embedded page must preserve its real origin (`http://mcppics.local`) so the parent receives that exact `event.origin`. The parent ignores messages from any other origin, any other frame, or an unknown protocol version.

## Failure behavior

If the device host cannot serve `/badge`, the browser will not deliver a trustworthy load/error signal to the parent. The parent therefore times out and displays “Couldn’t confirm mcppics.local” with setup guidance. Do not expect the parent site to distinguish DNS failure from a refused connection, blocked local-network permission, or another browser/network error.

## Verification checklist

- `http://mcppics.local/badge` loads directly on the local network.
- The document is transparent and compact, and its link opens the setup page in the top-level tab.
- A ready MCP service returns the green state and `status: "ready"`.
- A running HTTP service with an unready MCP service returns a non-green state and `status: "not_ready"`.
- The response can be framed by `https://mcp.pictures` and `https://www.mcp.pictures`.
- The response does not depend on CORS, external assets, cookies, or credentials.
- With the device host unavailable, the marketing site keeps its own fallback instructions visible and reports that it could not confirm the service.