@runsnative/mcp-server 0.5.1 → 0.7.0

package/dist/surface/marker-card.js

@@ -0,0 +1,245 @@
+/**
+ * The marker-card MCP App shell (JUNE-623) — the lasso round-trip finale.
+ *
+ * Fourth consumer of the JUNE-618 packaging seam (see gathering-card.ts for
+ * the first). Static shell: no per-call data is baked in. The host delivers
+ * the tool result (the capture's structural head) via the MCP Apps
+ * tool-result notification; the app script below renders the card
+ * client-side with DOM APIs (textContent only — a user-authored `note` can
+ * never parse as markup).
+ *
+ * Push→pull inversion (JUNE-623 comment 1, founder-normative): the pixel
+ * crop is NOT inlined in the tool result. The thumbnail slot starts empty;
+ * "Show the pixels" fetches it on demand via fetch_marker_crop.
+ */
+import { packageSurface } from './package-surface.js';
+export const MARKER_CARD_URI = 'ui://runsnative/marker-card.html';
+const CARD_CSS = `
+@layer rn-shell, primitives, semantics, themes;
+@layer rn-shell {
+  :root {
+    --run-color-text-primary: #1e293b;
+    --run-color-text-secondary: #64748b;
+    --run-color-surface-default: #ffffff;
+    --run-color-surface-subtle: #f8fafc;
+    --run-color-surface-canvas: transparent;
+    --run-color-border-default: #e2e8f0;
+    --run-color-focus-ring: #2563eb;
+    --run-font-size-s: 14px;
+    --run-font-size-m: 16px;
+  }
+}
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  color: var(--run-color-text-primary);
+  background: var(--run-color-surface-canvas);
+  padding: 12px;
+}
+.marker-card {
+  max-width: 440px;
+  border: 1px solid var(--run-color-border-default);
+  border-radius: 12px;
+  background: var(--run-color-surface-default);
+  padding: 20px;
+  display: none;
+  flex-direction: column;
+  gap: 10px;
+}
+.marker-card.is-ready { display: flex; }
+.card-inputs {
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 12px;
+  color: var(--run-color-text-secondary);
+  background: var(--run-color-surface-subtle);
+  border-radius: 6px;
+  padding: 8px 10px;
+  overflow-wrap: anywhere;
+}
+.card-thumb {
+  display: none;
+  max-width: 100%;
+  border-radius: 8px;
+  border: 1px solid var(--run-color-border-default);
+}
+.card-thumb.is-shown { display: block; }
+.card-actions { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; margin-top: 4px; }
+.card-change-row { display: none; align-items: center; gap: 8px; }
+.card-change-row.is-shown { display: flex; }
+.card-status { font-size: 12px; color: var(--run-color-text-secondary); min-height: 1.2em; }
+#placeholder { font-size: 13px; color: var(--run-color-text-secondary); padding: 8px 2px; }
+`;
+const CARD_BODY = `
+<div id="placeholder">Waiting for the region you circled…</div>
+<article class="marker-card" id="card">
+  <run-text variant="label" as="span" size="sm" color="secondary">You circled this</run-text>
+  <run-text id="card-type" variant="title" as="h3" size="md"></run-text>
+  <run-text id="card-note" variant="body" as="p" size="sm" color="secondary"></run-text>
+  <pre class="card-inputs" id="card-inputs"></pre>
+  <img class="card-thumb" id="card-thumb" alt="The region you circled" />
+  <div class="card-actions">
+    <run-button id="spotlight-btn" variant="primary" size="sm">Show me where this is</run-button>
+    <run-button id="whatis-btn" variant="secondary" size="sm">What is this?</run-button>
+    <run-button id="pixels-btn" variant="secondary" size="sm">Show the pixels</run-button>
+  </div>
+  <div class="card-change-row" id="change-row">
+    <select id="variant-select">
+      <option value="primary">primary</option>
+      <option value="secondary">secondary</option>
+      <option value="outline">outline</option>
+      <option value="ghost">ghost</option>
+      <option value="danger">danger</option>
+      <option value="link">link</option>
+    </select>
+    <run-button id="change-btn" variant="outline" size="sm">Change it</run-button>
+  </div>
+  <div class="card-status" id="card-status"></div>
+</article>
+`;
+// Static, data-free by design — see gathering-card.ts for the rationale this
+// mirrors: everything user-authored arrives at runtime via the tool-result
+// notification and is assigned with textContent, never interpolated here.
+const CARD_APP_SCRIPT = `
+const { App } = globalThis.__MCP_APP_SDK__;
+
+let currentCapture = null;
+
+function setText(id, value) {
+  document.getElementById(id).textContent = value == null ? '' : String(value);
+}
+
+function render(payload) {
+  const capture = payload && payload.capture;
+  if (!capture) return;
+  currentCapture = capture;
+  const card = document.getElementById('card');
+  const address = capture.address || {};
+
+  setText('card-type', address.type || 'Unknown component');
+  setText('card-note', capture.note || '');
+  document.getElementById('card-inputs').textContent =
+    JSON.stringify(capture.inputs || {}, null, 2);
+
+  // "Change it" is JUNE-512's write surface — run-button only. Omit the
+  // control entirely for other types rather than shipping a button that 422s.
+  const changeRow = document.getElementById('change-row');
+  changeRow.classList.toggle('is-shown', address.type === 'run-button');
+
+  document.getElementById('pixels-btn').disabled = !capture.has_crop;
+
+  document.getElementById('placeholder').style.display = 'none';
+  card.classList.add('is-ready');
+}
+
+const app = new App({ name: 'runsnative-marker-card', version: '1.0.0' }, {});
+
+// Register before connect() so no notification is missed.
+app.ontoolresult = (params) => {
+  if (params && params.isError) {
+    setText('placeholder', 'Could not load the marker capture — see the conversation for details.');
+    return;
+  }
+  render(params && params.structuredContent);
+};
+
+document.getElementById('spotlight-btn').addEventListener('click', async () => {
+  const status = document.getElementById('card-status');
+  const address = currentCapture && currentCapture.address;
+  const instanceId = address && address.instanceId;
+  if (!instanceId) {
+    status.textContent = 'This capture has no addressable instance.';
+    return;
+  }
+  status.textContent = 'Pointing your tab at the element you circled…';
+  try {
+    const result = await app.callServerTool({
+      name: 'spotlight',
+      arguments: { target: 'instance:' + instanceId, message: "Here's the element you circled." },
+    });
+    status.textContent = result && result.isError
+      ? 'No linked tab — open runsnative.org to see it live.'
+      : 'Watch your linked tab — the ring is landing on the element.';
+  } catch (e) {
+    status.textContent = 'No linked tab — open runsnative.org to see it live.';
+  }
+});
+
+document.getElementById('whatis-btn').addEventListener('click', async () => {
+  const status = document.getElementById('card-status');
+  const address = currentCapture && currentCapture.address;
+  if (!address || !address.type) {
+    status.textContent = 'No component type on this capture.';
+    return;
+  }
+  status.textContent = 'Asking about ' + address.type + '…';
+  try {
+    const result = await app.callServerTool({ name: 'get_component', arguments: { name: address.type } });
+    status.textContent = result && result.isError
+      ? 'Could not look up that component.'
+      : 'See the conversation for ' + address.type + \"'s contract.\";
+  } catch (e) {
+    status.textContent = 'Could not look up that component.';
+  }
+});
+
+document.getElementById('pixels-btn').addEventListener('click', async () => {
+  const status = document.getElementById('card-status');
+  if (!currentCapture || !currentCapture.has_crop) {
+    status.textContent = 'No pixels were captured for this region.';
+    return;
+  }
+  status.textContent = 'Fetching the pixels…';
+  try {
+    const result = await app.callServerTool({
+      name: 'fetch_marker_crop',
+      arguments: { capture_id: currentCapture.capture_id },
+    });
+    const block = result && Array.isArray(result.content)
+      ? result.content.find((c) => c.type === 'image')
+      : null;
+    if (result && result.isError || !block) {
+      status.textContent = 'Could not fetch the pixels — they may have expired.';
+      return;
+    }
+    const thumb = document.getElementById('card-thumb');
+    thumb.src = 'data:' + (block.mimeType || 'image/png') + ';base64,' + block.data;
+    thumb.classList.add('is-shown');
+    status.textContent = '';
+  } catch (e) {
+    status.textContent = 'Could not fetch the pixels — they may have expired.';
+  }
+});
+
+document.getElementById('change-btn').addEventListener('click', async () => {
+  const status = document.getElementById('card-status');
+  const address = currentCapture && currentCapture.address;
+  const instanceId = address && address.instanceId;
+  if (!instanceId) {
+    status.textContent = 'This capture has no addressable instance.';
+    return;
+  }
+  const variant = document.getElementById('variant-select').value;
+  status.textContent = 'Sending ' + variant + ' to your tab…';
+  try {
+    const result = await app.callServerTool({
+      name: 'set_instance_variant',
+      arguments: { instance_id: instanceId, variant: variant },
+    });
+    status.textContent = result && result.isError
+      ? 'No linked tab — open runsnative.org to try it live.'
+      : 'Watch your linked tab — the button is switching to ' + variant + '.';
+  } catch (e) {
+    status.textContent = 'No linked tab — open runsnative.org to try it live.';
+  }
+});
+
+await app.connect();
+`;
+export function buildMarkerCardHtml(assets) {
+    return packageSurface({
+        title: 'The region you circled',
+        bodyHtml: CARD_BODY,
+        css: CARD_CSS,
+        appScript: CARD_APP_SCRIPT,
+    }, assets);
+}

