@automatalabs/workflows 0.42.0 → 0.43.0

package/README.md

@@ -11,14 +11,15 @@ or a registered custom ACP agent — driving the actual subprocess to completion
 
 This package is the **canonical SDK** that the stdio MCP server
 [`@automatalabs/mcp-server`](https://www.npmjs.com/package/@automatalabs/mcp-server) is built on.
-If you want to expose a `workflow` tool to an MCP host (Claude Code, Zed, …), use that package; if
-you want to embed the runner in your own program, use this one.
+Its CLI can also delegate to a build-time embedded copy of that server with the `mcp` subcommand,
+so an MCP host can expose the `workflow` tool without a separate package install. The standalone
+MCP server package remains independently published, while programs embedding the runner continue
+to use this package's workflow/runner APIs.
 
-It is a **programmatic library**, not an MCP stdio server. It is a thin facade over the engine +
-ACP packages and adds ACP-defaulted helpers for ordinary runs (`runDynamicWorkflow`) and
-substitution tests (`runIsolation`). The ACP layer does use `@modelcontextprotocol/sdk` internally
-when it hosts the optional StructuredOutput tool for eligible agents; consumers still interact
-through this SDK's workflow/runner APIs rather than MCP server schemas.
+The SDK itself remains a thin programmatic facade over the engine + ACP packages, with
+ACP-defaulted helpers for ordinary runs (`runDynamicWorkflow`) and substitution tests
+(`runIsolation`). The ACP layer also uses `@modelcontextprotocol/sdk` internally when it hosts the
+optional StructuredOutput tool for eligible agents.
 
 ---
 
@@ -778,6 +779,36 @@ formatHarnessConfigReport(report); // the CLI's human table
 
 ---
 
+## Launching the MCP server — `agentprism-workflows mcp`
+
+Register the bundled stdio server directly from the workflows package; no separate
+`@automatalabs/mcp-server` installation is required:
+
+```json
+{
+  "mcpServers": {
+    "agentprism-workflow": {
+      "command": "npx",
+      "args": ["-y", "@automatalabs/workflows", "mcp"]
+    }
+  }
+}
+```
+
+For the source inner loop, build workflows before launching its compiled CLI:
+
+```bash
+pnpm --filter @automatalabs/workflows build
+node packages/workflows/dist/cli.js mcp
+```
+
+If the embedded bundle is absent in a monorepo checkout, the command falls back to the built
+`packages/mcp-server/dist/cli.js`. A root `pnpm build` therefore also supports development before
+running `node packages/workflows/dist/cli.js mcp`. The independently published
+`@automatalabs/mcp-server` package and `agentprism-workflow` bin remain available.
+
+---
+
 ## Structured output
 
 Pass a JSON Schema to `agent({ schema })` (in a script) or `runner.run(prompt, { schema })` (direct)

package/dist/cli.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
-// The @automatalabs/workflows bin (`agentprism-workflows`). Two subcommands:
+// The @automatalabs/workflows bin (`agentprism-workflows`). Three subcommands:
 //
 //   agentprism-workflows validate <workflow-file> [options]
 //   agentprism-workflows config [harness ...] [options]
+//   agentprism-workflows mcp
 //
 // validate checks a workflow script without spending tokens: static parse (meta literal,
 // syntax, direct nondeterministic call expressions), then a dry run over an in-process
@@ -13,7 +14,12 @@
 // config runs that same no-prompt probe standalone — no script needed — and prints each
 // requested harness's advertised config-option catalog (model ids, effort levels, modes,
 // …). See ./config.ts for the programmatic API (`probeHarnessConfig`).
+//
+// mcp delegates stdio unchanged to the MCP server embedded at build time. In a source
+// checkout without that bundle, it falls back to the separately built mcp-server entry.
+import { spawn } from "node:child_process";
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { constants as osConstants } from "node:os";
 import { resolve } from "node:path";
 import { openWorkflowDir } from "@automatalabs/workflow-engine";
 import { validateWorkflowScript, formatValidateReport } from "./validate.js";
@@ -27,6 +33,7 @@ Commands:
                                     catalog (model ids, effort levels, modes, …) so
                                     model/configOptions values come from the live
                                     catalog, not guesswork
+  mcp                               launch the embedded AgentPrism stdio MCP server
 
 Run \`agentprism-workflows <command> --help\` for that command's options.`;
 const USAGE = `Usage: agentprism-workflows validate <workflow-file-or-name> [options]
@@ -90,6 +97,13 @@ Options:
   -h, --help          show this help
 
 Exit codes: 0 all probed · 1 at least one probe failed · 3 usage error`;
+const MCP_USAGE = `Usage: agentprism-workflows mcp
+
+Launches the embedded AgentPrism MCP server over stdio. stdin and stdout are reserved
+for JSON-RPC framing and are inherited unchanged by the server process.
+
+Options:
+  -h, --help          show this help`;
 let activeCommand = "";
 function fail(message) {
     const hint = activeCommand === "" ? "agentprism-workflows --help" : `agentprism-workflows ${activeCommand} --help`;
@@ -143,6 +157,86 @@ async function mainConfig(rest) {
     writeFileSync(process.stdout.fd, json ? `${JSON.stringify(report, null, 2)}\n` : `${formatHarnessConfigReport(report)}\n`);
     process.exitCode = report.exitCode;
 }
+async function mainMcp(rest) {
+    if (rest.length === 1 && (rest[0] === "-h" || rest[0] === "--help")) {
+        process.stdout.write(`${MCP_USAGE}\n`);
+        process.exit(0);
+    }
+    if (rest.length > 0)
+        fail(`mcp does not accept arguments (received: ${rest.join(" ")})`);
+    const bundlePath = resolve(import.meta.dirname, "mcp-server.js");
+    const monorepoFallbackPath = resolve(import.meta.dirname, "../../mcp-server/dist/cli.js");
+    const serverPath = existsSync(bundlePath)
+        ? bundlePath
+        : existsSync(monorepoFallbackPath)
+            ? monorepoFallbackPath
+            : undefined;
+    if (serverPath === undefined) {
+        fail(`MCP server bundle not found at ${bundlePath}, and the monorepo fallback is not built. ` +
+            "Run `pnpm --filter @automatalabs/workflows build` to create the bundle, or run `pnpm build` at the repository root.");
+    }
+    await new Promise((resolvePromise) => {
+        const child = spawn(process.execPath, [serverPath], { stdio: "inherit" });
+        const forwardedSignals = ["SIGINT", "SIGTERM"];
+        let settled = false;
+        let cleaned = false;
+        const forwarders = new Map();
+        const cleanup = () => {
+            if (cleaned)
+                return;
+            cleaned = true;
+            for (const [signal, forward] of forwarders)
+                process.off(signal, forward);
+            child.off("error", onError);
+            child.off("exit", onExit);
+        };
+        const finish = (action) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            action();
+            resolvePromise();
+        };
+        const onError = (error) => {
+            finish(() => {
+                process.stderr.write(`mcp server failed to start: ${error.message}\n`);
+                process.exitCode = 1;
+            });
+        };
+        const onExit = (code, signal) => {
+            finish(() => {
+                if (signal === null) {
+                    process.exitCode = code ?? 1;
+                    return;
+                }
+                // Preserve signal termination for callers (shells, npx, and MCP hosts). Set a
+                // conventional nonzero fallback first in case re-raising is unsupported here.
+                process.exitCode = 128 + (osConstants.signals[signal] ?? 1);
+                try {
+                    process.kill(process.pid, signal);
+                }
+                catch (error) {
+                    process.stderr.write(`mcp server exited on ${signal}, but the parent could not re-raise it: ${error instanceof Error ? error.message : String(error)}\n`);
+                }
+            });
+        };
+        for (const signal of forwardedSignals) {
+            const forward = () => {
+                try {
+                    child.kill(signal);
+                }
+                catch (error) {
+                    process.stderr.write(`could not forward ${signal} to the mcp server: ${error instanceof Error ? error.message : String(error)}\n`);
+                }
+            };
+            forwarders.set(signal, forward);
+            process.on(signal, forward);
+        }
+        child.once("error", onError);
+        child.once("exit", onExit);
+    });
+}
 async function main(argv) {
     const [command, ...rest] = argv;
     if (command === undefined || command === "-h" || command === "--help") {
@@ -153,8 +247,12 @@ async function main(argv) {
         activeCommand = "config";
         return mainConfig(rest);
     }
+    if (command === "mcp") {
+        activeCommand = "mcp";
+        return mainMcp(rest);
+    }
     if (command !== "validate")
-        fail(`unknown command "${command}" — the commands are: validate, config`);
+        fail(`unknown command "${command}" — the commands are: validate, config, mcp`);
     activeCommand = "validate";
     let file;
     let json = false;