@runsnative/mcp-server 0.5.1 → 0.7.0

package/dist/tools/render-surface.js

@@ -0,0 +1,204 @@
+/**
+ * render_surface / surface_event tools (JUNE-793) — the MCP-host leg of the
+ * agent-surface runtime. Together they close the engine's render → suspend →
+ * resume loop at the user:
+ *
+ *  - `render_surface { route }` — the RENDER leg. Calls the engine gateway's
+ *    `surfaces/query` (threading the linked-session `agent_session_id`),
+ *    retains the pairing keys, and returns the `SurfaceSpec` for the agent-
+ *    surface MCP-App shell to mount.
+ *  - `surface_event { event_type, payload }` — the RESUME leg. Posts the
+ *    retained keys + the user's typed payload to `surfaces/{name}/event`,
+ *    handling the terminal ack, the chained successor, and the governor
+ *    rejection ("surface no longer active") distinctly.
+ *
+ * The active surface is held module-level for the MCP server process lifetime
+ * (one surface in flight at a time), mirroring bridge-client's `_linkedPairId`.
+ * The transport is injectable so tests exercise the full loop with a stub —
+ * no engine required.
+ */
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { getLinkedPairId } from '../bridge-client.js';
+import { componentsBundle, iframeRuntime } from '../surface/assets.js';
+import { AGENT_SURFACE_URI, buildAgentSurfaceHtml } from '../surface/agent-surface.js';
+import { SURFACE_MIME_TYPE } from '../surface/package-surface.js';
+import { SurfaceHostSession, SurfaceHostStateError, } from '../../../surface-protocol/surface-host-client.js';
+import { engineGatewayTransport } from '../surface/engine-gateway-transport.js';
+// ---------------------------------------------------------------------------
+// Module-level state — one active surface per MCP server process, and an
+// injectable transport (default: the engine gateway over HTTP).
+// ---------------------------------------------------------------------------
+let _transport = engineGatewayTransport;
+let _session = null;
+/** Test seam — swap the engine transport for a stub. */
+export function _setSurfaceTransport(t) {
+    _transport = t;
+}
+/** Test seam — reset transport + active surface between tests. */
+export function _resetSurfaceHost() {
+    _transport = engineGatewayTransport;
+    _session = null;
+}
+/** The session identity threaded on both legs: the linked pair, or an env override. */
+function currentAgentSessionId() {
+    const linked = getLinkedPairId();
+    if (linked)
+        return linked;
+    const env = process.env['MUKADRA_AGENT_SESSION_ID']?.trim();
+    return env ? env : undefined;
+}
+// ---------------------------------------------------------------------------
+// Tool + resource definitions
+// ---------------------------------------------------------------------------
+export const RENDER_SURFACE_TOOL = {
+    name: 'render_surface',
+    description: 'Render an agent surface at a route: ask the Mukadra engine what component to render there, ' +
+        'mount it as a live MCP App in this conversation, and suspend for the user to interact. The ' +
+        "user's typed response is posted back with surface_event, and the agent continues. Use when an " +
+        'agent reasoning step needs a user pick that a component surface can capture (the render → ' +
+        'suspend → resume loop). Requires a linked session so the resume is governed (resumable); ' +
+        'without one the surface renders non-resumable (one-shot).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            route: {
+                type: 'string',
+                description: "The surface route to resolve (e.g. '/pick/customer'). Matched by the engine's surface catalog.",
+            },
+        },
+        required: ['route'],
+    },
+    _meta: {
+        ui: { resourceUri: AGENT_SURFACE_URI },
+        'ui/resourceUri': AGENT_SURFACE_URI,
+    },
+};
+export const SURFACE_EVENT_TOOL = {
+    name: 'surface_event',
+    description: 'Post the user\'s response to the active surface back to the engine (the resume leg). Called by ' +
+        'the surface shell when the user interacts; resolves the suspended agent step. Returns the ' +
+        'outcome: done (agent continues), chained (a successor surface to render), or expired (the ' +
+        'surface is no longer active).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            event_type: { type: 'string', description: "Interaction type, e.g. 'submit', 'click', 'cancel'. Defaults to 'submit'." },
+            payload: { description: "The user's typed response, shaped by the surface's response contract." },
+        },
+        required: [],
+    },
+};
+export const AGENT_SURFACE_RESOURCE = {
+    uri: AGENT_SURFACE_URI,
+    name: 'Agent Surface',
+    description: 'Self-contained MCP App shell that mounts whatever component the engine surfaces at a route and ' +
+        'posts the user response back. Spec arrives via the tool-result notification; nothing external is loaded.',
+    mimeType: SURFACE_MIME_TYPE,
+};
+export async function readAgentSurfaceResource() {
+    const html = buildAgentSurfaceHtml({
+        componentsBundle: componentsBundle(),
+        iframeRuntime: iframeRuntime(),
+    });
+    return { contents: [{ uri: AGENT_SURFACE_URI, mimeType: SURFACE_MIME_TYPE, text: html }] };
+}
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+export async function handleRenderSurface(args) {
+    const route = typeof args['route'] === 'string' ? args['route'].trim() : '';
+    if (!route) {
+        throw new McpError(ErrorCode.InvalidParams, 'render_surface requires a non-empty "route".');
+    }
+    const session = new SurfaceHostSession({
+        transport: _transport,
+        agentSessionId: currentAgentSessionId(),
+    });
+    const outcome = await session.render(route);
+    if (outcome.status === 'not_found') {
+        // No declared surface matches this route (render-leg 404). Distinct from a
+        // governor rejection, which can only happen on the resume leg.
+        throw new McpError(ErrorCode.InvalidParams, `No surface is declared at route "${route}". Check the route, or the agent's surface catalog.`);
+    }
+    // Retain the active surface for the subsequent surface_event call.
+    _session = session;
+    const resumableNote = outcome.resumable
+        ? 'The surface is governed (resumable) — interact, and surface_event resumes the agent.'
+        : 'No linked session — this surface is NON-RESUMABLE (one-shot); link a session first to enable resume.';
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Rendered surface "${outcome.surfaceName}" (${outcome.spec.component}) at route "${route}". ` +
+                    resumableNote,
+            },
+        ],
+        structuredContent: {
+            spec: outcome.spec,
+            surface_instance_id: outcome.surfaceInstanceId,
+            correlation_id: outcome.correlationId,
+            resumable: outcome.resumable,
+        },
+    };
+}
+export async function handleSurfaceEvent(args) {
+    if (!_session || !_session.hasActiveSurface) {
+        throw new McpError(ErrorCode.InvalidParams, 'No active surface to respond to. Render one first with render_surface.');
+    }
+    const eventType = typeof args['event_type'] === 'string' && args['event_type'].trim() ? args['event_type'].trim() : 'submit';
+    const payload = args['payload'];
+    let outcome;
+    try {
+        outcome = await _session.submit(eventType, payload);
+    }
+    catch (e) {
+        if (e instanceof SurfaceHostStateError) {
+            // Non-resumable (session-less) surface, or ordering violation — a clean
+            // host-side signal, not a crash.
+            _session = null;
+            throw new McpError(ErrorCode.InvalidParams, e.message);
+        }
+        throw e;
+    }
+    switch (outcome.status) {
+        case 'done':
+            _session = null;
+            return {
+                content: [{ type: 'text', text: 'Response accepted — the agent is continuing.' }],
+                structuredContent: { status: 'done', correlation_id: outcome.correlationId },
+            };
+        case 'chained':
+            // Successor surface parked by the engine (same correlation_id). The shell
+            // re-mounts spec and loops.
+            return {
+                content: [
+                    { type: 'text', text: `Rendered the next surface (${outcome.spec.component}). Waiting for the user's response.` },
+                ],
+                structuredContent: {
+                    status: 'chained',
+                    spec: outcome.spec,
+                    surface_instance_id: outcome.surfaceInstanceId,
+                    correlation_id: outcome.correlationId,
+                },
+            };
+        case 'expired':
+            // Governor rejection — expired / cross-session / already-resolved. This
+            // is the "surface no longer active" state, distinct from a 404.
+            _session = null;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'That surface is no longer active (it expired or was already resolved). Render it again to continue.',
+                    },
+                ],
+                structuredContent: { status: 'expired' },
+            };
+        case 'not_found':
+            _session = null;
+            return {
+                content: [{ type: 'text', text: 'That surface is no longer available (unknown surface or route).' }],
+                structuredContent: { status: 'not_found' },
+            };
+    }
+}

