@runsnative/mcp-server 0.9.1 → 0.13.0

package/README.md

@@ -139,9 +139,11 @@ detour on top of the token cost.
 
 ## For RunsNative repo developers
 
-If you're working inside the RunsNative repo, use the `.mcp.json` at the repo root. It points at `packages/mcp-server/dist/index.js` directly and sets `RUNSNATIVE_CONTENT_ROOT` so you get live content from your working tree without hitting the cloud API.
+If you're working inside the RunsNative repo, use the `.mcp.json` at the repo root. It runs the launcher `tools/mcp/runsnative-mcp.mjs` and sets `RUNSNATIVE_CONTENT_ROOT` so you get live content from your working tree without hitting the cloud API.
 
-Build first:
+`dist/` is gitignored, so git worktrees never have one. The launcher serves this checkout's own `dist/index.js` when it exists, and otherwise the main checkout's (found via `git rev-parse --git-common-dir`). It refuses loudly — a failed MCP server at session start, with the reason in the MCP log — when there is no build, or when the build is older than a non-test file in its `src/` (a tool merged since would otherwise be silently missing). `RUNSNATIVE_MCP_ALLOW_STALE=1` serves a stale build anyway. It never builds for you (RUN-662).
+
+Build once, in the main checkout, and again after any `src/` change lands there:
 
 ```bash
 cd packages/mcp-server && npm run build

package/dist/bridge-client.js

@@ -3,10 +3,24 @@ let _linkedPairId = null;
 export function getLinkedPairId() { return _linkedPairId; }
 export function setLinkedPairId(id) { _linkedPairId = id; }
 export function clearLinkedPairId() { _linkedPairId = null; }
+/**
+ * Read an env var without assuming `process` exists (JUNE-1297).
+ *
+ * This module is reachable from surfaces that are NOT Node: the mcp-api-worker
+ * remote MCP endpoint binds the same `SESSION_ENACT_TOOLS` array the stdio
+ * server registers from — deliberately, so the two transports cannot advertise
+ * different verbs — and importing that array pulls this module in with it. A
+ * bare `process.env` at module scope would throw a ReferenceError while that
+ * graph loads on a runtime without `process`, taking the whole Worker down at
+ * boot, for values the Worker never reads. Behaviour under Node is unchanged.
+ */
+function readEnv(name) {
+    return typeof process === 'undefined' ? undefined : process.env[name];
+}
 // trim(): trailing whitespace from setx/cmd wrappers silently corrupts the
 // Authorization header (KUKAMANGA-wide env-read rule).
-const BASE_URL = (process.env['RUNSNATIVE_API_URL'] ?? 'https://api.runsnative.org/mcp').trim();
-const TOKEN = process.env['RUNSNATIVE_TENANT_TOKEN']?.trim();
+const BASE_URL = (readEnv('RUNSNATIVE_API_URL') ?? 'https://api.runsnative.org/mcp').trim();
+const TOKEN = readEnv('RUNSNATIVE_TENANT_TOKEN')?.trim();
 // Every worker path below is appended to BASE_URL verbatim ('/content',
 // '/pair/start', …), so BASE_URL must carry the '/mcp' prefix — which the default
 // above does. Pointing RUNSNATIVE_API_URL at the bare origin
@@ -18,7 +32,7 @@ const TOKEN = process.env['RUNSNATIVE_TENANT_TOKEN']?.trim();
 // set the bare origin, so a correctly-installed server failed every write and the
 // error gave no way to see why. Warn at startup instead of 404-ing silently later.
 // stderr only — stdout carries the MCP JSON-RPC frames and must not be polluted.
-if (process.env['RUNSNATIVE_API_URL'] && !/\/mcp\/?$/.test(BASE_URL)) {
+if (readEnv('RUNSNATIVE_API_URL') && !/\/mcp\/?$/.test(BASE_URL)) {
     process.stderr.write(`[runsnative-mcp] WARNING: RUNSNATIVE_API_URL is "${BASE_URL}", which does not end in "/mcp".\n` +
         `[runsnative-mcp] Worker requests will resolve to "${BASE_URL}/content" and 404.\n` +
         `[runsnative-mcp] Use "https://api.runsnative.org/mcp", or unset the variable to take the default.\n`);

package/dist/content.js

@@ -2,6 +2,7 @@ import { readFile, readdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isListed, discoveryFields } from './discovery.js';
 const VALID_TABS = ['usage', 'style', 'code', 'accessibility'];
 // Content store roots. fileURLToPath handles Windows drive letters correctly
 // (avoids /C:/C:/ doubling).
@@ -68,7 +69,8 @@ export async function listComponentMeta(includeDrafts = false) {
         const raw = await readFile(indexPath, 'utf8');
         const fm = parseFrontmatter(raw);
         const status = fm.status ?? 'unknown';
-        if (!includeDrafts && status !== 'ready')
+        const discoverable = { status, signed_off: fm.signed_off };
+        if (!isListed(discoverable, includeDrafts))
             continue;
         results.push({
             name: entry.name,
@@ -77,6 +79,7 @@ export async function listComponentMeta(includeDrafts = false) {
             surface: fm.surface ?? 'unknown',
             status,
             purpose: fm.purpose ?? '',
+            ...discoveryFields(discoverable),
         });
     }
     return results.sort((a, b) => a.name.localeCompare(b.name));

package/dist/discovery.js

@@ -0,0 +1,44 @@
+// Component discovery rule — RUN-731, founder ruling D1 (2026-09-19).
+//
+// Two facts, two fields, never collapsed into one:
+//   `status`      human content review (content schema §11). Only a reviewed
+//                 entry is ever `ready`.
+//   `signed_off`  the component itself is signed off for public docs (live
+//                 inventory `signed_off && audience === 'public-docs'`), kept in
+//                 sync by check-kb-drift.mjs.
+//
+// Discovery follows sign-off: by default `list_components` returns every
+// `ready` entry PLUS every signed-off entry whose content is still `draft`,
+// each marked so an agent can tell the docs are unreviewed. Drafts of
+// components that are NOT signed off stay hidden unless include_drafts.
+//
+// Pure and dependency-free on purpose: the local provider, the remote provider
+// and the hosted worker (packages/mcp-api-worker, a Cloudflare Worker with no
+// node:fs) all import this one module, so the three listings cannot disagree.
+export const UNREVIEWED_NOTE = 'The component is signed off, but these docs have not had human content review yet. ' +
+    'They may be machine-generated or incomplete, including the accessibility tab. ' +
+    'Verify against the component before relying on them.';
+// Frontmatter and the KV manifest both arrive as strings; accept either form.
+export function isSignedOff(value) {
+    return value === true || value === 'true';
+}
+export function isListed(entry, includeDrafts) {
+    if (includeDrafts)
+        return true;
+    if (entry.status === 'ready')
+        return true;
+    return entry.status === 'draft' && isSignedOff(entry.signed_off);
+}
+export function contentReview(entry) {
+    return entry.status === 'ready' ? 'reviewed' : 'unreviewed draft';
+}
+// The discovery fields every listing attaches to a component, in one place.
+export function discoveryFields(entry) {
+    const review = contentReview(entry);
+    const signed = isSignedOff(entry.signed_off);
+    return {
+        signed_off: signed,
+        content_review: review,
+        ...(review === 'unreviewed draft' && signed ? { content_note: UNREVIEWED_NOTE } : {}),
+    };
+}

package/dist/remote-provider.js

@@ -2,6 +2,7 @@ import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { isListed, discoveryFields } from './discovery.js';
 // ---------------------------------------------------------------------------
 // Helpers — copied from content.ts to avoid importing filesystem-bound code
 // ---------------------------------------------------------------------------
@@ -82,7 +83,7 @@ export class RemoteContentProvider {
     async listComponents(includeDrafts = false) {
         const manifest = await this.getManifest();
         return manifest.components
-            .filter(e => includeDrafts || e.status === 'ready')
+            .filter(e => isListed(e, includeDrafts))
             .map(e => ({
             name: e.name,
             title: e.title,
@@ -90,6 +91,7 @@ export class RemoteContentProvider {
             surface: e.surface,
             status: e.status,
             purpose: e.purpose,
+            ...discoveryFields(e),
         }))
             .sort((a, b) => a.name.localeCompare(b.name));
     }

package/dist/server.js

@@ -19,6 +19,10 @@ import { GET_COMPLETENESS_MAP_TOOL, handleGetCompletenessMap } from './tools/get
 import { LINK_SESSION_TOOL, handleLinkSession } from './tools/link-session.js';
 import { SET_SITE_CONTENT_TOOL, handleSetSiteContent } from './tools/set-site-content.js';
 import { PROMOTE_SITE_CONTENT_TOOL, handlePromoteSiteContent } from './tools/promote-site-content.js';
+import { ORDER_SITE_TOOL, handleOrderSite } from './tools/order-site.js';
+import { ORDER_CUSTOM_DOMAIN_TOOL, handleOrderCustomDomain } from './tools/order-custom-domain.js';
+import { LIST_ORDERS_TOOL, handleListOrders } from './tools/list-orders.js';
+import { SELECT_DOMAIN_CANDIDATE_TOOL, handleSelectDomainCandidate } from './tools/select-domain-candidate.js';
 import { handleSetTheme } from './tools/set-theme.js';
 import { handleSetSkin } from './tools/set-skin.js';
 import { handleSetMode } from './tools/set-mode.js';
@@ -28,6 +32,7 @@ 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';
+import { handleSetSufficiency } from './tools/set-sufficiency.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';
@@ -77,6 +82,10 @@ export async function createRunsnativeServer() {
             LINK_SESSION_TOOL,
             SET_SITE_CONTENT_TOOL,
             PROMOTE_SITE_CONTENT_TOOL,
+            ORDER_SITE_TOOL,
+            ORDER_CUSTOM_DOMAIN_TOOL,
+            LIST_ORDERS_TOOL,
+            SELECT_DOMAIN_CANDIDATE_TOOL,
             ...SESSION_ENACT_TOOLS,
             GET_MARKER_CAPTURE_TOOL,
             RENDER_MARKER_CAPTURE_TOOL,
@@ -121,6 +130,14 @@ export async function createRunsnativeServer() {
                 return handleSetSiteContent(request.params.arguments ?? {});
             case 'promote_site_content':
                 return handlePromoteSiteContent(request.params.arguments ?? {});
+            case 'order_site':
+                return handleOrderSite(request.params.arguments ?? {});
+            case 'order_custom_domain':
+                return handleOrderCustomDomain(request.params.arguments ?? {});
+            case 'list_orders':
+                return handleListOrders();
+            case 'select_domain_candidate':
+                return handleSelectDomainCandidate(request.params.arguments ?? {});
             case 'set_theme':
                 return handleSetTheme(request.params.arguments ?? {});
             case 'set_skin':
@@ -139,6 +156,8 @@ export async function createRunsnativeServer() {
                 return handleSpotlight(request.params.arguments ?? {});
             case 'resolve_target':
                 return handleResolveTarget(request.params.arguments ?? {});
+            case 'set_sufficiency':
+                return handleSetSufficiency(request.params.arguments ?? {});
             case 'get_marker_capture':
                 return handleGetMarkerCapture(request.params.arguments ?? {});
             case 'render_marker_capture':

package/dist/tools/list-components.js

@@ -2,14 +2,16 @@ import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 export const LIST_COMPONENTS_TOOL = {
     name: 'list_components',
     description: 'Lists RunsNative components available in the knowledge base. ' +
-        'Returns name, title, element tag, surface area, status, and purpose for each component. ' +
-        'By default returns only ready components. Pass include_drafts: true to include draft stubs.',
+        'Returns name, title, element tag, surface area, status, purpose, signed_off and content_review for each component. ' +
+        'By default returns every component signed off for use: those with reviewed docs (status "ready") and those ' +
+        'whose docs are still an unreviewed draft (content_review "unreviewed draft" — treat that content as a starting ' +
+        'point, not verified guidance). Pass include_drafts: true to also include components not yet signed off.',
     inputSchema: {
         type: 'object',
         properties: {
             include_drafts: {
                 type: 'boolean',
-                description: 'When true, includes draft/stub components in addition to ready ones. Default: false.',
+                description: 'When true, also includes components that are not signed off yet. Default: false.',
             },
         },
         required: [],

package/dist/tools/list-orders.js

@@ -0,0 +1,47 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { getWorkerApi } from '../bridge-client.js';
+// Ordinary MCP tool — the read leg of the order desk (JUNE-1403 / JUNE-1403.1).
+// Ungated on the worker side by design (GET /mcp/tenant/orders is a read of
+// the caller's own orders, not a spend), so it carries no _meta.copresence
+// and needs no role beyond a valid token.
+export const LIST_ORDERS_TOOL = {
+    name: 'list_orders',
+    description: "List the account's own orders (site and custom-domain), newest first. Use this to check progress on " +
+        'an order placed with order_site or order_custom_domain, or to see whether a custom-domain order has ' +
+        'reached "awaiting-selection" and needs select_domain_candidate. Requires an authenticated RunsNative ' +
+        'token; any role may read its own orders.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        required: [],
+    },
+};
+export async function handleListOrders() {
+    const res = await getWorkerApi('/tenant/orders');
+    if (res.status === 401) {
+        throw new McpError(ErrorCode.InvalidParams, 'Not authenticated. Set RUNSNATIVE_TENANT_TOKEN to a valid token.');
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new McpError(ErrorCode.InternalError, `Worker error ${res.status}: ${body}`);
+    }
+    const body = (await res.json());
+    if (body.orders.length === 0) {
+        return { content: [{ type: 'text', text: 'No orders on this account yet.' }] };
+    }
+    const lines = body.orders.map((o) => {
+        const subject = o.sku === 'create-site'
+            ? `site "${o.siteSlug}"`
+            : `custom domain [${(o.requestedCandidates ?? []).join(', ')}]${o.selectedCandidate ? ` → selected ${o.selectedCandidate}` : ''}`;
+        const err = o.error ? ` — error: ${o.error}` : '';
+        return `- ${o.id}: ${subject}, status: ${o.status}, production: ${o.production}${err}`;
+    });
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `${body.orders.length} order(s):\n${lines.join('\n')}`,
+            },
+        ],
+    };
+}

package/dist/tools/order-custom-domain.js

@@ -0,0 +1,96 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { postWorkerApi } from '../bridge-client.js';
+import { refusalMessage } from './order-site.js';
+// Ordinary MCP tool — see order-site.ts for the shared rationale
+// (JUNE-1403 / JUNE-1403.1). Sibling SKU on the same POST /tenant/orders
+// route; shares order-site.ts's refusalMessage for the identical 402 shape.
+export const ORDER_CUSTOM_DOMAIN_TOOL = {
+    name: 'order_custom_domain',
+    description: "Order a custom domain for the user's site. This consumes one order credit from the account — tell " +
+        "the user before calling it. Supply EXACTLY ONE of a concrete name (requestedName) or the customer's " +
+        'own candidate ideas (candidates) — never both. Availability is never a purchase guarantee: the order ' +
+        'consumes its credit and scores the candidate(s) server-side, but a candidate can still end up ' +
+        'unregistrable. Domain names are proposed, never auto-selected — once the order reaches ' +
+        '"awaiting-selection", call select_domain_candidate with the customer\'s pick. Poll progress with ' +
+        'list_orders. Requires an authenticated RunsNative token whose role may place orders (site:order).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            requestedName: {
+                type: 'string',
+                description: 'A single concrete domain name to order (e.g. "acme-bakery.com"). Mutually exclusive with candidates.',
+            },
+            candidates: {
+                type: 'array',
+                items: { type: 'string' },
+                description: "The customer's own hand-typed candidate domain names, scored server-side. Mutually exclusive " +
+                    'with requestedName.',
+            },
+            constraints: {
+                type: 'object',
+                description: 'Optional scoring/refusal constraints applied to each candidate: tlds (string[]), avoid ' +
+                    '(string[]), maxSyllables (number). These never invent a name — they only modulate scoring.',
+                properties: {
+                    tlds: { type: 'array', items: { type: 'string' } },
+                    avoid: { type: 'array', items: { type: 'string' } },
+                    maxSyllables: { type: 'number' },
+                },
+            },
+        },
+        required: [],
+    },
+};
+export async function handleOrderCustomDomain(args) {
+    const requestedName = args['requestedName'];
+    const candidates = args['candidates'];
+    const haveName = requestedName !== undefined && requestedName !== null;
+    const haveList = candidates !== undefined && candidates !== null;
+    if (haveName === haveList) {
+        throw new McpError(ErrorCode.InvalidParams, 'Supply exactly one of requestedName (a string) or candidates (a non-empty array), not both or neither.');
+    }
+    if (haveName && typeof requestedName !== 'string') {
+        throw new McpError(ErrorCode.InvalidParams, 'requestedName must be a string');
+    }
+    if (haveList && !Array.isArray(candidates)) {
+        throw new McpError(ErrorCode.InvalidParams, 'candidates must be an array of strings');
+    }
+    const body = { sku: 'custom-domain' };
+    if (haveName)
+        body['requestedName'] = requestedName;
+    if (haveList)
+        body['candidates'] = candidates;
+    const constraints = args['constraints'];
+    if (constraints !== undefined && constraints !== null)
+        body['constraints'] = constraints;
+    const res = await postWorkerApi('/tenant/orders', body);
+    if (res.status === 401) {
+        throw new McpError(ErrorCode.InvalidParams, 'Not authenticated. Set RUNSNATIVE_TENANT_TOKEN to a token that may place orders.');
+    }
+    if (res.status === 403) {
+        throw new McpError(ErrorCode.InvalidParams, 'Your role does not permit placing orders for this account.');
+    }
+    if (res.status === 402) {
+        throw new McpError(ErrorCode.InvalidParams, await refusalMessage(res));
+    }
+    if (res.status === 400) {
+        const errBody = (await res.json().catch(() => ({})));
+        throw new McpError(ErrorCode.InvalidParams, errBody.error ?? 'Order rejected by the server.');
+    }
+    if (!res.ok) {
+        const errBody = await res.text().catch(() => '');
+        throw new McpError(ErrorCode.InternalError, `Worker error ${res.status}: ${errBody}`);
+    }
+    const resBody = (await res.json());
+    const { order, created } = resBody;
+    const verb = created ? 'Ordered a custom domain from candidates' : 'Already have a pending custom-domain order for candidates';
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `${verb} [${(order.requestedCandidates ?? []).join(', ')}] (order ${order.id}, status: ${order.status}). ` +
+                    'Poll list_orders for scoring progress — availability is never a purchase guarantee, and once ' +
+                    'candidates are scored the customer must pick one with select_domain_candidate.',
+            },
+        ],
+    };
+}

package/dist/tools/order-site.js

@@ -0,0 +1,85 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { postWorkerApi } from '../bridge-client.js';
+// Ordinary MCP tool (JUNE-1403, surface corrected from the original ticket
+// text by the readiness pass JUNE-1403.1): placing an order is an
+// account/commerce action, not something enacted on a bound live session, so
+// per Copresence Protocol §5 it carries no `_meta.copresence` and is not in
+// SESSION_ENACT_TOOLS — same posture as set_site_content / promote_site_content.
+export const ORDER_SITE_TOOL = {
+    name: 'order_site',
+    description: "Order a new RunsNative site for the user's account (the \"create my site\" action). " +
+        'This consumes one order credit from the account — tell the user before calling it. A fulfilled order ' +
+        'attaches a preview-only site (production is NOT activated by this call — that is a separate, later ' +
+        'step) reachable at the address named in the response. Calling this again while an order for a new ' +
+        'site is still pending/building returns that SAME order rather than starting a second one — it is safe ' +
+        'to retry. Poll progress with list_orders. Requires an authenticated RunsNative token whose role may ' +
+        'place orders (site:order).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            siteSlug: {
+                type: 'string',
+                description: 'The slug for the new site: 3-40 characters, lowercase a-z, 0-9 and hyphens, starting and ' +
+                    'ending alphanumeric (e.g. "acme-bakery").',
+            },
+        },
+        required: ['siteSlug'],
+    },
+};
+export async function handleOrderSite(args) {
+    const siteSlug = args['siteSlug'];
+    if (typeof siteSlug !== 'string' || !siteSlug.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, 'siteSlug must be a non-empty string');
+    }
+    const res = await postWorkerApi('/tenant/orders', { sku: 'create-site', siteSlug: siteSlug.trim() });
+    if (res.status === 401) {
+        throw new McpError(ErrorCode.InvalidParams, 'Not authenticated. Set RUNSNATIVE_TENANT_TOKEN to a token that may place orders.');
+    }
+    if (res.status === 403) {
+        throw new McpError(ErrorCode.InvalidParams, 'Your role does not permit placing orders for this account.');
+    }
+    if (res.status === 402) {
+        throw new McpError(ErrorCode.InvalidParams, await refusalMessage(res));
+    }
+    if (res.status === 400) {
+        const body = (await res.json().catch(() => ({})));
+        throw new McpError(ErrorCode.InvalidParams, body.error ?? 'Order 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());
+    const { order, created } = body;
+    const verb = created ? 'Ordered' : 'Already have a pending order for';
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `${verb} site "${order.siteSlug}" (order ${order.id}, status: ${order.status}, ` +
+                    `production: ${order.production}). Poll list_orders for progress — the site stays preview-only ` +
+                    'until it is separately activated.',
+            },
+        ],
+    };
+}
+/**
+ * JUNE-1404 D0-D5's three refusal reasons, distinct conversion paths per
+ * §8.2 — surface the reason and payment_url rather than a generic failure
+ * (the build prompt's stated defect to avoid). Shared verbatim by
+ * order-custom-domain.ts, the sibling SKU on the same route.
+ */
+export async function refusalMessage(res) {
+    const body = (await res.json().catch(() => ({})));
+    const url = body.payment_url ? `: ${body.payment_url}` : '.';
+    if (body.reason === 'renewal_required') {
+        return `The account's order grant has lapsed — renew to keep ordering${url}`;
+    }
+    if (body.reason === 'quota_exhausted') {
+        const used = typeof body.used === 'number' && typeof body.quota_limit === 'number'
+            ? ` (${body.used}/${body.quota_limit} used)`
+            : '';
+        return `Order quota exhausted${used} — upgrade to order more${url}`;
+    }
+    return `Ordering is a paid capability this account doesn't hold yet — upgrade to unlock it${url}`;
+}

