@runsnative/mcp-server 0.5.1 → 0.6.0

package/dist/server.js

@@ -21,6 +21,7 @@ import { SET_THEME_TOOL, handleSetTheme } from './tools/set-theme.js';
 import { APPLY_INFERRED_THEME_TOOL, handleApplyInferredTheme } from './tools/apply-inferred-theme.js';
 import { NAVIGATE_TOOL, handleNavigate } from './tools/navigate.js';
 import { SET_INSTANCE_VARIANT_TOOL, handleSetInstanceVariant } from './tools/set-instance-variant.js';
+import { SPOTLIGHT_TOOL, handleSpotlight } from './tools/spotlight.js';
 import { GET_MARKER_CAPTURE_TOOL, handleGetMarkerCapture } from './tools/get-marker-capture.js';
 import { createProvider } from './provider.js';
 import { RemoteContentProvider } from './remote-provider.js';
@@ -64,6 +65,7 @@ export async function createRunsnativeServer() {
             APPLY_INFERRED_THEME_TOOL,
             NAVIGATE_TOOL,
             SET_INSTANCE_VARIANT_TOOL,
+            SPOTLIGHT_TOOL,
             GET_MARKER_CAPTURE_TOOL,
         ],
     }));
@@ -107,6 +109,8 @@ export async function createRunsnativeServer() {
                 return handleNavigate(request.params.arguments ?? {});
             case 'set_instance_variant':
                 return handleSetInstanceVariant(request.params.arguments ?? {});
+            case 'spotlight':
+                return handleSpotlight(request.params.arguments ?? {});
             case 'get_marker_capture':
                 return handleGetMarkerCapture(request.params.arguments ?? {});
             default:

package/dist/surface/gathering-card.js

@@ -72,6 +72,7 @@ const CARD_BODY = `
   </div>
   <div class="card-actions">
     <run-button id="view-btn" variant="primary" size="sm">View on Convene</run-button>
+    <run-button id="show-me-btn" variant="secondary" size="sm">Show me where</run-button>
   </div>
   <div class="card-status" id="card-status"></div>
 </article>
@@ -86,6 +87,17 @@ const { App } = globalThis.__MCP_APP_SDK__;
 const BRAND_ID = /^[a-z0-9][a-z0-9-]*$/;
 const ACCENT_HEX = /^#[0-9a-fA-F]{3,8}$/;
 
+// The current gathering's spotlight anchor, captured at render. The anchor
+// mirrors the data-tour="gathering-<id>" the Convene page (compare.js) puts on
+// each card. Sanitized to the safe attribute/URL charset so a hostile id can
+// never break out of the anchor or the deep-link query.
+let spotlightAnchor = null;
+
+function anchorFor(id) {
+  const safe = String(id == null ? '' : id).replace(/[^A-Za-z0-9_-]/g, '');
+  return safe ? 'gathering-' + safe : null;
+}
+
 function setText(id, value) {
   document.getElementById(id).textContent = value == null ? '' : String(value);
 }
@@ -94,6 +106,7 @@ function render(payload) {
   const g = payload && payload.gathering;
   if (!g) return;
   const card = document.getElementById('card');
+  spotlightAnchor = anchorFor(g.id);
 
   // Theme: landed brands get their token-engine CSS (scoped to
   // :where([data-run-theme="X"])); everything else falls back to the accent.
@@ -150,6 +163,32 @@ document.getElementById('view-btn').addEventListener('click', async () => {
   }
 });
 
+// Deixis (JUNE-621): point the linked tab at THIS gathering — navigate to
+// Convene and settle the spotlight ring on the user's own card. When no tab is
+// linked, degrade to a shareable "spotlight link" (independently valuable, the
+// same deep link a human hands another human).
+document.getElementById('show-me-btn').addEventListener('click', async () => {
+  const status = document.getElementById('card-status');
+  if (!spotlightAnchor) {
+    status.textContent = 'This gathering has no addressable anchor yet.';
+    return;
+  }
+  const target = '/compare/#' + spotlightAnchor;
+  const deepLink = 'https://runsnative.org/compare/?spotlight=' + encodeURIComponent(spotlightAnchor);
+  status.textContent = 'Pointing your tab at your gathering…';
+  try {
+    const result = await app.callServerTool({
+      name: 'spotlight',
+      arguments: { target: target, message: 'Here it is — your gathering, live on Convene.' },
+    });
+    status.textContent = result && result.isError
+      ? 'No linked tab — open your spotlight link: ' + deepLink
+      : 'Watch your linked tab — the ring is landing on your gathering.';
+  } catch (e) {
+    status.textContent = 'No linked tab — open your spotlight link: ' + deepLink;
+  }
+});
+
 await app.connect();
 `;
 export function buildGatheringCardHtml(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/get-marker-capture.js

@@ -13,12 +13,12 @@ export const GET_MARKER_CAPTURE_TOOL = {
         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',

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/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-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.6.0",
   "type": "module",
   "files": [
     "dist/"