@apexops/cli 0.10.0-next.5 → 0.11.0-next.1

package/dist/mcp.js

@@ -1,18 +1,359 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Server } from "@modelcontextprotocol/server";
+import { serveStdio, StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 import { z } from "zod";
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { lstatSync } from "node:fs";
+import { realpath } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
 import { ApexService, SUPPORTED_ARTIFACT_KINDS } from "./service.js";
 import { APEX_VERSION } from "./version.js";
+import { ApexError, EXIT_CODES, normalizeError, remediationForApexError } from "./errors.js";
+import { SECRET_VALUE_PATTERN } from "@apexops/contracts";
+import { MCP_DOCTOR_CHECK_LIMIT, MCP_OUTPUT_SCHEMAS } from "./mcp-output-schemas.js";
+import { TARGET_SCOPE_HINT, TARGET_SCOPE_PATTERN } from "./target-scope.js";
+import { resolveMcpWorkspace } from "./workspace-root.js";
+import { runtimeMismatchError, runtimeMismatchStatus, workspaceRuntimeBinding } from "./runtime-binding.js";
+import { MCP_TOOL_EFFECTS } from "./mcp-tool-effects.js";
+const errorMessages = {
+    APEX_USAGE: "Invalid operation arguments; check the tool input contract.",
+    APEX_NOT_FOUND: "Requested APEX state was not found; refresh status and check the identifier.",
+    APEX_CONFLICT: "The operation conflicts with current state; refresh status before retrying.",
+    APEX_WRITER_CONFLICT: "Another worktree owns this run's writer lease; retry from that worktree or release the lease.",
+    APEX_WORKSPACE_UNSUPPORTED: "The workspace path cannot be resolved to a supported APEX checkout; use a non-bare checkout or worktree.",
+    APEX_RUNTIME_MISMATCH: "This APEX runtime does not match the workspace runtime lock version.",
+    APEX_VALIDATION: "APEX validation failed; check the supplied input against the current task contract.",
+    APEX_STALE: "Task is stale or expired; refresh status before retrying.",
+    APEX_AUTHORIZATION: "Operation is not authorized in the current workflow state; check status and approval requirements.",
+    APEX_CURSOR_INVALID: "Cursor is invalid for this tool, workspace, or server session.",
+    APEX_RESULT_TOO_LARGE: "MCP result exceeded the bounded result size and cannot be paged safely.",
+    APEX_REVIEW_PENDING: "A rubber-duck review is waiting for its capture; operations that approve, delete or publish are blocked until it completes or is cancelled.",
+    APEX_INTERNAL: "APEX could not complete the operation.",
+};
+export const MCP_SERVER_INSTRUCTIONS = [
+    "APEX is a governed Azure workload lifecycle server; the kernel owns state, gates, authorization, and evidence.",
+    "Every tool call must include workspace as an absolute checkout or git worktree path.",
+    "Call status first, then use returned task, run, expected head, and owner epoch values exactly.",
+    "Do not retry mutations blindly after timeout, cancellation, or conflict; refresh status and confirm intent first.",
+    "Use ask_user for human approvals, risk decisions, missing inputs, and any choice the kernel requires.",
+    "Large read results may include nextCursor; call the same tool with the same workspace and cursor until it is absent.",
+].join(" ");
+export const MCP_MAX_SERIALIZED_RESULT_BYTES = 64 * 1024;
+const cursorInput = z.string().min(1).max(4096).optional();
+const pagePaths = {
+    taskContext: ["inputs"],
+    readTaskInput: ["content"],
+    projectList: ["projects"],
+    preview: ["markdown"],
+    inventory: ["resources"],
+    improvementObservations: ["observations"],
+    improvementProposals: ["proposals"],
+    render: ["markdown"],
+    doctorChecks: ["checks"],
+};
+function serviceResolver(serviceOrResolver) {
+    if (typeof serviceOrResolver.resolve === "function" &&
+        serviceOrResolver.defaultService !== undefined) {
+        return serviceOrResolver;
+    }
+    const service = serviceOrResolver;
+    return {
+        defaultService: service,
+        resolve: async (workspace) => {
+            const resolved = await resolveMcpWorkspace(workspace);
+            const serviceRoot = await realpath(service.root);
+            const requestedRoot = resolve(resolved.root);
+            const boundRoot = resolve(serviceRoot);
+            const matches = process.platform === "win32"
+                ? requestedRoot.toLocaleLowerCase() === boundRoot.toLocaleLowerCase()
+                : requestedRoot === boundRoot;
+            if (!matches) {
+                throw new ApexError("APEX_WORKSPACE_UNSUPPORTED", `Workspace ${resolved.workspace} resolves to ${requestedRoot}, but this MCP server is bound to ${boundRoot}; start the server with a workspace-aware service resolver for multi-worktree use`, EXIT_CODES.validation);
+            }
+            return { service, workspace: resolved.workspace };
+        },
+    };
+}
+const workspaceInput = z.string().superRefine((workspace, context) => {
+    if (!isAbsolute(workspace)) {
+        context.addIssue({ code: "custom", message: "workspace must be an absolute path" });
+        return;
+    }
+    try {
+        if (!lstatSync(workspace).isDirectory()) {
+            context.addIssue({ code: "custom", message: "workspace must be an existing directory" });
+        }
+    }
+    catch {
+        context.addIssue({ code: "custom", message: "workspace must be an existing directory" });
+    }
+});
 const artifactKind = z.enum(SUPPORTED_ARTIFACT_KINDS);
-const taskOutput = z.object({ kind: artifactKind, value: z.unknown(), summary: z.string().optional() });
-const reviewFinding = z
+const taskOutput = z.object({ kind: artifactKind, value: z.unknown(), summary: z.string().optional() }).strict();
+const stagingInput = (optional) => z
     .object({
-    id: z.string().min(1),
-    severity: z.enum(["critical", "high", "medium", "low", "info"]),
-    title: z.string().min(1),
-    detail: z.string().min(1),
+    taskId: z.string().min(1).max(128),
+    kind: artifactKind.optional(),
+    value: z.unknown().optional(),
+    summary: z.string().max(4096).optional(),
+    outputs: z.array(taskOutput).min(1).max(32).optional(),
 })
-    .strict();
+    .strict()
+    .superRefine((input, context) => {
+    const single = input.kind !== undefined && Object.hasOwn(input, "value");
+    const anySingle = input.kind !== undefined || Object.hasOwn(input, "value") || input.summary !== undefined;
+    if ((input.outputs !== undefined && anySingle) ||
+        (input.outputs === undefined && (anySingle ? !single : !optional)))
+        context.addIssue({
+            code: "custom",
+            message: "Supply exactly one complete kind/value form or a nonempty outputs bundle.",
+        });
+    if (input.outputs && new Set(input.outputs.map(({ kind }) => kind)).size !== input.outputs.length)
+        context.addIssue({ code: "custom", message: "Output kinds must be unique." });
+})
+    .meta({
+    oneOf: [
+        { required: ["outputs"], not: { anyOf: ["kind", "value", "summary"].map((key) => ({ required: [key] })) } },
+        { required: ["kind", "value"], not: { required: ["outputs"] } },
+        ...(optional
+            ? [{ not: { anyOf: ["kind", "value", "summary", "outputs"].map((key) => ({ required: [key] })) } }]
+            : []),
+    ],
+});
+export { MCP_TOOL_EFFECTS, MCP_TOOL_REVIEW_GUARDS } from "./mcp-tool-effects.js";
+/** Arguments naming workspace files whose content, not only path, identifies a repeated call. */
+const repeatFileArguments = {
+    governanceImport: ["path"],
+    governanceSelect: ["path"],
+};
+const readOnlyTools = new Set(Object.entries(MCP_TOOL_EFFECTS)
+    .filter(([, effect]) => effect === "read-only")
+    .map(([name]) => name));
+/** Tools in the `read-only` effect class. Every other APEX tool is state-changing, which the rubber-duck deny hook enforces. */
+export const MCP_READ_ONLY_TOOLS = readOnlyTools;
+/**
+ * The tool effect policy the plugin build ships beside the managed hooks (apex-mcp-tools.json), so the rubber-duck deny
+ * hook and the MCP annotations share one source.
+ */
+export function mcpToolPolicy() {
+    return {
+        server: "apex",
+        tools: Object.keys(MCP_OUTPUT_SCHEMAS).sort(),
+        readOnly: [...MCP_READ_ONLY_TOOLS].sort(),
+    };
+}
+const externalTools = new Set(["reconcile", "inventory", "diagnose", "doctor", "doctorChecks"]);
+function assertBoundedInput(value) {
+    const stack = [{ value, depth: 0 }];
+    let nodes = 0;
+    let bytes = 0;
+    while (stack.length > 0) {
+        const entry = stack.pop();
+        if (++nodes > 100_000 || entry.depth > 64 || bytes > 4 * 1024 * 1024)
+            throw new ApexError("APEX_VALIDATION", "Input budget exceeded", EXIT_CODES.validation);
+        if (typeof entry.value === "string")
+            bytes += Buffer.byteLength(entry.value);
+        else if (entry.value !== null && typeof entry.value === "object") {
+            const children = Object.entries(entry.value);
+            if (children.length + stack.length + nodes > 100_000)
+                throw new ApexError("APEX_VALIDATION", "Input budget exceeded", EXIT_CODES.validation);
+            for (const [key, child] of children) {
+                bytes += Buffer.byteLength(key);
+                stack.push({ value: child, depth: entry.depth + 1 });
+            }
+        }
+    }
+    if (Buffer.byteLength(JSON.stringify(value)) > 4 * 1024 * 1024)
+        throw new ApexError("APEX_VALIDATION", "Input budget exceeded", EXIT_CODES.validation);
+}
+const resultEnvelopeBytes = (structuredContent) => {
+    const text = JSON.stringify(structuredContent);
+    return Buffer.byteLength(JSON.stringify({
+        content: [{ type: "text", text }],
+        structuredContent,
+    }), "utf8");
+};
+const MCP_DOCTOR_SUMMARY_BYTES = 48 * 1024;
+/**
+ * Bounds a doctor report for MCP. Failing checks come first, then passing checks other than per-file `managed:`
+ * hashes; every check left out is counted in `omitted`, and doctorChecks pages the complete list. Remedies are
+ * deduplicated, so no distinct remedy is dropped. CLI output keeps the full report.
+ */
+export function summarizeDoctorReport(report) {
+    const failed = report.checks.filter(({ ok }) => !ok);
+    const passed = report.checks.filter(({ ok }) => ok);
+    const candidates = [...failed, ...passed.filter(({ id }) => !id.startsWith("managed:"))];
+    const checks = [];
+    const summary = () => {
+        const listedFailed = checks.filter(({ ok }) => !ok).length;
+        return {
+            healthy: report.healthy,
+            nextAction: report.nextAction,
+            remedies: [...new Set(report.remedies)],
+            counts: { total: report.checks.length, passed: passed.length, failed: failed.length },
+            checks: checks.map(({ id, ok, value, remedy, severity }) => ({
+                id,
+                ok,
+                value,
+                ...(remedy === undefined ? {} : { remedy }),
+                ...(severity === undefined ? {} : { severity }),
+            })),
+            omitted: { passed: passed.length - (checks.length - listedFailed), failed: failed.length - listedFailed },
+            truncated: checks.length < report.checks.length,
+        };
+    };
+    for (const check of candidates) {
+        if (checks.length >= MCP_DOCTOR_CHECK_LIMIT)
+            break;
+        checks.push(check);
+        if (resultEnvelopeBytes(summary()) > MCP_DOCTOR_SUMMARY_BYTES) {
+            checks.pop();
+            break;
+        }
+    }
+    return summary();
+}
+const resultHash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+function cursorError(message) {
+    return new ApexError("APEX_CURSOR_INVALID", message, EXIT_CODES.validation);
+}
+function tooLargeError(tool) {
+    return new ApexError("APEX_RESULT_TOO_LARGE", `${tool} returned more than ${MCP_MAX_SERIALIZED_RESULT_BYTES} serialized bytes and no safe page fits`, EXIT_CODES.validation);
+}
+function encodeCursor(secret, payload) {
+    const body = Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+    const mac = createHmac("sha256", secret).update(body).digest("base64url");
+    return `${body}.${mac}`;
+}
+function decodeBase64urlCursorPart(value, part) {
+    if (value === "" || !/^[A-Za-z0-9_-]+$/u.test(value))
+        throw cursorError(`Malformed cursor ${part}`);
+    const decoded = Buffer.from(value, "base64url");
+    if (decoded.toString("base64url") !== value)
+        throw cursorError(`Non-canonical cursor ${part}`);
+    return decoded;
+}
+function decodeCursor(secret, cursor) {
+    const [body, mac, extra] = cursor.split(".");
+    if (body === undefined || mac === undefined || extra !== undefined)
+        throw cursorError("Malformed cursor");
+    const rawBody = decodeBase64urlCursorPart(body, "payload");
+    const expected = createHmac("sha256", secret).update(body).digest();
+    const actual = decodeBase64urlCursorPart(mac, "signature");
+    if (actual.length !== expected.length || !timingSafeEqual(actual, expected))
+        throw cursorError("Tampered cursor");
+    let decoded;
+    try {
+        decoded = JSON.parse(rawBody.toString("utf8"));
+    }
+    catch {
+        throw cursorError("Malformed cursor payload");
+    }
+    if (decoded === null ||
+        decoded.v !== 1 ||
+        typeof decoded.tool !== "string" ||
+        typeof decoded.workspace !== "string" ||
+        !/^[0-9a-f]{64}$/u.test(decoded.hash) ||
+        !Array.isArray(decoded.path) ||
+        decoded.path.some((entry) => typeof entry !== "string") ||
+        !Number.isSafeInteger(decoded.offset) ||
+        decoded.offset < 0) {
+        throw cursorError("Invalid cursor payload");
+    }
+    return decoded;
+}
+function getPageTarget(value, path) {
+    let target = value;
+    for (const segment of path) {
+        if (target === null || typeof target !== "object" || Array.isArray(target))
+            return undefined;
+        target = target[segment];
+    }
+    return target;
+}
+function withPageTarget(value, path, page) {
+    const copy = structuredClone(value);
+    let target = copy;
+    for (const segment of path.slice(0, -1))
+        target = target[segment];
+    target[path.at(-1)] = page;
+    return copy;
+}
+function applyResultPaging(secret, tool, workspace, input, value) {
+    const path = pagePaths[tool];
+    const cursor = input.cursor;
+    if (cursor !== undefined && typeof cursor !== "string")
+        throw cursorError("Cursor must be a string");
+    if (path === undefined) {
+        if (cursor !== undefined)
+            throw cursorError("Tool does not accept cursors");
+        if (resultEnvelopeBytes(value) > MCP_MAX_SERIALIZED_RESULT_BYTES)
+            throw tooLargeError(tool);
+        return value;
+    }
+    if (cursor === undefined && resultEnvelopeBytes(value) <= MCP_MAX_SERIALIZED_RESULT_BYTES)
+        return value;
+    const hash = resultHash(value);
+    const payload = cursor === undefined
+        ? { v: 1, tool, workspace, hash, path: [...path], offset: 0 }
+        : decodeCursor(secret, cursor);
+    if (payload.tool !== tool || payload.workspace !== workspace || payload.path.join("/") !== path.join("/")) {
+        throw cursorError("Cursor belongs to a different tool, workspace, or result path");
+    }
+    if (payload.hash !== hash) {
+        throw new ApexError("APEX_STALE", "Cursor result state changed before paging completed", EXIT_CODES.stale, undefined);
+    }
+    const target = getPageTarget(value, path);
+    if (typeof target !== "string" && !Array.isArray(target))
+        throw tooLargeError(tool);
+    const total = target.length;
+    if (total === 0)
+        throw tooLargeError(tool);
+    if (payload.offset >= total)
+        throw cursorError("Cursor offset is outside the current result");
+    let best;
+    let low = 1;
+    let high = total - payload.offset;
+    while (low <= high) {
+        const count = Math.floor((low + high) / 2);
+        const end = payload.offset + count;
+        const page = typeof target === "string" ? target.slice(payload.offset, end) : target.slice(payload.offset, end);
+        const nextCursor = end < total ? encodeCursor(secret, { ...payload, offset: end }) : undefined;
+        const candidate = {
+            ...withPageTarget(value, path, page),
+            ...(nextCursor === undefined ? {} : { nextCursor }),
+        };
+        if (resultEnvelopeBytes(candidate) <= MCP_MAX_SERIALIZED_RESULT_BYTES) {
+            best = candidate;
+            low = count + 1;
+        }
+        else {
+            high = count - 1;
+        }
+    }
+    if (best === undefined)
+        throw tooLargeError(tool);
+    return best;
+}
+// One line per failing field: keep the first message per path, then collapse array indexes so repeated mistakes such as
+// "/decisionRecords/*/alternatives/*/benefits Expected string" appear once with a count.
+function validationIssues(details, limit = 8) {
+    const firstByPath = new Map();
+    for (const { path, message } of details) {
+        if (!firstByPath.has(String(path)))
+            firstByPath.set(String(path), String(message));
+    }
+    const groups = new Map();
+    for (const [path, message] of firstByPath) {
+        const pattern = path.replace(/\/\d+(?=\/|$)/gu, "/*");
+        const group = groups.get(`${pattern}\u0000${message}`);
+        if (group === undefined)
+            groups.set(`${pattern}\u0000${message}`, { path, message, count: 1 });
+        else
+            Object.assign(group, { path: pattern, count: group.count + 1 });
+    }
+    const lines = [...groups.values()].map(({ path, message, count }) => count === 1 ? `${path} ${message}` : `${path} ${message} (${count} places)`);
+    return lines.length > limit ? [...lines.slice(0, limit), `${lines.length - limit} more`] : lines;
+}
 const uniqueStrings = z
     .array(z.string().min(1))
     .min(1)
@@ -66,8 +407,9 @@ const projectCreateInput = z
     projectId: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
     displayName: z.string().min(1).max(256),
     environment: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
-    targetScope: z.string().min(1).max(1024).optional(),
+    targetScope: z.string().max(1024).regex(TARGET_SCOPE_PATTERN, `Use ${TARGET_SCOPE_HINT}`),
     iacTool: z.enum(["bicep", "terraform"]),
+    riskOwner: z.enum(["partner", "customer"]),
 })
     .strict();
 const projectIdInput = z.object({ projectId: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/) }).strict();