package/dist/tools/select-domain-candidate.js

@@ -0,0 +1,67 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { postWorkerApi } from '../bridge-client.js';
+// Ordinary MCP tool — the human-curation step of a custom-domain order
+// (JUNE-1112, discoverability leg JUNE-1403 / JUNE-1403.1). Deliberately a
+// SEPARATE act from order_custom_domain: candidates are proposed, never
+// auto-selected, so this always needs the customer's own pick.
+export const SELECT_DOMAIN_CANDIDATE_TOOL = {
+    name: 'select_domain_candidate',
+    description: 'Pick which scored domain candidate to buy for a custom-domain order that has reached ' +
+        '"awaiting-selection" (check with list_orders). This is a separate, human-directed act from placing ' +
+        'the order — never call this without the customer having chosen the name themselves. The candidate ' +
+        'must be one of the names already scored for this order.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            orderId: {
+                type: 'string',
+                description: 'The id of the custom-domain order (from order_custom_domain or list_orders).',
+            },
+            candidate: {
+                type: 'string',
+                description: 'The domain name the customer picked, exactly as scored for this order.',
+            },
+        },
+        required: ['orderId', 'candidate'],
+    },
+};
+export async function handleSelectDomainCandidate(args) {
+    const orderId = args['orderId'];
+    if (typeof orderId !== 'string' || !orderId.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, 'orderId must be a non-empty string');
+    }
+    const candidate = args['candidate'];
+    if (typeof candidate !== 'string' || !candidate.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, 'candidate must be a non-empty string');
+    }
+    const res = await postWorkerApi(`/tenant/orders/${encodeURIComponent(orderId.trim())}/select`, {
+        candidate: candidate.trim(),
+    });
+    if (res.status === 401) {
+        throw new McpError(ErrorCode.InvalidParams, 'Not authenticated. Set RUNSNATIVE_TENANT_TOKEN to a token that may place orders.');
+    }
+    if (res.status === 403) {
+        throw new McpError(ErrorCode.InvalidParams, 'Your role does not permit selecting a candidate for this account.');
+    }
+    if (res.status === 404) {
+        throw new McpError(ErrorCode.InvalidParams, 'No such order on this account.');
+    }
+    if (res.status === 400) {
+        const body = (await res.json().catch(() => ({})));
+        throw new McpError(ErrorCode.InvalidParams, body.error ?? 'Selection 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: `Selected "${body.order.selectedCandidate}" for order ${body.order.id} (status: ${body.order.status}). ` +
+                    'Poll list_orders for registration/point progress.',
+            },
+        ],
+    };
+}

