@runsnative/mcp-server 0.6.0 → 0.7.0

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-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/package.json

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