@runsnative/mcp-server 0.10.0 → 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/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

@@ -32,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';
@@ -155,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/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.10.0",
+  "version": "0.13.0",
   "type": "module",
   "files": [
     "dist/"