witnora 0.19.0 → 0.19.2

package/README.md

@@ -90,6 +90,20 @@ For a cloud Agent, the customer exposes only this path through its HTTPS ingress
 or private network. This generated endpoint is limited to the current sandbox
 Task/action path; it does not create a production Provider or broader authority.
 
+An MCP client can use the same exact path without receiving either local
+credential. Launch the stdio server from the onboarded repository:
+
+```bash
+npx witnora@latest mcp
+```
+
+It exposes one generated Action tool, for example `witnora_cancel-order`, plus
+`witnora_get_action`. The Agent can propose an Action and inspect its state, but
+there is no MCP approval, direct-execution, or self-verification tool. Human
+approval, customer-owned execution, the separate Probe, Receipt, and
+idempotency contract remain unchanged. See the public [MCP Action integration](https://witnora.com/docs/mcp-actions)
+and [HTTP Actions](https://witnora.com/docs/http-actions) guides.
+
 Initialization writes a reusable `.witnora/gateway/client.mjs`. Import its
 `witnoraGateway.start`, `event`, and `complete` methods at one existing sandbox
 workflow boundary. The generated README contains the exact code and privacy

package/dist/cli.js

@@ -161,6 +161,13 @@ else if (command === "onboard") {
         openBrowser: readBoolFlag("--no-browser") ? async () => { } : undefined,
     });
 }
