@nimrobo/mcporter-remote 0.1.0

package/src/server-proxy.ts

@@ -0,0 +1,407 @@
+import { createCallResult } from './result-utils.js';
+import type { CallOptions, ListToolsOptions, Runtime, ServerToolInfo } from './runtime.js';
+import { readSchemaCache, writeSchemaCache } from './schema-cache.js';
+
+type ToolCallOptions = CallOptions & { args?: unknown };
+type ToolArguments = CallOptions['args'];
+
+type ServerProxy = {
+  call(toolName: string, options?: ToolCallOptions): Promise<ReturnType<typeof createCallResult>>;
+  listTools(options?: ListToolsOptions): Promise<ServerToolInfo[]>;
+};
+
+type ToolSchemaInfo = {
+  schema: Record<string, unknown>;
+  orderedKeys: string[];
+  requiredKeys: string[];
+  propertySet: Set<string>;
+};
+
+const KNOWN_OPTION_KEYS = new Set(['tailLog', 'timeout', 'stream', 'streamLog', 'mimeType', 'metadata', 'log']);
+
+export interface ServerProxyOptions {
+  readonly mapPropertyToTool?: (property: string | symbol) => string;
+  readonly cacheSchemas?: boolean;
+  readonly initialSchemas?: Record<string, unknown>;
+}
+
+// defaultToolNameMapper converts camelCase property access into kebab-case tool names.
+function defaultToolNameMapper(propertyKey: string | symbol): string {
+  if (typeof propertyKey !== 'string') {
+    throw new TypeError('Tool name must be a string when using server proxy.');
+  }
+  return propertyKey.replace(/([a-z\d])([A-Z])/g, '$1-$2').toLowerCase();
+}
+
+// canonicalizeToolName strips punctuation for loose matching of tool names.
+function canonicalizeToolName(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+// isPlainObject narrows unknown values to plain object records.
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+// createToolSchemaInfo normalizes schema metadata used for argument mapping.
+function createToolSchemaInfo(schemaRaw: unknown): ToolSchemaInfo | undefined {
+  if (!schemaRaw || typeof schemaRaw !== 'object') {
+    return undefined;
+  }
+  const schema = schemaRaw as Record<string, unknown>;
+  const propertiesRaw = schema.properties;
+  const propertyKeys =
+    propertiesRaw && typeof propertiesRaw === 'object' ? Object.keys(propertiesRaw as Record<string, unknown>) : [];
+  const requiredKeys = Array.isArray(schema.required) ? (schema.required as string[]) : [];
+  const orderedKeys: string[] = [];
+  const seen = new Set<string>();
+
+  for (const key of requiredKeys) {
+    if (typeof key === 'string' && !seen.has(key)) {
+      orderedKeys.push(key);
+      seen.add(key);
+    }
+  }
+
+  for (const key of propertyKeys) {
+    if (!seen.has(key)) {
+      orderedKeys.push(key);
+      seen.add(key);
+    }
+  }
+
+  return {
+    schema,
+    orderedKeys,
+    requiredKeys,
+    propertySet: new Set([...propertyKeys, ...requiredKeys]),
+  };
+}
+
+// applyDefaults merges JSON-schema default values into the provided arguments.
+function applyDefaults(meta: ToolSchemaInfo, args?: ToolArguments): ToolArguments {
+  const propertiesRaw = meta.schema.properties;
+  if (!propertiesRaw || typeof propertiesRaw !== 'object') {
+    return args;
+  }
+
+  const result: Record<string, unknown> = isPlainObject(args) ? { ...(args as Record<string, unknown>) } : {};
+
+  for (const [key, value] of Object.entries(propertiesRaw as Record<string, unknown>)) {
+    if (
+      value &&
+      typeof value === 'object' &&
+      'default' in (value as Record<string, unknown>) &&
+      result[key] === undefined
+    ) {
+      result[key] = (value as Record<string, unknown>).default as unknown;
+    }
+  }
+
+  if (Object.keys(result).length === 0 && !isPlainObject(args)) {
+    return args;
+  }
+
+  return result as ToolArguments;
+}
+
+// validateRequired ensures all schema-required fields are present before invocation.
+function validateRequired(meta: ToolSchemaInfo, args?: ToolArguments): void {
+  if (meta.requiredKeys.length === 0) {
+    return;
+  }
+  if (!isPlainObject(args)) {
+    throw new Error(`Missing required arguments: ${meta.requiredKeys.join(', ')}`);
+  }
+  const missing = meta.requiredKeys.filter((key) => (args as Record<string, unknown>)[key] === undefined);
+  if (missing.length > 0) {
+    throw new Error(`Missing required arguments: ${missing.join(', ')}`);
+  }
+}
+
+// createServerProxy returns a proxy that maps property access to MCP tool invocations.
+export function createServerProxy(
+  runtime: Runtime,
+  serverName: string,
+  mapOrOptions?: ((property: string | symbol) => string) | ServerProxyOptions,
+  maybeOptions?: ServerProxyOptions
+): ServerProxy {
+  let mapPropertyToTool = defaultToolNameMapper;
+  let options: ServerProxyOptions | undefined;
+
+  if (typeof mapOrOptions === 'function') {
+    mapPropertyToTool = mapOrOptions;
+    options = maybeOptions;
+  } else if (mapOrOptions) {
+    options = mapOrOptions;
+    if (typeof mapOrOptions.mapPropertyToTool === 'function') {
+      mapPropertyToTool = mapOrOptions.mapPropertyToTool;
+    }
+  }
+
+  const cacheSchemas = options?.cacheSchemas ?? true;
+  const initialSchemas = options?.initialSchemas ?? undefined;
+
+  const toolSchemaCache = new Map<string, ToolSchemaInfo>();
+  const persistedSchemas = new Map<string, Record<string, unknown>>();
+  const toolAliasMap = new Map<string, string>();
+  let schemaFetch: Promise<void> | null = null;
+  let diskLoad: Promise<void> | null = null;
+  let persistPromise: Promise<void> | null = null;
+  let refreshPending = false;
+
+  let definitionForCache: ReturnType<Runtime['getDefinition']> | undefined;
+  if (cacheSchemas) {
+    try {
+      definitionForCache = runtime.getDefinition(serverName);
+    } catch {
+      definitionForCache = undefined;
+    }
+  }
+
+  if (cacheSchemas && !initialSchemas && definitionForCache) {
+    diskLoad = loadSchemasFromDisk(definitionForCache);
+    refreshPending = true;
+  }
+
+  if (initialSchemas) {
+    for (const [key, schemaRaw] of Object.entries(initialSchemas)) {
+      storeSchema(key, schemaRaw);
+    }
+    persistPromise = persistSchemas();
+  }
+
+  // consumePersist waits for any in-flight disk persistence to finish before reading from cache maps.
+  async function consumePersist(): Promise<void> {
+    if (!persistPromise) {
+      return;
+    }
+    try {
+      await persistPromise;
+    } finally {
+      persistPromise = null;
+    }
+  }
+
+  // ensureMetadata loads schema information for the requested tool, optionally refreshing from the server.
+  async function ensureMetadata(toolName: string): Promise<ToolSchemaInfo | undefined> {
+    await consumePersist();
+    const cached = toolSchemaCache.get(toolName);
+    if (cached && !refreshPending) {
+      return cached;
+    }
+
+    if (diskLoad) {
+      try {
+        await diskLoad;
+      } finally {
+        diskLoad = null;
+      }
+      if (toolSchemaCache.has(toolName) && !refreshPending) {
+        return toolSchemaCache.get(toolName);
+      }
+    }
+
+    if (!schemaFetch) {
+      schemaFetch = runtime
+        .listTools(serverName, { includeSchema: true })
+        .then((tools) => {
+          for (const tool of tools) {
+            if (!tool.inputSchema || typeof tool.inputSchema !== 'object') {
+              continue;
+            }
+            storeSchema(tool.name, tool.inputSchema);
+          }
+          persistPromise = persistSchemas();
+          refreshPending = false;
+        })
+        .catch((error) => {
+          schemaFetch = null;
+          throw error;
+        });
+    }
+
+    await schemaFetch;
+    await consumePersist();
+    return toolSchemaCache.get(toolName);
+  }
+
+  // storeSchema caches schema info locally and records aliases for lookup.
+  function storeSchema(key: string, schemaRaw: unknown) {
+    const info = createToolSchemaInfo(schemaRaw);
+    if (!info) {
+      return;
+    }
+    const canonical = mapPropertyToTool(key);
+    toolSchemaCache.set(canonical, info);
+    if (canonical !== key) {
+      toolSchemaCache.set(key, info);
+    }
+    const canonicalAlias = canonicalizeToolName(key);
+    if (!toolAliasMap.has(canonicalAlias)) {
+      toolAliasMap.set(canonicalAlias, key);
+    }
+    const mapperAlias = canonicalizeToolName(canonical);
+    if (!toolAliasMap.has(mapperAlias)) {
+      toolAliasMap.set(mapperAlias, key);
+    }
+    if (cacheSchemas && definitionForCache && isPlainObject(schemaRaw)) {
+      persistedSchemas.set(canonical, schemaRaw as Record<string, unknown>);
+    }
+  }
+
+  // loadSchemasFromDisk hydrates the in-memory cache from the persisted schema snapshot.
+  async function loadSchemasFromDisk(definition: ReturnType<Runtime['getDefinition']>): Promise<void> {
+    try {
+      const snapshot = await readSchemaCache(definition);
+      if (!snapshot) {
+        return;
+      }
+      for (const [key, schemaRaw] of Object.entries(snapshot.tools)) {
+        storeSchema(key, schemaRaw);
+      }
+    } catch {
+      // ignore cache read failures
+    }
+  }
+
+  // persistSchemas writes cached schema data to disk when enabled.
+  function persistSchemas(): Promise<void> | null {
+    if (!cacheSchemas || !definitionForCache || persistedSchemas.size === 0) {
+      return null;
+    }
+    const definition = definitionForCache;
+    const snapshot = {
+      updatedAt: new Date().toISOString(),
+      tools: Object.fromEntries(persistedSchemas.entries()),
+    };
+    return writeSchemaCache(definition, snapshot).catch(() => {
+      // best-effort persistence
+    });
+  }
+
+  const base: ServerProxy = {
+    call: async (toolName: string, options?: ToolCallOptions) => {
+      const result = await runtime.callTool(serverName, toolName, options ?? {});
+      return createCallResult(result);
+    },
+    listTools: (options) => runtime.listTools(serverName, options),
+  };
+
+  return new Proxy(base as ServerProxy & Record<string | symbol, unknown>, {
+    get(target, property, receiver) {
+      if (Reflect.has(target, property)) {
+        return Reflect.get(target, property, receiver);
+      }
+      const propertyKey = property;
+      const canonicalKey = typeof propertyKey === 'string' ? canonicalizeToolName(propertyKey) : null;
+      let resolvedToolName =
+        typeof propertyKey === 'string' && canonicalKey
+          ? (toolAliasMap.get(canonicalKey) ?? mapPropertyToTool(propertyKey))
+          : mapPropertyToTool(propertyKey);
+
+      return async (...callArgs: unknown[]) => {
+        let schemaInfo: ToolSchemaInfo | undefined;
+        try {
+          schemaInfo = await ensureMetadata(resolvedToolName);
+        } catch {
+          schemaInfo = undefined;
+        }
+        if (typeof propertyKey === 'string' && canonicalKey) {
+          const alias = toolAliasMap.get(canonicalKey);
+          if (alias && alias !== resolvedToolName) {
+            resolvedToolName = alias;
+            try {
+              schemaInfo = await ensureMetadata(resolvedToolName);
+            } catch {
+              // ignore and keep prior schema if available
+            }
+          }
+        }
+
+        const positional: unknown[] = [];
+        const argsAccumulator: Record<string, unknown> = {};
+        const optionsAccumulator: ToolCallOptions = {};
+
+        for (const arg of callArgs) {
+          if (isPlainObject(arg)) {
+            const keys = Object.keys(arg);
+            const treatAsArgs =
+              schemaInfo !== undefined &&
+              keys.length > 0 &&
+              (keys.every((key) => schemaInfo.propertySet.has(key)) ||
+                keys.every((key) => !KNOWN_OPTION_KEYS.has(key)));
+
+            if (treatAsArgs) {
+              Object.assign(argsAccumulator, arg as Record<string, unknown>);
+            } else {
+              Object.assign(optionsAccumulator, arg as ToolCallOptions);
+            }
+          } else {
+            positional.push(arg);
+          }
+        }
+
+        const explicitArgs = optionsAccumulator.args as ToolArguments | undefined;
+        if (explicitArgs !== undefined) {
+          delete (optionsAccumulator as Record<string, unknown>).args;
+        }
+
+        const finalOptions: ToolCallOptions = { ...optionsAccumulator };
+        let combinedArgs: ToolArguments | undefined = explicitArgs;
+
+        if (schemaInfo) {
+          const schema = schemaInfo;
+
+          if (positional.length > schema.orderedKeys.length) {
+            throw new Error(`Too many positional arguments for tool "${resolvedToolName}"`);
+          }
+
+          if (positional.length > 0) {
+            const baseArgs = isPlainObject(combinedArgs) ? { ...(combinedArgs as Record<string, unknown>) } : {};
+            positional.forEach((value, idx) => {
+              const key = schema.orderedKeys[idx];
+              if (key) {
+                baseArgs[key] = value;
+              }
+            });
+            combinedArgs = baseArgs as ToolArguments;
+          }
+
+          if (Object.keys(argsAccumulator).length > 0) {
+            const baseArgs = isPlainObject(combinedArgs) ? { ...(combinedArgs as Record<string, unknown>) } : {};
+            Object.assign(baseArgs, argsAccumulator);
+            combinedArgs = baseArgs as ToolArguments;
+          }
+
+          if (combinedArgs !== undefined) {
+            combinedArgs = applyDefaults(schema, combinedArgs);
+          } else {
+            const defaults = applyDefaults(schema, undefined);
+            if (defaults && typeof defaults === 'object') {
+              combinedArgs = defaults as ToolArguments;
+            }
+          }
+
+          validateRequired(schema, combinedArgs);
+        } else {
+          if (positional.length > 0) {
+            combinedArgs = positional as unknown as ToolArguments;
+          }
+          if (Object.keys(argsAccumulator).length > 0) {
+            const baseArgs = isPlainObject(combinedArgs) ? { ...(combinedArgs as Record<string, unknown>) } : {};
+            Object.assign(baseArgs, argsAccumulator);
+            combinedArgs = baseArgs as ToolArguments;
+          }
+        }
+
+        if (combinedArgs !== undefined) {
+          finalOptions.args = combinedArgs;
+        }
+
+        const result = await runtime.callTool(serverName, resolvedToolName, finalOptions);
+        return createCallResult(result);
+      };
+    },
+  });
+}

package/tests/adhoc-server.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { resolveEphemeralServer } from '../src/cli/adhoc-server.js';
+
+describe('resolveEphemeralServer', () => {
+  it('injects Accept header for HTTP definitions', () => {
+    const { definition } = resolveEphemeralServer({ httpUrl: 'https://example.com/mcp' });
+    expect(definition.command.kind).toBe('http');
+    const headers = definition.command.kind === 'http' ? definition.command.headers : undefined;
+    expect(headers?.accept?.toLowerCase()).toContain('application/json');
+    expect(headers?.accept?.toLowerCase()).toContain('text/event-stream');
+  });
+
+  it('auto-enables keep-alive for STDIO commands that match known signatures', () => {
+    const { definition, persistedEntry } = resolveEphemeralServer({
+      stdioCommand: 'npx -y chrome-devtools-mcp@latest',
+    });
+    expect(definition.name).toBe('chrome-devtools');
+    expect(definition.lifecycle?.mode).toBe('keep-alive');
+    expect(persistedEntry.lifecycle).toBe('keep-alive');
+  });
+
+  it('infers package names instead of wrapper flags for npx workflows', () => {
+    const { definition } = resolveEphemeralServer({
+      stdioCommand: 'npx -y xcodebuildmcp',
+    });
+    expect(definition.name).toBe('xcodebuildmcp');
+  });
+
+  it('drops versions when inferring scoped npm package names', () => {
+    const { definition } = resolveEphemeralServer({
+      stdioCommand: 'npx -y @scope/example-mcp@latest',
+    });
+    expect(definition.name).toBe('scope-example-mcp');
+  });
+
+  it('ignores additional positional args after double-dash when inferring package names', () => {
+    const { definition } = resolveEphemeralServer({
+      stdioCommand: 'npx -y @scope/xcodebuildmcp@canary -- --port 1234',
+    });
+    expect(definition.name).toBe('scope-xcodebuildmcp');
+  });
+
+  it('normalizes mixed-case package tokens and --yes flag variants', () => {
+    const { definition } = resolveEphemeralServer({
+      stdioCommand: 'npx --yes XcodeBuildMCP@1.2.3 doctor',
+    });
+    expect(definition.name).toBe('xcodebuildmcp');
+  });
+});

package/tests/call-arguments.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it, vi } from 'vitest';
+import { parseCallArguments } from '../src/cli/call-arguments.js';
+
+describe('parseCallArguments', () => {
+  it('parses legacy selector + key=value pairs', () => {
+    const args = ['linear.list_documents', 'limit=5', 'format=json'];
+    const parsed = parseCallArguments([...args]);
+    expect(parsed.selector).toBe('linear.list_documents');
+    expect(parsed.tool).toBeUndefined();
+    expect(parsed.args.limit).toBe(5);
+    expect(parsed.args.format).toBe('json');
+  });
+
+  it.each(['--server', '--mcp'] as const)('captures %s as server override', (flag) => {
+    const parsed = parseCallArguments([flag, 'linear', 'list_documents']);
+    expect(parsed.server).toBe('linear');
+    expect(parsed.tool).toBe('list_documents');
+  });
+
+  it('consumes function-style call expressions with HTTP selectors', () => {
+    const call = 'https://example.com/mcp.getComponents(limit: 3, projectId: "123")';
+    const parsed = parseCallArguments([call]);
+    expect(parsed.server).toBe('https://example.com/mcp');
+    expect(parsed.tool).toBe('getComponents');
+    expect(parsed.args.limit).toBe(3);
+    expect(parsed.args.projectId).toBe('123');
+  });
+
+  it('merges --args JSON blobs with positional fragments', () => {
+    const parsed = parseCallArguments([
+      '--args',
+      '{"query":"open issues"}',
+      'linear',
+      'list_documents',
+      'orderBy=updatedAt',
+    ]);
+    expect(parsed.selector).toBe('linear');
+    expect(parsed.tool).toBe('list_documents');
+    expect(parsed.args.query).toBe('open issues');
+    expect(parsed.args.orderBy).toBe('updatedAt');
+  });
+
+  it('throws when flags conflict with call expression content', () => {
+    expect(() => parseCallArguments(['--server', 'linear', 'cursor.list_documents(limit:1)'])).toThrow(
+      /Conflicting server names/
+    );
+  });
+
+  it('warns when colon-style arguments omit a value', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const parsed = parseCallArguments(['iterm-mcp.write_to_terminal', 'command:']);
+    expect(parsed.args.command).toBe('');
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("[mcporter] Argument 'command' was provided without a value.")
+    );
+    warnSpy.mockRestore();
+  });
+
+  it.each([
+    ['default', [], 123456, 'number'],
+    ['raw-strings', ['--raw-strings'], '123456', 'string'],
+    ['no-coerce', ['--no-coerce'], '123456', 'string'],
+  ] as const)('handles numeric coercion in %s mode', (_mode, flags, expected, expectedType) => {
+    const parsed = parseCallArguments([...flags, 'server.tool', 'code=123456']);
+    expect(parsed.args.code).toBe(expected);
+    expect(typeof parsed.args.code).toBe(expectedType);
+  });
+
+  it('preserves leading zeros when --raw-strings flag is used', () => {
+    const parsed = parseCallArguments(['--raw-strings', 'server.tool', 'pin=000123']);
+    expect(parsed.args.pin).toBe('000123');
+    expect(typeof parsed.args.pin).toBe('string');
+  });
+
+  it('still coerces booleans, nulls, and JSON with --raw-strings', () => {
+    const parsed = parseCallArguments(['--raw-strings', 'server.tool', 'enabled=true', 'value=null', 'meta={"a":1}']);
+    expect(parsed.args.enabled).toBe(true);
+    expect(parsed.args.value).toBeNull();
+    expect(parsed.args.meta).toEqual({ a: 1 });
+  });
+
+  it('keeps every value as a string when --no-coerce alias is used', () => {
+    const parsed = parseCallArguments([
+      '--no-coerce',
+      'server.tool',
+      'id=007',
+      'enabled=true',
+      'value=null',
+      'meta={"a":1}',
+      '123',
+    ]);
+    expect(parsed.args.id).toBe('007');
+    expect(parsed.args.enabled).toBe('true');
+    expect(parsed.args.value).toBe('null');
+    expect(parsed.args.meta).toBe('{"a":1}');
+    expect(typeof parsed.args.id).toBe('string');
+    expect(parsed.positionalArgs).toEqual(['123']);
+  });
+
+  it('captures --save-images output directory', () => {
+    const parsed = parseCallArguments(['--save-images', './tmp/images', 'server.tool']);
+    expect(parsed.saveImagesDir).toBe('./tmp/images');
+  });
+
+  it.each([
+    ['--save-images', /--save-images requires a directory path/],
+    ['--args', /--args requires a JSON value/],
+  ] as const)('throws when %s is missing a value', (flag, expectedError) => {
+    expect(() => parseCallArguments([flag])).toThrow(expectedError);
+  });
+});

