@runsnative/mcp-server 0.8.1 → 0.9.0

package/README.md

@@ -75,6 +75,8 @@ Paste that URL into Claude's "Add custom skill" dialog, or add it to your agent'
 | `link_session` | Pair the agent with a logged-in runsnative.org tab (consent-gated) |
 | `navigate` / `set_theme` | Drive the linked tab: change routes, switch themes |
 | `set_instance_variant` | Change a component instance in the linked tab by marker-capture handle |
+| `resolve_target` | Resolve a natural-language description ("language switcher") to live spotlight targets in the linked tab (JUNE-1257) |
+| `spotlight` | Settle a spotlight ring on a target in the linked tab — a `data-tour` contract anchor or a `resolve_target`/marker `instance:<handle>` (JUNE-621) |
 | `get_marker_capture` | Receive regions circled with the marker overlay — structural head only, pixels not inlined |
 | `render_marker_capture` | Render the most recent marker capture as a live MCP App card with spotlight/change/introspect actions (JUNE-623) |
 | `fetch_marker_crop` | Fetch a marker capture's pixel crop on demand — the lazy-pixel pull |

package/dist/server.js

@@ -27,6 +27,7 @@ import { handleApplyInferredTheme } from './tools/apply-inferred-theme.js';
 import { handleNavigate } from './tools/navigate.js';
 import { handleSetInstanceVariant } from './tools/set-instance-variant.js';
 import { handleSpotlight } from './tools/spotlight.js';
+import { handleResolveTarget } from './tools/resolve-target.js';
 // Session-enact tools register via the single-source list (JUNE-739) so the
 // registration surface and the reconciliation tests read the same array.
 import { SESSION_ENACT_TOOLS } from './tools/session-tools.js';
