@stigmer/cli 3.0.8

package/src/resources/apply/synth/runtime.ts

@@ -0,0 +1,39 @@
+// Runtime inference for SDK project synthesis.
+//
+// A project's `entry_point` extension determines which language runtime executes
+// it — there is no explicit `runtime` field (the proto enum was removed; the
+// extension is the single source of truth). Port of the Go CLI's
+// `internal/cli/apply/runtime.go`; the extension table is kept in lockstep with
+// the backend's `supportedEntryPointExtensions` (project validator).
+
+import { extname } from "node:path";
+import { UsageError } from "../../../errors/index.js";
+
+/** Language runtime used to execute an SDK entry point. */
+export type Runtime = "go" | "python" | "node";
+
+// Extension → runtime. Keep in sync with the backend project validator and Go's
+// extensionToRuntime.
+const EXTENSION_TO_RUNTIME: ReadonlyMap<string, Runtime> = new Map([
+  [".go", "go"],
+  [".py", "python"],
+  [".ts", "node"],
+  [".js", "node"],
+  [".mts", "node"],
+  [".mjs", "node"],
+]);
+
+/**
+ * Infer the runtime from an entry point's file extension. Throws a UsageError
+ * listing the supported extensions when the extension is unrecognized.
+ */
+export function inferRuntime(entryPoint: string): Runtime {
+  const ext = extname(entryPoint).toLowerCase();
+  const runtime = EXTENSION_TO_RUNTIME.get(ext);
+  if (runtime !== undefined) return runtime;
+
+  const supported = [...EXTENSION_TO_RUNTIME.keys()].join(", ");
+  throw new UsageError(
+    `cannot infer runtime from entry point '${entryPoint}' (extension '${ext}')\n\n` + `Supported extensions: ${supported}`,
+  );
+}

package/src/resources/apply/synth/synthesize.test.ts

