@stigmer/cli 3.1.6 → 3.1.8

package/src/local/runtime/node.ts

@@ -1,10 +1,10 @@
 // Resolution of the Node.js runtime used to launch the runner subprocess.
 //
 // We reuse the very Node that is running the CLI (process.execPath). The CLI is
-// itself an npm package with `engines: node >= 20`, so a suitable Node is always
-// present by construction — there is deliberately no hermetic Node download
-// (DD-002: keep the base install lean; nothing to acquire that the host already
-// guarantees). This is exactly what the conformance harness does
+// itself an npm package with `engines: node >= 22.13`, so a suitable Node is
+// always present by construction — there is deliberately no hermetic Node
+// download (DD-002: keep the base install lean; nothing to acquire that the host
+// already guarantees). This is exactly what the conformance harness does
 // (`spawn(process.execPath, ...)`). An explicit STIGMER_NODE_BIN override is
 // honored and version-checked for advanced/multi-runtime setups.
 
@@ -12,8 +12,20 @@ import { execFileSync } from "node:child_process";
 import { CliExitError } from "../../errors/cli-exit-error.js";
 import { ExitCode } from "../../errors/exit-codes.js";
 
-/** Minimum Node major version the runner requires. */
-export const MIN_NODE_MAJOR = 20;
+/**
+ * Minimum Node version the runner requires: 22.13. The runner's durable local
+ * checkpointer imports Node's built-in `node:sqlite`, which is only available
+ * WITHOUT the --experimental-sqlite flag from v22.13 (and v23.4) onward. A
+ * major-only gate would let 22.0-22.12 pass and then crash at checkpointer
+ * creation, so the minor is enforced when the major is exactly 22.
+ */
+export const MIN_NODE_MAJOR = 22;
+export const MIN_NODE_MINOR_ON_MAJOR = 13;
+
+interface NodeVersion {
+  major: number;
+  minor: number;
+}
 
 /**
  * Resolve the Node binary to launch the runner with. Honors STIGMER_NODE_BIN
@@ -22,46 +34,52 @@ export const MIN_NODE_MAJOR = 20;
 export function resolveNode(): string {
   const override = process.env.STIGMER_NODE_BIN;
   if (override !== undefined && override !== "") {
-    assertVersion(override, probeNodeMajor(override));
+    assertVersion(override, probeNodeVersion(override));
     return override;
   }
-  // The CLI's own runtime: major is readable directly, no subprocess needed.
-  assertVersion(process.execPath, currentMajor());
+  // The CLI's own runtime: version is readable directly, no subprocess needed.
+  assertVersion(process.execPath, parseVersion(process.versions.node));
   return process.execPath;
 }
 
-function currentMajor(): number | null {
-  return parseMajor(process.versions.node);
-}
-
-function probeNodeMajor(bin: string): number | null {
+function probeNodeVersion(bin: string): NodeVersion | null {
   try {
     const out = execFileSync(bin, ["--version"], { encoding: "utf8" });
-    return parseMajor(out.trim());
+    return parseVersion(out.trim());
   } catch {
     return null;
   }
 }
 
-// Parses "v22.22.2" or "22.22.2" to its major number.
-function parseMajor(version: string): number | null {
-  const match = /^v?(\d+)\./.exec(version.trim());
+// Parses "v22.22.2" or "22.22.2" to its major/minor numbers.
+function parseVersion(version: string): NodeVersion | null {
+  const match = /^v?(\d+)\.(\d+)\./.exec(version.trim());
   if (match === null) return null;
   const major = Number.parseInt(match[1], 10);
-  return Number.isInteger(major) ? major : null;
+  const minor = Number.parseInt(match[2], 10);
+  if (!Number.isInteger(major) || !Number.isInteger(minor)) return null;
+  return { major, minor };
+}
+
+// True when the version is at or above the 22.13 floor.
+function meetsFloor(v: NodeVersion): boolean {
+  if (v.major > MIN_NODE_MAJOR) return true;
+  return v.major === MIN_NODE_MAJOR && v.minor >= MIN_NODE_MINOR_ON_MAJOR;
 }
 
-function assertVersion(bin: string, major: number | null): void {
-  if (major === null) {
+function assertVersion(bin: string, version: NodeVersion | null): void {
+  const floor = `${MIN_NODE_MAJOR}.${MIN_NODE_MINOR_ON_MAJOR}`;
+  if (version === null) {
     throw new CliExitError(`could not determine the Node version of ${bin}`, ExitCode.General, [
-      `Ensure ${bin} is a working Node >= ${MIN_NODE_MAJOR} runtime.`,
+      `Ensure ${bin} is a working Node >= ${floor} runtime.`,
     ]);
   }
-  if (major < MIN_NODE_MAJOR) {
+  if (!meetsFloor(version)) {
     throw new CliExitError(
-      `Node >= ${MIN_NODE_MAJOR} is required to run the runner (found major ${major} at ${bin})`,
+      `Node >= ${floor} is required to run the runner ` +
+        `(found ${version.major}.${version.minor} at ${bin})`,
       ExitCode.General,
-      [`Upgrade Node to ${MIN_NODE_MAJOR} or newer, or point STIGMER_NODE_BIN at one.`],
+      [`Upgrade Node to ${floor} or newer, or point STIGMER_NODE_BIN at one.`],
     );
   }
 }

package/src/local/runtime/runtime.test.ts

@@ -3,7 +3,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { CliExitError } from "../../errors/cli-exit-error.js";
-import { MIN_NODE_MAJOR, resolveNode } from "./node.js";
+import { MIN_NODE_MAJOR, MIN_NODE_MINOR_ON_MAJOR, resolveNode } from "./node.js";
 import { acquireRunner, resolveRunner } from "./runner.js";
 import { resolveServerBinary } from "./server.js";
 import { which } from "./which.js";
@@ -57,7 +57,7 @@ describe("resolveNode", () => {
   });
 
   it("honors a valid override", () => {
-    process.env.STIGMER_NODE_BIN = process.execPath; // a real Node >= 20
+    process.env.STIGMER_NODE_BIN = process.execPath; // a real Node >= 22.13
     expect(resolveNode()).toBe(process.execPath);
   });
 
@@ -66,8 +66,9 @@ describe("resolveNode", () => {
     expect(() => resolveNode()).toThrow(CliExitError);
   });
 
-  it("requires Node >= 20", () => {
-    expect(MIN_NODE_MAJOR).toBe(20);
+  it("requires Node >= 22.13 (the node:sqlite floor)", () => {
+    expect(MIN_NODE_MAJOR).toBe(22);
+    expect(MIN_NODE_MINOR_ON_MAJOR).toBe(13);
   });
 });
 

package/src/program.test.ts

@@ -43,6 +43,13 @@ describe("buildProgram", () => {
     expect(message?.required).toBe(true);
   });
 
+  it("exposes the share subcommands", () => {
+    const program = buildProgram();
+    const share = program.commands.find((command) => command.name() === "share");
+    const subs = share?.commands.map((command) => command.name());
+    expect(subs).toEqual(["agent"]);
+  });
+
   it("exposes the usage subcommands", () => {
     const program = buildProgram();
     const usage = program.commands.find((command) => command.name() === "usage");

package/src/program.ts

@@ -31,6 +31,7 @@ import { registerRun } from "./commands/run.js";
 import { registerSearch } from "./commands/search.js";
 import { registerSeedpack } from "./commands/seedpack.js";
 import { registerSetup } from "./commands/setup.js";
+import { registerShare } from "./commands/share.js";
 import { registerStatus } from "./commands/status.js";
 import { registerTag } from "./commands/tag.js";
 import { registerUp } from "./commands/up.js";
@@ -76,6 +77,7 @@ export function buildProgram(): Command {
   registerValidate(program);
   registerDelete(program);
   registerTag(program);
+  registerShare(program);
   registerDiff(program);
   registerUsage(program);
   registerPush(program);

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

@@ -3,8 +3,9 @@
 // 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.
+// an --env-provided value AND the CLI args it received (process.argv beyond the
+// script path) through the tool description, so tests can assert env propagation
+// and ${VAR} argument expansion.
 
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -18,11 +19,15 @@ const server = new Server(
   { capabilities: { tools: {}, resources: {} } },
 );
 
+const receivedArgs = process.argv.slice(2);
+
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
     {
       name: "echo",
-      description: `echo a message (token=${process.env.FIXTURE_TOKEN ?? "unset"})`,
+      description:
+        `echo a message (token=${process.env.FIXTURE_TOKEN ?? "unset"}) ` +
+        `(args=${JSON.stringify(receivedArgs)})`,
       inputSchema: { type: "object", properties: { text: { type: "string" } } },
     },
     { name: "noop", description: "", inputSchema: { type: "object" } },

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

@@ -168,6 +168,66 @@ describe("OAuth guidance gate", () => {
   });
 });
 
+describe("oauth_only servers reject the manual-token routes", () => {
+  beforeEach(() => {
+    servedSpec.spec!.auth = create(McpServerAuthSchema, {
+      targetEnvVar: "GITHUB_TOKEN",
+      oauthOnly: true,
+    });
+  });
+
+  it("rejects --env (which cannot satisfy an OAuth-only endpoint) instead of pushing a doomed token", async () => {
+    const err = await connectMcpServer(client, {
+      reference: "github",
+      org: "acme",
+      timeoutMs: 30_000,
+      dryRun: false,
+      envOverrides: ["GITHUB_TOKEN=ghp-x"],
+      backendType: "cloud",
+      interactive: false,
+    }).catch((e: unknown) => e);
+
+    expect(err).toBeInstanceOf(UsageError);
+    expect((err as UsageError).message).toMatch(/requires OAuth/i);
+    // The guidance must NOT recommend the manual-token route for an oauth_only server.
+    expect((err as UsageError).message).not.toContain("--env TOKEN=");
+    expect(connectCalls).toHaveLength(0);
+  });
+
+  it("omits the --env suggestion from the non-interactive OAuth guidance", async () => {
+    const err = await connectMcpServer(client, {
+      reference: "github",
+      org: "acme",
+      timeoutMs: 30_000,
+      dryRun: false,
+      envOverrides: [],
+      backendType: "cloud",
+      interactive: false,
+    }).catch((e: unknown) => e);
+
+    expect(err).toBeInstanceOf(UsageError);
+    expect((err as UsageError).message).not.toContain("--env TOKEN=");
+    expect(connectCalls).toHaveLength(0);
+  });
+
+  it("refuses --dry-run local discovery (no locally-obtainable OAuth token) with a clear message", async () => {
+    const err = await connectMcpServer(client, {
+      reference: "github",
+      org: "acme",
+      timeoutMs: 10_000,
+      dryRun: true,
+      envOverrides: [],
+      backendType: "cloud",
+      interactive: false,
+    }).catch((e: unknown) => e);
+
+    expect(err).toBeInstanceOf(UsageError);
+    expect((err as UsageError).message).toMatch(/requires OAuth/i);
+    expect((err as UsageError).message).toContain("--dry-run");
+    expect(connectCalls).toHaveLength(0);
+  });
+});
+
 describe("dry-run path", () => {
   it("discovers locally and never calls the Connect RPC", async () => {
     const result = await connectMcpServer(client, {
@@ -192,4 +252,35 @@ describe("dry-run path", () => {
     expect(text).toContain("Tools (2):");
     expect(text).toContain("Dry run — results not saved");
   }, 15_000);
+
+  it("maps an unresolved ${VAR} arg to actionable guidance and never calls Connect", async () => {
+    // Server references a declared env var in its args, but it is not set.
+    delete process.env.NEEDED_DIR;
+    servedSpec = create(McpServerSchema, {
+      metadata: { id: "mcp_1", name: "filesystem", slug: "filesystem", org: "acme" },
+      spec: {
+        serverType: {
+          case: "stdio",
+          value: { command: process.execPath, args: [FIXTURE, "${NEEDED_DIR}"] },
+        },
+        env: { NEEDED_DIR: { isSecret: false, description: "Root directory the server may access" } },
+      },
+    });
+
+    const err = await connectMcpServer(client, {
+      reference: "filesystem",
+      org: "acme",
+      timeoutMs: 10_000,
+      dryRun: true,
+      envOverrides: [],
+      backendType: "cloud",
+      interactive: false,
+    }).catch((e: unknown) => e);
+
+    expect(err).toBeInstanceOf(UsageError);
+    const message = (err as UsageError).message;
+    expect(message).toContain("NEEDED_DIR");
+    expect(message).toContain("--env");
+    expect(connectCalls).toHaveLength(0);
+  }, 15_000);
 });

package/src/resources/connect/connect.ts

@@ -18,6 +18,7 @@ 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 { PlaceholderResolutionError } from "../mcp/placeholder-resolver.js";
 import { buildRuntimeEnv } from "../mcp/runtime-env.js";
 import { parseReference } from "../reference.js";
 import { localDiscover } from "./discover.js";
@@ -47,8 +48,20 @@ export async function connectMcpServer(client: Stigmer, opts: ConnectOptions): P
 
   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 };
+    // An oauth_only endpoint rejects static tokens, and the OAuth token lives in
+    // the backend's managed environment — never on the caller's machine. So local
+    // discovery cannot authenticate it; say so plainly instead of failing on a 401.
+    if (isOAuthOnly(server)) throw oauthOnlyDryRunError(server, opts.reference);
+    try {
+      const capabilities = await localDiscover(server.spec, opts.envOverrides, opts.timeoutMs);
+      return { server, capabilities, updated: undefined };
+    } catch (err) {
+      // A ${VAR} placeholder that could not be resolved is a configuration
+      // problem, not a discovery failure — surface it as actionable guidance
+      // instead of a raw resolver error or a cryptic subprocess crash.
+      if (err instanceof PlaceholderResolutionError) throw unresolvedEnvError(server, err);
+      throw err;
+    }
   }
 
   await ensureOAuthSatisfied(client, server, opts);
@@ -77,7 +90,18 @@ async function resolveMcpServer(client: Stigmer, reference: string, org: string)
 // 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;
+  if (!oauthRequired(server)) return;
+
+  const oauthOnly = isOAuthOnly(server);
+
+  // A manually supplied token is a valid bypass for a normal OAuth server (many
+  // vendors also accept a PAT), but an oauth_only endpoint rejects static tokens
+  // outright — so --env cannot connect it. Fail with guidance rather than push a
+  // token the endpoint will reject.
+  if (opts.envOverrides.length > 0) {
+    if (!oauthOnly) return;
+    throw oauthOnlyEnvError(server, opts.reference);
+  }
 
   const status = await client.mcpServer.getOAuthGrantStatus(
     create(GetOAuthGrantStatusInputSchema, {
@@ -87,22 +111,76 @@ async function ensureOAuthSatisfied(client: Stigmer, server: McpServer, opts: Co
   );
   if (status.connected) return;
 
-  if (!opts.interactive) throw oauthGuidanceError(server, opts.reference);
+  if (!opts.interactive) throw oauthGuidanceError(server, opts.reference, oauthOnly);
 
   const { runOAuthFlow } = await import("./oauth.js");
   await runOAuthFlow({ client, server, org: opts.org, backendType: opts.backendType });
 }
 
-function oauthGuidanceError(server: McpServer, reference: string): UsageError {
+// Turn a strict-resolution failure into actionable guidance. A declared-but-unset
+// variable is the user's to provide; an undeclared one is a bug in the server
+// definition. Both are far clearer than the cryptic subprocess crash (ENOENT on a
+// literal "${VAR}" path) that motivated issue #141.
+function unresolvedEnvError(server: McpServer, err: PlaceholderResolutionError): UsageError {
+  const slug = server.metadata?.slug ?? server.metadata?.name ?? server.metadata?.id ?? "this server";
+  const decl = server.spec?.env?.[err.variableName];
+  if (decl) {
+    const hint = decl.description !== "" ? ` (${decl.description})` : "";
+    return new UsageError(
+      `MCP server '${slug}' needs environment variable ${err.variableName}${hint}, but it is not set.\n` +
+        `Provide it with --env ${err.variableName}=<value> or export it in your shell before running --dry-run.`,
+    );
+  }
+  const where = err.context !== undefined ? ` in its ${err.context}` : "";
+  return new UsageError(
+    `MCP server '${slug}' references \${${err.variableName}}${where} but does not declare ${err.variableName} under spec.env.\n` +
+      `This is a problem with the server definition — declare ${err.variableName} in the server's env, or remove the placeholder.`,
+  );
+}
+
+function oauthGuidanceError(server: McpServer, reference: string, oauthOnly: boolean): UsageError {
   const slug = server.metadata?.slug ?? server.metadata?.name ?? reference;
+  const choices = [
+    "  - Re-run this command in an interactive terminal to complete OAuth in your browser",
+  ];
+  // Only offer the manual-token route for servers that actually accept one.
+  // Suggesting it for an oauth_only endpoint would send the user down a dead end.
+  if (!oauthOnly) {
+    choices.push(`  - Provide credentials directly: stigmer connect mcp-server ${slug} --env TOKEN=...`);
+  }
   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=...`,
+      `To connect${oauthOnly ? "" : ", choose one of"}:\n` +
+      choices.join("\n"),
+  );
+}
+
+// An oauth_only server whose endpoint rejects static tokens was given a manual
+// token via --env. Explain that OAuth is the only path rather than pushing a
+// credential the endpoint will reject with an opaque 401.
+function oauthOnlyEnvError(server: McpServer, reference: string): UsageError {
+  const slug = server.metadata?.slug ?? server.metadata?.name ?? reference;
+  return new UsageError(
+    `MCP server '${slug}' requires OAuth and rejects manually-entered tokens, so --env cannot connect it.\n` +
+      `Re-run without --env in an interactive terminal to sign in: stigmer connect mcp-server ${slug}`,
+  );
+}
+
+// --dry-run discovers locally, but an oauth_only endpoint needs an OAuth token
+// that only the backend can obtain and store — there is nothing valid to send
+// from the caller's machine. Say so plainly instead of attempting a doomed 401.
+function oauthOnlyDryRunError(server: McpServer, reference: string): UsageError {
+  const slug = server.metadata?.slug ?? server.metadata?.name ?? reference;
+  return new UsageError(
+    `MCP server '${slug}' requires OAuth, so --dry-run cannot discover it locally — its endpoint only accepts an OAuth token that the connected backend obtains for you.\n` +
+      `Run it for real and sign in when prompted: stigmer connect mcp-server ${slug}`,
   );
 }
 
 function oauthRequired(server: McpServer): boolean {
   return (server.spec?.auth?.targetEnvVar ?? "") !== "";
 }
+
+function isOAuthOnly(server: McpServer): boolean {
+  return server.spec?.auth?.oauthOnly === true;
+}

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

@@ -8,8 +8,9 @@
 import { create } from "@bufbuild/protobuf";
 import { McpServerSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
 import { fileURLToPath } from "node:url";
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
 import { localDiscover } from "./discover.js";
+import { PlaceholderResolutionError } from "../mcp/placeholder-resolver.js";
 
 const FIXTURE = fileURLToPath(new URL("./__fixtures__/stdio-server.mjs", import.meta.url));
 const CRASH_FIXTURE = fileURLToPath(new URL("./__fixtures__/stdio-crash.mjs", import.meta.url));
@@ -20,6 +21,15 @@ function stdioSpec(scriptPath: string) {
   });
 }
 
+// A spec whose args reference ${ALLOWED_DIR}, declared under spec.env — the shape
+// the seedpack filesystem server uses (issue #141).
+function stdioSpecWithPlaceholderArg(scriptPath: string) {
+  return create(McpServerSpecSchema, {
+    serverType: { case: "stdio", value: { command: process.execPath, args: [scriptPath, "${ALLOWED_DIR}"] } },
+    env: { ALLOWED_DIR: { isSecret: false, description: "Directory the server may access" } },
+  });
+}
+
 describe("localDiscover (stdio subprocess)", () => {
   it("discovers tools and resource templates and converts them to proto", async () => {
     const caps = await localDiscover(stdioSpec(FIXTURE), [], 10_000);
@@ -43,3 +53,32 @@ describe("localDiscover (stdio subprocess)", () => {
     await expect(localDiscover(stdioSpec(CRASH_FIXTURE), [], 10_000)).rejects.toThrow(/fixture boom: missing CONFIG/);
   }, 15_000);
 });
+
+describe("localDiscover (${VAR} argument expansion — issue #141)", () => {
+  const original = process.env;
+  afterEach(() => {
+    process.env = original;
+  });
+
+  it("expands a declared ${VAR} arg from --env into the spawned subprocess", async () => {
+    const caps = await localDiscover(stdioSpecWithPlaceholderArg(FIXTURE), ["ALLOWED_DIR=/tmp/allowed"], 10_000);
+    // The fixture echoes the argv it actually received; the resolved value must
+    // reach the subprocess, never the literal placeholder.
+    expect(caps.tools[0].description).toContain('args=["/tmp/allowed"]');
+    expect(caps.tools[0].description).not.toContain("${ALLOWED_DIR}");
+  }, 15_000);
+
+  it("expands a declared ${VAR} arg from the exported shell environment", async () => {
+    process.env = { ...original, ALLOWED_DIR: "/tmp/from-shell" };
+    const caps = await localDiscover(stdioSpecWithPlaceholderArg(FIXTURE), [], 10_000);
+    expect(caps.tools[0].description).toContain('args=["/tmp/from-shell"]');
+  }, 15_000);
+
+  it("rejects with a placeholder error before spawning when the declared var is unset", async () => {
+    process.env = { ...original };
+    delete process.env.ALLOWED_DIR;
+    await expect(localDiscover(stdioSpecWithPlaceholderArg(FIXTURE), [], 10_000)).rejects.toBeInstanceOf(
+      PlaceholderResolutionError,
+    );
+  }, 15_000);
+});

package/src/resources/connect/discover.ts

@@ -21,7 +21,8 @@ import {
 import type { JsonObject } from "@bufbuild/protobuf";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
-import { mergeProcessEnv } from "../mcp/runtime-env.js";
+import { mergeProcessEnv, resolveDeclaredEnvValues } from "../mcp/runtime-env.js";
+import { resolveHeaders, resolvePlaceholders } from "../mcp/placeholder-resolver.js";
 
 /** Discover an MCP server's capabilities locally without persisting to the backend. */
 export async function localDiscover(
@@ -79,13 +80,21 @@ interface BuiltTransport {
 }
 
 async function buildTransport(spec: McpServerSpec, envOverrides: readonly string[]): Promise<BuiltTransport> {
+  // ${VAR} placeholders in args/headers resolve against the exact same env the
+  // backend hands the runner for real connect (declared keys from the OS env +
+  // --env overrides) — so dry-run is a faithful preview. Resolution is strict:
+  // an unresolved placeholder throws before any subprocess is spawned, matching
+  // the proto contract (never pass a literal "${VAR}" to the server).
+  const resolutionEnv = resolveDeclaredEnvValues(spec.env ?? {}, envOverrides);
+
   if (spec.serverType?.case === "stdio") {
     const { command, args, workingDir } = spec.serverType.value;
     if (command === "") throw new Error("stdio transport requires a command");
+    const resolvedArgs = args.map((arg, i) => resolvePlaceholders(arg, resolutionEnv, `stdio arg[${i}]`));
     const { StdioClientTransport } = await import("@modelcontextprotocol/sdk/client/stdio.js");
     const transport = new StdioClientTransport({
       command,
-      args: [...args],
+      args: resolvedArgs,
       cwd: workingDir !== "" ? workingDir : undefined,
       env: mergeProcessEnv([...envOverrides, ...goRunEnvOverrides(command, args)]),
       // "pipe" exposes the child stderr as a PassThrough immediately, so we can
@@ -104,8 +113,11 @@ async function buildTransport(spec: McpServerSpec, envOverrides: readonly string
     const { url, headers } = spec.serverType.value;
     if (url === "") throw new Error("HTTP transport requires a URL");
     const { StreamableHTTPClientTransport } = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
-    const requestInit = Object.keys(headers).length > 0 ? { headers: { ...headers } } : undefined;
-    const transport = new StreamableHTTPClientTransport(new URL(url), requestInit ? { requestInit } : undefined);
+    const resolvedHeaders = Object.keys(headers).length > 0 ? resolveHeaders(headers, resolutionEnv) : undefined;
+    const transport = new StreamableHTTPClientTransport(
+      new URL(url),
+      resolvedHeaders ? { requestInit: { headers: resolvedHeaders } } : undefined,
+    );
     return { transport, readStderr: () => "" };
   }
 

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

@@ -3,14 +3,7 @@ import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1
 import type { Stigmer } from "@stigmer/sdk";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { UsageError } from "../../errors/index.js";
-import {
-  browserCommand,
-  DEFAULT_CLOUD_CONSOLE_URL,
-  resolveConsoleURL,
-  runOAuthFlow,
-  waitForOAuthGrant,
-  type OAuthFlowDeps,
-} from "./oauth.js";
+import { browserCommand, runOAuthFlow, waitForOAuthGrant, type OAuthFlowDeps } from "./oauth.js";
 
 const server = create(McpServerSchema, {
   metadata: { id: "mcp_1", slug: "github", name: "GitHub" },
@@ -33,22 +26,6 @@ function fakeClient(connectOnCall: number): { client: Stigmer; calls: () => numb
 
 const noopSleep = async (): Promise<void> => {};
 
-describe("resolveConsoleURL", () => {
-  it("prefers the STIGMER_CONSOLE_URL override", () => {
-    expect(resolveConsoleURL("cloud", { STIGMER_CONSOLE_URL: "https://console.example" } as NodeJS.ProcessEnv)).toBe(
-      "https://console.example",
-    );
-  });
-
-  it("uses the local web-console port for the local backend", () => {
-    expect(resolveConsoleURL("local", {} as NodeJS.ProcessEnv)).toBe("http://localhost:8234");
-  });
-
-  it("uses the cloud console URL for the cloud backend", () => {
-    expect(resolveConsoleURL("cloud", {} as NodeJS.ProcessEnv)).toBe(DEFAULT_CLOUD_CONSOLE_URL);
-  });
-});
-
 describe("browserCommand", () => {
   it("maps each supported platform to its opener", () => {
     expect(browserCommand("darwin", "https://x")).toEqual(["open", ["https://x"]]);

package/src/resources/connect/oauth.ts

@@ -16,11 +16,8 @@ import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/
 import { GetOAuthGrantStatusInputSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
 import type { Stigmer } from "@stigmer/sdk";
 import type { BackendType } from "../../config/config.js";
+import { resolveConsoleURL } from "../../config/index.js";
 import { UsageError } from "../../errors/index.js";
-import { WEB_CONSOLE_PORT } from "../../local/constants.js";
-
-/** Well-known URL for the Stigmer Cloud web console. */
-export const DEFAULT_CLOUD_CONSOLE_URL = "https://app.stigmer.ai";
 
 const POLL_INTERVAL_MS = 3000;
 const POLL_TIMEOUT_MS = 5 * 60 * 1000;
@@ -109,19 +106,6 @@ export async function checkOAuthGrant(client: Stigmer, mcpServerId: string, org:
   return status.connected;
 }
 
-/**
- * Resolve the web console URL:
- *   1. `STIGMER_CONSOLE_URL` (explicit override)
- *   2. local backend → `http://localhost:{WEB_CONSOLE_PORT}`
- *   3. cloud backend → {@link DEFAULT_CLOUD_CONSOLE_URL}
- */
-export function resolveConsoleURL(backendType: BackendType, env: NodeJS.ProcessEnv = process.env): string {
-  const override = env.STIGMER_CONSOLE_URL;
-  if (override !== undefined && override !== "") return override;
-  if (backendType === "local") return `http://localhost:${WEB_CONSOLE_PORT}`;
-  return DEFAULT_CLOUD_CONSOLE_URL;
-}
-
 // Probe the local web console with a short-timeout GET. Any HTTP response (even
 // an error status) means it's serving; a network/timeout failure means it isn't.
 async function probeWebConsole(url: string): Promise<boolean> {