package/dist/tools/apply-inferred-theme.js

@@ -19,11 +19,11 @@ export const APPLY_INFERRED_THEME_TOOL = {
         },
         required: ['brief'],
     },
-    // LSP §5.1 — session-targeting; the first entitlement:'paid' capability on
-    // the bridge (JUNE-650). `enactment` names the worker allow-list entry the
-    // command leg submits after the paid inference leg succeeds.
+    // Copresence Protocol §5.1 — session-targeting; the first entitlement:'paid'
+    // capability on the bridge (JUNE-650). `enactment` names the worker
+    // allow-list entry the command leg submits after the paid inference leg succeeds.
     _meta: {
-        lsp: {
+        copresence: {
             target: 'session',
             tier: 'reversible',
             consent: 'implicit',

package/dist/tools/fetch-marker-crop.js

@@ -0,0 +1,67 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { getWorkerApi, getLinkedPairId } from '../bridge-client.js';
+export const FETCH_MARKER_CROP_TOOL = {
+    name: 'fetch_marker_crop',
+    description: 'Fetch the pixel crop for a marker capture, on demand (JUNE-623 push→pull inversion). ' +
+        'render_marker_capture and get_marker_capture deliver the structural head only — call this when the ' +
+        'user\'s complaint is visual (a gap, alignment, or render fidelity issue that a component-instance ' +
+        'address alone cannot answer). Requires an active linked session; the crop must still be within its ' +
+        'capture window (~15 minutes) or this returns not-found.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            capture_id: {
+                type: 'string',
+                description: 'The capture_id from a marker-capture head (get_marker_capture or render_marker_capture).',
+            },
+        },
+        required: ['capture_id'],
+    },
+    // Copresence Protocol §5.1 (copresence-protocol-v0.1, mukadra repo) — a
+    // session-targeting READ leg like get_marker_capture: it drains a stored
+    // resource rather than enacting a command, so no allow-list `enactment`.
+    _meta: {
+        copresence: {
+            target: 'session',
+            tier: 'reversible',
+            consent: 'implicit',
+            entitlement: 'free',
+            visibility: 'advertised',
+        },
+    },
+};
+export async function handleFetchMarkerCrop(args) {
+    const captureId = args['capture_id'];
+    if (typeof captureId !== 'string' || !captureId.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, 'capture_id 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 getWorkerApi(`/session/${pairId}/captures/${encodeURIComponent(captureId.trim())}/crop`);
+    if (res.status === 404) {
+        throw new McpError(ErrorCode.InvalidParams, 'Crop not found — it may have expired, or the linked session was re-linked. Re-circle the region if you still need it.');
+    }
+    if (res.status === 410) {
+        throw new McpError(ErrorCode.InvalidParams, 'Linked session revoked or expired. Re-link with link_session.');
+    }
+    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 buffer = await res.arrayBuffer();
+    const bytes = new Uint8Array(buffer);
+    let binary = '';
+    const CHUNK = 0x8000;
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+    }
+    const b64 = btoa(binary);
+    return {
+        content: [{ type: 'image', data: b64, mimeType: 'image/png' }],
+    };
+}