@@ -0,0 +1,109 @@
+// Synthesize orchestration with an injected spawn: asserts the env/cwd/command
+// handed to the subprocess, the per-runtime command choice, the `.stigmer`
+// output dir, and the actionable errors on non-zero exit / spawn failure /
+// missing inputs.
+
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { runtimeCommand, type SpawnFn, synthesize } from "./synthesize.js";
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "synth-exec-"));
+  writeFileSync(join(dir, "index.ts"), "// entry");
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+const ok: SpawnFn = async () => ({ exitCode: 0, stdout: "done", stderr: "" });
+const noPrepare = () => {};
+
+describe("synthesize", () => {
+  it("spawns the entry point with the synthesis env and cwd, creating .stigmer", async () => {
+    const calls: Array<{ command: string; args: readonly string[]; cwd: string; env: NodeJS.ProcessEnv }> = [];
+    const spawn: SpawnFn = async (command, args, options) => {
+      calls.push({ command, args, cwd: options.cwd, env: options.env });
+      return { exitCode: 0, stdout: "", stderr: "" };
+    };
+
+    const result = await synthesize(
+      { projectDir: dir, entryPoint: "index.ts", runtime: "node", orgId: "acme" },
+      { spawn, prepare: noPrepare },
+    );
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].command).toBe("npx");
+    // The entry is passed as an absolute path (npx ignores cwd for relative).
+    expect(calls[0].args[0]).toBe("tsx");
+    expect(isAbsolute(calls[0].args[1])).toBe(true);
+    expect(calls[0].args[1].endsWith("/index.ts")).toBe(true);
+    expect(calls[0].cwd).toBe(result.outputDir.replace(/\/\.stigmer$/, ""));
+    expect(calls[0].env.STIGMER_OUT_DIR).toBe(result.outputDir);
+    expect(calls[0].env.STIGMER_ORG_ID).toBe("acme");
+    expect(result.outputDir.endsWith("/.stigmer")).toBe(true);
+    expect(existsSync(result.outputDir)).toBe(true);
+  });
+
+  it("omits STIGMER_ORG_ID when no org is given", async () => {
+    let env: NodeJS.ProcessEnv = {};
+    const spawn: SpawnFn = async (_c, _a, options) => {
+      env = options.env;
+      return { exitCode: 0, stdout: "", stderr: "" };
+    };
+    await synthesize({ projectDir: dir, entryPoint: "index.ts", runtime: "node", orgId: "" }, { spawn, prepare: noPrepare });
+    expect(env.STIGMER_ORG_ID).toBeUndefined();
+  });
+
+  it("maps a non-zero exit to an actionable error with stderr and guidance", async () => {
+    const spawn: SpawnFn = async () => ({ exitCode: 1, stdout: "", stderr: "ReferenceError: boom" });
+    await expect(
+      synthesize({ projectDir: dir, entryPoint: "index.ts", runtime: "node", orgId: "" }, { spawn, prepare: noPrepare }),
+    ).rejects.toThrow(/SDK synthesis failed:[\s\S]*ReferenceError: boom[\s\S]*npm install/);
+  });
+
+  it("maps a spawn failure (missing binary) to an actionable error", async () => {
+    const spawn: SpawnFn = async () => {
+      throw new Error("spawn npx ENOENT");
+    };
+    await expect(
+      synthesize({ projectDir: dir, entryPoint: "index.ts", runtime: "node", orgId: "" }, { spawn, prepare: noPrepare }),
+    ).rejects.toThrow(/SDK synthesis failed:[\s\S]*spawn npx ENOENT/);
+  });
+
+  it("rejects a missing entry point before spawning", async () => {
+    const spawn = vi.fn(ok);
+    await expect(
+      synthesize({ projectDir: dir, entryPoint: "missing.ts", runtime: "node", orgId: "" }, { spawn, prepare: noPrepare }),
+    ).rejects.toThrow(/entry point not found/);
+    expect(spawn).not.toHaveBeenCalled();
+  });
+
+  it("rejects a missing project directory", async () => {
+    await expect(
+      synthesize({ projectDir: join(dir, "nope"), entryPoint: "index.ts", runtime: "node", orgId: "" }, { spawn: ok }),
+    ).rejects.toThrow(/project directory not found/);
+  });
+
+  it("enforces node readiness via the default prepare (node_modules missing)", async () => {
+    writeFileSync(join(dir, "package.json"), "{}");
+    await expect(
+      synthesize({ projectDir: dir, entryPoint: "index.ts", runtime: "node", orgId: "" }, { spawn: ok }),
+    ).rejects.toThrow(/node_modules not found/);
+  });
+});
+
+describe("runtimeCommand", () => {
+  it("chooses the runner per runtime and extension", () => {
+    expect(runtimeCommand("go", "main.go")).toEqual(["go", "run", "main.go"]);
+    expect(runtimeCommand("python", "main.py")).toEqual(["python3", "main.py"]);
+    expect(runtimeCommand("node", "index.ts")).toEqual(["npx", "tsx", "index.ts"]);
+    expect(runtimeCommand("node", "index.mts")).toEqual(["npx", "tsx", "index.mts"]);
+    expect(runtimeCommand("node", "index.js")).toEqual(["node", "index.js"]);
+    expect(runtimeCommand("node", "index.mjs")).toEqual(["node", "index.mjs"]);
+  });
+});

package/src/resources/apply/synth/synthesize.ts