package/tests/cli-auth-help.test.ts

@@ -0,0 +1,43 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+process.env.MCPORTER_DISABLE_AUTORUN = '1';
+const cliModulePromise = import('../src/cli.js');
+
+describe('mcporter auth help shortcut', () => {
+  let previousNoForceExit: string | undefined;
+
+  beforeEach(() => {
+    previousNoForceExit = process.env.MCPORTER_NO_FORCE_EXIT;
+    process.env.MCPORTER_NO_FORCE_EXIT = '1';
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    process.exitCode = undefined;
+    if (previousNoForceExit === undefined) {
+      delete process.env.MCPORTER_NO_FORCE_EXIT;
+    } else {
+      process.env.MCPORTER_NO_FORCE_EXIT = previousNoForceExit;
+    }
+  });
+
+  it('prints auth-specific help when --help is used', async () => {
+    const { runCli } = await cliModulePromise;
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    await runCli(['auth', '--help']);
+
+    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('Usage: mcporter auth'));
+    expect(process.exitCode).toBe(0);
+  });
+
+  it('prints auth-specific help when the bare help token follows the command', async () => {
+    const { runCli } = await cliModulePromise;
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    await runCli(['auth', 'help']);
+
+    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('Usage: mcporter auth'));
+    expect(process.exitCode).toBe(0);
+  });
+});