package/dist/tools/get-marker-capture.js

@@ -1,24 +1,25 @@
 import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import { getWorkerApi, getLinkedPairId } from '../bridge-client.js';
-const CROP_PREFIX = 'data:image/png;base64,';
 export const GET_MARKER_CAPTURE_TOOL = {
     name: 'get_marker_capture',
     description: 'Fetch pending marker captures from the linked runsnative.org tab — regions the user circled ' +
         'with the marker overlay. Use when the user says they marked, circled, or pointed at something ' +
         'on the site, or asks "can you see what I selected?". Each capture carries the resolved ' +
-        'component-instance address (usable with set_instance_variant), its render inputs, an optional ' +
-        'user note, and the pixel crop as an image so you see exactly what they saw. Single delivery: a ' +
-        'capture is returned once. Requires an active linked session (call link_session first).',
+        'component-instance address (usable with set_instance_variant), its render inputs, and an ' +
+        'optional user note — the structural head only (JUNE-623 push→pull inversion). Pixels are NOT ' +
+        'inlined: when `has_crop` is true and the complaint is visual (not structural), call ' +
+        'fetch_marker_crop with the capture_id to see the region. Single delivery: a capture head is ' +
+        'returned once. Requires an active linked session (call link_session first).',
     inputSchema: {
         type: 'object',
         properties: {},
     },
-    // LSP §5.1 (linked-session-protocol-v0.1, mukadra repo) — session-targeting,
-    // but the READ leg of the bridge: it drains the session's capture queue
-    // rather than enacting a command, so there is no allow-list `enactment`
-    // (the field is optional per §5.1).
+    // Copresence Protocol §5.1 (copresence-protocol-v0.1, mukadra repo) —
+    // session-targeting, but the READ leg of the bridge: it drains the
+    // session's capture queue rather than enacting a command, so there is no
+    // allow-list `enactment` (the field is optional per §5.1).
     _meta: {
-        lsp: {
+        copresence: {
             target: 'session',
             tier: 'reversible',
             consent: 'implicit',
@@ -68,18 +69,9 @@ export async function handleGetMarkerCapture(_args) {
                 inputs: cap.inputs,
                 note: cap.note,
                 created_at: cap.created_at,
+                has_crop: cap.has_crop,
             }, null, 2),
         });
-        // The pixel crop is co-equal with the structural address (design doc
-        // §3.4) — deliver it as an image block so the agent SEES the region,
-        // not a reference to it.
-        if (cap.crop && cap.crop.startsWith(CROP_PREFIX)) {
-            content.push({
-                type: 'image',
-                data: cap.crop.slice(CROP_PREFIX.length),
-                mimeType: 'image/png',
-            });
-        }
     }
     if (data.truncated) {
         content.push({

package/dist/tools/navigate.js

@@ -14,11 +14,11 @@ export const NAVIGATE_TOOL = {
         },
         required: ['path'],
     },
-    // 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/render-marker-capture.js

@@ -0,0 +1,83 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { getWorkerApi, getLinkedPairId } from '../bridge-client.js';
+import { componentsBundle, iframeRuntime } from '../surface/assets.js';
+import { buildMarkerCardHtml, MARKER_CARD_URI } from '../surface/marker-card.js';
+import { SURFACE_MIME_TYPE } from '../surface/package-surface.js';
+export const RENDER_MARKER_CAPTURE_TOOL = {
+    name: 'render_marker_capture',
+    description: "Render the user's most recent marker capture — a region they circled with the marker overlay on " +
+        'the linked runsnative.org tab — as a live MCP App card in this conversation (JUNE-623). The card is ' +
+        'a HANDLE, not a picture: it carries live actions targeting the captured instance ("Show me where " +' +
+        '"this is", "Change it", "What is this?"), plus an on-demand pixel fetch. Use when the user says they ' +
+        'circled or marked something and you want to hand them (and yourself) a live surface instead of raw ' +
+        'JSON. Requires an active linked session (call link_session first).',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        required: [],
+    },
+    _meta: {
+        ui: { resourceUri: MARKER_CARD_URI },
+        // Legacy key for hosts predating _meta.ui (ext-apps compatibility shim).
+        'ui/resourceUri': MARKER_CARD_URI,
+    },
+};
+export const MARKER_CARD_RESOURCE = {
+    uri: MARKER_CARD_URI,
+    name: 'Marker Capture Card',
+    description: 'Self-contained MCP App shell that renders a marker capture as a live RunsNative card with ' +
+        'spotlight/change/introspect actions. The pixel crop is fetched on demand, never inlined.',
+    mimeType: SURFACE_MIME_TYPE,
+};
+export async function readMarkerCardResource() {
+    const html = buildMarkerCardHtml({
+        componentsBundle: componentsBundle(),
+        iframeRuntime: iframeRuntime(),
+    });
+    return {
+        contents: [{ uri: MARKER_CARD_URI, mimeType: SURFACE_MIME_TYPE, text: html }],
+    };
+}
+export async function handleRenderMarkerCapture() {
+    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 getWorkerApi(`/session/${pairId}/captures`);
+    if (res.status === 404) {
+        throw new McpError(ErrorCode.InvalidParams, 'Linked session not found or expired. Re-link with link_session.');
+    }
+    if (res.status === 410) {
+        throw new McpError(ErrorCode.InvalidParams, 'Linked session revoked or expired. Re-link with link_session.');
+    }
+    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 data = (await res.json());
+    const captures = data.captures ?? [];
+    if (captures.length === 0) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'No pending marker captures. Ask the user to arm the marker overlay and circle a region on the linked tab.',
+                },
+            ],
+        };
+    }
+    // Head endpoint returns oldest-first — the most recent pending capture is last.
+    const capture = captures[captures.length - 1];
+    return {
+        content: [
+            {
+                type: 'text',
+                text: 'Rendered the region the user circled as a live card in the conversation.',
+            },
+        ],
+        structuredContent: { capture },
+    };
+}