+else if (command === "mcp") {
+    const { runWitnoraMcpStdioServer } = await import("./mcp.js");
+    await runWitnoraMcpStdioServer({
+        repository: readFlag("--repo") ?? process.cwd(),
+        dir: readFlag("--dir"),
+    });
+}
 else if (command === "release") {
     const action = process.argv[3] ?? "help";
     if (action !== "evaluate")
@@ -862,6 +869,7 @@ else if (command === "conformance") {
 else {
     process.stdout.write(`Usage:
   witnora onboard --project <project-id>
+  witnora mcp
   witnora try --template workflow [--push]
   witnora init --subject my-browser-agent
   witnora connect --server https://witnora.com --project <project-id>

package/dist/command-help.js

@@ -54,6 +54,21 @@ Options:
   --repo <directory>      Repository to configure (default: current directory)
   --template <type>       Override automatic repository detection
   --no-browser            Print the approval URL without opening it
+`;
+    if (command === "mcp")
+        return `Usage:
+  witnora mcp [--repo <agent-repository>] [--dir <gateway-directory>]
+
+Starts a local stdio MCP server for the one exact sandbox HTTP Action generated
+by onboarding. The MCP process reads ignored Gateway credentials locally; they
+are never exposed as tool inputs. The Agent can propose and inspect an Action,
+but cannot approve it, execute outside the customer Gateway, or self-assert an
+independently verified result.
+
+Options:
+  --repo <directory>      Onboarded Agent repository (default: current directory)
+  --dir <directory>       Gateway directory relative to the repo (default: .witnora/gateway)
+  --help, -h              Show this help without starting the MCP server
 `;
     if (command === "gateway")
         return `Usage:

package/dist/gateway.js

@@ -1463,6 +1463,21 @@ async function loadConfiguredCustomerHttpAction(directory, gateway) {
         throw new Error("Customer HTTP Action token is missing or invalid.");
     return { action, token };
 }
+export async function loadCustomerMcpActionBinding(options = {}) {
+    const directory = resolve(options.repository ?? process.cwd(), options.dir ?? ".witnora/gateway");
+    const gateway = parseConfig(await readFile(join(directory, "gateway.json"), "utf8"));
+    const configured = await loadConfiguredCustomerHttpAction(directory, gateway);
+    if (!configured) {
+        throw new Error("Witnora MCP requires one configured sandbox HTTP Action. Run onboarding for one exact Task/action path first.");
+    }
+    const secrets = parseSecrets(await readFile(join(directory, "secrets.json"), "utf8"));
+    return {
+        baseUrl: `http://${gateway.host}:${gateway.port}`,
+        action: configured.action,
+        actionToken: configured.token,
+        gatewayToken: secrets.gatewayToken,
+    };
+}
 export function createCustomerHttpActionConfig(activations) {
     if (activations.length !== 1)
         return undefined;

package/dist/index.js

@@ -9,6 +9,7 @@ export * from "./failure-review.js";
 export * from "./evidence-signing.js";
 export * from "./local-server.js";
 export * from "./monitor.js";
+export * from "./mcp.js";
 export * from "./onboard.js";
 export * from "./normalizers.js";
 export * from "./report.js";

package/dist/mcp.js

@@ -0,0 +1,91 @@
+import { createHash } from "node:crypto";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { loadCustomerMcpActionBinding, } from "./gateway.js";
+const IDENTIFIER = /^[A-Za-z0-9._:-]{1,160}$/;
+const STATUS = /^[A-Za-z0-9._:-]{1,100}$/;
+export function createWitnoraMcpServer(options) {
+    if (options.action.environment !== "sandbox" || options.action.actionPathId !== options.action.id) {
+        throw new Error("Witnora MCP accepts one exact sandbox Task/action binding only.");
+    }
+    const actionTool = witnoraMcpActionToolName(options.action.id);
+    const server = new McpServer({ name: "witnora", version: "0.1.0" });
+    const issuedActionIds = new Set();
+    server.registerTool(actionTool, {
+        description: `Propose the exact ${options.action.actionPathId} sandbox action through the customer-owned Witnora Gateway. This tool cannot approve its own action. A result is proved only after the independent Probe and signed Receipt are present.`,
+        inputSchema: {
+            idempotencyKey: z.string().regex(IDENTIFIER).describe("Stable external request ID. Reuse it only for an exact retry."),
+            resourceId: z.string().regex(IDENTIFIER).describe("The exact sandbox resource covered by this action path."),
+            status: z.string().regex(STATUS).optional().describe(`Requested state. Defaults to ${options.action.defaultStatus}.`),
+        },
+    }, async (input) => {
+        const action = await options.transport.propose(input);
+        const actionId = typeof action.id === "string" && IDENTIFIER.test(action.id) ? action.id : undefined;
+        if (!actionId)
+            throw new Error("Witnora Gateway returned an Action without a valid Action ID.");
+        issuedActionIds.add(actionId);
+        return toolResult(action);
+    });
+    server.registerTool("witnora_get_action", {
+        description: "Read the current Action, approval, execution, Probe, and Receipt state. Reported success is not an independently verified outcome.",
+        inputSchema: {
+            actionId: z.string().regex(IDENTIFIER),
+        },
+    }, async ({ actionId }) => {
+        if (!issuedActionIds.has(actionId)) {
+            throw new Error("This MCP session can inspect only Actions returned by its exact sandbox Action tool. Retry the exact proposal first after a restart.");
+        }
+        return toolResult(await options.transport.getAction(actionId));
+    });
+    return server;
+}
+export async function createWitnoraMcpServerFromRepository(options = {}) {
+    const binding = await loadCustomerMcpActionBinding(options);
+    return {
+        server: createWitnoraMcpServer({ action: binding.action, transport: gatewayTransport(binding, options.fetch ?? fetch) }),
+        actionTool: witnoraMcpActionToolName(binding.action.id),
+        action: binding.action,
+    };
+}
+export async function runWitnoraMcpStdioServer(options = {}) {
+    const { server } = await createWitnoraMcpServerFromRepository(options);
+    await server.connect(new StdioServerTransport());
+}
+export function witnoraMcpActionToolName(actionId) {
+    const normalized = actionId.toLowerCase().replace(/[^a-z0-9_-]+/g, "_").replace(/^_+|_+$/g, "") || "action";
+    const candidate = `witnora_${normalized}`;
+    if (candidate.length <= 96)
+        return candidate;
+    const suffix = createHash("sha256").update(actionId).digest("hex").slice(0, 10);
+    return `${candidate.slice(0, 85)}_${suffix}`;
+}
+function gatewayTransport(binding, requestFetch) {
+    return {
+        propose: ({ idempotencyKey, resourceId, status }) => requestJson(requestFetch, `${binding.baseUrl}${binding.action.path}`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${binding.actionToken}`,
+                "content-type": "application/json",
+                "idempotency-key": idempotencyKey,
+            },
+            body: JSON.stringify({ resourceId, ...(status === undefined ? {} : { status }) }),
+        }),
+        getAction: (actionId) => requestJson(requestFetch, `${binding.baseUrl}/v1/actions/${encodeURIComponent(actionId)}`, { headers: { authorization: `Bearer ${binding.gatewayToken}` } }),
+    };
+}
+async function requestJson(requestFetch, url, init) {
+    const response = await requestFetch(url, { ...init, signal: init.signal ?? AbortSignal.timeout(10_000) });
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok) {
+        const message = typeof body.error === "string" ? body.error : `Witnora Gateway returned HTTP ${response.status}.`;
+        throw new Error(message.slice(0, 500));
+    }
+    return body;
+}
+function toolResult(value) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+        structuredContent: value,
+    };
+}

package/dist/onboard.js

@@ -311,7 +311,7 @@ export async function runOnboard(options) {
             ? "Runtime: LOCAL_SANDBOX_READY. This proves only the generated localhost sandbox loop is ready; it does not establish coverage, CURRENT, or a verified customer outcome.\n"
             : `Runtime: RECORDED_ONLY. ${runtimeReadiness.limitations[0]}\n`);
         output(assuranceHarnessReadiness.state === "ACTIVE"
-            ? `Assurance Harness: ACTIVE. Nora can dispatch authority-ready Replay and no-write Shadow evaluations without manual Workflow IDs, evaluator origins, credentials, or contract digests.${realPathActivation.activations.length ? ` ${realPathActivation.activations.length} exact Stripe test-mode real-path binding(s) passed read-only preflight.` : ""}\n`
+            ? `Assurance Harness: ACTIVE. Nora can dispatch authority-ready Replay and no-write Shadow evaluations without manual Workflow IDs, evaluator origins, credentials, or contract digests.${realPathActivation.activations.length ? ` ${realPathActivation.activations.length} exact sandbox real-path binding(s) passed read-only preflight.` : ""}\n`
             : `Assurance Harness: WAITING_FOR_CUSTOMER_HARNESS. ${assuranceHarnessReadiness.limitation}\n`);
         if (httpActionSetup?.state === "READY" && httpActionSetup.action) {
             output(`HTTP Action: READY. POST ${managedGateway.baseUrl}${httpActionSetup.action.path}; copy the action-scoped token and request example from .witnora/gateway/HTTP_ACTION.md.\n`);

package/dist/real-path-activation.js

@@ -12,7 +12,7 @@ export async function activateRealPathIntegrations(options) {
         throw new Error(`Could not load approved real-path integrations (${response.status}).`);
     const body = await boundedJson(response);
     const approved = Array.isArray(body.integrations) ? body.integrations.map(parsePlan).filter((plan) => plan.status === "READY_TO_ACTIVATE" || plan.status === "HARNESS_ACTIVE") : [];
-    const plans = approved.filter((plan) => ["STRIPE_REFUND", "SHOPIFY_DISPUTE", "ZENDESK_TICKET", "SALESFORCE_RECORD", "HUBSPOT_CRM_RECORD", "POSTGRES_RECORD"].includes(plan.generated.providerPackId) && plan.environment === "sandbox" && plan.customerSummary.evaluationMode === "SHADOW");
+    const plans = approved.filter((plan) => ["STRIPE_REFUND", "SHOPIFY_DISPUTE", "ZENDESK_TICKET", "SALESFORCE_RECORD", "HUBSPOT_CRM_RECORD", "POSTGRES_RECORD", "QUEUE_JOB"].includes(plan.generated.providerPackId) && plan.environment === "sandbox" && plan.customerSummary.evaluationMode === "SHADOW");
     if (!plans.length)
         return { state: "NOT_CONFIGURED", created: false, activations: [], generatedFiles: [], rollback: async () => undefined };
     const environment = options.env ?? process.env;
@@ -91,6 +91,8 @@ async function providerPreflight(request, env, plan, now, postgresClientFactory)
     }
     if (plan.generated.providerPackId === "SHOPIFY_DISPUTE")
         return shopifyDisputePreflight(request, env, plan, now);
+    if (plan.generated.providerPackId === "QUEUE_JOB" && plan.environment === "sandbox")
+        return localSandboxFixturePreflight(plan, now, "queue-job", "queue-job-sandbox");
     if (plan.generated.providerPackId === "ZENDESK_TICKET")
         return zendeskPreflight(request, env, plan, now);
     if (plan.generated.providerPackId === "SALESFORCE_RECORD")
@@ -124,10 +126,13 @@ async function shopifyDisputePreflight(request, env, plan, now) {
     return preflightResult(plan, now, "shopify", id, observation);
 }
 function shopifySandboxFixturePreflight(plan, now) {
-    const resourceId = `sellershield-dispute-${sha(plan.taskContractDigestSha256).slice(0, 16)}`;
+    return localSandboxFixturePreflight(plan, now, "sellershield-dispute", "shopify-sandbox");
+}
+function localSandboxFixturePreflight(plan, now, resourcePrefix, scenarioPrefix) {
+    const resourceId = `${resourcePrefix}-${sha(plan.taskContractDigestSha256).slice(0, 16)}`;
     const observation = { status: plan.generated.criterion.expected };
     const resultDigest = sha(canonical(observation));
-    return { acceptance: { kind: "READ_ONLY_PROVIDER_PREFLIGHT", passedAt: now.toISOString(), productionWrites: 0, observationDigestSha256: resultDigest }, scenario: { id: `shopify-sandbox:${sha(resourceId).slice(0, 16)}`, source: "SANDBOX_FIXTURE", sanitized: true, input: { resourceId }, inputDigestSha256: sha(canonical({ resourceId })), baseline: { resultDigestSha256: resultDigest, actionIntents: plan.generated.actionPathBindings.map((item) => ({ pathId: item.actionPathId, parametersDigestSha256: sha(resourceId) })) } } };
+    return { acceptance: { kind: "READ_ONLY_PROVIDER_PREFLIGHT", passedAt: now.toISOString(), productionWrites: 0, observationDigestSha256: resultDigest }, scenario: { id: `${scenarioPrefix}:${sha(resourceId).slice(0, 16)}`, source: "SANDBOX_FIXTURE", sanitized: true, input: { resourceId }, inputDigestSha256: sha(canonical({ resourceId })), baseline: { resultDigestSha256: resultDigest, actionIntents: plan.generated.actionPathBindings.map((item) => ({ pathId: item.actionPathId, parametersDigestSha256: sha(resourceId) })) } } };
 }
 async function stripePreflight(request, secret, plan, now) {
     const response = await request("https://api.stripe.com/v1/refunds?limit=1", { headers: { authorization: `Bearer ${secret}` }, redirect: "error", signal: AbortSignal.timeout(5_000) });
@@ -240,7 +245,7 @@ async function postgresPreflight(env, plan, now, clientFactory) {
 }
 async function defaultPostgresClient(connectionString) { const imported = await import("pg"); return new imported.Client({ connectionString, application_name: "witnora-read-only-preflight" }); }
 function generatedProviderHarness(plans) {
-    const contracts = plans.map((plan) => ({ taskContractId: plan.taskContractId, providerPackId: plan.generated.providerPackId, providerConfiguration: plan.generated.providerConfiguration ?? {}, credentialHandle: `.witnora/provider-credentials/${plan.id}.secret`, criterion: plan.generated.criterion, actionPathIds: plan.generated.actionPathBindings.map((item) => item.actionPathId), ...(plan.generated.providerPackId === "SHOPIFY_DISPUTE" && plan.environment === "sandbox" && plan.generated.providerConfiguration === undefined ? { sandboxObservation: { [plan.generated.criterion.field]: plan.generated.criterion.expected } } : {}) }));
+    const contracts = plans.map((plan) => ({ taskContractId: plan.taskContractId, providerPackId: plan.generated.providerPackId, providerConfiguration: plan.generated.providerConfiguration ?? {}, credentialHandle: `.witnora/provider-credentials/${plan.id}.secret`, criterion: plan.generated.criterion, actionPathIds: plan.generated.actionPathBindings.map((item) => item.actionPathId), ...((plan.generated.providerPackId === "SHOPIFY_DISPUTE" && plan.environment === "sandbox" && plan.generated.providerConfiguration === undefined) || (plan.generated.providerPackId === "QUEUE_JOB" && plan.environment === "sandbox") ? { sandboxObservation: { [plan.generated.criterion.field]: plan.generated.criterion.expected } } : {}) }));
     return `import {createHash} from "node:crypto";
 import {readFile} from "node:fs/promises";
 import {join} from "node:path";
@@ -258,6 +263,8 @@ export async function checkWitnoraProviderHealth(context){for(const contract of
 async function persistProviderCredential(repository, plan, environment) {
     if (plan.generated.providerPackId === "SHOPIFY_DISPUTE" && plan.environment === "sandbox" && plan.generated.providerConfiguration === undefined)
         return;
+    if (plan.generated.providerPackId === "QUEUE_JOB" && plan.environment === "sandbox")
+        return;
     const name = providerCredentialEnvironmentName(plan.generated.providerPackId);
     const value = environment[name];
     const directory = join(repository, ".witnora", "provider-credentials");

package/mcp.d.ts

@@ -0,0 +1,42 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+export interface WitnoraMcpActionConfig {
+  id: string;
+  actionPathId: string;
+  defaultStatus: string;
+  environment: "sandbox";
+}
+
+export interface WitnoraMcpActionTransport {
+  propose(input: {
+    idempotencyKey: string;
+    resourceId: string;
+    status?: string;
+  }): Promise<Record<string, unknown>>;
+  getAction(actionId: string): Promise<Record<string, unknown>>;
+}
+
+export interface WitnoraMcpServerOptions {
+  action: WitnoraMcpActionConfig;
+  transport: WitnoraMcpActionTransport;
+}
+
+export function createWitnoraMcpServer(options: WitnoraMcpServerOptions): McpServer;
+
+export function createWitnoraMcpServerFromRepository(options?: {
+  repository?: string;
+  dir?: string;
+  fetch?: typeof fetch;
+}): Promise<{
+  server: McpServer;
+  actionTool: string;
+  action: WitnoraMcpActionConfig;
+}>;
+
+export function runWitnoraMcpStdioServer(options?: {
+  repository?: string;
+  dir?: string;
+  fetch?: typeof fetch;
+}): Promise<void>;
+
+export function witnoraMcpActionToolName(actionId: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "witnora",
-  "version": "0.19.0",
+  "version": "0.19.2",
   "description": "Independent assurance for covered agent action paths across models and frameworks.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -36,6 +36,10 @@
   },
   "exports": {
     "./cli": "./dist/cli.js",
+    "./mcp": {
+      "types": "./mcp.d.ts",
+      "import": "./dist/mcp.js"
+    },
     "./browser-adapter-kit": {
       "types": "./dist/vendor/onegent-runtime/browser-adapter-kit.d.ts",
       "import": "./dist/vendor/onegent-runtime/browser-adapter-kit.js"
@@ -63,6 +67,7 @@
   },
   "files": [
     "dist",
+    "mcp.d.ts",
     "README.md",
     "LICENSE",
     "package.json"
@@ -82,6 +87,8 @@
     "vitest": "^4.0.13"
   },
   "optionalDependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "zod": "^4.3.6",
     "pg": "^8.16.3"
   }
 }