@@ -0,0 +1,161 @@
+// SDK synthesis execution.
+//
+// Runs a project's `entry_point` as a subprocess with `STIGMER_OUT_DIR` (and
+// `STIGMER_ORG_ID`) set; the program writes `.pb` files into that dir, which the
+// reader then decodes. Uniform subprocess model for every runtime (DD-009 §5):
+//   go      → `go run <entry>`
+//   python  → `python3 <entry>`
+//   node    → `npx tsx <entry>` for TS, `node <entry>` for JS
+//
+// `tsx` (not Go's `ts-node`) executes TypeScript entries — it is the runner the
+// CLI ecosystem already standardizes on (DD-009 alternatives). The spawn is
+// injected so the orchestration is unit-testable without a real subprocess
+// (mirrors `connect/oauth.ts`). Port of `internal/cli/apply/synthesize.go`.
+
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+import { extname, join, resolve } from "node:path";
+import { UsageError } from "../../../errors/index.js";
+import type { Runtime } from "./runtime.js";
+
+/** Result of running a subprocess to completion. */
+export interface SpawnResult {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+/** A function that runs a command to completion (injectable for tests). */
+export type SpawnFn = (
+  command: string,
+  args: readonly string[],
+  options: { readonly cwd: string; readonly env: NodeJS.ProcessEnv },
+) => Promise<SpawnResult>;
+
+/** Inputs for one synthesis run. */
+export interface SynthesizeOptions {
+  /** Directory containing the SDK code and stigmer.yaml. */
+  readonly projectDir: string;
+  /** Entry point file, relative to `projectDir`. */
+  readonly entryPoint: string;
+  /** Runtime inferred from the entry point extension. */
+  readonly runtime: Runtime;
+  /** Resolved org, injected as STIGMER_ORG_ID (empty = omit). */
+  readonly orgId: string;
+}
+
+/** Injectable collaborators (defaults run real subprocesses / fs checks). */
+export interface SynthesizeDeps {
+  readonly spawn?: SpawnFn;
+  readonly prepare?: (runtime: Runtime, projectDir: string) => void;
+}
+
+/** Outcome of synthesis: where the `.pb` files were written, plus SDK stdout. */
+export interface SynthesizeResult {
+  readonly outputDir: string;
+  readonly stdout: string;
+}
+
+/**
+ * Execute the SDK entry point and leave the synthesized `.pb` files in
+ * `<projectDir>/.stigmer`. Validates inputs, runs runtime prep, spawns the
+ * program with the synthesis env, and maps a non-zero exit (or spawn failure)
+ * to an actionable error. The caller reads the output dir with the reader.
+ */
+export async function synthesize(opts: SynthesizeOptions, deps: SynthesizeDeps = {}): Promise<SynthesizeResult> {
+  if (opts.projectDir === "") throw new UsageError("project directory is required");
+  if (opts.entryPoint === "") throw new UsageError("entry point is required");
+
+  const projectDir = resolve(opts.projectDir);
+  if (!existsSync(projectDir)) throw new UsageError(`project directory not found: ${opts.projectDir}`);
+  const entryAbs = join(projectDir, opts.entryPoint);
+  if (!existsSync(entryAbs)) throw new UsageError(`entry point not found: ${opts.entryPoint}`);
+
+  const outputDir = join(projectDir, ".stigmer");
+  mkdirSync(outputDir, { recursive: true });
+
+  (deps.prepare ?? defaultPrepare)(opts.runtime, projectDir);
+
+  // Pass the ABSOLUTE entry path: `npx` resolves a relative entry against the
+  // npm project root (its "local prefix"), not the spawn cwd, so a relative path
+  // breaks for the node runtime. An absolute path is correct for every runtime;
+  // cwd stays the project dir so the program's own relative imports resolve.
+  const [command, ...args] = runtimeCommand(opts.runtime, entryAbs);
+  const env: NodeJS.ProcessEnv = { ...process.env, STIGMER_OUT_DIR: outputDir };
+  if (opts.orgId !== "") env.STIGMER_ORG_ID = opts.orgId;
+
+  let result: SpawnResult;
+  try {
+    result = await (deps.spawn ?? defaultSpawn)(command, args, { cwd: projectDir, env });
+  } catch (err) {
+    throw new UsageError(formatExecutionError(opts.runtime, "", (err as Error).message));
+  }
+  if (result.exitCode !== 0) {
+    throw new UsageError(formatExecutionError(opts.runtime, result.stderr, `exited with code ${result.exitCode}`));
+  }
+
+  return { outputDir, stdout: result.stdout };
+}
+
+/** Command + args to execute an entry point for the given runtime. */
+export function runtimeCommand(runtime: Runtime, entryPoint: string): string[] {
+  switch (runtime) {
+    case "go":
+      return ["go", "run", entryPoint];
+    case "python":
+      return ["python3", entryPoint];
+    case "node": {
+      const ext = extname(entryPoint).toLowerCase();
+      // TypeScript entries run through tsx; plain JS runs on node directly.
+      return ext === ".ts" || ext === ".tsx" || ext === ".mts" ? ["npx", "tsx", entryPoint] : ["node", entryPoint];
+    }
+  }
+}
+
+// Lightweight, runtime-specific readiness checks (no subprocess). Unlike Go we
+// do NOT auto-run `go mod tidy`; the entry-point run surfaces missing deps and
+// the user resolves them — keeping the single subprocess the synthesis itself.
+function defaultPrepare(runtime: Runtime, projectDir: string): void {
+  if (runtime === "node") {
+    if (!existsSync(join(projectDir, "package.json"))) {
+      throw new UsageError("package.json not found: run 'npm init' to initialize a Node.js project");
+    }
+    if (!existsSync(join(projectDir, "node_modules"))) {
+      throw new UsageError("node_modules not found: run 'npm install' to install dependencies");
+    }
+  } else if (runtime === "go" && !existsSync(join(projectDir, "go.mod"))) {
+    throw new UsageError("go.mod not found: run 'go mod init' to initialize a Go module");
+  }
+}
+
+// Real subprocess: collects stdout/stderr, resolves with the exit code.
+const defaultSpawn: SpawnFn = (command, args, options) =>
+  new Promise<SpawnResult>((resolvePromise, rejectPromise) => {
+    const child = spawn(command, [...args], { cwd: options.cwd, env: options.env });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", (err) => rejectPromise(err));
+    child.on("close", (code) => resolvePromise({ exitCode: code ?? 0, stdout, stderr }));
+  });
+
+// Actionable failure message: truncated stderr + runtime-specific guidance.
+// Port of Go's formatExecutionError.
+function formatExecutionError(runtime: Runtime, stderr: string, fallback: string): string {
+  let detail = stderr.length > 800 ? `${stderr.slice(0, 800)}\n... (truncated)` : stderr;
+  if (detail === "") detail = fallback;
+
+  const guidance =
+    runtime === "go"
+      ? "Check for compile errors above. Run 'go build' to see full error output."
+      : runtime === "python"
+        ? "If you see import errors, install your dependencies (e.g. pip install -r requirements.txt)."
+        : "If you see module errors, run 'npm install' to install dependencies.";
+
+  return `SDK synthesis failed:\n${detail}\n\n${guidance}`;
+}

package/src/resources/connect/__fixtures__/stdio-crash.mjs

@@ -0,0 +1,6 @@
+// A stdio command that fails to start an MCP server: it writes a diagnostic to
+// stderr and exits non-zero. Used to assert connect --dry-run surfaces a clear
+// connection error (and the subprocess stderr) rather than hanging.
+
+process.stderr.write("fixture boom: missing CONFIG\n");
+process.exit(1);

package/src/resources/connect/__fixtures__/stdio-server.mjs

@@ -0,0 +1,43 @@
+// Minimal stdio MCP server fixture for `connect --dry-run` discovery tests.
+//
+// Spawned as a subprocess by discover.ts via StdioClientTransport. Advertises a
+// single tool and a single resource template using the low-level Server API
+// (the most version-stable surface of @modelcontextprotocol/sdk). It also echoes
+// an --env-provided value through the tool description so tests can assert env
+// propagation when needed.
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  ListResourceTemplatesRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const server = new Server(
+  { name: "fixture-mcp", version: "0.0.1" },
+  { capabilities: { tools: {}, resources: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "echo",
+      description: `echo a message (token=${process.env.FIXTURE_TOKEN ?? "unset"})`,
+      inputSchema: { type: "object", properties: { text: { type: "string" } } },
+    },
+    { name: "noop", description: "", inputSchema: { type: "object" } },
+  ],
+}));
+
+server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
+  resourceTemplates: [
+    {
+      uriTemplate: "file:///{path}",
+      name: "local-file",
+      description: "a local file",
+      mimeType: "text/plain",
+    },
+  ],
+}));
+
+await server.connect(new StdioServerTransport());