@@ -136,6 +137,8 @@ export async function createRunsnativeServer() {
                 return handleSetInstanceVariant(request.params.arguments ?? {});
             case 'spotlight':
                 return handleSpotlight(request.params.arguments ?? {});
+            case 'resolve_target':
+                return handleResolveTarget(request.params.arguments ?? {});
             case 'get_marker_capture':
                 return handleGetMarkerCapture(request.params.arguments ?? {});
             case 'render_marker_capture':

package/dist/tools/resolve-target.js

@@ -0,0 +1,161 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { postWorkerApi, getWorkerApi, getLinkedPairId } from '../bridge-client.js';
+/**
+ * resolve_target (JUNE-1257) — the resolution step in front of `spotlight`.
+ *
+ * The linked tab resolves the description against its LIVE document (the
+ * data-run-instance registry plus raw interactive elements) and answers with
+ * scored candidates over the command-result return leg. This tool then hands
+ * the agent `instance:<handle>` strings that `spotlight` accepts as-is.
+ *
+ * Loud-failure contract (the ticket's acceptance): no-match, tab-timeout,
+ * and in-tab errors all surface as McpError — never as success-shaped text.
+ */
+// The tab polls its command queue every 5s; one full cycle plus dispatch and
+// ack comfortably fits in two poll windows. 8 × 2s keeps the worst case ~16s.
+const RESULT_POLL_ATTEMPTS = 8;
+const RESULT_POLL_INTERVAL_MS = 2000;
+export const RESOLVE_TARGET_TOOL = {
+    name: 'resolve_target',
+    description: "Find where something is on the user's linked runsnative.org tab from a natural-language description — " +
+        'the resolution step in front of `spotlight` for targets that have no pre-authored anchor (most of the ' +
+        'site). Pass a concise noun phrase naming the UI element in the words a label would use ("language ' +
+        'switcher", "changelog link", "search button") — not a whole question. Returns scored candidates, each ' +
+        'with an `instance:<handle>` target string; pick the best match (the signals tell you what each one is) ' +
+        'and pass its target to `spotlight`. Candidates resolve against the live page, so resolve and spotlight ' +
+        'in the same breath — handles do not survive navigation. Requires an active linked session ' +
+        '(call link_session first).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            description: {
+                type: 'string',
+                description: 'What to find, as a short descriptive phrase in the words the UI itself would use ' +
+                    '("language switcher", "changelog link"). Max 200 characters.',
+            },
+            limit: {
+                type: 'number',
+                description: 'Maximum candidates to return (1-10, default 5).',
+            },
+        },
+        required: ['description'],
+    },
+    // Copresence Protocol §5.1 — session-targeting capability. Read-only in
+    // effect (nothing mutated, nothing shown), tier stays 'reversible': the
+    // protocol has no lower tier, and resolution is strictly weaker than the
+    // spotlight it precedes.
+    _meta: {
+        copresence: {
+            target: 'session',
+            tier: 'reversible',
+            consent: 'implicit',
+            entitlement: 'free',
+            visibility: 'advertised',
+            enactment: 'tour.resolveTarget',
+        },
+    },
+};
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function formatCandidate(c, index) {
+    const signals = [`<${c.tag}>`];
+    if (c.aria)
+        signals.push(`aria-label: "${c.aria}"`);
+    if (c.text)
+        signals.push(`text: "${c.text}"`);
+    if (c.id)
+        signals.push(`id: ${c.id}`);
+    if (c.icon)
+        signals.push(`icon: ${c.icon}`);
+    if (c.href)
+        signals.push(`href: ${c.href}`);
+    return `${index + 1}. ${c.target}\n   ${signals.join(' · ')} · score ${c.score}`;
+}
+export async function handleResolveTarget(args) {
+    const description = args['description'];
+    if (typeof description !== 'string' || !description.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, 'description must be a non-empty string');
+    }
+    if (description.length > 200) {
+        throw new McpError(ErrorCode.InvalidParams, 'description must be at most 200 characters');
+    }
+    const limit = args['limit'];
+    if (limit !== undefined && (typeof limit !== 'number' || !Number.isInteger(limit) || limit < 1 || limit > 10)) {
+        throw new McpError(ErrorCode.InvalidParams, 'limit must be an integer between 1 and 10 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 = [description.trim()];
+    if (limit !== undefined)
+        commandArgs.push(limit);
+    const res = await postWorkerApi('/tenant/command', {
+        pair_id: pairId,
+        capability: 'tour',
+        method: 'resolveTarget',
+        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}`);
+    }
+    const { command_id: commandId } = (await res.json());
+    if (!commandId) {
+        throw new McpError(ErrorCode.InternalError, 'Worker accepted the command but returned no command_id to poll.');
+    }
+    const waitedSeconds = Math.round((RESULT_POLL_ATTEMPTS * RESULT_POLL_INTERVAL_MS) / 1000);
+    for (let attempt = 0; attempt < RESULT_POLL_ATTEMPTS; attempt++) {
+        await sleep(RESULT_POLL_INTERVAL_MS);
+        const poll = await getWorkerApi(`/tenant/command/${commandId}/result`);
+        if (!poll.ok) {
+            const body = await poll.text().catch(() => '');
+            throw new McpError(ErrorCode.InternalError, `Worker error ${poll.status} while polling for the result: ${body}`);
+        }
+        const payload = (await poll.json());
+        if (payload.status === 'pending')
+            continue;
+        if (payload.status === 'expired') {
+            throw new McpError(ErrorCode.InternalError, 'The linked tab never picked the command up before it expired. The tab may be closed or backgrounded — bring runsnative.org to the front and retry.');
+        }
+        if (payload.status === 'no_result') {
+            throw new McpError(ErrorCode.InternalError, 'The page acknowledged the command but attached no result — the site build likely predates resolve_target support. The site needs a rebuild before this tool can work against it.');
+        }
+        // status === 'done'
+        const result = payload.result ?? {};
+        if (result.status === 'error') {
+            throw new McpError(ErrorCode.InternalError, `The page failed to resolve the description: ${result.error ?? 'unknown error'}`);
+        }
+        if (result.status === 'no_match') {
+            throw new McpError(ErrorCode.InvalidParams, `No element on the current page matched "${description.trim()}" (${result.scanned ?? '?'} elements scanned). ` +
+                'Try different words — ideally the ones the UI label itself uses — or navigate to the page the element lives on first.');
+        }
+        const candidates = result.candidates ?? [];
+        if (result.status !== 'ok' || candidates.length === 0) {
+            throw new McpError(ErrorCode.InternalError, `The page returned an unrecognized resolution result: ${JSON.stringify(result).slice(0, 300)}`);
+        }
+        const lines = candidates.map(formatCandidate);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Resolved "${description.trim()}" to ${candidates.length} candidate(s) on the current page:\n\n` +
+                        `${lines.join('\n')}\n\n` +
+                        'Pick the best match and pass its target string to `spotlight` now — instance handles are live-page state and do not survive navigation.',
+                },
+            ],
+        };
+    }
+    throw new McpError(ErrorCode.InternalError, `The linked tab did not answer within ~${waitedSeconds}s. It may be closed, backgrounded, or on a slow connection — bring runsnative.org to the front and retry.`);
+}

package/dist/tools/session-tools.js

@@ -22,6 +22,7 @@ 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';
+import { RESOLVE_TARGET_TOOL } from './resolve-target.js';
 export const SESSION_ENACT_TOOLS = [
     SET_THEME_TOOL,
     SET_SKIN_TOOL,
@@ -31,6 +32,7 @@ export const SESSION_ENACT_TOOLS = [
     NAVIGATE_TOOL,
     SET_INSTANCE_VARIANT_TOOL,
     SPOTLIGHT_TOOL,
+    RESOLVE_TARGET_TOOL,
 ];
 /** The `capability.method` allow-list entries this tool set can enact. */
 export function listSessionEnactments() {

package/package.json

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