package/dist/tools/session-tools.js

@@ -8,7 +8,17 @@
  * 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.
+ * reconciliation test fails until all four of those surfaces carry it.
+ *
+ * A FIFTH surface then has to account for it, and it is easy to miss because a
+ * different test owns it: the remote HTTP transport (mcp-api-worker
+ * src/mcp/tools.ts, asserted by test/mcp/remote-surface.test.ts, JUNE-1297).
+ * Every stdio tool must be either bound there or listed in
+ * DEFERRED_FROM_REMOTE with the reason it is not — absence has to be a decision
+ * someone wrote down rather than a smaller surface nobody noticed shipping.
+ * Binding is a positional projection of named args (ARG_PROJECTIONS), so a verb
+ * whose argument is one structured object (intake.setSufficiency, JUNE-1577) or
+ * whose args are built conditionally (tour.spotlight) is deferred instead.
  *
  * NOT in this list: read-leg session tools with no enactment
  * (get_marker_capture, fetch_marker_crop, render_marker_capture) and the
@@ -23,6 +33,7 @@ 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';
+import { SET_SUFFICIENCY_TOOL } from './set-sufficiency.js';
 export const SESSION_ENACT_TOOLS = [
     SET_THEME_TOOL,
     SET_SKIN_TOOL,
@@ -33,6 +44,7 @@ export const SESSION_ENACT_TOOLS = [
     SET_INSTANCE_VARIANT_TOOL,
     SPOTLIGHT_TOOL,
     RESOLVE_TARGET_TOOL,
+    SET_SUFFICIENCY_TOOL,
 ];
 /** The `capability.method` allow-list entries this tool set can enact. */
 export function listSessionEnactments() {

package/dist/tools/set-sufficiency.js

@@ -0,0 +1,146 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { postWorkerApi, getLinkedPairId } from '../bridge-client.js';
+/**
+ * The intake sufficiency block (JUNE-1577 leg A).
+ *
+ * The wire shape is the `state` object JUNE-1430's `record_answer` returns —
+ * an interview session relays it here after every accepted answer and the
+ * paired tab's meter panel redraws. The worker's allow-list
+ * (`mcp-api-worker/src/handlers/pair/sufficiency-block.ts`) is the single
+ * authority on the block's vocabulary; this tool checks only that the three
+ * required containers are present, so an obvious mistake fails locally instead
+ * of costing a round trip, and lets the worker name anything subtler.
+ *
+ * There is no `label` on the wire, by ruling: the eight dimension labels are
+ * byte-frozen in the model's §2 and the page holds them keyed by `n`.
+ */
+export const SET_SUFFICIENCY_TOOL = {
+    name: 'set_sufficiency',
+    description: "Push the intake sufficiency block to the user's linked runsnative.org interview page — the eight-dimension " +
+        'meter panel redraws within one poll interval. Call it after every answer you accept during a partner intake ' +
+        "interview, passing the `state` object from the interview skill's record_answer verbatim, so the person " +
+        'answering watches the meters move and can see how close the intake is to done. Display-only: the page shows ' +
+        'what you send and scores nothing itself, so the block you send IS what they see. Reversible — the next block ' +
+        'replaces it, and a reload clears the panel. Requires an active linked session (call link_session first).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            rows: {
+                type: 'array',
+                description: 'Exactly 8 rows, one per dimension, in the model\'s order 1-8. Each is {n, band, source, next}: `band` is ' +
+                    'unknown|developing|nearly|sufficient|strong; `source` is partner|artifact|modal|research|confirmed, and ' +
+                    'must be the em-dash "—" exactly when the band is unknown; `next` says what would move the row ("—" when ' +
+                    'the row is settled). No `label` — the page holds the frozen dimension labels itself.',
+                items: {
+                    type: 'object',
+                    properties: {
+                        n: { type: 'integer', minimum: 1, maximum: 8, description: 'Dimension number, matching the row position.' },
+                        band: {
+                            type: 'string',
+                            enum: ['unknown', 'developing', 'nearly', 'sufficient', 'strong'],
+                            description: 'How well the intake knows this dimension.',
+                        },
+                        source: {
+                            type: 'string',
+                            enum: ['partner', 'artifact', 'modal', 'research', 'confirmed', '—'],
+                            description: 'What supplied it. "—" exactly when the band is unknown.',
+                        },
+                        next: { type: 'string', description: 'What would move this row, or "—" when it is settled.' },
+                    },
+                    required: ['n', 'band', 'source', 'next'],
+                },
+            },
+            asking_now: {
+                type: ['integer', 'null'],
+                minimum: 1,
+                maximum: 8,
+                description: 'The dimension being asked about right now, or null when nothing is (the twin step asks nothing).',
+            },
+            budget: {
+                type: ['object', 'null'],
+                description: 'Interview budget: {asked, limit} during the brief phase, {elapsed, estimate} during the informed ' +
+                    'interview, null for the twin step (which prints no budget line).',
+            },
+            gate: {
+                type: 'string',
+                enum: ['research-ready', 'decide-ready'],
+                description: 'Which gate the block is measured against. Selects the threshold marker the page draws on every meter: ' +
+                    'the brief runs against research-ready, the twin and informed interview against decide-ready.',
+            },
+            short: {
+                type: 'array',
+                items: { type: 'integer', minimum: 1, maximum: 8 },
+                description: 'Dimension numbers still below the gate, ascending and distinct. Empty means the gate is met.',
+            },
+        },
+        required: ['rows', 'gate', 'short'],
+    },
+    // Copresence Protocol §5.1 (copresence-protocol-v0.1, mukadra repo) —
+    // session-targeting capability. `enactment` names the worker allow-list entry
+    // this tool submits. Reversible: the panel is display-only, the next block
+    // replaces this one, and nothing is persisted.
+    _meta: {
+        copresence: {
+            target: 'session',
+            tier: 'reversible',
+            consent: 'implicit',
+            entitlement: 'free',
+            visibility: 'advertised',
+            enactment: 'intake.setSufficiency',
+        },
+    },
+};
+export async function handleSetSufficiency(args) {
+    if (!Array.isArray(args['rows'])) {
+        throw new McpError(ErrorCode.InvalidParams, 'rows must be an array of the eight dimension rows');
+    }
+    if (typeof args['gate'] !== 'string' || !args['gate']) {
+        throw new McpError(ErrorCode.InvalidParams, 'gate must be "research-ready" or "decide-ready"');
+    }
+    if (!Array.isArray(args['short'])) {
+        throw new McpError(ErrorCode.InvalidParams, 'short must be an array of dimension numbers (empty when the gate is met)');
+    }
+    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.');
+    }
+    // The WHOLE argument object goes on the wire as one block. Producer fields
+    // the page does not read (interview_id, phase, gate_met) ride along
+    // deliberately: the worker ignores unknown keys rather than rejecting them,
+    // so a new producer field is never a breaking change across the two graphs.
+    const res = await postWorkerApi('/tenant/command', {
+        pair_id: pairId,
+        capability: 'intake',
+        method: 'setSufficiency',
+        args: [args],
+    });
+    if (res.status === 404) {
+        throw new McpError(ErrorCode.InvalidParams, 'Linked session not found or expired. Re-link with link_session.');
+    }
+    // The allow-list rejects with 400 ("Command not allowed: <defect>") — the
+    // worker's own status for a refused command. 422 is mapped alongside it for
+    // parity with the other session verbs, whose 422 branch predates this one.
+    // Surfacing the worker's text matters more here than for a scalar verb: the
+    // rejection names which row and which token was wrong.
+    if (res.status === 400 || res.status === 422) {
+        const body = (await res.json().catch(() => ({})));
+        throw new McpError(ErrorCode.InvalidParams, body.error ?? 'Sufficiency block rejected by the 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 short = args['short'];
+    const status = short.length === 0 ? 'the gate is met' : `still short on ${short.join(', ')}`;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Sufficiency block enqueued (${args['gate']}, ${status}). The panel will redraw within one poll interval.`,
+            },
+        ],
+    };
+}

package/package.json

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