package/src/resources/connect/connect.integration.test.ts

@@ -0,0 +1,185 @@
+// In-process integration test for `connect mcp-server` orchestration.
+//
+// Stands up a Connect backend serving the McpServer query + command controllers,
+// points an SDK node client at it, and drives connectMcpServer end to end: the
+// push path (asserts ConnectInput fields + rendered capabilities), the OAuth
+// guidance gate, and the dry-run path (local discovery, no Connect RPC).
+
+import { create } from "@bufbuild/protobuf";
+import type { ConnectRouter } from "@connectrpc/connect";
+import { connectNodeAdapter } from "@connectrpc/connect-node";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
+import {
+  type ConnectInput,
+  GetOAuthGrantStatusOutputSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
+import { McpServerQueryController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/query_pb";
+import { McpServerAuthSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { createNodeClient, normalizeEndpoint } from "@stigmer/sdk/node";
+import { createServer as createHttp2Server, type Http2Server, type ServerHttp2Session } from "node:http2";
+import type { AddressInfo } from "node:net";
+import { fileURLToPath } from "node:url";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { UsageError } from "../../errors/index.js";
+import { connectMcpServer } from "./connect.js";
+import { renderConnectResult } from "./display.js";
+
+const FIXTURE = fileURLToPath(new URL("./__fixtures__/stdio-server.mjs", import.meta.url));
+
+let backend: Http2Server;
+let client: Stigmer;
+const openSessions = new Set<ServerHttp2Session>();
+
+let connectCalls: ConnectInput[] = [];
+let grantConnected = false;
+// The server returned by getByReference; mutated per test for auth scenarios.
+let servedSpec: ReturnType<typeof create<typeof McpServerSchema>>;
+
+beforeEach(() => {
+  connectCalls = [];
+  grantConnected = false;
+  servedSpec = create(McpServerSchema, {
+    metadata: { id: "mcp_1", name: "github", slug: "github", org: "acme" },
+    spec: {
+      serverType: { case: "stdio", value: { command: process.execPath, args: [FIXTURE] } },
+      env: { GITHUB_TOKEN: { isSecret: true } },
+    },
+  });
+});
+
+// The updated server the Connect RPC returns, carrying discovered capabilities.
+const updatedServer = create(McpServerSchema, {
+  metadata: { id: "mcp_1", name: "github", slug: "github", org: "acme" },
+  spec: { serverType: { case: "stdio", value: { command: "github-mcp" } } },
+  status: {
+    discoveredCapabilities: {
+      tools: [{ name: "search_issues", description: "search issues" }],
+      resourceTemplates: [{ name: "issue", uriTemplate: "github:///issues/{id}" }],
+    },
+  },
+});
+
+beforeAll(async () => {
+  const routes = (router: ConnectRouter) => {
+    router.service(McpServerQueryController, {
+      getByReference: () => servedSpec,
+      get: () => servedSpec,
+      getOAuthGrantStatus: () => create(GetOAuthGrantStatusOutputSchema, { connected: grantConnected }),
+    });
+    router.service(McpServerCommandController, {
+      connect: (req) => (connectCalls.push(req), updatedServer),
+    });
+  };
+
+  backend = createHttp2Server(connectNodeAdapter({ routes }));
+  backend.on("session", (session) => {
+    openSessions.add(session);
+    session.on("close", () => openSessions.delete(session));
+  });
+  await new Promise<void>((resolve) => backend.listen(0, "127.0.0.1", resolve));
+  const port = (backend.address() as AddressInfo).port;
+  client = createNodeClient({ baseUrl: normalizeEndpoint(`127.0.0.1:${port}`) });
+});
+
+afterAll(async () => {
+  for (const session of openSessions) session.destroy();
+  await new Promise<void>((resolve) => backend.close(() => resolve()));
+});
+
+describe("connect push path", () => {
+  it("sends ConnectInput with merged runtime env and returns discovered capabilities", async () => {
+    const result = await connectMcpServer(client, {
+      reference: "github",
+      org: "acme",
+      timeoutMs: 30_000,
+      dryRun: false,
+      envOverrides: ["GITHUB_TOKEN=ghp-override"],
+      backendType: "cloud",
+      interactive: false,
+    });
+
+    expect(connectCalls).toHaveLength(1);
+    expect(connectCalls[0].mcpServerId).toBe("mcp_1");
+    expect(connectCalls[0].runtimeEnv.GITHUB_TOKEN.value).toBe("ghp-override");
+    expect(connectCalls[0].runtimeEnv.GITHUB_TOKEN.isSecret).toBe(true);
+
+    expect(result.updated?.metadata?.id).toBe("mcp_1");
+    expect(result.capabilities?.tools.map((t) => t.name)).toEqual(["search_issues"]);
+  });
+});
+
+describe("OAuth guidance gate", () => {
+  beforeEach(() => {
+    servedSpec.spec!.auth = create(McpServerAuthSchema, { targetEnvVar: "GITHUB_TOKEN" });
+  });
+
+  it("stops with actionable guidance when auth is required off an interactive terminal", async () => {
+    await expect(
+      connectMcpServer(client, {
+        reference: "github",
+        org: "acme",
+        timeoutMs: 30_000,
+        dryRun: false,
+        envOverrides: [],
+        backendType: "cloud",
+        interactive: false,
+      }),
+    ).rejects.toThrow(UsageError);
+    expect(connectCalls).toHaveLength(0);
+  });
+
+  it("proceeds when an OAuth grant already exists", async () => {
+    grantConnected = true;
+    await connectMcpServer(client, {
+      reference: "github",
+      org: "acme",
+      timeoutMs: 30_000,
+      dryRun: false,
+      envOverrides: [],
+      backendType: "cloud",
+      interactive: false,
+    });
+    expect(connectCalls).toHaveLength(1);
+  });
+
+  it("proceeds when --env credentials are supplied (bypassing OAuth)", async () => {
+    await connectMcpServer(client, {
+      reference: "github",
+      org: "acme",
+      timeoutMs: 30_000,
+      dryRun: false,
+      envOverrides: ["GITHUB_TOKEN=ghp-x"],
+      backendType: "cloud",
+      interactive: false,
+    });
+    expect(connectCalls).toHaveLength(1);
+  });
+});
+
+describe("dry-run path", () => {
+  it("discovers locally and never calls the Connect RPC", async () => {
+    const result = await connectMcpServer(client, {
+      reference: "github",
+      org: "acme",
+      timeoutMs: 10_000,
+      dryRun: true,
+      envOverrides: [],
+      backendType: "cloud",
+      interactive: false,
+    });
+
+    expect(connectCalls).toHaveLength(0);
+    expect(result.updated).toBeUndefined();
+    expect(result.capabilities?.tools.map((t) => t.name)).toEqual(["echo", "noop"]);
+
+    const lines: string[] = [];
+    renderConnectResult(result, (l) => lines.push(l), false);
+    const text = lines.join("\n");
+    expect(text).toContain("MCP Server: acme/github");
+    expect(text).toContain("Transport:  stdio");
+    expect(text).toContain("Tools (2):");
+    expect(text).toContain("Dry run — results not saved");
+  }, 15_000);
+});

package/src/resources/connect/connect.ts

@@ -0,0 +1,107 @@
+// `connect mcp-server` orchestration. Mirrors Go's mcpserver.Connect (connect.go):
+// resolve the server, then either push to the backend (the Connect RPC runs
+// discovery server-side and persists capabilities + tool-approval policies) or,
+// for --dry-run, discover locally and return without persisting.
+//
+// OAuth: when a server requires OAuth, has no existing grant, and no --env was
+// supplied, the interactive browser flow (oauth.ts) shepherds the user through
+// the web console and waits for the grant. Off an interactive terminal (CI,
+// pipes) we stop with actionable guidance instead of blocking for 5 minutes.
+// Audit identity (reviewer) and token acquisition stay server-side by design.
+
+import { create } from "@bufbuild/protobuf";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { ConnectInputSchema, GetOAuthGrantStatusInputSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
+import type { DiscoveredCapabilities } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/status_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import type { BackendType } from "../../config/config.js";
+import { UsageError } from "../../errors/index.js";
+import { defaultRegistry } from "../../registry/index.js";
+import { buildRuntimeEnv } from "../mcp/runtime-env.js";
+import { parseReference } from "../reference.js";
+import { localDiscover } from "./discover.js";
+
+export interface ConnectOptions {
+  readonly reference: string;
+  readonly org: string;
+  readonly timeoutMs: number;
+  readonly dryRun: boolean;
+  readonly envOverrides: readonly string[];
+  /** Backend type, for resolving the OAuth web-console URL. */
+  readonly backendType: BackendType;
+  /** Whether an interactive terminal is available to run the OAuth flow. */
+  readonly interactive: boolean;
+}
+
+export interface ConnectResult {
+  readonly server: McpServer;
+  readonly capabilities: DiscoveredCapabilities | undefined;
+  /** Set when capabilities were persisted (non-dry-run); undefined for dry-run. */
+  readonly updated: McpServer | undefined;
+}
+
+/** Connect to an MCP server and discover its capabilities (push or dry-run). */
+export async function connectMcpServer(client: Stigmer, opts: ConnectOptions): Promise<ConnectResult> {
+  const server = await resolveMcpServer(client, opts.reference, opts.org);
+
+  if (opts.dryRun) {
+    if (server.spec === undefined) throw new UsageError("MCP server has no spec; cannot discover capabilities");
+    const capabilities = await localDiscover(server.spec, opts.envOverrides, opts.timeoutMs);
+    return { server, capabilities, updated: undefined };
+  }
+
+  await ensureOAuthSatisfied(client, server, opts);
+
+  const updated = await client.mcpServer.connect(
+    create(ConnectInputSchema, {
+      mcpServerId: server.metadata?.id ?? "",
+      runtimeEnv: buildRuntimeEnv(server, opts.envOverrides),
+    }),
+  );
+  return { server, capabilities: updated.status?.discoveredCapabilities, updated };
+}
+
+// Resolve a reference (id, org/slug, or bare slug) to an McpServer. Mirrors Go's
+// GetFromBackend.
+async function resolveMcpServer(client: Stigmer, reference: string, org: string): Promise<McpServer> {
+  const idPrefix = defaultRegistry().getByAlias("mcp-server")?.idPrefix ?? "";
+  const parsed = parseReference(reference, org, idPrefix);
+  if (parsed.kind === "id") return client.mcpServer.get(parsed.id);
+  return client.mcpServer.getByReference({ org: parsed.org, slug: parsed.slug });
+}
+
+// Ensure an OAuth grant exists before connecting an auth-configured server that
+// was given no --env credentials. On an interactive terminal, run the browser
+// flow and wait for the grant; otherwise stop with actionable guidance so
+// scripted callers get a clean, stable failure instead of a 5-minute block.
+async function ensureOAuthSatisfied(client: Stigmer, server: McpServer, opts: ConnectOptions): Promise<void> {
+  if (!oauthRequired(server) || opts.envOverrides.length > 0) return;
+
+  const status = await client.mcpServer.getOAuthGrantStatus(
+    create(GetOAuthGrantStatusInputSchema, {
+      resourceId: server.metadata?.id ?? "",
+      org: opts.org,
+    }),
+  );
+  if (status.connected) return;
+
+  if (!opts.interactive) throw oauthGuidanceError(server, opts.reference);
+
+  const { runOAuthFlow } = await import("./oauth.js");
+  await runOAuthFlow({ client, server, org: opts.org, backendType: opts.backendType });
+}
+
+function oauthGuidanceError(server: McpServer, reference: string): UsageError {
+  const slug = server.metadata?.slug ?? server.metadata?.name ?? reference;
+  return new UsageError(
+    `MCP server '${slug}' requires OAuth authentication, which needs an interactive terminal.\n\n` +
+      "To connect, choose one of:\n" +
+      "  - Re-run this command in an interactive terminal to complete OAuth in your browser\n" +
+      `  - Provide credentials directly: stigmer connect mcp-server ${slug} --env TOKEN=...`,
+  );
+}
+
+function oauthRequired(server: McpServer): boolean {
+  return (server.spec?.auth?.targetEnvVar ?? "") !== "";
+}