@@ -103,8 +445,9 @@ const reviewDecisionInput = z
         .array(z
         .object({
         findingId: z.string().min(1),
-        action: z.enum(["revise", "accept-risk"]),
-        rationale: z.string().min(1),
+        action: z.enum(["revise", "accept-risk", "acknowledge", "dismiss"]),
+        rationale: z.string().min(1).optional(),
+        owner: z.string().min(1).optional(),
         expiresAt: z.string().datetime().optional(),
     })
         .strict())
@@ -116,68 +459,321 @@ const normalizeOutputs = (outputs) => outputs.map(({ kind, value, summary }) =>
     value,
     ...(summary === undefined ? {} : { summary }),
 }));
-export function createMcpServer(service) {
-    const server = new McpServer({ name: "apex", version: APEX_VERSION });
-    const result = (value) => ({
-        content: [{ type: "text", text: JSON.stringify(value) }],
-        structuredContent: value,
+/**
+ * Builds the APEX MCP tool table and shared call state once, and returns a cheap, side-effect-free factory for
+ * low-level SDK `Server` instances. Every instance from one factory shares the service resolver, single-slot queue,
+ * rate limit, and cursor secret, so per-connection (stdio) and per-request (HTTP) instances behave as one server.
+ */
+export function createMcpServerFactory(serviceOrResolver, options = {}) {
+    const services = serviceResolver(serviceOrResolver);
+    let activeService = services.defaultService;
+    const service = new Proxy(services.defaultService, {
+        get(target, property, receiver) {
+            const actual = activeService ?? target;
+            const value = Reflect.get(actual, property, receiver);
+            return typeof value === "function" ? value.bind(actual) : value;
+        },
     });
-    server.registerTool("status", { description: "Read selected APEX run status" }, async () => result(await service.status()));
-    server.registerTool("capabilityList", { description: "Read capability pack availability" }, async () => result(await service.capabilityList()));
-    server.registerTool("capabilityStatus", { description: "Read one capability pack status", inputSchema: { pack: z.string() } }, async ({ pack }) => result(await service.capabilityStatus(pack)));
-    server.registerTool("nextTask", {
-        description: "Get the next workflow result. Handle needs_input before requesting context; only status=task returns a task.taskId.",
+    const queueTimeoutMs = options.queueTimeoutMs ?? 30_000;
+    if (!Number.isSafeInteger(queueTimeoutMs) || queueTimeoutMs < 1 || queueTimeoutMs > 30_000)
+        throw new Error("Invalid MCP queue timeout");
+    // Cursors are only valid for the server process that issued them; a restart invalidates every outstanding cursor.
+    const cursorSecret = randomBytes(32);
+    const result = (value) => {
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            throw new Error("MCP success results require an object envelope");
+        return {
+            content: [{ type: "text", text: JSON.stringify(value) }],
+            structuredContent: value,
+        };
+    };
+    const tools = new Map();
+    const toolDefinitions = [];
+    let active = false;
+    const waiting = [];
+    const release = () => {
+        const next = waiting.shift();
+        if (next === undefined)
+            active = false;
+        else
+            next.start();
+    };
+    const acquire = (signal) => {
+        if (signal?.aborted)
+            return Promise.reject(new ApexError("APEX_CONFLICT", "Cancelled", EXIT_CODES.conflict));
+        if (!active) {
+            active = true;
+            return Promise.resolve(release);
+        }
+        if (waiting.length >= 31)
+            return Promise.reject(new ApexError("APEX_CONFLICT", "Queue full", EXIT_CODES.conflict));
+        return new Promise((resolve, reject) => {
+            const cleanup = () => {
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", cancel);
+            };
+            const cancel = () => {
+                const index = waiting.indexOf(waiter);
+                if (index < 0)
+                    return;
+                waiting.splice(index, 1);
+                cleanup();
+                reject(new ApexError("APEX_CONFLICT", "Queue cancelled or expired", EXIT_CODES.conflict));
+            };
+            const waiter = {
+                start: () => {
+                    cleanup();
+                    resolve(release);
+                },
+            };
+            const timer = setTimeout(cancel, queueTimeoutMs);
+            waiting.push(waiter);
+            signal?.addEventListener("abort", cancel, { once: true });
+            if (signal?.aborted)
+                cancel();
+        });
+    };
+    let rateWindowStart = Date.now();
+    let rateCount = 0;
+    function registerTool(name, config, callback) {
+        if (tools.has(name))
+            throw new Error(`Duplicate MCP tool ${name}`);
+        const outputSchema = MCP_OUTPUT_SCHEMAS[name];
+        if (outputSchema === undefined)
+            throw new Error(`Missing output schema for ${name}`);
+        const effect = MCP_TOOL_EFFECTS[name];
+        if (effect === undefined)
+            throw new Error(`Missing effect class for ${name}`);
+        const fileArguments = repeatFileArguments[name];
+        const originalInputSchema = config.inputSchema === undefined
+            ? z.object({}).strict()
+            : config.inputSchema instanceof z.ZodObject
+                ? config.inputSchema.strict().meta(config.inputSchema.meta() ?? {})
+                : z.object(config.inputSchema).strict();
+        const inputSchema = originalInputSchema
+            .extend({ workspace: workspaceInput })
+            .strict()
+            .meta(originalInputSchema.meta() ?? {});
+        const guarded = async (args, signal) => {
+            const extra = { signal };
+            const checkCancelled = () => {
+                if (signal.aborted)
+                    throw new ApexError("APEX_CONFLICT", "Cancelled", EXIT_CODES.conflict);
+            };
+            let releaseSlot;
+            let serviceValidation;
+            try {
+                checkCancelled();
+                if (Date.now() - rateWindowStart >= 60_000) {
+                    rateWindowStart = Date.now();
+                    rateCount = 0;
+                }
+                if (++rateCount > 240)
+                    throw new ApexError("APEX_CONFLICT", "Call rate exceeded", EXIT_CODES.conflict);
+                assertBoundedInput(args);
+                const input = inputSchema.safeParse(args);
+                if (!input.success) {
+                    const issues = validationIssues(input.error.issues.map(({ path, message }) => ({ path: `/${path.map(String).join("/")}`, message })));
+                    const reason = issues.length === 0 ? "Invalid tool arguments" : `Invalid tool arguments: ${issues.join("; ")}`;
+                    if (!SECRET_VALUE_PATTERN.test(reason))
+                        serviceValidation = reason;
+                    throw new ApexError("APEX_VALIDATION", "Invalid tool arguments", EXIT_CODES.validation);
+                }
+                releaseSlot = await acquire(signal);
+                checkCancelled();
+                const { workspace, ...toolInput } = input.data;
+                const resolved = await services.resolve(workspace);
+                // Every tool call passes this one runtime binding check before the service is touched. An initialized
+                // workspace must be locked to exactly this runtime version; only read-only status reports a mismatch.
+                const binding = await workspaceRuntimeBinding(resolved.service.root);
+                if (binding.state === "mismatch" && name !== "status")
+                    throw runtimeMismatchError(binding);
+                resolved.service.setWorkspacePath?.(resolved.workspace);
+                activeService = resolved.service;
+                let response;
+                try {
+                    const execute = async () => binding.state === "mismatch"
+                        ? result(runtimeMismatchStatus(binding))
+                        : await Reflect.apply(callback, undefined, config.inputSchema === undefined ? [extra] : [toolInput, extra]);
+                    // The adapter only describes the call; the kernel repeat guard behind the service decides whether a repeat
+                    // is answered from the original result. A result that would fail the contract checks below is rejected
+                    // before the guard can store it, so a failed call is never replayed.
+                    response =
+                        effect === "repeat-guarded"
+                            ? result(await resolved.service.repeatSafe({
+                                operation: name,
+                                arguments: toolInput,
+                                ...(fileArguments === undefined ? {} : { fileArguments }),
+                            }, async () => {
+                                const value = (await execute()).structuredContent;
+                                if (!outputSchema.safeParse(value).success)
+                                    throw new Error("Invalid MCP result contract");
+                                if (resultEnvelopeBytes(value) > MCP_MAX_SERIALIZED_RESULT_BYTES)
+                                    throw tooLargeError(name);
+                                // Apply the final result budget before the guard can store the value, so a result the adapter
+                                // rejects is never replayed.
+                                assertBoundedInput(value);
+                                return value;
+                            }, signal))
+                            : effect === "read-only"
+                                ? await execute()
+                                : effect === "read"
+                                    ? await resolved.service.withWorkspaceReadLock(execute, signal)
+                                    : await resolved.service.withWorkspaceWriteLock(execute, signal);
+                }
+                catch (error) {
+                    const normalized = normalizeError(error);
+                    const governance = typeof normalized.details?.reason === "string" &&
+                        normalized.details.reason.startsWith("GOVERNANCE_");
+                    if (normalized.code === "APEX_VALIDATION" || governance) {
+                        const issues = validationIssues(Array.isArray(normalized.details)
+                            ? normalized.details
+                            : []);
+                        const reason = issues.length === 0 ? normalized.message : `${normalized.message}: ${issues.join("; ")}`;
+                        if (!SECRET_VALUE_PATTERN.test(reason))
+                            serviceValidation = reason;
+                    }
+                    if (normalized.code === "APEX_WRITER_CONFLICT" && !SECRET_VALUE_PATTERN.test(normalized.message)) {
+                        serviceValidation = normalized.message;
+                    }
+                    if (normalized.code === "APEX_WORKSPACE_UNSUPPORTED" && !SECRET_VALUE_PATTERN.test(normalized.message)) {
+                        serviceValidation = normalized.message;
+                    }
+                    throw error;
+                }
+                if (response.structuredContent === undefined)
+                    throw new Error("MCP success results require structuredContent");
+                response.structuredContent = applyResultPaging(cursorSecret, name, resolved.workspace, toolInput, response.structuredContent);
+                response.content = [{ type: "text", text: JSON.stringify(response.structuredContent) }];
+                assertBoundedInput(response.structuredContent);
+                if (!outputSchema.safeParse(response.structuredContent).success)
+                    throw new Error("Invalid MCP result contract");
+                return response;
+            }
+            catch (error) {
+                const normalized = normalizeError(error);
+                const { code } = normalized;
+                if (serviceValidation === undefined &&
+                    (code === "APEX_WRITER_CONFLICT" ||
+                        code === "APEX_WORKSPACE_UNSUPPORTED" ||
+                        code === "APEX_RUNTIME_MISMATCH") &&
+                    !SECRET_VALUE_PATTERN.test(normalized.message)) {
+                    serviceValidation = normalized.message;
+                }
+                // Input-schema and kernel validation reasons let agents correct typed input; guard, internal and secret-like
+                // messages stay generic.
+                const message = serviceValidation === undefined ? errorMessages[code] : serviceValidation.slice(0, 2_000);
+                return {
+                    ...result({ error: { code, message, remediation: remediationForApexError(normalized) } }),
+                    isError: true,
+                };
+            }
+            finally {
+                releaseSlot?.();
+            }
+        };
+        const inputJson = z.toJSONSchema(inputSchema, { target: "draft-7", io: "input" });
+        const annotations = {
+            readOnlyHint: readOnlyTools.has(name),
+            destructiveHint: !readOnlyTools.has(name),
+            idempotentHint: readOnlyTools.has(name),
+            openWorldHint: externalTools.has(name),
+        };
+        const definition = {
+            name,
+            ...(config.description === undefined ? {} : { description: config.description }),
+            inputSchema: inputJson,
+            outputSchema: z.toJSONSchema(outputSchema, { target: "draft-7" }),
+            annotations,
+        };
+        toolDefinitions.push(definition);
+        tools.set(name, { definition, call: guarded });
+    }
+    registerTool("status", { description: "Read selected APEX run status" }, async () => result(await service.workspaceStatus()));
+    registerTool("releaseWriter", { description: "Release this workspace's writer lease for the selected run." }, async () => result(await service.releaseWriter()));
+    registerTool("capabilityList", { description: "Read capability pack availability" }, async () => result({ packs: await service.capabilityList() }));
+    registerTool("capabilityStatus", { description: "Read one capability pack status", inputSchema: { pack: z.string() } }, async ({ pack }) => result(await service.capabilityStatus(pack)));
+    registerTool("nextTask", {
+        description: "Advance the workflow by issuing a request or task; this can write state and is not retry-safe. For status=needs_input, collect answers and call recordInput; for status=needs_review, present findings and call reviewDecide with the user's decisions. Only status=task returns a task.taskId for taskContext. Do not poll unresolved input or review results.",
     }, async () => result(await service.nextTask()));
-    server.registerTool("taskContext", {
+    registerTool("taskContext", {
         description: "Read context only for the exact task.taskId returned by nextTask with status=task.",
-        inputSchema: { taskId: z.string() },
+        inputSchema: { taskId: z.string(), cursor: cursorInput },
     }, async ({ taskId }) => result(await service.taskContext(taskId)));
-    server.registerTool("readTaskInput", {
-        description: "Read a bounded chunk of the accepted source artifact for an active review task.",
+    registerTool("readTaskInput", {
+        description: "Read authoritative UTF-8-bounded task input; inputHash selects an authorized dependency, review-metadata, or governance-findings:<ARM types> for the enforcing policies an Architecture design must map.",
         inputSchema: {
             taskId: z.string(),
             offset: z.number().int().nonnegative().optional(),
             limit: z.number().int().min(1).max(6_000).optional(),
+            cursor: cursorInput,
+            inputHash: z
+                .union([
+                z.string().regex(/^[0-9a-f]{64}$/u),
+                z.literal("review-metadata"),
+                z.string().regex(/^governance-findings:[A-Za-z0-9./,]{0,2000}$/u),
+            ])
+                .optional(),
         },
-    }, async ({ taskId, offset, limit }) => result(await service.readTaskInput(taskId, offset, limit)));
-    server.registerTool("recordInput", { description: "Record answers for the exact pending kernel input request", inputSchema: inputSubmission }, async (input) => result(await service.recordInput(input)));
-    server.registerTool("projectCreate", {
-        description: "Create and select a new project with its initial environment run",
+    }, async ({ taskId, offset, limit, inputHash }) => result(await service.readTaskInput(taskId, offset, limit, inputHash)));
+    registerTool("recordInput", {
+        description: "Record answers for the exact pending kernel input request",
+        inputSchema: inputSubmission,
+    }, async (input) => result(await service.recordInput(input)));
+    registerTool("governanceImport", {
+        description: "Import governance for the active discovery task: either a reviewed local subscription baseline by path (never its contents) or reference: true for the shipped ALZ Corp reference baseline.",
+        inputSchema: { path: z.string().min(1).optional(), reference: z.literal(true).optional() },
+    }, async ({ path, reference }) => {
+        if ((path === undefined) === (reference === undefined))
+            throw new ApexError("APEX_USAGE", "Provide exactly one of path or reference", EXIT_CODES.usage);
+        return result(await (path === undefined ? service.importGovernanceReference() : service.importGovernanceBaseline(path)));
+    });
+    registerTool("governanceSelect", {
+        description: "Prepare or recall the target governance snapshot reuse/refresh question; only a local path is accepted. Does not import or collect Azure policy.",
+        inputSchema: { path: z.string().min(1), reopen: z.boolean().optional() },
+    }, async ({ path, reopen }) => result(await service.selectGovernanceBaseline(path, ...(reopen === undefined ? [] : [{ reopen }]))));
+    registerTool("projectCreate", {
+        description: "Create and select a new project with its initial environment run. targetScope is the user's explicit choice: local, or a full /subscriptions/<id>/resourceGroups/<name> path.",
         inputSchema: projectCreateInput,
     }, async (input) => result(await service.createProject(input)));
-    server.registerTool("projectList", { description: "List projects in the current workspace" }, async () => result({ projects: await service.listProjects() }));
-    server.registerTool("projectUse", { description: "Select an existing project and optionally one of its runs", inputSchema: projectUseInput }, async ({ projectId, runId }) => result(await service.use(projectId, runId)));
-    server.registerTool("projectDelete", {
+    registerTool("projectList", { description: "List projects in the current workspace", inputSchema: { cursor: cursorInput } }, async () => result({ projects: await service.listProjects() }));
+    registerTool("projectUse", { description: "Select an existing project and optionally one of its runs", inputSchema: projectUseInput }, async ({ projectId, runId }) => result(await service.use(projectId, runId)));
+    registerTool("projectDelete", {
         description: "Delete a project and all of its run-bound state after explicit confirmation",
         inputSchema: projectDeleteInput,
     }, async ({ projectId, confirm }) => result(await service.deleteProject(projectId, confirm)));
-    server.registerTool("gateDecide", {
+    registerTool("gateDecide", {
         description: "Record an explicitly confirmed human decision for Gate 1, 2, or 3 using the local OS username as actor. Gate 4 remains CLI-only.",
         inputSchema: gateDecisionInput,
     }, async ({ gate, decision }) => result(await service.decideInteractiveGate(gate, decision)));
-    server.registerTool("reviewDecide", {
-        description: "Resolve all current review findings atomically by requesting revision or accepting permitted time-bound risk.",
+    registerTool("reviewDecide", {
+        description: "Resolve review findings atomically by revision, Requirements obligation acknowledgment with an owner, or permitted time-bound risk.",
         inputSchema: reviewDecisionInput,
-    }, async ({ reviewHash, decisions }) => result(await service.decideReview(reviewHash, decisions.map(({ expiresAt, ...decision }) => ({
+    }, async ({ reviewHash, decisions }) => result(await service.decideReview(reviewHash, decisions.map(({ rationale, owner, expiresAt, ...decision }) => ({
         ...decision,
+        ...(rationale === undefined ? {} : { rationale }),
+        ...(owner === undefined ? {} : { owner }),
         ...(expiresAt === undefined ? {} : { expiresAt }),
     })))));
-    server.registerTool("stageArtifact", {
-        inputSchema: {
-            taskId: z.string(),
-            kind: artifactKind.optional(),
-            value: z.unknown().optional(),
-            summary: z.string().optional(),
-            outputs: z.array(taskOutput).optional(),
-        },
-    }, async ({ taskId, kind, value, summary, outputs }) => {
-        if (outputs !== undefined)
-            return result(await Promise.all(normalizeOutputs(outputs).map((output) => service.stageArtifact(taskId, output))));
+    registerTool("stageArtifact", {
+        description: "Stage one typed artifact or an outputs[] bundle for the exact active task; staging does not complete the task.",
+        inputSchema: stagingInput(false),
+    }, async ({ taskId, kind, value, summary, outputs }, extra) => {
+        if (outputs !== undefined) {
+            const artifacts = [];
+            for (const output of normalizeOutputs(outputs)) {
+                if (extra.signal.aborted)
+                    throw new ApexError("APEX_CONFLICT", "Cancelled", EXIT_CODES.conflict);
+                artifacts.push(await service.stageArtifact(taskId, output));
+            }
+            return result({ artifacts });
+        }
         if (kind === undefined)
             throw new Error("stageArtifact requires kind/value or outputs[]");
         return result(await service.stageArtifact(taskId, { kind, value, ...(summary === undefined ? {} : { summary }) }));
     });
-    server.registerTool("stageFile", {
+    registerTool("stageFile", {
+        description: "Stage a generated file for the exact active task, optionally checking its expected SHA; does not deploy it.",
         inputSchema: {
             taskId: z.string(),
             path: z.string(),
@@ -188,7 +784,8 @@ export function createMcpServer(service) {
                 .optional(),
         },
     }, async ({ taskId, path, content, expectedSha }) => result(await service.stageFile(taskId, path, content, expectedSha)));
-    server.registerTool("generateIac", {
+    registerTool("generateIac", {
+        description: "Generate IaC and complete the active CodeGen task from accepted inputs and bindings. Success already accepts the manifest and handoff; return the receipt without calling completeTask again. Does not authorize deployment.",
         inputSchema: {
             taskId: z.string(),
             existingResources: z.array(z.string()).optional(),
@@ -202,52 +799,63 @@ export function createMcpServer(service) {
         ...(azapiProviderConstraint === undefined ? {} : { azapiProviderConstraint }),
         ...(lockFileContent === undefined ? {} : { lockFileContent }),
     })));
-    server.registerTool("validateTask", {
-        inputSchema: {
-            taskId: z.string(),
-            kind: artifactKind.optional(),
-            value: z.unknown().optional(),
-            summary: z.string().optional(),
-            outputs: z.array(taskOutput).optional(),
-        },
-    }, async ({ taskId, kind, value, summary, outputs }) => result(await service.validateTask(taskId, outputs === undefined
-        ? kind === undefined
-            ? undefined
-            : { kind, value, ...(summary === undefined ? {} : { summary }) }
-        : normalizeOutputs(outputs))));
-    server.registerTool("completeTask", {
+    registerTool("validateTask", {
+        description: "With only taskId for an IaC validation task, execute native checks and return runtime-owned outputs and execution metadata. valid:false and blockedValidatorIds mean required checks remain unexecuted; do not complete. Supplied artifacts are only checked/staged. Task completion and approval are separate.",
+        inputSchema: stagingInput(true),
+    }, async ({ taskId, kind, value, summary, outputs }, extra) => {
+        if (outputs !== undefined) {
+            const staged = [];
+            for (const output of normalizeOutputs(outputs)) {
+                if (extra.signal.aborted)
+                    throw new ApexError("APEX_CONFLICT", "Cancelled", EXIT_CODES.conflict);
+                const validated = await service.validateTask(taskId, output);
+                if (validated.staged !== undefined)
+                    staged.push(...(Array.isArray(validated.staged) ? validated.staged : [validated.staged]));
+            }
+            return result({ valid: true, taskId, staged });
+        }
+        return result(await service.validateTask(taskId, kind === undefined ? undefined : { kind, value, ...(summary === undefined ? {} : { summary }) }));
+    });
+    registerTool("completeTask", {
         description: "Complete a task atomically with a nonempty outputs[] bundle.",
         inputSchema: {
             taskId: z.string(),
             outputs: z.array(taskOutput).min(1),
         },
     }, async ({ taskId, outputs }) => result(await service.completeTaskOutputs(taskId, normalizeOutputs(outputs))));
-    server.registerTool("requirementsComplete", {
+    registerTool("requirementsComplete", {
         description: "Complete the active Requirements task atomically.",
         inputSchema: { taskId: z.string(), requirements: z.unknown() },
     }, async ({ taskId, requirements }) => result(await service.completeRequirements(taskId, requirements)));
-    server.registerTool("architectureComplete", {
-        description: "Complete the active Architecture task atomically with all required outputs.",
+    registerTool("architectureComplete", {
+        description: "Complete Architecture atomically; APEX derives identity, artifact hashes, top-level requirementTraceability, and cost/SKU bindings. Each SKU and SLO decision lists its component requirementIds. policyMappings maps each governanceFindings entry from task context to a component; APEX marks findings whose resource types match no component resourceTypes not-applicable. A rejection lists every problem across all four inputs.",
         inputSchema: {
             taskId: z.string(),
             architecture: z.unknown(),
             costEstimate: z.unknown(),
             decisionManifest: z.unknown(),
+            policyMappings: z.array(z.unknown()),
         },
-    }, async ({ taskId, architecture, costEstimate, decisionManifest }) => result(await service.completeArchitecture(taskId, architecture, costEstimate, decisionManifest)));
-    server.registerTool("reviewComplete", {
-        description: "Complete the active review task; APEX derives subject identity, hash, timestamp, and evidence binding.",
-        inputSchema: { taskId: z.string(), findings: z.array(reviewFinding) },
-    }, async ({ taskId, findings }) => result(await service.completeReview(taskId, findings)));
-    server.registerTool("planComplete", {
+    }, async ({ taskId, architecture, costEstimate, decisionManifest, policyMappings }) => result(await service.completeArchitecture(taskId, architecture, costEstimate, decisionManifest, policyMappings)));
+    registerTool("reviewComplete", {
+        description: "Complete the active review task from rubber-duck's captured output after running rubber-duck in sync mode with the exact reviewRequest.prompt from taskContext. Takes no findings: APEX derives them only from the verified capture. A missing, edited, replayed or mismatched capture fails closed and the review counts as not done.",
+        inputSchema: { taskId: z.string() },
+    }, async ({ taskId }) => result(await service.completeReview(taskId)));
+    registerTool("planComplete", {
         description: "Atomically complete a plan. Derives the canonical implementation intent hash for the binding; do not supply intentHash.",
         inputSchema: planCompletionInput,
     }, async ({ taskId, implementationIntent, iacBinding, environmentInputs }) => result(await service.completePlan(taskId, implementationIntent, iacBinding, environmentInputs)));
-    server.registerTool("preview", { description: "Read the current operator-created deployment preview" }, async () => result(await service.currentPreview()));
-    server.registerTool("reconcile", {}, async () => result(await service.reconcile()));
-    server.registerTool("inventory", {}, async () => result(await service.inventory()));
-    server.registerTool("diagnose", {}, async () => result(await service.diagnose()));
-    server.registerTool("improvementObserve", {
+    registerTool("preview", { description: "Read the current operator-created deployment preview", inputSchema: { cursor: cursorInput } }, async () => result({ markdown: await service.currentPreview() }));
+    registerTool("reconcile", { description: "Run the kernel-authorized reconciliation operation for the selected run." }, async () => result(await service.reconcile()));
+    registerTool("inventory", {
+        description: "Run the bounded inventory operation for the selected run and return its evidence.",
+        inputSchema: { cursor: cursorInput },
+    }, async () => result(await service.inventory()));
+    registerTool("diagnose", { description: "Run bounded diagnosis for the selected run and return the kernel-recorded result." }, async () => {
+        const { status, doctor } = (await service.diagnose());
+        return result({ status, doctor: summarizeDoctorReport(doctor) });
+    });
+    registerTool("improvementObserve", {
         description: "Submit one bounded redacted observation for the selected run",
         inputSchema: {
             taskId: z.string().optional(),
@@ -281,12 +889,43 @@ export function createMcpServer(service) {
         ...(taskId === undefined ? {} : { taskId }),
         ...(observedAt === undefined ? {} : { observedAt }),
     })));
-    server.registerTool("improvementObservations", { description: "Read bounded observations" }, async () => result(await service.improvementObservations()));
-    server.registerTool("improvementProposals", { description: "Read inert improvement proposals" }, async () => result(await service.improvementProposals()));
-    server.registerTool("render", { inputSchema: { kind: z.enum(["status", "requirements", "preview", "approval", "inventory"]) } }, async ({ kind }) => result(await service.render(kind)));
-    server.registerTool("promote", { inputSchema: { environment: z.string(), target: z.string() } }, async ({ environment, target }) => result(await service.promote(environment, target)));
-    server.registerTool("doctor", { inputSchema: { fix: z.boolean().optional(), yes: z.boolean().optional() } }, async ({ fix, yes }) => result(await service.doctor(fix, yes)));
-    server.registerTool("submitEvidence", {
+    registerTool("improvementObservations", { description: "Read bounded observations", inputSchema: { cursor: cursorInput } }, async () => result({ observations: await service.improvementObservations() }));
+    registerTool("improvementProposals", { description: "Read inert improvement proposals", inputSchema: { cursor: cursorInput } }, async () => result({ proposals: await service.improvementProposals() }));
+    registerTool("render", {
+        description: "Render the selected run's status, requirements, preview, approval, inventory, structured Architecture decisions, implementation plan, plan-bound deployment guide, operational runbook, or evidence-bound deployment summary as a human-readable projection.",
+        inputSchema: {
+            kind: z.enum([
+                "status",
+                "requirements",
+                "preview",
+                "approval",
+                "inventory",
+                "deployment-summary",
+                "deployment-guide",
+                "implementation-plan",
+                "architecture-decisions",
+                "operations-runbook",
+            ]),
+            cursor: cursorInput,
+        },
+    }, async ({ kind }) => result({ markdown: await service.render(kind) }));
+    registerTool("promote", {
+        description: "Promote the selected run to a target environment through kernel checks; does not approve or execute deployment.",
+        inputSchema: { environment: z.string(), target: z.string() },
+    }, async ({ environment, target }) => result(await service.promote(environment, target)));
+    registerTool("doctor", {
+        description: "Inspect local APEX installation health; request repairs with fix and explicit confirmation with yes. Returns counts, remedies, and a bounded check list with failing checks first; when truncated, read every check with doctorChecks.",
+        inputSchema: { fix: z.boolean().optional(), yes: z.boolean().optional() },
+    }, async ({ fix, yes }) => result(summarizeDoctorReport(await service.doctor(fix, yes))));
+    registerTool("doctorChecks", {
+        description: "Read every local APEX installation health check without repairing; failedOnly limits the list to failing checks.",
+        inputSchema: { failedOnly: z.boolean().optional(), cursor: cursorInput },
+    }, async ({ failedOnly }) => {
+        const { checks } = await service.doctor();
+        return result({ checks: failedOnly === true ? checks.filter(({ ok }) => !ok) : checks });
+    });
+    registerTool("submitEvidence", {
+        description: "Submit JSON evidence bound to the exact active task after validating its context; does not complete the task.",
         inputSchema: {
             taskId: z.string(),
             kind: z.string(),
@@ -297,9 +936,83 @@ export function createMcpServer(service) {
         await service.taskContext(taskId);
         return result(await service.acceptEvidence({ kind, contentType: "application/json", value, required: required ?? false }));
     });
-    return server;
+    // Unknown tool names keep the v1-era externally visible shape (an isError tool result, not a JSON-RPC error), now
+    // as the standard APEX error envelope so clients parse one error contract.
+    const unknownTool = (name) => {
+        const label = typeof name === "string" && /^[A-Za-z][A-Za-z0-9_-]{0,63}$/u.test(name) ? ` ${name}` : "";
+        const error = new ApexError("APEX_USAGE", `Unknown tool${label}; call tools/list for available tools`, EXIT_CODES.usage);
+        return {
+            ...result({ error: { code: error.code, message: error.message, remediation: remediationForApexError(error) } }),
+            isError: true,
+        };
+    };
+    return () => {
+        const server = new Server({ name: "apex", version: APEX_VERSION }, { capabilities: { tools: {} }, instructions: MCP_SERVER_INSTRUCTIONS });
+        server.setRequestHandler("tools/list", () => ({ tools: toolDefinitions }));
+        server.setRequestHandler("tools/call", async (request, ctx) => {
+            const tool = tools.get(request.params.name);
+            if (tool === undefined)
+                return unknownTool(request.params.name);
+            const response = await tool.call(request.params.arguments ?? {}, ctx.mcpReq.signal);
+            return server.projectCallToolResult(response, tool.definition.outputSchema);
+        });
+        return server;
+    };
 }
-export async function serveMcp(service) {
-    await createMcpServer(service).connect(new StdioServerTransport());
+export function createMcpServer(serviceOrResolver, options = {}) {
+    return createMcpServerFactory(serviceOrResolver, options)();
+}
+/**
+ * Serves APEX over stdio until the connection ends (stdin EOF), the transport fails, or SIGINT/SIGTERM arrives.
+ * `serveStdio` answers `server/discover` for protocol 2026-07-28 and, with `legacy: "serve"`, still serves a 2025-era
+ * `initialize` (including the discover-then-initialize fallback) from the same factory. Stdout stays protocol-only.
+ * A stdin error closes the connection and rejects. `streams` defaults to the process stdio.
+ */
+export async function serveMcp(serviceOrResolver, streams = {}) {
+    const factory = createMcpServerFactory(serviceOrResolver);
+    const stdin = streams.stdin ?? process.stdin;
+    const stdout = streams.stdout ?? process.stdout;
+    await new Promise((resolve, reject) => {
+        let settled = false;
+        let failure;
+        let handle;
+        const signals = ["SIGINT", "SIGTERM"];
+        const cleanup = () => {
+            stdin.off("error", fail);
+            for (const signal of signals)
+                process.off(signal, shutdown);
+        };
+        // Every exit path funnels through the transport closing; a recorded stream failure keeps the promise rejecting.
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if (failure === undefined)
+                resolve();
+            else
+                reject(failure);
+        };
+        const shutdown = () => {
+            void (handle?.close() ?? Promise.resolve()).then(finish, (error) => {
+                failure ??= error instanceof Error ? error : new Error(String(error));
+                finish();
+            });
+        };
+        function fail(error) {
+            failure ??= error;
+            shutdown();
+        }
+        class ApexStdioTransport extends StdioServerTransport {
+            async close() {
+                await super.close();
+                finish();
+            }
+        }
+        stdin.once("error", fail);
+        for (const signal of signals)
+            process.once(signal, shutdown);
+        handle = serveStdio(factory, { legacy: "serve", transport: new ApexStdioTransport(stdin, stdout) });
+    });
 }
 //# sourceMappingURL=mcp.js.map