package/tests/cli-auth-retry.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it, vi } from 'vitest';
+
+process.env.MCPORTER_DISABLE_AUTORUN = '1';
+const cliModulePromise = import('../src/cli.js');
+
+const baseDefinition = {
+  name: 'adhoc-server',
+  command: { kind: 'http' as const, url: new URL('https://example.com/mcp') },
+  source: { kind: 'local' as const, path: '<adhoc>' },
+};
+
+describe('handleAuth retry logic', () => {
+  it('retries once when the first attempt is unauthorized', async () => {
+    const { handleAuth } = await cliModulePromise;
+    const listTools = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('SSE error: Non-200 status code (401)'))
+      .mockResolvedValueOnce([{ name: 'ok' }]);
+    const runtime = {
+      registerDefinition: vi.fn(),
+      getDefinition: vi.fn().mockReturnValue(baseDefinition),
+      listTools,
+    } as unknown as Awaited<ReturnType<typeof import('../src/runtime.js')['createRuntime']>>;
+
+    await expect(handleAuth(runtime, ['adhoc-server'])).resolves.toBeUndefined();
+    expect(listTools).toHaveBeenCalledTimes(2);
+  });
+
+  it('throws after the second unauthorized attempt', async () => {
+    const { handleAuth } = await cliModulePromise;
+    const listTools = vi.fn().mockRejectedValue(new Error('SSE error: Non-200 status code (401)'));
+    const runtime = {
+      registerDefinition: vi.fn(),
+      getDefinition: vi.fn().mockReturnValue(baseDefinition),
+      listTools,
+    } as unknown as Awaited<ReturnType<typeof import('../src/runtime.js')['createRuntime']>>;
+
+    await expect(handleAuth(runtime, ['adhoc-server'])).rejects.toThrow(/Failed to authorize/);
+    expect(listTools).toHaveBeenCalledTimes(2);
+  });
+});