@runsnative/mcp-server 0.9.1 → 0.10.0

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/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';
@@ -77,6 +81,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 +129,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':

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

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