@runsnative/mcp-server 0.2.0 → 0.4.0

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

@@ -4,13 +4,28 @@ 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. Each capture carries the resolved component-instance address, its ' +
-        'render inputs, an optional user note, and the pixel crop as an image. Single delivery: a ' +
-        'capture is returned once. Requires an active linked session (link_session first).',
+        '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).',
     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).
+    _meta: {
+        lsp: {
+            target: 'session',
+            tier: 'reversible',
+            consent: 'implicit',
+            entitlement: 'free',
+            visibility: 'advertised',
+        },
+    },
 };
 export async function handleGetMarkerCapture(_args) {
     const pairId = getLinkedPairId();

package/dist/tools/navigate.js

@@ -2,8 +2,11 @@ import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import { postWorkerApi, getLinkedPairId } from '../bridge-client.js';
 export const NAVIGATE_TOOL = {
     name: 'navigate',
-    description: 'Navigate the linked runsnative.org tab to a path. Slash shim: /rn-go <path>. ' +
-        'Reversible — the user can navigate back. Requires an active linked session (link_session first).',
+    description: "Send the user's linked runsnative.org tab to a different page. Use when the user asks to see, open, or go to " +
+        'something on the site — a component page, a docs section, the gallery — so they watch their own tab move ' +
+        'instead of following a pasted link. The command is enqueued and the tab navigates within one poll interval. ' +
+        'Reversible — the user can navigate back. Requires an active linked session (call link_session first). ' +
+        'Slash shim: /rn-go <path>.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -11,6 +14,19 @@ 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).
+    _meta: {
+        lsp: {
+            target: 'session',
+            tier: 'reversible',
+            consent: 'implicit',
+            entitlement: 'free',
+            visibility: 'advertised',
+            enactment: 'navigation.navigate',
+        },
+    },
 };
 export async function handleNavigate(args) {
     const path = args['path'];

package/dist/tools/render-gathering.js

@@ -0,0 +1,88 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { getWorkerApi } from '../bridge-client.js';
+import { componentsBundle, iframeRuntime, themeCss } from '../surface/assets.js';
+import { buildGatheringCardHtml, GATHERING_CARD_URI } from '../surface/gathering-card.js';
+import { SURFACE_MIME_TYPE } from '../surface/package-surface.js';
+// Display labels for the brands offered by the create-gathering form
+// (compare.js). Unknown brand_ids fall back to the id itself client-side.
+const BRAND_LABELS = {
+    'dotorg-site': 'RunsNative',
+    'harlow-pets': 'Harlow Pets',
+    'clay-studio': 'Kiln & Clay Studio',
+};
+export const RENDER_GATHERING_TOOL = {
+    name: 'render_gathering',
+    description: "Render the user's most recent Convene gathering as a live, branded, interactive card " +
+        'inside this conversation (an MCP App surface — real run-* components, the tenant\'s own ' +
+        'theme, a working View action). Use as the finale of the create-a-gathering exercise, ' +
+        'right after the user has created their gathering on the site. Requires the tenant ' +
+        'API token (RUNSNATIVE_TENANT_TOKEN) so the gathering can be fetched from the tenant store.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        required: [],
+    },
+    _meta: {
+        ui: { resourceUri: GATHERING_CARD_URI },
+        // Legacy key for hosts predating _meta.ui (ext-apps compatibility shim).
+        'ui/resourceUri': GATHERING_CARD_URI,
+    },
+};
+export const GATHERING_CARD_RESOURCE = {
+    uri: GATHERING_CARD_URI,
+    name: 'Gathering Card',
+    description: 'Self-contained MCP App shell that renders a Convene gathering as a branded RunsNative card. ' +
+        'Data arrives via the tool-result notification; nothing external is loaded.',
+    mimeType: SURFACE_MIME_TYPE,
+};
+export async function readGatheringCardResource() {
+    const html = buildGatheringCardHtml({
+        componentsBundle: componentsBundle(),
+        iframeRuntime: iframeRuntime(),
+    });
+    return {
+        contents: [{ uri: GATHERING_CARD_URI, mimeType: SURFACE_MIME_TYPE, text: html }],
+    };
+}
+export async function handleRenderGathering() {
+    const res = await getWorkerApi('/tenant/gatherings');
+    if (res.status === 401) {
+        throw new McpError(ErrorCode.InvalidParams, 'Not authenticated with the tenant store. Set RUNSNATIVE_TENANT_TOKEN in the MCP server ' +
+            'config (the same tenant the user signs into on the site — a linked session guarantees they match).');
+    }
+    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 gatherings = data.gatherings ?? [];
+    if (gatherings.length === 0) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'No gatherings found for this tenant yet. Create one first — on the Convene page ' +
+                        '(/compare/), sign in and submit the create-gathering form (exercise step 2) — then call this tool again.',
+                },
+            ],
+        };
+    }
+    // Rows arrive ORDER BY created_at DESC — the first is the most recent.
+    const gathering = gatherings[0];
+    const css = await themeCss(gathering.brand_id);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Rendered "${gathering.title}" (${gathering.brand_id}) as a live card in the conversation. ` +
+                    'The card is the real surface — same components and theme as the site, with a working View action.',
+            },
+        ],
+        structuredContent: {
+            gathering,
+            theme_css: css,
+            theme_landed: css !== null,
+            brand_label: BRAND_LABELS[gathering.brand_id] ?? null,
+        },
+    };
+}

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

@@ -4,9 +4,11 @@ import { postWorkerApi, getLinkedPairId } from '../bridge-client.js';
 const RUN_BUTTON_VARIANTS = ['primary', 'secondary', 'outline', 'ghost', 'danger', 'link'];
 export const SET_INSTANCE_VARIANT_TOOL = {
     name: 'set_instance_variant',
-    description: 'Change the variant of a specific run-button instance on the linked runsnative.org tab, ' +
-        'targeted by the instance_id captured via the marker overlay. Slash shim: /rn-set-variant. ' +
-        'Reversible — the user can switch back at any time. Requires an active linked session (link_session first).',
+    description: 'Restyle ONE specific run-button on the linked runsnative.org tab — the instance the user circled with the ' +
+        'marker overlay — leaving every other element untouched. Use after get_marker_capture hands you an ' +
+        'address.instanceId and the user wants that exact button tried in a different variant. The command is enqueued ' +
+        'and the tab applies it within one poll interval, if the instance is still on the page. Reversible — set it ' +
+        'back at any time. Requires an active linked session (call link_session first). Slash shim: /rn-set-variant.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -21,6 +23,19 @@ 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).
+    _meta: {
+        lsp: {
+            target: 'session',
+            tier: 'reversible',
+            consent: 'implicit',
+            entitlement: 'free',
+            visibility: 'advertised',
+            enactment: 'instance.setVariant',
+        },
+    },
 };
 export async function handleSetInstanceVariant(args) {
     const instanceId = args['instance_id'];

package/dist/tools/set-theme.js

@@ -2,8 +2,11 @@ import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import { postWorkerApi, getLinkedPairId } from '../bridge-client.js';
 export const SET_THEME_TOOL = {
     name: 'set_theme',
-    description: 'Apply a theme (color palette) to the linked runsnative.org tab. Slash shim: /rn-theme <theme>. ' +
-        'Reversible — the user can switch back at any time. Requires an active linked session (link_session first).',
+    description: "Restyle the user's linked runsnative.org tab with a named theme — colors, surfaces, and typography change live " +
+        'in their browser. Use when the user asks to change how the site looks, try a different brand feel, or compare ' +
+        'palettes. The command is enqueued and the tab applies it within one poll interval; nothing is saved — fully ' +
+        'reversible, switch again or back at any time. Requires an active linked session (call link_session first). ' +
+        'Slash shim: /rn-theme <theme>.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -11,6 +14,19 @@ 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).
+    _meta: {
+        lsp: {
+            target: 'session',
+            tier: 'reversible',
+            consent: 'implicit',
+            entitlement: 'free',
+            visibility: 'advertised',
+            enactment: 'theme.setTheme',
+        },
+    },
 };
 export async function handleSetTheme(args) {
     const theme = args['theme'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runsnative/mcp-server",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "files": [
     "dist/"
@@ -15,7 +15,7 @@
     "runsnative-mcp": "./dist/index.js"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && node scripts/build-iframe-runtime.mjs",
     "dev": "tsc --watch",
     "start": "node dist/index.js",
     "http-server": "node dist/http-server.js",
@@ -24,10 +24,13 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.7.4",
     "@modelcontextprotocol/sdk": "^1.0.0"
   },
   "devDependencies": {
+    "@runsnative/components": "^0.5.0",
     "@types/node": "^25.6.0",
+    "esbuild": "^0.25.0",
     "playwright": "^1.58.2",
     "sharp": "^0.33.0",
     "typescript": "^5.5.3",

package/dist/tools/surface-preview.js

@@ -1,36 +0,0 @@
-import { readFileSync } from 'node:fs';
-import { resolve, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-export const SURFACE_PREVIEW_TOOL = {
-    name: 'surface_preview',
-    description: 'Renders a RunsNative component fixture (run-table + run-button) inside an MCP App ' +
-        'iframe. Used to verify that RunsNative web components hydrate correctly in the claude.ai ' +
-        'MCP Apps sandbox. Returns HTML content. This tool exists for RUN-477 verification — ' +
-        'it is not a production surface.',
-    inputSchema: {
-        type: 'object',
-        properties: {},
-        required: [],
-    },
-};
-export function handleSurfacePreview() {
-    // Read fixture from the fixtures/ sibling dir at call time, not compile time,
-    // so hot-reloading the fixture doesn't require rebuilding the server.
-    // In dist/, __dirname resolves to dist/tools/; fixture is at ../../fixtures/.
-    const fixturePath = resolve(__dirname, '../../fixtures/surface-preview.html');
-    const html = readFileSync(fixturePath, 'utf8');
-    return {
-        content: [
-            {
-                type: 'resource',
-                resource: {
-                    uri: 'data:text/html;charset=utf-8,surface-preview',
-                    mimeType: 'text/html',
-                    text: html,
-                },
-            },
-        ],
-    };
-}