package/dist/tools/search-docs.js

@@ -1,7 +1,7 @@
 import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 export const SEARCH_DOCS_TOOL = {
     name: 'search_docs',
-    description: 'Lexical search across all RunsNative component documentation, foundations, and exercises. ' +
+    description: 'Lexical search across all RunsNative component documentation, foundations, exercises, and composition patterns (recipes). ' +
         'Useful when you do not know the exact component name — for example, searching "focus ring token" ' +
         'or "which component handles multi-select". Returns scored results with excerpts.',
     inputSchema: {

package/dist/tools/session-tools.js

@@ -0,0 +1,38 @@
+/**
+ * The session-ENACT tool set — every MCP tool that submits a command into a
+ * linked session (Copresence Protocol §5.1 `target: 'session'` with an
+ * `enactment`). Single source of truth (JUNE-739): server.ts registers from
+ * this list, copresence-meta.test.ts asserts annotations over it, and the
+ * cross-surface reconciliation test (mcp-api-worker
+ * test/cross-surface-reconciliation.test.ts) binds it to the worker
+ * allow-list, entitlement registry, and org DISPATCH_TABLE.
+ *
+ * Adding a session verb? Add the tool HERE (never only in server.ts) — the
+ * reconciliation test fails until all four surfaces carry it.
+ *
+ * NOT in this list: read-leg session tools with no enactment
+ * (get_marker_capture, fetch_marker_crop, render_marker_capture) and the
+ * binding-redemption tool (link_session).
+ */
+import { SET_THEME_TOOL } from './set-theme.js';
+import { SET_SKIN_TOOL } from './set-skin.js';
+import { SET_MODE_TOOL } from './set-mode.js';
+import { SET_CONTRAST_TOOL } from './set-contrast.js';
+import { APPLY_INFERRED_THEME_TOOL } from './apply-inferred-theme.js';
+import { NAVIGATE_TOOL } from './navigate.js';
+import { SET_INSTANCE_VARIANT_TOOL } from './set-instance-variant.js';
+import { SPOTLIGHT_TOOL } from './spotlight.js';
+export const SESSION_ENACT_TOOLS = [
+    SET_THEME_TOOL,
+    SET_SKIN_TOOL,
+    SET_MODE_TOOL,
+    SET_CONTRAST_TOOL,
+    APPLY_INFERRED_THEME_TOOL,
+    NAVIGATE_TOOL,
+    SET_INSTANCE_VARIANT_TOOL,
+    SPOTLIGHT_TOOL,
+];
+/** The `capability.method` allow-list entries this tool set can enact. */
+export function listSessionEnactments() {
+    return SESSION_ENACT_TOOLS.map((t) => t._meta?.copresence?.enactment).filter((e) => typeof e === 'string');
+}

package/dist/tools/set-contrast.js

@@ -0,0 +1,59 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { postWorkerApi, getLinkedPairId } from '../bridge-client.js';
+export const SET_CONTRAST_TOOL = {
+    name: 'set_contrast',
+    description: "Switch the user's linked runsnative.org tab between standard and high contrast — the accessibility axis of the " +
+        'theme, orthogonal to light/dark mode. Use when the user asks for higher contrast, better legibility, or to go ' +
+        'back to the standard rendering. The command is enqueued and the tab applies it within one poll interval; ' +
+        'nothing is saved — fully reversible. Requires an active linked session (call link_session first).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            contrast: { type: 'string', enum: ['standard', 'high'], description: "Contrast to apply: 'standard' or 'high'." },
+        },
+        required: ['contrast'],
+    },
+    // Copresence Protocol §5.1 — session-targeting capability; `enactment` names
+    // the worker allow-list entry this tool submits (JUNE-626 / JUNE-739).
+    _meta: {
+        copresence: {
+            target: 'session',
+            tier: 'reversible',
+            consent: 'implicit',
+            entitlement: 'free',
+            visibility: 'advertised',
+            enactment: 'theme.setContrast',
+        },
+    },
+};
+export async function handleSetContrast(args) {
+    const contrast = args['contrast'];
+    if (contrast !== 'standard' && contrast !== 'high') {
+        throw new McpError(ErrorCode.InvalidParams, "contrast must be 'standard' or 'high'");
+    }
+    const pairId = getLinkedPairId();
+    if (!pairId) {
+        throw new McpError(ErrorCode.InvalidParams, 'No linked session. Call link_session with the pairing code first, or open runsnative.org and start the pairing flow.');
+    }
+    const res = await postWorkerApi('/tenant/command', {
+        pair_id: pairId,
+        capability: 'theme',
+        method: 'setContrast',
+        args: [contrast],
+    });
+    if (res.status === 404) {
+        throw new McpError(ErrorCode.InvalidParams, 'Linked session not found or expired. Re-link with link_session.');
+    }
+    if (res.status === 422) {
+        const body = await res.json().catch(() => ({}));
+        throw new McpError(ErrorCode.InvalidParams, body.error ?? 'Command rejected by allow-list.');
+    }
+    if (res.status === 409) {
+        throw new McpError(ErrorCode.InvalidParams, 'No live tab detected. Open runsnative.org, ensure the tab is active, then retry.');
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new McpError(ErrorCode.InternalError, `Worker error ${res.status}: ${body}`);
+    }
+    return { content: [{ type: 'text', text: `Contrast command enqueued: ${contrast}. The tab will apply it within one poll interval.` }] };
+}

