dynmcp 0.4.1 → 0.6.0

package/dist/index.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import process7 from "process";
+import process14 from "process";
 import { Command } from "commander";
 
 // package.json
 var package_default = {
   name: "dynmcp",
-  version: "0.4.1",
+  version: "0.6.0",
   description: "Dynamic MCP context management tool for AI MCP-enabled agents and clients.",
   author: "Brandon Burrus <brandon@burrus.io>",
   license: "MIT",
@@ -69,6 +69,7 @@ var package_default = {
   },
   dependencies: {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@napi-rs/keyring": "^1.3.0",
     boxen: "^8.0.1",
     chalk: "^5.6.2",
     commander: "^14.0.3",
@@ -98,9 +99,330 @@ var package_default = {
 import figlet from "figlet";
 import chalk from "chalk";
 
-// src/proxy/index.ts
-import process6 from "process";
-import { StdioClientTransport as StdioClientTransport2 } from "@modelcontextprotocol/sdk/client/stdio.js";
+// src/auth/errors.ts
+var AuthRequiredError = class extends Error {
+  mcpName;
+  constructor(mcpName2) {
+    super(
+      `Upstream MCP "${mcpName2}" requires authorization. Run \`dynmcp login ${mcpName2}\` from your terminal, then retry.`
+    );
+    this.name = "AuthRequiredError";
+    this.mcpName = mcpName2;
+  }
+};
+function isAuthRequiredError(error) {
+  let current = error;
+  for (let depth = 0; depth < 8 && current !== null && current !== void 0; depth += 1) {
+    if (current instanceof AuthRequiredError) return true;
+    if (current instanceof Error && current.name === "AuthRequiredError") return true;
+    if (current instanceof Error) {
+      current = current.cause;
+      continue;
+    }
+    return false;
+  }
+  return false;
+}
+
+// src/auth/keychain-store.ts
+import { Entry } from "@napi-rs/keyring";
+
+// src/auth/types.ts
+var KEYCHAIN_BLOB_VERSION = 1;
+
+// src/auth/keychain-store.ts
+var KEYCHAIN_SERVICE = "dynmcp";
+function buildKeychainAccount(mcpName2, serverUrl) {
+  const origin = new URL(serverUrl).origin;
+  return `${mcpName2}:${origin}`;
+}
+var KeychainStore = class {
+  constructor(mcpName2, serverUrl, service = KEYCHAIN_SERVICE) {
+    this.mcpName = mcpName2;
+    this.serverUrl = serverUrl;
+    this.entry = new Entry(service, buildKeychainAccount(mcpName2, serverUrl));
+  }
+  mcpName;
+  serverUrl;
+  entry;
+  /**
+   * Returns the parsed blob or `undefined` if no entry exists. Entries written under
+   * a different {@link KeychainBlob.version} are treated as absent — the caller must
+   * re-authenticate. Malformed JSON also returns `undefined` (corrupt entries are not
+   * surfaced as errors; recovery is the same: re-auth).
+   */
+  get() {
+    const raw = this.entry.getPassword();
+    if (raw === null) return void 0;
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return void 0;
+    }
+    if (!isCurrentVersionBlob(parsed)) {
+      return void 0;
+    }
+    return parsed;
+  }
+  /**
+   * Persists the blob atomically. Caller must construct a complete {@link
+   * KeychainBlob} — partial updates are not supported. To mutate, call {@link get},
+   * spread, and pass the result back to {@link set}.
+   */
+  set(blob) {
+    const stamped = { ...blob, version: KEYCHAIN_BLOB_VERSION };
+    this.entry.setPassword(JSON.stringify(stamped));
+  }
+  /**
+   * Deletes the entry. Returns `true` if an entry was present and removed, `false`
+   * if there was nothing to delete. Idempotent: callers should treat both outcomes
+   * as success (a no-op delete is not an error).
+   */
+  delete() {
+    return this.entry.deletePassword();
+  }
+};
+function isCurrentVersionBlob(value) {
+  return typeof value === "object" && value !== null && "version" in value && value.version === KEYCHAIN_BLOB_VERSION;
+}
+
+// src/auth/oauth-provider.ts
+import { randomBytes } from "crypto";
+var CLIENT_NAME = "dynmcp";
+var SOFTWARE_ID = "dynmcp";
+var REFRESH_SLACK_SECONDS = 30;
+var BaseOAuthProvider = class {
+  constructor(mcpName2, keychain, configAuth) {
+    this.mcpName = mcpName2;
+    this.keychain = keychain;
+    this.configAuth = configAuth;
+  }
+  mcpName;
+  keychain;
+  configAuth;
+  clientInformation() {
+    if (this.configAuth !== void 0) {
+      const info2 = { client_id: this.configAuth.client_id };
+      if (this.configAuth.client_secret !== void 0) {
+        info2.client_secret = this.configAuth.client_secret;
+      }
+      return info2;
+    }
+    const blob = this.keychain.get();
+    if (blob?.dcr === void 0) return void 0;
+    const info = { client_id: blob.dcr.client_id };
+    if (blob.dcr.client_secret !== void 0) {
+      info.client_secret = blob.dcr.client_secret;
+    }
+    return info;
+  }
+  tokens() {
+    const blob = this.keychain.get();
+    if (blob === void 0) return void 0;
+    const remaining = Math.max(
+      0,
+      blob.expires_at - Math.floor(Date.now() / 1e3) - REFRESH_SLACK_SECONDS
+    );
+    const tokens = {
+      access_token: blob.access_token,
+      token_type: blob.token_type,
+      expires_in: remaining
+    };
+    if (blob.refresh_token !== void 0) tokens.refresh_token = blob.refresh_token;
+    if (blob.scope_granted !== void 0) tokens.scope = blob.scope_granted;
+    return tokens;
+  }
+  /**
+   * Builds the {@link OAuthDiscoveryState} the SDK can use to skip rediscovery,
+   * reconstructed from the cached keychain blob. Returns `undefined` when there is
+   * no cached blob (e.g. fresh login flow before saveTokens fires).
+   */
+  buildDiscoveryStateFromBlob(blob) {
+    if (blob === void 0) return void 0;
+    return {
+      authorizationServerUrl: blob.authorization_server.issuer,
+      authorizationServerMetadata: {
+        issuer: blob.authorization_server.issuer,
+        authorization_endpoint: blob.authorization_server.authorization_endpoint,
+        token_endpoint: blob.authorization_server.token_endpoint,
+        ...blob.authorization_server.registration_endpoint !== void 0 ? { registration_endpoint: blob.authorization_server.registration_endpoint } : {},
+        response_types_supported: ["code"]
+      },
+      resourceMetadata: {
+        resource: blob.resource_metadata.resource,
+        authorization_servers: blob.resource_metadata.authorization_servers
+      }
+    };
+  }
+};
+var ProxyOAuthProvider = class extends BaseOAuthProvider {
+  get redirectUrl() {
+    return void 0;
+  }
+  get clientMetadata() {
+    return {
+      client_name: CLIENT_NAME,
+      software_id: SOFTWARE_ID,
+      redirect_uris: [],
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: this.configAuth?.client_secret !== void 0 ? "client_secret_basic" : "none",
+      ...this.configAuth?.scope !== void 0 ? { scope: this.configAuth.scope } : {}
+    };
+  }
+  saveTokens(tokens) {
+    const existing = this.keychain.get();
+    if (existing === void 0) {
+      throw new AuthRequiredError(this.mcpName);
+    }
+    const expiresAt = tokens.expires_in !== void 0 ? Math.floor(Date.now() / 1e3) + tokens.expires_in : existing.expires_at;
+    const updated = {
+      ...existing,
+      access_token: tokens.access_token,
+      token_type: tokens.token_type ?? "Bearer",
+      expires_at: expiresAt,
+      refresh_token: tokens.refresh_token ?? existing.refresh_token,
+      ...tokens.scope !== void 0 ? { scope_granted: tokens.scope } : {}
+    };
+    this.keychain.set(updated);
+  }
+  redirectToAuthorization(_url) {
+    throw new AuthRequiredError(this.mcpName);
+  }
+  saveCodeVerifier(_verifier) {
+    throw new AuthRequiredError(this.mcpName);
+  }
+  codeVerifier() {
+    throw new AuthRequiredError(this.mcpName);
+  }
+  discoveryState() {
+    return this.buildDiscoveryStateFromBlob(this.keychain.get());
+  }
+  invalidateCredentials(_scope) {
+    this.keychain.delete();
+  }
+};
+var LoginOAuthProvider = class extends BaseOAuthProvider {
+  redirectUriString;
+  pending = {};
+  callbacks;
+  constructor(opts) {
+    super(opts.mcpName, opts.keychain, opts.configAuth);
+    this.redirectUriString = opts.redirectUri;
+    this.callbacks = opts.callbacks;
+  }
+  get redirectUrl() {
+    return this.redirectUriString;
+  }
+  get clientMetadata() {
+    return {
+      client_name: CLIENT_NAME,
+      software_id: SOFTWARE_ID,
+      redirect_uris: [this.redirectUriString],
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: this.configAuth?.client_secret !== void 0 ? "client_secret_basic" : "none",
+      ...this.configAuth?.scope !== void 0 ? { scope: this.configAuth.scope } : {}
+    };
+  }
+  state() {
+    if (this.pending.state !== void 0) return this.pending.state;
+    const generated = randomBytes(32).toString("base64url");
+    this.pending.state = generated;
+    return generated;
+  }
+  /** The state value generated for this flow, for the callback handler to verify. */
+  get currentState() {
+    return this.pending.state;
+  }
+  clientInformation() {
+    if (this.pending.dcr !== void 0) {
+      const info = { client_id: this.pending.dcr.client_id };
+      if (this.pending.dcr.client_secret !== void 0) {
+        info.client_secret = this.pending.dcr.client_secret;
+      }
+      return info;
+    }
+    return super.clientInformation();
+  }
+  saveClientInformation(info) {
+    this.pending.dcr = info;
+  }
+  saveTokens(tokens) {
+    const discovery = this.pending.discovery ?? this.buildDiscoveryStateFromBlob(this.keychain.get());
+    if (discovery === void 0) {
+      throw new Error(
+        `Cannot persist tokens for "${this.mcpName}": no discovery state captured during the flow.`
+      );
+    }
+    if (discovery.authorizationServerMetadata === void 0) {
+      throw new Error(
+        `Cannot persist tokens for "${this.mcpName}": authorization server metadata not available.`
+      );
+    }
+    if (discovery.resourceMetadata === void 0) {
+      throw new Error(
+        `Cannot persist tokens for "${this.mcpName}": protected resource metadata not available.`
+      );
+    }
+    const expiresAt = tokens.expires_in !== void 0 ? Math.floor(Date.now() / 1e3) + tokens.expires_in : Math.floor(Date.now() / 1e3) + 3600;
+    const authorizationServer = {
+      issuer: discovery.authorizationServerMetadata.issuer ?? discovery.authorizationServerUrl,
+      authorization_endpoint: discovery.authorizationServerMetadata.authorization_endpoint,
+      token_endpoint: discovery.authorizationServerMetadata.token_endpoint,
+      ...discovery.authorizationServerMetadata.registration_endpoint !== void 0 ? { registration_endpoint: discovery.authorizationServerMetadata.registration_endpoint } : {}
+    };
+    const resourceMetadata = {
+      resource: discovery.resourceMetadata.resource,
+      authorization_servers: discovery.resourceMetadata.authorization_servers ?? []
+    };
+    const blob = {
+      version: KEYCHAIN_BLOB_VERSION,
+      access_token: tokens.access_token,
+      token_type: tokens.token_type ?? "Bearer",
+      expires_at: expiresAt,
+      ...tokens.refresh_token !== void 0 ? { refresh_token: tokens.refresh_token } : {},
+      ...tokens.scope !== void 0 ? { scope_granted: tokens.scope } : {},
+      authorization_server: authorizationServer,
+      resource_metadata: resourceMetadata,
+      ...this.pending.dcr !== void 0 ? {
+        dcr: {
+          client_id: this.pending.dcr.client_id,
+          ...this.pending.dcr.client_secret !== void 0 ? { client_secret: this.pending.dcr.client_secret } : {}
+        }
+      } : {}
+    };
+    this.keychain.set(blob);
+  }
+  async redirectToAuthorization(url) {
+    await this.callbacks.onAuthorizationUrl(url);
+  }
+  saveCodeVerifier(verifier) {
+    this.pending.codeVerifier = verifier;
+  }
+  codeVerifier() {
+    if (this.pending.codeVerifier === void 0) {
+      throw new Error("Code verifier requested before it was saved.");
+    }
+    return this.pending.codeVerifier;
+  }
+  saveDiscoveryState(state) {
+    this.pending.discovery = state;
+  }
+  /**
+   * Force a fresh RFC 9728 + RFC 8414 discovery for every login flow. We intentionally
+   * do NOT pre-seed from the keychain on login — if endpoints changed since the last
+   * login, we want to pick them up now and persist the new snapshot.
+   */
+  discoveryState() {
+    return void 0;
+  }
+};
+
+// src/auth/login.ts
+import process4 from "process";
+import { auth, extractWWWAuthenticateParams } from "@modelcontextprotocol/sdk/client/auth.js";
 
 // src/config/schema.ts
 import { z } from "zod";
@@ -122,26 +444,35 @@ var stdioTransport = z.object({
 var httpUrl = z.string().url().refine((u) => u.startsWith("http://") || u.startsWith("https://"), {
   message: "URL must use http:// or https:// scheme"
 });
+var authConfig = z.object({
+  client_id: z.string().min(1, { message: "auth.client_id must be a non-empty string" }).refine((value) => value.trim().length > 0, {
+    message: "auth.client_id must not be whitespace-only"
+  }),
+  client_secret: z.string().min(1).optional(),
+  scope: z.string().min(1).optional()
+}).strict().optional();
 var streamableHttpTransport = z.object({
   transport: z.literal("streamable-http"),
   description,
   url: httpUrl,
-  headers: z.record(z.string(), z.string()).optional()
+  headers: z.record(z.string(), z.string()).optional(),
+  auth: authConfig
 }).strict();
 var sseTransport = z.object({
   transport: z.literal("sse"),
   description,
   url: httpUrl,
-  headers: z.record(z.string(), z.string()).optional()
+  headers: z.record(z.string(), z.string()).optional(),
+  auth: authConfig
 }).strict();
-var transportConfig = z.discriminatedUnion("transport", [
+var transportConfigSchema = z.discriminatedUnion("transport", [
   stdioTransport,
   streamableHttpTransport,
   sseTransport
 ]);
 var mcpConfigSchema = z.object({
   env: envModeSchema.optional(),
-  mcp: z.record(mcpName, transportConfig).refine((obj) => Object.keys(obj).length > 0, { message: "At least one MCP must be configured" })
+  mcp: z.record(mcpName, transportConfigSchema).refine((obj) => Object.keys(obj).length > 0, { message: "At least one MCP must be configured" })
 });
 
 // src/config/loader.ts
@@ -208,9 +539,9 @@ function filterDefined(env) {
 var TOP_LEVEL_PASSTHROUGH_KEYS = /* @__PURE__ */ new Set(["$schema", "env"]);
 var MissingEnvVarsError = class extends Error {
   constructor(missingVars) {
-    const list = missingVars.join(", ");
+    const list2 = missingVars.join(", ");
     const plural = missingVars.length === 1 ? "" : "s";
-    super(`Missing required environment variable${plural}: ${list}`);
+    super(`Missing required environment variable${plural}: ${list2}`);
     this.missingVars = missingVars;
     this.name = "MissingEnvVarsError";
   }
@@ -348,28 +679,1124 @@ function loadConfig(options = {}) {
     throw new Error(`Invalid config file (${resolvedPath}):
 ${formatted}`);
   }
-  return result.data;
+  return result.data;
+}
+function readEnvMode(content) {
+  if (content === null || typeof content !== "object" || Array.isArray(content)) {
+    return DEFAULT_ENV_MODE;
+  }
+  const value = content.env;
+  if (value === void 0) return DEFAULT_ENV_MODE;
+  if (typeof value === "string" && VALID_ENV_MODES.includes(value)) {
+    return value;
+  }
+  return DEFAULT_ENV_MODE;
+}
+function isYamlFile(filePath) {
+  return filePath.endsWith(".yml") || filePath.endsWith(".yaml");
+}
+
+// src/config/json-schema.ts
+import { z as z2 } from "zod";
+
+// src/auth/browser.ts
+import { spawn } from "child_process";
+import process3 from "process";
+async function openUrl(url) {
+  const { command, args } = openerForPlatform(url);
+  return new Promise((resolve4, reject) => {
+    const child = spawn(command, args, {
+      stdio: "ignore",
+      detached: true
+    });
+    child.once("error", reject);
+    child.once("spawn", () => {
+      child.unref();
+      resolve4();
+    });
+  });
+}
+function openerForPlatform(url) {
+  switch (process3.platform) {
+    case "darwin":
+      return { command: "open", args: [url] };
+    case "win32":
+      return { command: "cmd", args: ["/c", "start", '""', url] };
+    default:
+      return { command: "xdg-open", args: [url] };
+  }
+}
+
+// src/auth/callback-server.ts
+import { createServer } from "http";
+var CallbackTimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(`Timed out after ${timeoutMs}ms waiting for the OAuth callback.`);
+    this.name = "CallbackTimeoutError";
+  }
+};
+var CallbackOAuthError = class extends Error {
+  constructor(oauthError, oauthErrorDescription) {
+    super(
+      oauthErrorDescription ? `OAuth error from authorization server: ${oauthError} \u2014 ${oauthErrorDescription}` : `OAuth error from authorization server: ${oauthError}`
+    );
+    this.oauthError = oauthError;
+    this.oauthErrorDescription = oauthErrorDescription;
+    this.name = "CallbackOAuthError";
+  }
+  oauthError;
+  oauthErrorDescription;
+};
+var SUCCESS_HTML = `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>dynmcp \u2014 authorization complete</title>
+    <style>
+      body { font-family: -apple-system, BlinkMacSystemFont, sans-serif; padding: 4rem; max-width: 36rem; margin: 0 auto; color: #222; }
+      code { background: #f4f4f4; padding: 0.1rem 0.3rem; border-radius: 3px; }
+    </style>
+  </head>
+  <body>
+    <h1>Authorization complete</h1>
+    <p>You may close this tab and return to your terminal.</p>
+    <p><small>Issued by <code>dynmcp</code>.</small></p>
+  </body>
+</html>
+`;
+var ERROR_HTML_PREFIX = `<!DOCTYPE html>
+<html lang="en">
+  <head><meta charset="utf-8" /><title>dynmcp \u2014 authorization failed</title></head>
+  <body style="font-family: -apple-system, BlinkMacSystemFont, sans-serif; padding: 4rem; max-width: 36rem; margin: 0 auto;">
+    <h1>Authorization failed</h1>
+    <p>`;
+var ERROR_HTML_SUFFIX = `</p>
+    <p>Return to your terminal for details.</p>
+  </body>
+</html>
+`;
+var CallbackServer = class _CallbackServer {
+  server = null;
+  boundPort = null;
+  pending = null;
+  /** The redirect path served. Must match the redirect URI registered with the OAuth client. */
+  static CALLBACK_PATH = "/callback";
+  /** Begins listening on `127.0.0.1` at an OS-assigned port. */
+  async start() {
+    if (this.server !== null) {
+      throw new Error("CallbackServer is already started.");
+    }
+    const server = createServer((req, res) => this.handleRequest(req, res));
+    await new Promise((resolve4, reject) => {
+      const onError = (err) => {
+        server.removeListener("listening", onListening);
+        reject(err);
+      };
+      const onListening = () => {
+        server.removeListener("error", onError);
+        resolve4();
+      };
+      server.once("error", onError);
+      server.once("listening", onListening);
+      server.listen({ port: 0, host: "127.0.0.1" });
+    });
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+      server.close();
+      throw new Error("Failed to determine bound port for callback server.");
+    }
+    this.boundPort = address.port;
+    this.server = server;
+  }
+  /** The port the OS assigned. Available after {@link start} resolves. */
+  get port() {
+    if (this.boundPort === null) {
+      throw new Error("CallbackServer is not started.");
+    }
+    return this.boundPort;
+  }
+  /** The full redirect URI to register with the authorization server. */
+  get redirectUri() {
+    return `http://127.0.0.1:${this.port}${_CallbackServer.CALLBACK_PATH}`;
+  }
+  /**
+   * Resolves with the captured `code` and `state` once a valid callback is received,
+   * or rejects with {@link CallbackTimeoutError} / {@link CallbackOAuthError} on the
+   * documented failure paths. Only one callback is accepted; subsequent requests to
+   * `/callback` after the first valid hit return `400`.
+   */
+  awaitCallback(timeoutMs) {
+    if (this.server === null) {
+      return Promise.reject(new Error("CallbackServer is not started."));
+    }
+    if (this.pending !== null) {
+      return Promise.reject(new Error("awaitCallback already in progress."));
+    }
+    return new Promise((resolve4, reject) => {
+      const timer = setTimeout(() => {
+        this.pending = null;
+        reject(new CallbackTimeoutError(timeoutMs));
+      }, timeoutMs);
+      this.pending = { resolve: resolve4, reject, timer };
+    });
+  }
+  /** Closes the listening socket. Safe to call multiple times. */
+  async stop() {
+    if (this.pending !== null) {
+      clearTimeout(this.pending.timer);
+      this.pending = null;
+    }
+    if (this.server === null) return;
+    await new Promise((resolve4) => {
+      this.server.close(() => resolve4());
+    });
+    this.server = null;
+    this.boundPort = null;
+  }
+  handleRequest(req, res) {
+    if (req.method !== "GET") {
+      res.writeHead(405, { "content-type": "text/plain", allow: "GET" });
+      res.end("Method Not Allowed");
+      return;
+    }
+    const url = new URL(req.url ?? "/", `http://127.0.0.1:${this.boundPort ?? 0}`);
+    if (url.pathname !== _CallbackServer.CALLBACK_PATH) {
+      res.writeHead(404, { "content-type": "text/plain" });
+      res.end("Not Found");
+      return;
+    }
+    if (this.pending === null) {
+      res.writeHead(400, { "content-type": "text/plain" });
+      res.end("No callback expected.");
+      return;
+    }
+    const oauthError = url.searchParams.get("error");
+    if (oauthError !== null) {
+      const errorDescription = url.searchParams.get("error_description") ?? void 0;
+      this.respondError(res, oauthError, errorDescription);
+      const { reject, timer: timer2 } = this.pending;
+      clearTimeout(timer2);
+      this.pending = null;
+      reject(new CallbackOAuthError(oauthError, errorDescription));
+      return;
+    }
+    const code = url.searchParams.get("code");
+    const state = url.searchParams.get("state");
+    if (code === null || state === null) {
+      this.respondError(res, "invalid_callback", "Missing code or state parameter.");
+      const { reject, timer: timer2 } = this.pending;
+      clearTimeout(timer2);
+      this.pending = null;
+      reject(new Error("Callback missing code or state parameter."));
+      return;
+    }
+    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+    res.end(SUCCESS_HTML);
+    const { resolve: resolve4, timer } = this.pending;
+    clearTimeout(timer);
+    this.pending = null;
+    resolve4({ code, state });
+  }
+  respondError(res, errorCode, description2) {
+    res.writeHead(400, { "content-type": "text/html; charset=utf-8" });
+    res.end(
+      ERROR_HTML_PREFIX + escapeHtml(description2 ?? `OAuth error: ${errorCode}`) + ERROR_HTML_SUFFIX
+    );
+  }
+};
+function escapeHtml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+
+// src/auth/login.ts
+var CALLBACK_TIMEOUT_MS = 6e4;
+async function login(options) {
+  const config = loadConfig({
+    configPath: options.configPath,
+    envFilePath: options.envFilePath
+  });
+  const entry = resolveOAuthCapableEntry(config, options.mcpName);
+  const writeStatus = options.writeStatus ?? defaultStatusWriter;
+  const openInBrowser = options.openInBrowser ?? openUrl;
+  writeStatus(`Probing ${entry.url} for OAuth challenge...
+`);
+  const resourceMetadataUrl = await probeFor401ResourceMetadata(entry.url);
+  if (resourceMetadataUrl === void 0) {
+    throw new Error(
+      `Upstream "${options.mcpName}" did not return a 401 challenge with a WWW-Authenticate \`resource_metadata\` URL. The server does not appear to require OAuth; no credentials stored.`
+    );
+  }
+  const keychain = new KeychainStore(options.mcpName, entry.url);
+  const callbackServer = new CallbackServer();
+  await callbackServer.start();
+  writeStatus(`Callback server listening on ${callbackServer.redirectUri}
+`);
+  try {
+    const provider = new LoginOAuthProvider({
+      mcpName: options.mcpName,
+      keychain,
+      configAuth: configAuthFromEntry(entry),
+      redirectUri: callbackServer.redirectUri,
+      callbacks: {
+        onAuthorizationUrl: async (url) => {
+          writeStatus(`Opening browser for authorization: ${url.toString()}
+`);
+          try {
+            await openInBrowser(url.toString());
+          } catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            writeStatus(
+              `Failed to launch browser (${reason}). Open this URL manually:
+  ${url.toString()}
+`
+            );
+          }
+        }
+      }
+    });
+    const firstResult = await auth(provider, {
+      serverUrl: entry.url,
+      resourceMetadataUrl,
+      ...entry.auth?.scope !== void 0 ? { scope: entry.auth.scope } : {}
+    });
+    if (firstResult === "AUTHORIZED") {
+      writeStatus(`Already authorized for "${options.mcpName}"; no changes made.
+`);
+      return;
+    }
+    writeStatus(`Waiting for browser callback (timeout ${CALLBACK_TIMEOUT_MS / 1e3}s)...
+`);
+    const { code, state: receivedState } = await callbackServer.awaitCallback(CALLBACK_TIMEOUT_MS);
+    const expectedState = provider.currentState;
+    if (expectedState === void 0 || receivedState !== expectedState) {
+      throw new Error(
+        "OAuth state mismatch on callback. Possible CSRF attempt or stale browser tab; not exchanging the authorization code."
+      );
+    }
+    const secondResult = await auth(provider, {
+      serverUrl: entry.url,
+      authorizationCode: code,
+      resourceMetadataUrl,
+      ...entry.auth?.scope !== void 0 ? { scope: entry.auth.scope } : {}
+    });
+    if (secondResult !== "AUTHORIZED") {
+      throw new Error(`Token exchange did not return AUTHORIZED (got ${secondResult}).`);
+    }
+    writeStatus(`Successfully authenticated "${options.mcpName}".
+`);
+  } finally {
+    await callbackServer.stop();
+  }
+}
+function resolveOAuthCapableEntry(config, mcpName2) {
+  const entry = config.mcp[mcpName2];
+  if (entry === void 0) {
+    const available = Object.keys(config.mcp).sort().join(", ");
+    throw new Error(`Unknown MCP "${mcpName2}". Configured MCPs: ${available || "(none)"}.`);
+  }
+  if (entry.transport !== "streamable-http" && entry.transport !== "sse") {
+    throw new Error(
+      `MCP "${mcpName2}" uses the "${entry.transport}" transport; OAuth is only supported for streamable-http and sse upstreams.`
+    );
+  }
+  return entry;
+}
+function configAuthFromEntry(entry) {
+  if (entry.auth === void 0) return void 0;
+  const overrides = { client_id: entry.auth.client_id };
+  if (entry.auth.client_secret !== void 0) overrides.client_secret = entry.auth.client_secret;
+  if (entry.auth.scope !== void 0) overrides.scope = entry.auth.scope;
+  return overrides;
+}
+async function probeFor401ResourceMetadata(serverUrl) {
+  let response;
+  try {
+    response = await fetch(serverUrl, { method: "GET", redirect: "manual" });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to reach ${serverUrl}: ${reason}`);
+  }
+  if (response.status !== 401) {
+    return void 0;
+  }
+  const { resourceMetadataUrl } = extractWWWAuthenticateParams(response);
+  return resourceMetadataUrl;
+}
+function defaultStatusWriter(message) {
+  process4.stderr.write(message);
+}
+
+// src/auth/logout.ts
+import process5 from "process";
+async function logout(options) {
+  const config = loadConfig({
+    configPath: options.configPath,
+    envFilePath: options.envFilePath
+  });
+  const entry = resolveOAuthCapableEntry2(config, options.mcpName);
+  const writeStatus = options.writeStatus ?? defaultStatusWriter2;
+  const keychain = new KeychainStore(options.mcpName, entry.url);
+  const removed = keychain.delete();
+  if (removed) {
+    writeStatus(`Removed keychain credentials for "${options.mcpName}".
+`);
+  } else {
+    writeStatus(
+      `No keychain credentials were stored for "${options.mcpName}"; nothing to remove.
+`
+    );
+  }
+}
+function resolveOAuthCapableEntry2(config, mcpName2) {
+  const entry = config.mcp[mcpName2];
+  if (entry === void 0) {
+    const available = Object.keys(config.mcp).sort().join(", ");
+    throw new Error(`Unknown MCP "${mcpName2}". Configured MCPs: ${available || "(none)"}.`);
+  }
+  if (entry.transport !== "streamable-http" && entry.transport !== "sse") {
+    throw new Error(
+      `MCP "${mcpName2}" uses the "${entry.transport}" transport; OAuth is only supported for streamable-http and sse upstreams.`
+    );
+  }
+  return entry;
+}
+function defaultStatusWriter2(message) {
+  process5.stderr.write(message);
+}
+
+// src/diagnostics/list.ts
+import process6 from "process";
+
+// src/diagnostics/format.ts
+function renderTable(headers, rows) {
+  const allRows = [headers, ...rows];
+  const widths = headers.map(
+    (_, colIdx) => Math.max(...allRows.map((row) => (row[colIdx] ?? "").length))
+  );
+  return allRows.map(
+    (row) => row.map((cell, i) => {
+      if (i === headers.length - 1) return cell;
+      return cell.padEnd(widths[i] ?? 0);
+    }).join("  ").trimEnd()
+  ).join("\n");
+}
+function truncate(value, max) {
+  if (value.length <= max) return value;
+  if (max <= 3) return value.slice(0, max);
+  return `${value.slice(0, max - 3)}...`;
+}
+function humanizeDuration(seconds) {
+  if (seconds < 0) return "expired";
+  if (seconds < 60) return `${Math.floor(seconds)}s`;
+  const totalMinutes = Math.floor(seconds / 60);
+  if (totalMinutes < 60) return `${totalMinutes}m`;
+  const totalHours = Math.floor(totalMinutes / 60);
+  const remainingMinutes = totalMinutes % 60;
+  if (totalHours < 24) {
+    return remainingMinutes > 0 ? `${totalHours}h ${remainingMinutes}m` : `${totalHours}h`;
+  }
+  const totalDays = Math.floor(totalHours / 24);
+  const remainingHours = totalHours % 24;
+  return remainingHours > 0 ? `${totalDays}d ${remainingHours}h` : `${totalDays}d`;
+}
+
+// src/diagnostics/list.ts
+var ENDPOINT_MAX_WIDTH = 48;
+async function list(options = {}) {
+  const config = loadConfig({
+    configPath: options.configPath,
+    envFilePath: options.envFilePath
+  });
+  const write = options.write ?? ((chunk) => void process6.stdout.write(chunk));
+  const now = options.now ?? (() => Math.floor(Date.now() / 1e3));
+  const entries = buildEntries(config, now);
+  if (options.json === true) {
+    write(`${JSON.stringify(entries, null, 2)}
+`);
+    return;
+  }
+  if (entries.length === 0) {
+    write("No upstream MCPs configured.\n");
+    return;
+  }
+  const headers = ["NAME", "TRANSPORT", "MODE", "ENDPOINT", "AUTH"];
+  const rows = entries.map((entry) => [
+    entry.name,
+    entry.transport,
+    entry.mode,
+    truncate(entry.endpoint, ENDPOINT_MAX_WIDTH),
+    formatAuthStatus(entry.auth)
+  ]);
+  write(`${renderTable(headers, rows)}
+`);
+}
+function buildEntries(config, now) {
+  return Object.entries(config.mcp).map(([name, entry]) => {
+    const mode = entry.description !== void 0 ? "lazy" : "eager";
+    if (entry.transport === "stdio") {
+      const command = entry.command;
+      const args = (entry.args ?? []).join(" ");
+      const endpoint = args.length > 0 ? `${command} ${args}` : command;
+      const built2 = {
+        name,
+        transport: "stdio",
+        mode,
+        endpoint,
+        auth: { kind: "n/a" }
+      };
+      if (entry.description !== void 0) built2.description = entry.description;
+      return built2;
+    }
+    const hasAuthHeader = hasBearerAuthHeader(entry.headers);
+    const keychain = new KeychainStore(name, entry.url);
+    const blob = keychain.get();
+    let auth2;
+    if (blob !== void 0) {
+      const expiresInSeconds = blob.expires_at - now();
+      auth2 = {
+        kind: "oauth",
+        status: "logged_in",
+        expiresInSeconds,
+        expiresAt: blob.expires_at
+      };
+      if (hasAuthHeader) auth2.alsoHeader = true;
+    } else if (hasAuthHeader) {
+      auth2 = { kind: "header" };
+    } else {
+      auth2 = { kind: "oauth", status: "not_logged_in" };
+    }
+    const built = {
+      name,
+      transport: entry.transport,
+      mode,
+      endpoint: entry.url,
+      auth: auth2
+    };
+    if (entry.description !== void 0) built.description = entry.description;
+    return built;
+  });
+}
+function hasBearerAuthHeader(headers) {
+  if (headers === void 0) return false;
+  for (const key of Object.keys(headers)) {
+    if (key.toLowerCase() === "authorization") return true;
+  }
+  return false;
+}
+function formatAuthStatus(auth2) {
+  switch (auth2.kind) {
+    case "n/a":
+      return "n/a";
+    case "header":
+      return "header";
+    case "oauth": {
+      if (auth2.status === "not_logged_in") return "oauth: not logged in";
+      const duration = humanizeDuration(auth2.expiresInSeconds ?? 0);
+      const base = `oauth: logged in (expires in ${duration})`;
+      return auth2.alsoHeader === true ? `${base} (header also set)` : base;
+    }
+  }
+}
+
+// src/diagnostics/test.ts
+import process8 from "process";
+
+// src/proxy/transport-factory.ts
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+function createTransport(mcpName2, config) {
+  switch (config.transport) {
+    case "stdio":
+      return new StdioClientTransport({
+        command: config.command,
+        args: config.args,
+        env: config.env
+      });
+    case "streamable-http":
+      return new StreamableHTTPClientTransport(new URL(config.url), {
+        ...config.headers !== void 0 ? { requestInit: { headers: config.headers } } : {},
+        authProvider: buildOAuthProvider(mcpName2, config)
+      });
+    case "sse":
+      return new SSEClientTransport(new URL(config.url), {
+        ...config.headers !== void 0 ? { requestInit: { headers: config.headers } } : {},
+        authProvider: buildOAuthProvider(mcpName2, config)
+      });
+    default: {
+      const _exhaustive = config;
+      return _exhaustive;
+    }
+  }
+}
+function buildOAuthProvider(mcpName2, config) {
+  const keychain = new KeychainStore(mcpName2, config.url);
+  return new ProxyOAuthProvider(mcpName2, keychain, config.auth);
+}
+
+// src/proxy/upstream-client.ts
+import process7 from "process";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import {
+  CreateMessageRequestSchema,
+  ElicitRequestSchema,
+  ListRootsRequestSchema,
+  LoggingMessageNotificationSchema,
+  PromptListChangedNotificationSchema,
+  ResourceListChangedNotificationSchema,
+  ResourceUpdatedNotificationSchema,
+  ToolListChangedNotificationSchema
+} from "@modelcontextprotocol/sdk/types.js";
+var UpstreamClient = class {
+  transport;
+  onTransportError;
+  notificationHandlers;
+  serverRequestHandlers;
+  client = null;
+  constructor({
+    name,
+    transport,
+    onTransportError,
+    notifications,
+    serverRequests
+  }) {
+    this.transport = transport;
+    this.notificationHandlers = notifications ?? {};
+    this.serverRequestHandlers = serverRequests ?? {};
+    this.onTransportError = onTransportError ?? ((error) => {
+      process7.stderr.write(`[${name}] Upstream MCP transport error: ${error.message}
+`);
+    });
+  }
+  async connect() {
+    this.transport.onerror = this.onTransportError;
+    this.client = new Client(
+      { name: "dynamic-discovery-mcp", version: "1.0.0" },
+      {
+        capabilities: {
+          // Declare every client-side capability the proxy may relay on behalf of the host.
+          // Actual reachability of each feature depends on what the host supports — if the
+          // host does not support sampling, for instance, the host call returns an error
+          // which we forward back to the upstream verbatim.
+          sampling: {},
+          elicitation: {},
+          roots: { listChanged: true }
+        }
+      }
+    );
+    this.registerServerRequestHandlers(this.client);
+    if (this.notificationHandlers.onToolsListChanged !== void 0) {
+      this.client.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
+        await this.notificationHandlers.onToolsListChanged?.();
+      });
+    }
+    if (this.notificationHandlers.onResourcesListChanged !== void 0) {
+      this.client.setNotificationHandler(ResourceListChangedNotificationSchema, async () => {
+        await this.notificationHandlers.onResourcesListChanged?.();
+      });
+    }
+    if (this.notificationHandlers.onResourceUpdated !== void 0) {
+      this.client.setNotificationHandler(ResourceUpdatedNotificationSchema, async (notification) => {
+        await this.notificationHandlers.onResourceUpdated?.({ uri: notification.params.uri });
+      });
+    }
+    if (this.notificationHandlers.onPromptsListChanged !== void 0) {
+      this.client.setNotificationHandler(PromptListChangedNotificationSchema, async () => {
+        await this.notificationHandlers.onPromptsListChanged?.();
+      });
+    }
+    if (this.notificationHandlers.onLogMessage !== void 0) {
+      this.client.setNotificationHandler(LoggingMessageNotificationSchema, async (notification) => {
+        await this.notificationHandlers.onLogMessage?.(notification.params);
+      });
+    }
+    await this.client.connect(this.transport);
+  }
+  async setLoggingLevel(level, options) {
+    const client = this.requireClient();
+    await client.setLoggingLevel(level, options);
+  }
+  async listPrompts(options) {
+    const client = this.requireClient();
+    const result = await client.listPrompts(void 0, options);
+    return result.prompts;
+  }
+  async getPrompt(name, args, options) {
+    const client = this.requireClient();
+    const params = { name };
+    if (args !== void 0) {
+      params.arguments = args;
+    }
+    return client.getPrompt(params, options);
+  }
+  async complete(params, options) {
+    const client = this.requireClient();
+    return client.complete(params, options);
+  }
+  /**
+   * Returns the capabilities advertised by the upstream server during initialize.
+   * Returns `undefined` if the client is not connected, or if the SDK has not yet
+   * recorded the server's capabilities (e.g. during a partially-completed handshake).
+   */
+  getCapabilities() {
+    return this.client?.getServerCapabilities();
+  }
+  async listTools(options) {
+    const client = this.requireClient();
+    const result = await client.listTools(void 0, options);
+    return result.tools.map((tool) => {
+      const upstreamTool = {
+        name: tool.name,
+        description: tool.description ?? "",
+        inputSchema: tool.inputSchema
+      };
+      if (tool.outputSchema !== void 0) {
+        upstreamTool.outputSchema = tool.outputSchema;
+      }
+      if (tool.annotations !== void 0) {
+        upstreamTool.annotations = {
+          title: tool.annotations.title,
+          readOnlyHint: tool.annotations.readOnlyHint,
+          destructiveHint: tool.annotations.destructiveHint,
+          idempotentHint: tool.annotations.idempotentHint,
+          openWorldHint: tool.annotations.openWorldHint
+        };
+      }
+      return upstreamTool;
+    });
+  }
+  async callTool(name, input, options) {
+    const client = this.requireClient();
+    const result = await client.callTool({ name, arguments: input }, void 0, options);
+    return result;
+  }
+  async listResources(options) {
+    const client = this.requireClient();
+    const result = await client.listResources(void 0, options);
+    return result.resources;
+  }
+  async listResourceTemplates(options) {
+    const client = this.requireClient();
+    const result = await client.listResourceTemplates(void 0, options);
+    return result.resourceTemplates;
+  }
+  async readResource(uri, options) {
+    const client = this.requireClient();
+    return client.readResource({ uri }, options);
+  }
+  async subscribeResource(uri, options) {
+    const client = this.requireClient();
+    await client.subscribeResource({ uri }, options);
+  }
+  async unsubscribeResource(uri, options) {
+    const client = this.requireClient();
+    await client.unsubscribeResource({ uri }, options);
+  }
+  async disconnect() {
+    if (this.client === null) {
+      return;
+    }
+    await this.client.close();
+    this.client = null;
+  }
+  /**
+   * Sends `notifications/roots/list_changed` to the upstream, letting it know that
+   * the host's set of filesystem roots has changed.
+   */
+  async sendRootsListChanged() {
+    const client = this.requireClient();
+    await client.sendRootsListChanged();
+  }
+  registerServerRequestHandlers(client) {
+    if (this.serverRequestHandlers.onCreateMessage !== void 0) {
+      client.setRequestHandler(
+        CreateMessageRequestSchema,
+        async (request, extra) => {
+          return this.serverRequestHandlers.onCreateMessage(request.params, {
+            signal: extra.signal
+          });
+        }
+      );
+    }
+    if (this.serverRequestHandlers.onElicitInput !== void 0) {
+      client.setRequestHandler(
+        ElicitRequestSchema,
+        async (request, extra) => {
+          return this.serverRequestHandlers.onElicitInput(request.params, {
+            signal: extra.signal
+          });
+        }
+      );
+    }
+    if (this.serverRequestHandlers.onListRoots !== void 0) {
+      client.setRequestHandler(
+        ListRootsRequestSchema,
+        async (request, extra) => {
+          return this.serverRequestHandlers.onListRoots(request.params, {
+            signal: extra.signal
+          });
+        }
+      );
+    }
+  }
+  requireClient() {
+    if (this.client === null) {
+      throw new Error("Client is not connected. Call connect() first.");
+    }
+    return this.client;
+  }
+};
+
+// src/diagnostics/test.ts
+var DESCRIPTION_MAX_LENGTH = 100;
+var DEFAULT_TIMEOUT_MS = 15e3;
+async function test(options = {}) {
+  const config = loadConfig({
+    configPath: options.configPath,
+    envFilePath: options.envFilePath
+  });
+  const write = options.write ?? ((chunk) => void process8.stdout.write(chunk));
+  const now = options.now ?? (() => Math.floor(Date.now() / 1e3));
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  if (options.mcpName !== void 0) {
+    return runSingle(config, options.mcpName, {
+      write,
+      now,
+      timeoutMs,
+      json: options.json === true
+    });
+  }
+  return runAll(config, { write, now, timeoutMs, json: options.json === true });
+}
+async function runSingle(config, mcpName2, options) {
+  const entry = config.mcp[mcpName2];
+  if (entry === void 0) {
+    const available = Object.keys(config.mcp).sort().join(", ");
+    throw new Error(`Unknown MCP "${mcpName2}". Configured MCPs: ${available || "(none)"}.`);
+  }
+  if (!options.json) {
+    options.write(`Testing "${mcpName2}" (${entry.transport}, ${endpointForEntry(entry)})
+`);
+  }
+  const result = await probeOne(mcpName2, entry, options.timeoutMs, options.now);
+  if (options.json) {
+    options.write(`${JSON.stringify(result, null, 2)}
+`);
+  } else {
+    for (const step of result.steps) {
+      options.write(`  [${step.status}] ${step.label}
+`);
+      if (step.error !== void 0) {
+        options.write(`    -> ${step.error}
+`);
+      }
+    }
+    renderDiscoveredSurface(options.write, result);
+    options.write(`Result: ${result.result}
+`);
+  }
+  return result.result === "PASS" ? 0 : 1;
+}
+async function runAll(config, options) {
+  const names = Object.keys(config.mcp);
+  const total = names.length;
+  if (!options.json) {
+    options.write(`Testing all configured upstreams (${total})...
+
+`);
+  }
+  const results = [];
+  for (let index = 0; index < names.length; index += 1) {
+    const name = names[index];
+    const entry = config.mcp[name];
+    if (!options.json) {
+      options.write(`[${index + 1}/${total}] ${name} (${entry.transport}) ... `);
+    }
+    const result = await probeOne(name, entry, options.timeoutMs, options.now);
+    results.push(result);
+    if (!options.json) {
+      if (result.result === "PASS") {
+        const counts = `${result.tools?.length ?? 0} tools, ${(result.resources?.length ?? 0) + (result.resource_templates?.length ?? 0)} resources, ${result.prompts?.length ?? 0} prompts`;
+        options.write(`PASS (${counts})
+`);
+      } else {
+        options.write(`FAIL (${result.fail_reason ?? "unknown"})
+`);
+      }
+    }
+  }
+  const passed = results.filter((r) => r.result === "PASS").length;
+  const failed = results.length - passed;
+  if (options.json) {
+    const payload = { summary: { passed, failed }, results };
+    options.write(`${JSON.stringify(payload, null, 2)}
+`);
+  } else {
+    options.write(`
+Summary: ${passed} passed, ${failed} failed
+`);
+  }
+  return failed === 0 ? 0 : 1;
+}
+async function probeOne(mcpName2, entry, timeoutMs, now) {
+  const result = {
+    name: mcpName2,
+    result: "PASS",
+    transport: entry.transport,
+    endpoint: endpointForEntry(entry),
+    auth: deriveAuthSummary(mcpName2, entry, now),
+    steps: []
+  };
+  if (entry.transport !== "stdio") {
+    result.steps.push({ label: authStepLabel(result.auth), status: "ok" });
+  }
+  const clientHolder = { value: null };
+  let timeoutHandle;
+  const run = (async () => {
+    const transport = createTransport(mcpName2, entry);
+    const client = new UpstreamClient({
+      name: mcpName2,
+      transport,
+      onTransportError: () => {
+      }
+    });
+    clientHolder.value = client;
+    await client.connect();
+    result.steps.push({ label: "Connected and initialized", status: "ok" });
+    const caps = client.getCapabilities();
+    result.capabilities = caps;
+    result.steps.push({
+      label: `Capabilities: ${describeCapabilities(caps)}`,
+      status: "ok"
+    });
+    const tools = await client.listTools();
+    result.tools = tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description
+    }));
+    result.steps.push({
+      label: `tools/list returned ${tools.length} tool${tools.length === 1 ? "" : "s"}`,
+      status: "ok"
+    });
+    let resources = [];
+    let templates = [];
+    if (caps?.resources !== void 0) {
+      try {
+        resources = await client.listResources();
+        templates = await client.listResourceTemplates();
+        result.resources = resources.map((r) => {
+          const out = {
+            uri: r.uri,
+            name: r.name
+          };
+          if (r.description !== void 0) out.description = r.description;
+          return out;
+        });
+        result.resource_templates = templates.map((t) => {
+          const out = {
+            uriTemplate: t.uriTemplate,
+            name: t.name
+          };
+          if (t.description !== void 0) out.description = t.description;
+          return out;
+        });
+        result.steps.push({
+          label: `resources/list returned ${resources.length} resource${resources.length === 1 ? "" : "s"}, ${templates.length} template${templates.length === 1 ? "" : "s"}`,
+          status: "ok"
+        });
+      } catch (error) {
+        result.steps.push({
+          label: "resources/list",
+          status: "fail",
+          error: errorMessage(error)
+        });
+      }
+    }
+    let prompts = [];
+    if (caps?.prompts !== void 0) {
+      try {
+        prompts = await client.listPrompts();
+        result.prompts = prompts.map((p) => {
+          const out = { name: p.name };
+          if (p.description !== void 0) out.description = p.description;
+          return out;
+        });
+        result.steps.push({
+          label: `prompts/list returned ${prompts.length} prompt${prompts.length === 1 ? "" : "s"}`,
+          status: "ok"
+        });
+      } catch (error) {
+        result.steps.push({
+          label: "prompts/list",
+          status: "fail",
+          error: errorMessage(error)
+        });
+      }
+    }
+  })();
+  const timeout = new Promise((_, reject) => {
+    timeoutHandle = setTimeout(() => {
+      reject(new TestTimeoutError(timeoutMs));
+    }, timeoutMs);
+  });
+  try {
+    await Promise.race([run, timeout]);
+  } catch (error) {
+    result.result = "FAIL";
+    result.fail_reason = failReason(error, mcpName2);
+    result.steps.push({
+      label: `aborted: ${result.fail_reason}`,
+      status: "fail",
+      error: errorMessage(error)
+    });
+  } finally {
+    if (timeoutHandle !== void 0) clearTimeout(timeoutHandle);
+    const connected = clientHolder.value;
+    if (connected !== null) {
+      try {
+        await connected.disconnect();
+      } catch {
+      }
+    }
+  }
+  if (result.result === "PASS" && result.steps.some((s) => s.status === "fail")) {
+    result.result = "FAIL";
+    const failed = result.steps.find((s) => s.status === "fail");
+    result.fail_reason = failed?.error ?? failed?.label ?? "unknown";
+  }
+  return result;
+}
+var TestTimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(`Test timed out after ${timeoutMs}ms`);
+    this.name = "TestTimeoutError";
+  }
+};
+function endpointForEntry(entry) {
+  if (entry.transport === "stdio") {
+    const args = (entry.args ?? []).join(" ");
+    return args.length > 0 ? `${entry.command} ${args}` : entry.command;
+  }
+  return entry.url;
 }
-function readEnvMode(content) {
-  if (content === null || typeof content !== "object" || Array.isArray(content)) {
-    return DEFAULT_ENV_MODE;
+function deriveAuthSummary(mcpName2, entry, now) {
+  if (entry.transport === "stdio") return { kind: "n/a" };
+  const keychain = new KeychainStore(mcpName2, entry.url);
+  const blob = keychain.get();
+  if (blob !== void 0) {
+    return {
+      kind: "oauth",
+      status: "valid",
+      expiresInSeconds: blob.expires_at - now()
+    };
   }
-  const value = content.env;
-  if (value === void 0) return DEFAULT_ENV_MODE;
-  if (typeof value === "string" && VALID_ENV_MODES.includes(value)) {
-    return value;
+  const hasHeader = entry.headers !== void 0 && Object.keys(entry.headers).some((k) => k.toLowerCase() === "authorization");
+  if (hasHeader) return { kind: "header" };
+  return { kind: "oauth", status: "missing" };
+}
+function authStepLabel(auth2) {
+  switch (auth2.kind) {
+    case "n/a":
+      return "(no auth applicable)";
+    case "header":
+      return "Static Authorization header present";
+    case "oauth":
+      if (auth2.status === "missing") return "No cached OAuth token";
+      return `OAuth token present (expires in ${humanizeDuration(auth2.expiresInSeconds ?? 0)})`;
   }
-  return DEFAULT_ENV_MODE;
 }
-function isYamlFile(filePath) {
-  return filePath.endsWith(".yml") || filePath.endsWith(".yaml");
+function describeCapabilities(caps) {
+  if (caps === void 0) return "(none advertised)";
+  const parts = [];
+  for (const [name, value] of Object.entries(caps)) {
+    if (value === void 0 || value === null) continue;
+    if (typeof value === "object" && Object.keys(value).length > 0) {
+      const flags = Object.entries(value).filter(([, v]) => v === true).map(([k]) => k).join(",");
+      parts.push(flags.length > 0 ? `${name}(${flags})` : name);
+    } else {
+      parts.push(name);
+    }
+  }
+  return parts.length > 0 ? parts.join(", ") : "(none advertised)";
+}
+function failReason(error, mcpName2) {
+  if (isAuthRequiredError(error)) {
+    return `auth required: run \`dynmcp login ${mcpName2}\``;
+  }
+  if (error instanceof TestTimeoutError) return error.message;
+  if (error instanceof Error) return error.message.split("\n")[0] ?? "unknown error";
+  return String(error);
+}
+function errorMessage(error) {
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+function renderDiscoveredSurface(write, result) {
+  if (result.result !== "PASS") return;
+  const sections = [
+    [
+      `Tools (${result.tools?.length ?? 0})`,
+      result.tools && result.tools.length > 0 ? () => {
+        const sorted = [...result.tools ?? []].sort((a, b) => a.name.localeCompare(b.name));
+        for (const tool of sorted) {
+          write(`  - ${tool.name}: ${truncate(tool.description, DESCRIPTION_MAX_LENGTH)}
+`);
+        }
+      } : void 0
+    ],
+    [
+      `Resources (${result.resources?.length ?? 0})`,
+      result.resources && result.resources.length > 0 ? () => {
+        const sorted = [...result.resources ?? []].sort((a, b) => a.uri.localeCompare(b.uri));
+        for (const r of sorted) {
+          const tail = r.description ?? r.name;
+          write(`  - ${r.uri}: ${truncate(tail, DESCRIPTION_MAX_LENGTH)}
+`);
+        }
+      } : void 0
+    ],
+    [
+      `Resource templates (${result.resource_templates?.length ?? 0})`,
+      result.resource_templates && result.resource_templates.length > 0 ? () => {
+        const sorted = [...result.resource_templates ?? []].sort(
+          (a, b) => a.uriTemplate.localeCompare(b.uriTemplate)
+        );
+        for (const t of sorted) {
+          const tail = t.description ?? t.name;
+          write(`  - ${t.uriTemplate}: ${truncate(tail, DESCRIPTION_MAX_LENGTH)}
+`);
+        }
+      } : void 0
+    ],
+    [
+      `Prompts (${result.prompts?.length ?? 0})`,
+      result.prompts && result.prompts.length > 0 ? () => {
+        const sorted = [...result.prompts ?? []].sort((a, b) => a.name.localeCompare(b.name));
+        for (const p of sorted) {
+          const tail = p.description ?? "";
+          write(
+            `  - ${p.name}${tail.length > 0 ? `: ${truncate(tail, DESCRIPTION_MAX_LENGTH)}` : ""}
+`
+          );
+        }
+      } : void 0
+    ]
+  ];
+  for (const [header, render] of sections) {
+    if (render === void 0) continue;
+    write(`
+${header}:
+`);
+    render();
+  }
 }
 
-// src/config/json-schema.ts
-import { z as z2 } from "zod";
+// src/proxy/index.ts
+import process11 from "process";
+import { StdioClientTransport as StdioClientTransport2 } from "@modelcontextprotocol/sdk/client/stdio.js";
 
 // src/proxy/orchestrator.ts
-import process4 from "process";
+import process9 from "process";
 
 // src/proxy/capability-aggregator.ts
 function aggregateCapabilities(upstreams) {
@@ -782,305 +2209,92 @@ var ToolCatalog = class _ToolCatalog {
       const sortedNames = [...this.tools.keys()].sort().join(", ");
       return `Unknown tool: "${toolName}". Available tools: ${sortedNames}`;
     }
-    return buildToolDetailsString(toolName, tool);
-  }
-};
-function buildFlatDescription(tools) {
-  const sortedTools = [...tools].sort((a, b) => a.name.localeCompare(b.name));
-  const toolLines = sortedTools.map((tool) => `- ${tool.name}: ${tool.description}`).join("\n");
-  return `${DISCOVER_TOOL_PREAMBLE}
-
-<tools>
-${toolLines}
-</tools>`;
-}
-function buildGroupedDescription(groups, lazyDescriptions) {
-  const parts = [DISCOVER_TOOL_PREAMBLE];
-  if (lazyDescriptions.size > 0) {
-    parts.push(DYNAMIC_DISCOVERY_PREAMBLE);
-    parts.push(buildMcpServersBlock(lazyDescriptions));
-  }
-  if (groups.size > 0) {
-    parts.push(buildToolsBlock(groups));
-  } else if (lazyDescriptions.size > 0) {
-    parts.push(NO_TOOLS_LOADED_FOOTER);
-  } else {
-    parts.push("<tools>\n</tools>");
-  }
-  return parts.join("\n\n");
-}
-function buildToolsBlock(groups) {
-  const sortedMcpNames = [...groups.keys()].sort();
-  const sections = sortedMcpNames.map((mcpName2) => {
-    const tools = groups.get(mcpName2);
-    const sortedTools = [...tools].sort((a, b) => a.name.localeCompare(b.name));
-    const toolLines = sortedTools.map((tool) => `- ${tool.name}: ${tool.description}`).join("\n");
-    return `${mcpName2}:
-${toolLines}`;
-  });
-  return `<tools>
-${sections.join("\n\n")}
-</tools>`;
-}
-function buildMcpServersBlock(lazyDescriptions) {
-  const lines = [...lazyDescriptions].map(([name, desc]) => `- ${name}: ${desc}`).join("\n");
-  return `<mcp_servers>
-${lines}
-</mcp_servers>`;
-}
-function buildToolDetailsString(displayName, tool) {
-  const lines = [
-    `Tool: ${displayName}`,
-    `Description: ${tool.description}`,
-    "",
-    "Input Schema:",
-    JSON.stringify(tool.inputSchema, null, 2)
-  ];
-  if (tool.outputSchema !== void 0) {
-    lines.push("", "Output Schema:", JSON.stringify(tool.outputSchema, null, 2));
-  }
-  const annotationLines = buildAnnotationLines(tool);
-  if (annotationLines.length > 0) {
-    lines.push("", "Annotations:", ...annotationLines);
-  }
-  return lines.join("\n");
-}
-function buildAnnotationLines(tool) {
-  if (tool.annotations === void 0) {
-    return [];
-  }
-  const { annotations } = tool;
-  const lines = [];
-  if (annotations.title !== void 0) {
-    lines.push(`- title: ${annotations.title}`);
-  }
-  if (annotations.readOnlyHint !== void 0) {
-    lines.push(`- readOnlyHint: ${annotations.readOnlyHint}`);
-  }
-  if (annotations.destructiveHint !== void 0) {
-    lines.push(`- destructiveHint: ${annotations.destructiveHint}`);
-  }
-  if (annotations.idempotentHint !== void 0) {
-    lines.push(`- idempotentHint: ${annotations.idempotentHint}`);
-  }
-  if (annotations.openWorldHint !== void 0) {
-    lines.push(`- openWorldHint: ${annotations.openWorldHint}`);
-  }
-  return lines;
-}
-
-// src/proxy/upstream-client.ts
-import process3 from "process";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import {
-  CreateMessageRequestSchema,
-  ElicitRequestSchema,
-  ListRootsRequestSchema,
-  LoggingMessageNotificationSchema,
-  PromptListChangedNotificationSchema,
-  ResourceListChangedNotificationSchema,
-  ResourceUpdatedNotificationSchema,
-  ToolListChangedNotificationSchema
-} from "@modelcontextprotocol/sdk/types.js";
-var UpstreamClient = class {
-  transport;
-  onTransportError;
-  notificationHandlers;
-  serverRequestHandlers;
-  client = null;
-  constructor({
-    name,
-    transport,
-    onTransportError,
-    notifications,
-    serverRequests
-  }) {
-    this.transport = transport;
-    this.notificationHandlers = notifications ?? {};
-    this.serverRequestHandlers = serverRequests ?? {};
-    this.onTransportError = onTransportError ?? ((error) => {
-      process3.stderr.write(`[${name}] Upstream MCP transport error: ${error.message}
-`);
-    });
-  }
-  async connect() {
-    this.transport.onerror = this.onTransportError;
-    this.client = new Client(
-      { name: "dynamic-discovery-mcp", version: "1.0.0" },
-      {
-        capabilities: {
-          // Declare every client-side capability the proxy may relay on behalf of the host.
-          // Actual reachability of each feature depends on what the host supports — if the
-          // host does not support sampling, for instance, the host call returns an error
-          // which we forward back to the upstream verbatim.
-          sampling: {},
-          elicitation: {},
-          roots: { listChanged: true }
-        }
-      }
-    );
-    this.registerServerRequestHandlers(this.client);
-    if (this.notificationHandlers.onToolsListChanged !== void 0) {
-      this.client.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
-        await this.notificationHandlers.onToolsListChanged?.();
-      });
-    }
-    if (this.notificationHandlers.onResourcesListChanged !== void 0) {
-      this.client.setNotificationHandler(ResourceListChangedNotificationSchema, async () => {
-        await this.notificationHandlers.onResourcesListChanged?.();
-      });
-    }
-    if (this.notificationHandlers.onResourceUpdated !== void 0) {
-      this.client.setNotificationHandler(ResourceUpdatedNotificationSchema, async (notification) => {
-        await this.notificationHandlers.onResourceUpdated?.({ uri: notification.params.uri });
-      });
-    }
-    if (this.notificationHandlers.onPromptsListChanged !== void 0) {
-      this.client.setNotificationHandler(PromptListChangedNotificationSchema, async () => {
-        await this.notificationHandlers.onPromptsListChanged?.();
-      });
-    }
-    if (this.notificationHandlers.onLogMessage !== void 0) {
-      this.client.setNotificationHandler(LoggingMessageNotificationSchema, async (notification) => {
-        await this.notificationHandlers.onLogMessage?.(notification.params);
-      });
-    }
-    await this.client.connect(this.transport);
-  }
-  async setLoggingLevel(level, options) {
-    const client = this.requireClient();
-    await client.setLoggingLevel(level, options);
-  }
-  async listPrompts(options) {
-    const client = this.requireClient();
-    const result = await client.listPrompts(void 0, options);
-    return result.prompts;
-  }
-  async getPrompt(name, args, options) {
-    const client = this.requireClient();
-    const params = { name };
-    if (args !== void 0) {
-      params.arguments = args;
-    }
-    return client.getPrompt(params, options);
-  }
-  async complete(params, options) {
-    const client = this.requireClient();
-    return client.complete(params, options);
-  }
-  /**
-   * Returns the capabilities advertised by the upstream server during initialize.
-   * Returns `undefined` if the client is not connected, or if the SDK has not yet
-   * recorded the server's capabilities (e.g. during a partially-completed handshake).
-   */
-  getCapabilities() {
-    return this.client?.getServerCapabilities();
-  }
-  async listTools(options) {
-    const client = this.requireClient();
-    const result = await client.listTools(void 0, options);
-    return result.tools.map((tool) => {
-      const upstreamTool = {
-        name: tool.name,
-        description: tool.description ?? "",
-        inputSchema: tool.inputSchema
-      };
-      if (tool.outputSchema !== void 0) {
-        upstreamTool.outputSchema = tool.outputSchema;
-      }
-      if (tool.annotations !== void 0) {
-        upstreamTool.annotations = {
-          title: tool.annotations.title,
-          readOnlyHint: tool.annotations.readOnlyHint,
-          destructiveHint: tool.annotations.destructiveHint,
-          idempotentHint: tool.annotations.idempotentHint,
-          openWorldHint: tool.annotations.openWorldHint
-        };
-      }
-      return upstreamTool;
-    });
+    return buildToolDetailsString(toolName, tool);
   }
-  async callTool(name, input, options) {
-    const client = this.requireClient();
-    const result = await client.callTool({ name, arguments: input }, void 0, options);
-    return result;
+};
+function buildFlatDescription(tools) {
+  const sortedTools = [...tools].sort((a, b) => a.name.localeCompare(b.name));
+  const toolLines = sortedTools.map((tool) => `- ${tool.name}: ${tool.description}`).join("\n");
+  return `${DISCOVER_TOOL_PREAMBLE}
+
+<tools>
+${toolLines}
+</tools>`;
+}
+function buildGroupedDescription(groups, lazyDescriptions) {
+  const parts = [DISCOVER_TOOL_PREAMBLE];
+  if (lazyDescriptions.size > 0) {
+    parts.push(DYNAMIC_DISCOVERY_PREAMBLE);
+    parts.push(buildMcpServersBlock(lazyDescriptions));
   }
-  async listResources(options) {
-    const client = this.requireClient();
-    const result = await client.listResources(void 0, options);
-    return result.resources;
+  if (groups.size > 0) {
+    parts.push(buildToolsBlock(groups));
+  } else if (lazyDescriptions.size > 0) {
+    parts.push(NO_TOOLS_LOADED_FOOTER);
+  } else {
+    parts.push("<tools>\n</tools>");
   }
-  async listResourceTemplates(options) {
-    const client = this.requireClient();
-    const result = await client.listResourceTemplates(void 0, options);
-    return result.resourceTemplates;
+  return parts.join("\n\n");
+}
+function buildToolsBlock(groups) {
+  const sortedMcpNames = [...groups.keys()].sort();
+  const sections = sortedMcpNames.map((mcpName2) => {
+    const tools = groups.get(mcpName2);
+    const sortedTools = [...tools].sort((a, b) => a.name.localeCompare(b.name));
+    const toolLines = sortedTools.map((tool) => `- ${tool.name}: ${tool.description}`).join("\n");
+    return `${mcpName2}:
+${toolLines}`;
+  });
+  return `<tools>
+${sections.join("\n\n")}
+</tools>`;
+}
+function buildMcpServersBlock(lazyDescriptions) {
+  const lines = [...lazyDescriptions].map(([name, desc]) => `- ${name}: ${desc}`).join("\n");
+  return `<mcp_servers>
+${lines}
+</mcp_servers>`;
+}
+function buildToolDetailsString(displayName, tool) {
+  const lines = [
+    `Tool: ${displayName}`,
+    `Description: ${tool.description}`,
+    "",
+    "Input Schema:",
+    JSON.stringify(tool.inputSchema, null, 2)
+  ];
+  if (tool.outputSchema !== void 0) {
+    lines.push("", "Output Schema:", JSON.stringify(tool.outputSchema, null, 2));
   }
-  async readResource(uri, options) {
-    const client = this.requireClient();
-    return client.readResource({ uri }, options);
+  const annotationLines = buildAnnotationLines(tool);
+  if (annotationLines.length > 0) {
+    lines.push("", "Annotations:", ...annotationLines);
   }
-  async subscribeResource(uri, options) {
-    const client = this.requireClient();
-    await client.subscribeResource({ uri }, options);
+  return lines.join("\n");
+}
+function buildAnnotationLines(tool) {
+  if (tool.annotations === void 0) {
+    return [];
   }
-  async unsubscribeResource(uri, options) {
-    const client = this.requireClient();
-    await client.unsubscribeResource({ uri }, options);
+  const { annotations } = tool;
+  const lines = [];
+  if (annotations.title !== void 0) {
+    lines.push(`- title: ${annotations.title}`);
   }
-  async disconnect() {
-    if (this.client === null) {
-      return;
-    }
-    await this.client.close();
-    this.client = null;
+  if (annotations.readOnlyHint !== void 0) {
+    lines.push(`- readOnlyHint: ${annotations.readOnlyHint}`);
   }
-  /**
-   * Sends `notifications/roots/list_changed` to the upstream, letting it know that
-   * the host's set of filesystem roots has changed.
-   */
-  async sendRootsListChanged() {
-    const client = this.requireClient();
-    await client.sendRootsListChanged();
+  if (annotations.destructiveHint !== void 0) {
+    lines.push(`- destructiveHint: ${annotations.destructiveHint}`);
   }
-  registerServerRequestHandlers(client) {
-    if (this.serverRequestHandlers.onCreateMessage !== void 0) {
-      client.setRequestHandler(
-        CreateMessageRequestSchema,
-        async (request, extra) => {
-          return this.serverRequestHandlers.onCreateMessage(request.params, {
-            signal: extra.signal
-          });
-        }
-      );
-    }
-    if (this.serverRequestHandlers.onElicitInput !== void 0) {
-      client.setRequestHandler(
-        ElicitRequestSchema,
-        async (request, extra) => {
-          return this.serverRequestHandlers.onElicitInput(request.params, {
-            signal: extra.signal
-          });
-        }
-      );
-    }
-    if (this.serverRequestHandlers.onListRoots !== void 0) {
-      client.setRequestHandler(
-        ListRootsRequestSchema,
-        async (request, extra) => {
-          return this.serverRequestHandlers.onListRoots(request.params, {
-            signal: extra.signal
-          });
-        }
-      );
-    }
+  if (annotations.idempotentHint !== void 0) {
+    lines.push(`- idempotentHint: ${annotations.idempotentHint}`);
   }
-  requireClient() {
-    if (this.client === null) {
-      throw new Error("Client is not connected. Call connect() first.");
-    }
-    return this.client;
+  if (annotations.openWorldHint !== void 0) {
+    lines.push(`- openWorldHint: ${annotations.openWorldHint}`);
   }
-};
+  return lines;
+}
 
 // src/proxy/upstream-registry.ts
 var UpstreamRegistry = class {
@@ -1333,6 +2547,9 @@ var Orchestrator = class {
       }
     } catch (error) {
       await this.registry.deleteOne(mcpName2);
+      if (isAuthRequiredError(error)) {
+        throw error;
+      }
       const failures = this.lazyRegistry.recordFailure(mcpName2);
       if (failures >= MAX_LOAD_ATTEMPTS) {
         this.lazyRegistry.take(mcpName2);
@@ -1579,7 +2796,7 @@ var Orchestrator = class {
       targets.push(
         action(client).catch((error) => {
           const message = error instanceof Error ? error.message : String(error);
-          process4.stderr.write(`dynmcp: ${label} failed for "${mcpName2}": ${message}
+          process9.stderr.write(`dynmcp: ${label} failed for "${mcpName2}": ${message}
 `);
         })
       );
@@ -1604,13 +2821,13 @@ function splitNamespacedName(namespacedName, knownMcpNames) {
 }
 function logCollisions(resourceRouter, promptRouter) {
   for (const collision of resourceRouter.collisions()) {
-    process4.stderr.write(
+    process9.stderr.write(
       `dynmcp: resource URI collision: "${collision.uri}" is provided by "${collision.chosen}" and "${collision.shadowed}"; routing to "${collision.chosen}".
 `
     );
   }
   for (const collision of promptRouter.collisions()) {
-    process4.stderr.write(
+    process9.stderr.write(
       `dynmcp: prompt name collision: "${collision.name}" is provided by "${collision.chosen}" and "${collision.shadowed}"; routing to "${collision.chosen}".
 `
     );
@@ -1618,7 +2835,7 @@ function logCollisions(resourceRouter, promptRouter) {
 }
 
 // src/proxy/server.ts
-import process5 from "process";
+import process10 from "process";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
@@ -1765,7 +2982,7 @@ var ProxyServer = class {
   async start() {
     const server = this.buildServer();
     const transport = new StdioServerTransport();
-    process5.stderr.write("Starting dynamic-discovery-mcp server over stdio\n");
+    process10.stderr.write("Starting dynamic-discovery-mcp server over stdio\n");
     await server.connect(transport);
   }
   /**
@@ -1978,35 +3195,6 @@ var ProxyServer = class {
   }
 };
 
-// src/proxy/transport-factory.ts
-import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
-function createTransport(config) {
-  switch (config.transport) {
-    case "stdio":
-      return new StdioClientTransport({
-        command: config.command,
-        args: config.args,
-        env: config.env
-      });
-    case "streamable-http":
-      return new StreamableHTTPClientTransport(
-        new URL(config.url),
-        config.headers ? { requestInit: { headers: config.headers } } : void 0
-      );
-    case "sse":
-      return new SSEClientTransport(
-        new URL(config.url),
-        config.headers ? { requestInit: { headers: config.headers } } : void 0
-      );
-    default: {
-      const _exhaustive = config;
-      return _exhaustive;
-    }
-  }
-}
-
 // src/proxy/index.ts
 var SINGLE_MCP_NAME = "__default__";
 async function startProxy(command, args) {
@@ -2024,7 +3212,7 @@ async function startProxyFromConfig(options = {}) {
   const eagerMcps = /* @__PURE__ */ new Map();
   const lazyMcps = /* @__PURE__ */ new Map();
   for (const [name, entry] of Object.entries(config.mcp)) {
-    const transport = createTransport(entry);
+    const transport = createTransport(name, entry);
     if (entry.description !== void 0) {
       lazyMcps.set(name, { transport, description: entry.description });
     } else {
@@ -2046,7 +3234,7 @@ function buildOrchestrator(params) {
     lazyMcps: params.lazyMcps,
     namespaced: params.namespaced,
     onTransportError: (mcpName2, error) => {
-      process6.stderr.write(
+      process11.stderr.write(
         `${params.transportErrorPrefix(mcpName2)} transport error: ${error.message}
 `
       );
@@ -2060,19 +3248,19 @@ async function runProxy(orchestrator) {
     if (isShuttingDown) return;
     isShuttingDown = true;
     orchestrator.disconnectAll().catch((error) => {
-      process6.stderr.write(
+      process11.stderr.write(
         `dynmcp: error during disconnect: ${error instanceof Error ? error.message : String(error)}
 `
       );
-    }).finally(() => process6.exit(exitCode));
+    }).finally(() => process11.exit(exitCode));
   };
   activeShutdown.shutdown = shutdown;
   try {
     await orchestrator.connect();
   } catch (error) {
-    process6.stderr.write(`dynmcp: ${error instanceof Error ? error.message : String(error)}
+    process11.stderr.write(`dynmcp: ${error instanceof Error ? error.message : String(error)}
 `);
-    process6.exit(1);
+    process11.exit(1);
     return;
   }
   const proxyServer = new ProxyServer({
@@ -2109,10 +3297,10 @@ async function runProxy(orchestrator) {
     onElicitInput: (params, options) => proxyServer.forwardElicitInput(params, options),
     onListRoots: (params, options) => proxyServer.forwardListRoots(params, options)
   });
-  process6.on("SIGINT", () => shutdown(0));
-  process6.on("SIGTERM", () => shutdown(0));
-  process6.stdin.on("end", () => shutdown(0));
-  process6.stdin.on("close", () => shutdown(0));
+  process11.on("SIGINT", () => shutdown(0));
+  process11.on("SIGTERM", () => shutdown(0));
+  process11.stdin.on("end", () => shutdown(0));
+  process11.stdin.on("close", () => shutdown(0));
   try {
     await proxyServer.start();
   } catch (error) {
@@ -2121,6 +3309,215 @@ async function runProxy(orchestrator) {
   }
 }
 
+// src/scaffold/init.ts
+import { existsSync as existsSync3, writeFileSync } from "fs";
+import { resolve as resolve3 } from "path";
+import process12 from "process";
+
+// src/scaffold/format.ts
+import { extname } from "path";
+function detectFormat(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  return ext === ".yml" || ext === ".yaml" ? "yaml" : "json";
+}
+var SCHEMA_URL = "https://dynamicmcp.tools/config.json";
+
+// src/scaffold/init.ts
+function init(options = {}) {
+  const cwd = options.cwd ?? process12.cwd();
+  const stdout = options.write ?? ((chunk) => void process12.stdout.write(chunk));
+  const fileWriter = options.fileWriter ?? ((p, c) => writeFileSync(p, c, "utf-8"));
+  const fileExists = options.fileExists ?? ((p) => existsSync3(p));
+  const targetPath = resolveInitPath({ cwd, path: options.path, yaml: options.yaml === true });
+  const format = detectFormat(targetPath);
+  if (fileExists(targetPath) && options.force !== true) {
+    throw new Error(`File already exists: ${targetPath}
+Use --force to overwrite.`);
+  }
+  const contents = format === "yaml" ? renderYamlSkeleton() : renderJsonSkeleton();
+  fileWriter(targetPath, contents);
+  stdout(`Wrote ${targetPath}
+`);
+  stdout("\nThis config has no MCPs yet. Add one with:\n");
+  stdout("  dynmcp add <name> --command <cmd>                          (stdio upstream)\n");
+  stdout("  dynmcp add <name> --transport streamable-http --url <url>  (remote HTTP upstream)\n");
+  stdout("\nSee https://dynamicmcp.tools for full documentation.\n");
+}
+function resolveInitPath(opts) {
+  if (opts.path !== void 0) {
+    return resolve3(opts.cwd, opts.path);
+  }
+  return resolve3(opts.cwd, opts.yaml ? "mcp.yaml" : "mcp.json");
+}
+function renderJsonSkeleton() {
+  const body = JSON.stringify({ $schema: SCHEMA_URL, mcp: {} }, null, 2);
+  return `${body}
+`;
+}
+function renderYamlSkeleton() {
+  return `# yaml-language-server: $schema=${SCHEMA_URL}
+
+mcp: {}
+`;
+}
+
+// src/scaffold/add.ts
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import process13 from "process";
+import { parseDocument } from "yaml";
+function add(options) {
+  validateName(options.name);
+  const stdout = options.write ?? ((chunk) => void process13.stdout.write(chunk));
+  const fileReader = options.fileReader ?? ((p) => readFileSync3(p, "utf-8"));
+  const fileWriter = options.fileWriter ?? ((p, c) => writeFileSync2(p, c, "utf-8"));
+  const resolvePath = options.resolvePath ?? resolveConfigPath;
+  let targetPath;
+  try {
+    targetPath = resolvePath(options.configPath);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`${message}
+Hint: run 'dynmcp init' to create a starter config file.`);
+  }
+  const raw = fileReader(targetPath);
+  const format = detectFormat(targetPath);
+  const entry = buildEntry(options);
+  const parsed = transportConfigSchema.safeParse(entry);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((i) => `  - ${i.path.join(".") || "<root>"}: ${i.message}`).join("\n");
+    throw new Error(`Invalid MCP entry:
+${issues}`);
+  }
+  const next = format === "yaml" ? writeYaml(raw, options.name, parsed.data, options.force === true) : writeJson(raw, options.name, parsed.data, options.force === true);
+  fileWriter(targetPath, next);
+  stdout(`Added '${options.name}' (${options.transport}) to ${targetPath}
+`);
+}
+function validateName(name) {
+  if (!MCP_NAME_PATTERN.test(name)) {
+    throw new Error(
+      `Invalid MCP name '${name}'. Names must match ${MCP_NAME_PATTERN.source} (lowercase letters, digits, and dashes; starting with a letter or digit).`
+    );
+  }
+}
+function buildEntry(options) {
+  if (options.transport === "stdio") {
+    if (options.command === void 0 || options.command.length === 0) {
+      throw new Error("--command is required for stdio transport");
+    }
+    const entry2 = {
+      transport: "stdio",
+      command: options.command
+    };
+    if (options.description !== void 0) entry2.description = options.description;
+    if (options.args !== void 0 && options.args.length > 0) {
+      entry2.args = options.args;
+    }
+    if (options.envVars !== void 0 && options.envVars.length > 0) {
+      entry2.env = parseKeyValuePairs(options.envVars, "--env");
+    }
+    return entry2;
+  }
+  if (options.url === void 0 || options.url.length === 0) {
+    throw new Error(`--url is required for ${options.transport} transport`);
+  }
+  const entry = {
+    transport: options.transport,
+    url: options.url
+  };
+  if (options.description !== void 0) entry.description = options.description;
+  if (options.headers !== void 0 && options.headers.length > 0) {
+    entry.headers = parseHeaderPairs(options.headers);
+  }
+  const auth2 = buildAuthBlock(options);
+  if (auth2 !== void 0) entry.auth = auth2;
+  return entry;
+}
+function buildAuthBlock(options) {
+  const hasAny = options.clientId !== void 0 || options.clientSecret !== void 0 || options.scope !== void 0;
+  if (!hasAny) return void 0;
+  if (options.clientId === void 0) {
+    throw new Error("--client-id is required when --client-secret or --scope is provided");
+  }
+  const auth2 = { client_id: options.clientId };
+  if (options.clientSecret !== void 0) auth2.client_secret = options.clientSecret;
+  if (options.scope !== void 0) auth2.scope = options.scope;
+  return auth2;
+}
+function parseKeyValuePairs(pairs, flag) {
+  const out = {};
+  for (const pair of pairs) {
+    const eq = pair.indexOf("=");
+    if (eq <= 0) {
+      throw new Error(`${flag} expects KEY=VALUE (got: ${JSON.stringify(pair)})`);
+    }
+    const key = pair.slice(0, eq);
+    out[key] = pair.slice(eq + 1);
+  }
+  return out;
+}
+function parseHeaderPairs(pairs) {
+  const out = {};
+  for (const pair of pairs) {
+    const colon = pair.indexOf(":");
+    if (colon <= 0) {
+      throw new Error(`--header expects "Name: Value" (got: ${JSON.stringify(pair)})`);
+    }
+    const key = pair.slice(0, colon).trim();
+    const value = pair.slice(colon + 1).trim();
+    if (key.length === 0) {
+      throw new Error(`--header name cannot be empty (got: ${JSON.stringify(pair)})`);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+function writeJson(raw, name, entry, force) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to parse config as JSON: ${message}`);
+  }
+  if (!isPlainObject(parsed)) {
+    throw new Error("Top-level config must be a JSON object.");
+  }
+  let mcp = parsed.mcp;
+  if (mcp === void 0) {
+    mcp = {};
+    parsed.mcp = mcp;
+  } else if (!isPlainObject(mcp)) {
+    throw new Error("Config field 'mcp' must be an object.");
+  }
+  const mcpRecord = mcp;
+  if (mcpRecord[name] !== void 0 && !force) {
+    throw new Error(`Entry '${name}' already exists. Use --force to overwrite.`);
+  }
+  mcpRecord[name] = entry;
+  return `${JSON.stringify(parsed, null, 2)}
+`;
+}
+function writeYaml(raw, name, entry, force) {
+  const doc = parseDocument(raw);
+  if (doc.errors.length > 0) {
+    const first = doc.errors[0]?.message ?? "unknown error";
+    throw new Error(`Failed to parse config as YAML: ${first}`);
+  }
+  if (!doc.has("mcp")) {
+    doc.set("mcp", {});
+  }
+  const path = ["mcp", name];
+  if (doc.hasIn(path) && !force) {
+    throw new Error(`Entry '${name}' already exists. Use --force to overwrite.`);
+  }
+  doc.setIn(path, entry);
+  return doc.toString();
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 // src/cli.ts
 var cliBanner = chalk.bold.magentaBright(
   figlet.textSync("DYNAMIC MCP", {
@@ -2131,41 +3528,162 @@ var cliBanner = chalk.bold.magentaBright(
 );
 var cli = new Command(package_default.name).description(package_default.description).version(package_default.version).addHelpText("beforeAll", cliBanner).addHelpText(
   "after",
-  "\nExamples:\n  dynmcp -- npx -y chrome-devtools-mcp@latest\n  dynmcp --config ./mcp.json\n"
+  "\nExamples:\n  dynmcp -- npx -y chrome-devtools-mcp@latest\n  dynmcp --config ./mcp.json\n  dynmcp init\n  dynmcp add filesystem --command npx --arg -y --arg @modelcontextprotocol/server-filesystem --arg /tmp\n  dynmcp add github --transport streamable-http --url https://api.githubcopilot.com/mcp\n  dynmcp ls\n  dynmcp test github\n  dynmcp login github\n  dynmcp logout github\n"
 ).option("-c, --config <path>", "Path to config file (JSON or YAML)").option("-e, --env <path>", "Path to a .env file for environment variable interpolation").allowExcessArguments(true).passThroughOptions(true).action(async (_options, cmd) => {
-  const separatorIndex = process7.argv.indexOf("--");
+  const separatorIndex = process14.argv.indexOf("--");
   const configPath = cmd.opts().config;
   const envFilePath = cmd.opts().env;
   if (separatorIndex !== -1) {
-    const [command, ...args] = process7.argv.slice(separatorIndex + 1);
+    const [command, ...args] = process14.argv.slice(separatorIndex + 1);
     if (command === void 0) {
-      process7.stderr.write(
+      process14.stderr.write(
         "dynmcp: no upstream command provided after --.\nUsage: dynmcp -- <command> [args...]\n"
       );
-      process7.exit(1);
+      process14.exit(1);
     }
     try {
       await startProxy(command, args);
     } catch (error) {
-      process7.stderr.write(`dynmcp: ${error instanceof Error ? error.message : String(error)}
+      process14.stderr.write(`dynmcp: ${error instanceof Error ? error.message : String(error)}
 `);
-      process7.exit(1);
+      process14.exit(1);
     }
     return;
   }
   try {
     await startProxyFromConfig({ configPath, envFilePath });
   } catch (error) {
-    process7.stderr.write(`dynmcp: ${error instanceof Error ? error.message : String(error)}
+    process14.stderr.write(`dynmcp: ${error instanceof Error ? error.message : String(error)}
+`);
+    process14.exit(1);
+  }
+});
+cli.command("init").description("Write a starter config file (mcp.json by default) in the current directory.").option("--path <path>", "Explicit target path (extension determines format).").option("--yaml", "Write mcp.yaml instead of mcp.json (ignored if --path is set).").option("--force", "Overwrite an existing file.").action((options) => {
+  try {
+    init({
+      ...options.path !== void 0 ? { path: options.path } : {},
+      ...options.yaml === true ? { yaml: true } : {},
+      ...options.force === true ? { force: true } : {}
+    });
+  } catch (error) {
+    process14.stderr.write(`dynmcp: ${error instanceof Error ? error.message : String(error)}
+`);
+    process14.exit(1);
+  }
+});
+var collectRepeatable = (value, previous) => [...previous, value];
+cli.command("add <name>").description("Insert a new MCP entry into the resolved config file.").option(
+  "-t, --transport <transport>",
+  "Transport: stdio | streamable-http | sse (default: stdio).",
+  "stdio"
+).option("-c, --config <path>", "Path to config file (otherwise auto-discovered).").option("--description <text>", "Per-entry description; presence makes the entry lazy.").option("--command <cmd>", "(stdio) Command to spawn for the upstream MCP.").option(
+  "--arg <arg>",
+  "(stdio) Repeatable positional argument passed after --command.",
+  collectRepeatable,
+  []
+).option(
+  "--env <KEY=VAL>",
+  "(stdio) Repeatable env var for the spawned process.",
+  collectRepeatable,
+  []
+).option("--url <url>", "(http/sse) Endpoint URL.").option(
+  "--header <header>",
+  '(http/sse) Repeatable "Name: Value" header.',
+  collectRepeatable,
+  []
+).option("--client-id <id>", "(http/sse) Pre-registered OAuth client_id (skips DCR).").option("--client-secret <secret>", "(http/sse) Pre-registered OAuth client_secret.").option("--scope <scope>", "(http/sse) OAuth scope to request.").option("--force", "Overwrite an existing entry with the same name.").action(
+  (name, options) => {
+    try {
+      const transport = options.transport;
+      if (transport !== "stdio" && transport !== "streamable-http" && transport !== "sse") {
+        throw new Error(
+          `Invalid --transport '${options.transport}'. Must be one of: stdio, streamable-http, sse.`
+        );
+      }
+      add({
+        name,
+        transport,
+        ...options.config !== void 0 ? { configPath: options.config } : {},
+        ...options.force === true ? { force: true } : {},
+        ...options.description !== void 0 ? { description: options.description } : {},
+        ...options.command !== void 0 ? { command: options.command } : {},
+        ...options.arg.length > 0 ? { args: options.arg } : {},
+        ...options.env.length > 0 ? { envVars: options.env } : {},
+        ...options.url !== void 0 ? { url: options.url } : {},
+        ...options.header.length > 0 ? { headers: options.header } : {},
+        ...options.clientId !== void 0 ? { clientId: options.clientId } : {},
+        ...options.clientSecret !== void 0 ? { clientSecret: options.clientSecret } : {},
+        ...options.scope !== void 0 ? { scope: options.scope } : {}
+      });
+    } catch (error) {
+      process14.stderr.write(`dynmcp: ${error instanceof Error ? error.message : String(error)}
+`);
+      process14.exit(1);
+    }
+  }
+);
+cli.command("login <name>").description("Run the OAuth authorization-code flow for an upstream MCP and store tokens.").option("-c, --config <path>", "Path to config file (JSON or YAML)").option("-e, --env <path>", "Path to a .env file for environment variable interpolation").action(async (name, options) => {
+  try {
+    await login({
+      mcpName: name,
+      ...options.config !== void 0 ? { configPath: options.config } : {},
+      ...options.env !== void 0 ? { envFilePath: options.env } : {}
+    });
+  } catch (error) {
+    process14.stderr.write(`dynmcp: ${error instanceof Error ? error.message : String(error)}
+`);
+    process14.exit(1);
+  }
+});
+cli.command("logout <name>").description("Delete the OAuth keychain entry for an upstream MCP.").option("-c, --config <path>", "Path to config file (JSON or YAML)").option("-e, --env <path>", "Path to a .env file for environment variable interpolation").action(async (name, options) => {
+  try {
+    await logout({
+      mcpName: name,
+      ...options.config !== void 0 ? { configPath: options.config } : {},
+      ...options.env !== void 0 ? { envFilePath: options.env } : {}
+    });
+  } catch (error) {
+    process14.stderr.write(`dynmcp: ${error instanceof Error ? error.message : String(error)}
+`);
+    process14.exit(1);
+  }
+});
+cli.command("ls").description("List configured upstream MCPs with transport, mode, endpoint, and auth status.").option("-c, --config <path>", "Path to config file (JSON or YAML)").option("-e, --env <path>", "Path to a .env file for environment variable interpolation").option("--json", "Emit JSON instead of the aligned text table").action(async (options) => {
+  try {
+    await list({
+      ...options.config !== void 0 ? { configPath: options.config } : {},
+      ...options.env !== void 0 ? { envFilePath: options.env } : {},
+      ...options.json === true ? { json: true } : {}
+    });
+  } catch (error) {
+    process14.stderr.write(`dynmcp: ${error instanceof Error ? error.message : String(error)}
 `);
-    process7.exit(1);
+    process14.exit(1);
   }
 });
+cli.command("test [name]").description("Probe one or all configured upstream MCPs and print their discovered catalogs.").option("-c, --config <path>", "Path to config file (JSON or YAML)").option("-e, --env <path>", "Path to a .env file for environment variable interpolation").option("--json", "Emit JSON instead of the formatted text output").option("--timeout <ms>", "Per-MCP timeout in milliseconds (default: 15000)", (v) => Number(v)).action(
+  async (name, options) => {
+    try {
+      const exitCode = await test({
+        ...name !== void 0 ? { mcpName: name } : {},
+        ...options.config !== void 0 ? { configPath: options.config } : {},
+        ...options.env !== void 0 ? { envFilePath: options.env } : {},
+        ...options.json === true ? { json: true } : {},
+        ...options.timeout !== void 0 && !Number.isNaN(options.timeout) ? { timeoutMs: options.timeout } : {}
+      });
+      if (exitCode !== 0) process14.exit(exitCode);
+    } catch (error) {
+      process14.stderr.write(`dynmcp: ${error instanceof Error ? error.message : String(error)}
+`);
+      process14.exit(1);
+    }
+  }
+);
 
 // src/index.ts
-import process8 from "process";
+import process15 from "process";
 async function main() {
-  cli.parse(process8.argv);
+  cli.parse(process15.argv);
 }
 main();
 //# sourceMappingURL=index.js.map