package/dist/tools/set-instance-variant.js

@@ -23,11 +23,11 @@ export const SET_INSTANCE_VARIANT_TOOL = {
         },
         required: ['instance_id', 'variant'],
     },
-    // LSP §5.1 (linked-session-protocol-v0.1, mukadra repo) — marks this as a
-    // session-targeting capability. `enactment` names the worker allow-list
-    // entry this tool submits (JUNE-626).
+    // Copresence Protocol §5.1 (copresence-protocol-v0.1, mukadra repo) — marks
+    // this as a session-targeting capability. `enactment` names the worker
+    // allow-list entry this tool submits (JUNE-626).
     _meta: {
-        lsp: {
+        copresence: {
             target: 'session',
             tier: 'reversible',
             consent: 'implicit',

package/dist/tools/set-mode.js

@@ -0,0 +1,59 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { postWorkerApi, getLinkedPairId } from '../bridge-client.js';
+export const SET_MODE_TOOL = {
+    name: 'set_mode',
+    description: "Switch the user's linked runsnative.org tab between light and dark mode — the luminance axis of the theme, " +
+        'orthogonal to contrast. Use when the user asks for dark mode, light mode, or to compare the two. The command ' +
+        'is enqueued and the tab applies it within one poll interval; nothing is saved — fully reversible. Requires an ' +
+        'active linked session (call link_session first).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            mode: { type: 'string', enum: ['light', 'dark'], description: "Mode to apply: 'light' or 'dark'." },
+        },
+        required: ['mode'],
+    },
+    // Copresence Protocol §5.1 — session-targeting capability; `enactment` names
+    // the worker allow-list entry this tool submits (JUNE-626 / JUNE-739).
+    _meta: {
+        copresence: {
+            target: 'session',
+            tier: 'reversible',
+            consent: 'implicit',
+            entitlement: 'free',
+            visibility: 'advertised',
+            enactment: 'theme.setMode',
+        },
+    },
+};
+export async function handleSetMode(args) {
+    const mode = args['mode'];
+    if (mode !== 'light' && mode !== 'dark') {
+        throw new McpError(ErrorCode.InvalidParams, "mode must be 'light' or 'dark'");
+    }
+    const pairId = getLinkedPairId();
+    if (!pairId) {
+        throw new McpError(ErrorCode.InvalidParams, 'No linked session. Call link_session with the pairing code first, or open runsnative.org and start the pairing flow.');
+    }
+    const res = await postWorkerApi('/tenant/command', {
+        pair_id: pairId,
+        capability: 'theme',
+        method: 'setMode',
+        args: [mode],
+    });
+    if (res.status === 404) {
+        throw new McpError(ErrorCode.InvalidParams, 'Linked session not found or expired. Re-link with link_session.');
+    }
+    if (res.status === 422) {
+        const body = await res.json().catch(() => ({}));
+        throw new McpError(ErrorCode.InvalidParams, body.error ?? 'Command rejected by allow-list.');
+    }
+    if (res.status === 409) {
+        throw new McpError(ErrorCode.InvalidParams, 'No live tab detected. Open runsnative.org, ensure the tab is active, then retry.');
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new McpError(ErrorCode.InternalError, `Worker error ${res.status}: ${body}`);
+    }
+    return { content: [{ type: 'text', text: `Mode command enqueued: ${mode}. The tab will apply it within one poll interval.` }] };
+}

package/dist/tools/set-site-content.js

@@ -0,0 +1,69 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { postWorkerApi } from '../bridge-client.js';
+// An ORDINARY (non-session-targeting) authenticated MCP tool. Unlike the
+// session-ENACT tools (set_theme, set_instance_variant, …), this does NOT drive a
+// live bound tab through a pair — it persists content to the caller's PREVIEW
+// namespace via the tenant token, and the preview site renders it on next load.
+// Per Copresence Protocol §5.1, a tool that does not target a bound live session
+// is an ordinary MCP tool, so it carries NO _meta.copresence and is NOT in
+// SESSION_ENACT_TOOLS (see copresence-meta.test.ts: "Content tools likewise").
+export const SET_SITE_CONTENT_TOOL = {
+    name: 'set_site_content',
+    description: "Edit a section of the user's own site content in their PREVIEW environment. The change is " +
+        'saved to preview ONLY — the staging and production versions of the site are never touched — and ' +
+        'the preview site shows it on next load. Use this for content edits the user describes in words ' +
+        '(e.g. "we\'re past the summer closings, remove them from les heures"). Provide the section key and ' +
+        'the FULL new content object for that section — it replaces the current preview content. The shape ' +
+        'is section-specific and validated server-side; an invalid shape is rejected. Requires an ' +
+        'authenticated RunsNative token whose role may edit this site.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            section_key: {
+                type: 'string',
+                description: "The section to edit, page-namespaced, e.g. 'index:les-heures'.",
+            },
+            content: {
+                type: 'object',
+                description: 'The full replacement content object for the section (section-specific shape, validated ' +
+                    'server-side).',
+            },
+        },
+        required: ['section_key', 'content'],
+    },
+};
+export async function handleSetSiteContent(args) {
+    const sectionKey = args['section_key'];
+    if (typeof sectionKey !== 'string' || !sectionKey.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, 'section_key must be a non-empty string');
+    }
+    const content = args['content'];
+    if (!content || typeof content !== 'object' || Array.isArray(content)) {
+        throw new McpError(ErrorCode.InvalidParams, 'content must be an object');
+    }
+    const res = await postWorkerApi('/content', { section_key: sectionKey.trim(), content });
+    if (res.status === 401) {
+        throw new McpError(ErrorCode.InvalidParams, 'Not authenticated. Set RUNSNATIVE_TENANT_TOKEN to a token that may edit this site.');
+    }
+    if (res.status === 403) {
+        throw new McpError(ErrorCode.InvalidParams, 'Your role does not permit editing this site.');
+    }
+    if (res.status === 400) {
+        const body = (await res.json().catch(() => ({})));
+        throw new McpError(ErrorCode.InvalidParams, body.error ?? 'Content rejected by the server.');
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new McpError(ErrorCode.InternalError, `Worker error ${res.status}: ${body}`);
+    }
+    const body = (await res.json());
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Saved "${body.section_key}" to your preview site (version ${body.version}). ` +
+                    'Reload the preview to see it — staging and production are unchanged.',
+            },
+        ],
+    };
+}

package/dist/tools/set-skin.js

@@ -0,0 +1,60 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { postWorkerApi, getLinkedPairId } from '../bridge-client.js';
+export const SET_SKIN_TOOL = {
+    name: 'set_skin',
+    description: "Apply a named skin to the user's linked runsnative.org tab — the rendering treatment (e.g. wireframe, " +
+        'glassmorphism, crystalline) layered over the active theme, orthogonal to theme, mode, and contrast. Use when ' +
+        'the user asks to try a different look-and-feel treatment. The command is enqueued and the tab applies it ' +
+        'within one poll interval; nothing is saved — fully reversible. Requires an active linked session (call ' +
+        'link_session first).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            skin: { type: 'string', description: 'Skin identifier, e.g. "wireframe" or "glassmorphism".' },
+        },
+        required: ['skin'],
+    },
+    // Copresence Protocol §5.1 — session-targeting capability; `enactment` names
+    // the worker allow-list entry this tool submits (JUNE-626 / JUNE-739).
+    _meta: {
+        copresence: {
+            target: 'session',
+            tier: 'reversible',
+            consent: 'implicit',
+            entitlement: 'free',
+            visibility: 'advertised',
+            enactment: 'theme.setSkin',
+        },
+    },
+};
+export async function handleSetSkin(args) {
+    const skin = args['skin'];
+    if (typeof skin !== 'string' || !skin.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, 'skin must be a non-empty string');
+    }
+    const pairId = getLinkedPairId();
+    if (!pairId) {
+        throw new McpError(ErrorCode.InvalidParams, 'No linked session. Call link_session with the pairing code first, or open runsnative.org and start the pairing flow.');
+    }
+    const res = await postWorkerApi('/tenant/command', {
+        pair_id: pairId,
+        capability: 'theme',
+        method: 'setSkin',
+        args: [skin.trim()],
+    });
+    if (res.status === 404) {
+        throw new McpError(ErrorCode.InvalidParams, 'Linked session not found or expired. Re-link with link_session.');
+    }
+    if (res.status === 422) {
+        const body = await res.json().catch(() => ({}));
+        throw new McpError(ErrorCode.InvalidParams, body.error ?? 'Command rejected by allow-list.');
+    }
+    if (res.status === 409) {
+        throw new McpError(ErrorCode.InvalidParams, 'No live tab detected. Open runsnative.org, ensure the tab is active, then retry.');
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new McpError(ErrorCode.InternalError, `Worker error ${res.status}: ${body}`);
+    }
+    return { content: [{ type: 'text', text: `Skin command enqueued: ${skin.trim()}. The tab will apply it within one poll interval.` }] };
+}

package/dist/tools/set-theme.js

@@ -14,11 +14,11 @@ export const SET_THEME_TOOL = {
         },
         required: ['theme'],
     },
-    // LSP §5.1 (linked-session-protocol-v0.1, mukadra repo) — marks this as a
-    // session-targeting capability. `enactment` names the worker allow-list
-    // entry this tool submits (JUNE-626).
+    // Copresence Protocol §5.1 (copresence-protocol-v0.1, mukadra repo) — marks
+    // this as a session-targeting capability. `enactment` names the worker
+    // allow-list entry this tool submits (JUNE-626).
     _meta: {
-        lsp: {
+        copresence: {
             target: 'session',
             tier: 'reversible',
             consent: 'implicit',

package/dist/tools/spotlight.js

@@ -0,0 +1,85 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { postWorkerApi, getLinkedPairId } from '../bridge-client.js';
+export const SPOTLIGHT_TOOL = {
+    name: 'spotlight',
+    description: "Point at something on the user's linked runsnative.org tab — a spotlight ring settles on a named " +
+        'element while the rest of the page dims (non-modal, they can still interact). Use to SHOW rather than ' +
+        'describe: "show me where X lives", "highlight the Y control". The target is a contract anchor ' +
+        '(a data-tour name the design system maintains), optionally prefixed with a route to point across ' +
+        'pages: "/compare/#gathering-g-1" navigates the tab there first, "quick-start" points on the current ' +
+        'page. Optional message shows a small card by the ring. Requires an active linked session (call ' +
+        'link_session first); fully reversible — the ring dismisses on "Got it", Escape, or navigation.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            target: {
+                type: 'string',
+                description: 'Contract anchor to point at. Bare anchor ("quick-start") points on the current page; ' +
+                    '"/route#anchor" ("/compare/#gathering-g-1") points across pages, navigating there first.',
+            },
+            message: {
+                type: 'string',
+                description: 'Optional short text shown in a card beside the spotlight ring.',
+            },
+        },
+        required: ['target'],
+    },
+    // Copresence Protocol §5.1 (copresence-protocol-v0.1, mukadra repo) —
+    // session-targeting capability. `enactment` names the worker allow-list
+    // entry this tool submits.
+    _meta: {
+        copresence: {
+            target: 'session',
+            tier: 'reversible',
+            consent: 'implicit',
+            entitlement: 'free',
+            visibility: 'advertised',
+            enactment: 'tour.spotlight',
+        },
+    },
+};
+export async function handleSpotlight(args) {
+    const target = args['target'];
+    if (typeof target !== 'string' || !target.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, 'target must be a non-empty string');
+    }
+    const message = args['message'];
+    if (message !== undefined && typeof message !== 'string') {
+        throw new McpError(ErrorCode.InvalidParams, 'message must be a string when present');
+    }
+    const pairId = getLinkedPairId();
+    if (!pairId) {
+        throw new McpError(ErrorCode.InvalidParams, 'No linked session. Call link_session with the pairing code first, or open runsnative.org and start the pairing flow.');
+    }
+    const commandArgs = [target.trim()];
+    if (typeof message === 'string' && message.trim())
+        commandArgs.push(message.trim());
+    const res = await postWorkerApi('/tenant/command', {
+        pair_id: pairId,
+        capability: 'tour',
+        method: 'spotlight',
+        args: commandArgs,
+    });
+    if (res.status === 404) {
+        throw new McpError(ErrorCode.InvalidParams, 'Linked session not found or expired. Re-link with link_session.');
+    }
+    if (res.status === 422) {
+        const body = (await res.json().catch(() => ({})));
+        throw new McpError(ErrorCode.InvalidParams, body.error ?? 'Command rejected by allow-list.');
+    }
+    if (res.status === 409) {
+        throw new McpError(ErrorCode.InvalidParams, 'No live tab detected. Open runsnative.org, ensure the tab is active, then retry.');
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new McpError(ErrorCode.InternalError, `Worker error ${res.status}: ${body}`);
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Spotlight command enqueued for "${target.trim()}". The tab will settle the ring within one poll interval.`,
+            },
+        ],
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runsnative/mcp-server",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "type": "module",
   "files": [
     "dist/"