@nimrobo/mcporter-remote 0.1.0

package/src/runtime-oauth-support.ts

@@ -0,0 +1,24 @@
+import type { ServerDefinition } from './config.js';
+import { analyzeConnectionError } from './error-classifier.js';
+import type { Logger } from './logging.js';
+
+export function maybeEnableOAuth(definition: ServerDefinition, logger: Logger): ServerDefinition | undefined {
+  if (definition.auth === 'oauth') {
+    return undefined;
+  }
+  if (definition.command.kind !== 'http') {
+    return undefined;
+  }
+  // Allow OAuth promotion for any HTTP server that returns 401,
+  // not just ad-hoc servers (fixes issue #38)
+  logger.info(`Detected OAuth requirement for '${definition.name}'. Launching browser flow...`);
+  return {
+    ...definition,
+    auth: 'oauth',
+  };
+}
+
+export function isUnauthorizedError(error: unknown): boolean {
+  const issue = analyzeConnectionError(error);
+  return issue.kind === 'auth';
+}

package/src/runtime-process-utils.ts

@@ -0,0 +1,324 @@
+import type { ChildProcess } from 'node:child_process';
+import { execFile } from 'node:child_process';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { Logger } from './logging.js';
+
+// closeTransportAndWait closes transports and ensures backing processes exit cleanly.
+export async function closeTransportAndWait(
+  logger: Logger,
+  transport: Transport & { close(): Promise<void> }
+): Promise<void> {
+  const pidBeforeClose = getTransportPid(transport);
+  const childProcess =
+    transport instanceof StdioClientTransport
+      ? ((transport as unknown as { _process?: ChildProcess | null })._process ?? null)
+      : null;
+  try {
+    await transport.close();
+  } catch (error) {
+    logger.warn(`Failed to close transport cleanly: ${(error as Error).message}`);
+  }
+
+  if (childProcess) {
+    await waitForChildClose(childProcess, 1_000).catch(() => {});
+  }
+
+  if (!pidBeforeClose) {
+    return;
+  }
+
+  await ensureProcessTerminated(logger, pidBeforeClose);
+}
+
+function getTransportPid(transport: Transport & { pid?: number | null }): number | null {
+  if (transport instanceof StdioClientTransport) {
+    const pid = transport.pid;
+    return typeof pid === 'number' && pid > 0 ? pid : null;
+  }
+  if ('pid' in transport) {
+    const candidate = transport.pid;
+    if (typeof candidate === 'number' && candidate > 0) {
+      return candidate;
+    }
+  }
+  const rawPid = (transport as unknown as { _process?: { pid?: number } | null | undefined })._process?.pid;
+  return typeof rawPid === 'number' && rawPid > 0 ? rawPid : null;
+}
+
+async function ensureProcessTerminated(logger: Logger, pid: number): Promise<void> {
+  await ensureProcessTreeTerminated(logger, pid);
+}
+
+async function waitForChildClose(child: ChildProcess, timeoutMs: number): Promise<void> {
+  if (
+    (child as { exitCode?: number | null }).exitCode !== null &&
+    (child as { exitCode?: number | null }).exitCode !== undefined
+  ) {
+    return;
+  }
+  await new Promise<void>((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      resolve();
+    };
+    const cleanup = () => {
+      child.removeListener('close', finish);
+      child.removeListener('exit', finish);
+      child.removeListener('error', finish);
+      if (timer) {
+        clearTimeout(timer);
+      }
+    };
+    child.once('close', finish);
+    child.once('exit', finish);
+    child.once('error', finish);
+    let timer: NodeJS.Timeout | undefined;
+    if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
+      timer = setTimeout(finish, timeoutMs);
+      timer.unref?.();
+    }
+  });
+
+  try {
+    child.stdin?.end?.();
+  } catch {
+    // ignore
+  }
+  try {
+    child.stdout?.destroy?.();
+    child.stdout?.removeAllListeners?.();
+    (child.stdout as unknown as { unref?: () => void })?.unref?.();
+  } catch {
+    // ignore
+  }
+  try {
+    child.stderr?.destroy?.();
+    child.stderr?.removeAllListeners?.();
+    (child.stderr as unknown as { unref?: () => void })?.unref?.();
+  } catch {
+    // ignore
+  }
+  try {
+    const stdio = (child as { stdio?: unknown[] }).stdio;
+    if (Array.isArray(stdio)) {
+      for (const stream of stdio) {
+        if (!stream || typeof stream !== 'object') {
+          continue;
+        }
+        try {
+          (stream as { removeAllListeners?: () => void }).removeAllListeners?.();
+          (stream as { destroy?: () => void }).destroy?.();
+          (stream as { end?: () => void }).end?.();
+        } catch {
+          // ignore
+        }
+      }
+    }
+  } catch {
+    // ignore
+  }
+  try {
+    child.removeAllListeners();
+  } catch {
+    // ignore
+  }
+  try {
+    child.unref?.();
+  } catch {
+    // ignore
+  }
+}
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function ensureProcessTreeTerminated(logger: Logger, rootPid: number): Promise<void> {
+  if (!isProcessAlive(rootPid)) {
+    return;
+  }
+
+  let targets = await collectProcessTreePids(rootPid);
+  if (await waitForTreeExit(targets, 300)) {
+    return;
+  }
+
+  await sendSignalToTargets(targets, 'SIGTERM');
+  targets = await collectProcessTreePids(rootPid);
+  if (await waitForTreeExit(targets, 700)) {
+    return;
+  }
+
+  targets = await collectProcessTreePids(rootPid);
+  await sendSignalToTargets(targets, 'SIGKILL');
+  if (await waitForTreeExit(targets, 500)) {
+    return;
+  }
+
+  logger.warn(`Process tree rooted at pid=${rootPid} did not exit after SIGKILL.`);
+}
+
+async function sendSignalToTargets(pids: number[], signal: NodeJS.Signals): Promise<void> {
+  const seen = new Set<number>();
+  for (const pid of pids) {
+    if (seen.has(pid)) {
+      continue;
+    }
+    seen.add(pid);
+    sendSignal(pid, signal);
+  }
+}
+
+function sendSignal(pid: number, signal: NodeJS.Signals): void {
+  try {
+    process.kill(pid, signal);
+  } catch (error) {
+    if (typeof error === 'object' && error && 'code' in error && (error as { code?: string }).code === 'ESRCH') {
+      return;
+    }
+    throw error;
+  }
+}
+
+async function listDescendantPids(rootPid: number): Promise<number[]> {
+  if (!isProcessAlive(rootPid)) {
+    return [];
+  }
+  if (process.platform === 'win32') {
+    return listDescendantPidsWindows(rootPid);
+  }
+
+  try {
+    const { stdout } = await execFileAsync('ps', ['-eo', 'pid=,ppid=']);
+    const children = new Map<number, number[]>();
+    for (const line of stdout.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) {
+        continue;
+      }
+      const [pidText, ppidText] = trimmed.split(/\s+/, 2);
+      const pid = Number.parseInt(pidText ?? '', 10);
+      const ppid = Number.parseInt(ppidText ?? '', 10);
+      if (!Number.isFinite(pid) || !Number.isFinite(ppid)) {
+        continue;
+      }
+      const bucket = children.get(ppid) ?? [];
+      bucket.push(pid);
+      children.set(ppid, bucket);
+    }
+
+    return collectDescendantsFromChildren(rootPid, children);
+  } catch {
+    return [];
+  }
+}
+
+async function listDescendantPidsWindows(rootPid: number): Promise<number[]> {
+  try {
+    const powershellScript =
+      'Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId | ConvertTo-Json -Compress';
+    const { stdout } = await execFileAsync('powershell.exe', ['-NoProfile', '-Command', powershellScript]);
+    const trimmed = stdout.trim();
+    if (!trimmed) {
+      return [];
+    }
+    const parsed = JSON.parse(trimmed) as
+      | { ProcessId?: number; ParentProcessId?: number }
+      | Array<{ ProcessId?: number; ParentProcessId?: number }>;
+    const entries = Array.isArray(parsed) ? parsed : [parsed];
+    const children = new Map<number, number[]>();
+    for (const entry of entries) {
+      const pidCandidate = entry?.ProcessId;
+      const ppidCandidate = entry?.ParentProcessId;
+      if (typeof pidCandidate !== 'number' || typeof ppidCandidate !== 'number') {
+        continue;
+      }
+      const pid = Number.isFinite(pidCandidate) ? pidCandidate : undefined;
+      const ppid = Number.isFinite(ppidCandidate) ? ppidCandidate : undefined;
+      if (pid === undefined || ppid === undefined) {
+        continue;
+      }
+      const bucket = children.get(ppid) ?? [];
+      bucket.push(pid);
+      children.set(ppid, bucket);
+    }
+    return collectDescendantsFromChildren(rootPid, children);
+  } catch {
+    return [];
+  }
+}
+
+function execFileAsync(command: string, args: readonly string[]): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    execFile(command, args, { encoding: 'utf8' }, (error, stdout, stderr) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve({ stdout, stderr });
+    });
+  });
+}
+
+async function collectProcessTreePids(rootPid: number): Promise<number[]> {
+  const descendants = await listDescendantPids(rootPid);
+  return [...descendants, rootPid];
+}
+
+function collectDescendantsFromChildren(rootPid: number, children: Map<number, number[]>): number[] {
+  const result: number[] = [];
+  const queue = [...(children.get(rootPid) ?? [])];
+  const seen = new Set<number>(queue);
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (current === undefined) {
+      continue;
+    }
+    result.push(current);
+    for (const child of children.get(current) ?? []) {
+      if (!seen.has(child)) {
+        seen.add(child);
+        queue.push(child);
+      }
+    }
+  }
+  return result;
+}
+
+export const __testHooks = {
+  listDescendantPids,
+};
+
+async function waitForTreeExit(pids: number[], durationMs: number): Promise<boolean> {
+  const deadline = Date.now() + durationMs;
+  while (true) {
+    if (pids.every((pid) => !isProcessAlive(pid))) {
+      return true;
+    }
+    if (Date.now() >= deadline) {
+      return false;
+    }
+    const remaining = Math.max(10, Math.min(100, deadline - Date.now()));
+    await delay(remaining);
+  }
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    if (typeof (timer as { unref?: () => void }).unref === 'function') {
+      (timer as { unref?: () => void }).unref?.();
+    }
+  });
+}

package/src/runtime.ts

@@ -0,0 +1,321 @@
+import { createRequire } from 'node:module';
+
+import type { CallToolRequest, ListResourcesRequest } from '@modelcontextprotocol/sdk/types.js';
+import { loadServerDefinitions, type ServerDefinition } from './config.js';
+import { createPrefixedConsoleLogger, type Logger, type LogLevel, resolveLogLevelFromEnv } from './logging.js';
+import { closeTransportAndWait } from './runtime-process-utils.js';
+import './sdk-patches.js';
+import { shouldResetConnection } from './runtime/errors.js';
+import { resolveOAuthTimeoutFromEnv } from './runtime/oauth.js';
+import { type ClientContext, createClientContext } from './runtime/transport.js';
+import { normalizeTimeout, raceWithTimeout } from './runtime/utils.js';
+
+const PACKAGE_NAME = 'mcporter';
+// Keep version in one place by reading package.json; fall back gracefully when bundled without it (e.g., bun bundle).
+const CLIENT_VERSION = (() => {
+  try {
+    return createRequire(import.meta.url)('../package.json').version as string;
+  } catch {
+    return process.env.MCPORTER_VERSION ?? '0.0.0-dev';
+  }
+})();
+export const MCPORTER_VERSION = CLIENT_VERSION;
+const OAUTH_CODE_TIMEOUT_MS = resolveOAuthTimeoutFromEnv();
+
+export interface RuntimeOptions {
+  readonly configPath?: string;
+  readonly servers?: ServerDefinition[];
+  readonly rootDir?: string;
+  readonly clientInfo?: {
+    name: string;
+    version: string;
+  };
+  readonly logger?: RuntimeLogger;
+  readonly oauthTimeoutMs?: number;
+}
+
+export type RuntimeLogger = Logger;
+
+export interface CallOptions {
+  readonly args?: CallToolRequest['params']['arguments'];
+  readonly timeoutMs?: number;
+}
+
+export interface ListToolsOptions {
+  readonly includeSchema?: boolean;
+  readonly autoAuthorize?: boolean;
+  readonly allowCachedAuth?: boolean;
+}
+
+interface ConnectOptions {
+  readonly maxOAuthAttempts?: number;
+  readonly skipCache?: boolean;
+  readonly allowCachedAuth?: boolean;
+}
+
+export interface Runtime {
+  listServers(): string[];
+  getDefinitions(): ServerDefinition[];
+  getDefinition(server: string): ServerDefinition;
+  registerDefinition(definition: ServerDefinition, options?: { overwrite?: boolean }): void;
+  listTools(server: string, options?: ListToolsOptions): Promise<ServerToolInfo[]>;
+  callTool(server: string, toolName: string, options?: CallOptions): Promise<unknown>;
+  listResources(server: string, options?: Partial<ListResourcesRequest['params']>): Promise<unknown>;
+  connect(server: string): Promise<ClientContext>;
+  close(server?: string): Promise<void>;
+}
+
+export interface ServerToolInfo {
+  readonly name: string;
+  readonly description?: string;
+  readonly inputSchema?: unknown;
+  readonly outputSchema?: unknown;
+}
+
+// createRuntime spins up a pooled MCP runtime from config JSON or provided definitions.
+export async function createRuntime(options: RuntimeOptions = {}): Promise<Runtime> {
+  // Build the runtime with either the provided server list or the config file contents.
+  const servers =
+    options.servers ??
+    (await loadServerDefinitions({
+      configPath: options.configPath,
+      rootDir: options.rootDir,
+    }));
+
+  const runtime = new McpRuntime(servers, options);
+  return runtime;
+}
+
+// callOnce connects to a server, invokes a single tool, and disposes the connection immediately.
+export async function callOnce(params: {
+  server: string;
+  toolName: string;
+  args?: Record<string, unknown>;
+  configPath?: string;
+}): Promise<unknown> {
+  const runtime = await createRuntime({ configPath: params.configPath });
+  try {
+    return await runtime.callTool(params.server, params.toolName, {
+      args: params.args,
+    });
+  } finally {
+    await runtime.close(params.server);
+  }
+}
+
+class McpRuntime implements Runtime {
+  private readonly definitions: Map<string, ServerDefinition>;
+  private readonly clients = new Map<string, Promise<ClientContext>>();
+  private readonly logger: RuntimeLogger;
+  private readonly clientInfo: { name: string; version: string };
+  private readonly oauthTimeoutMs?: number;
+
+  constructor(servers: ServerDefinition[], options: RuntimeOptions = {}) {
+    this.definitions = new Map(servers.map((entry) => [entry.name, entry]));
+    this.logger = options.logger ?? createConsoleLogger();
+    this.clientInfo = options.clientInfo ?? {
+      name: PACKAGE_NAME,
+      version: CLIENT_VERSION,
+    };
+    this.oauthTimeoutMs = options.oauthTimeoutMs;
+  }
+
+  // listServers returns configured names sorted alphabetically for stable CLI output.
+  listServers(): string[] {
+    return [...this.definitions.keys()].sort((a, b) => a.localeCompare(b));
+  }
+
+  // getDefinitions exposes raw server metadata to consumers such as the CLI.
+  getDefinitions(): ServerDefinition[] {
+    return [...this.definitions.values()];
+  }
+
+  // getDefinition throws when the caller requests an unknown server name.
+  getDefinition(server: string): ServerDefinition {
+    const definition = this.definitions.get(server);
+    if (!definition) {
+      throw new Error(`Unknown MCP server '${server}'.`);
+    }
+    return definition;
+  }
+
+  registerDefinition(definition: ServerDefinition, options: { overwrite?: boolean } = {}): void {
+    if (!options.overwrite && this.definitions.has(definition.name)) {
+      throw new Error(`MCP server '${definition.name}' already exists.`);
+    }
+    this.definitions.set(definition.name, definition);
+    this.clients.delete(definition.name);
+  }
+
+  // listTools queries tool metadata and optionally includes schemas when requested.
+  async listTools(server: string, options: ListToolsOptions = {}): Promise<ServerToolInfo[]> {
+    // Toggle auto authorization so list can run without forcing OAuth flows.
+    const autoAuthorize = options.autoAuthorize !== false;
+    const context = await this.connect(server, {
+      maxOAuthAttempts: autoAuthorize ? undefined : 0,
+      skipCache: !autoAuthorize,
+      allowCachedAuth: options.allowCachedAuth,
+    });
+    try {
+      const tools: ServerToolInfo[] = [];
+      let cursor: string | undefined;
+      do {
+        const response = await context.client.listTools(cursor ? { cursor } : undefined);
+        tools.push(
+          ...(response.tools ?? []).map((tool) => ({
+            name: tool.name,
+            description: tool.description ?? undefined,
+            inputSchema: options.includeSchema ? tool.inputSchema : undefined,
+            outputSchema: options.includeSchema ? tool.outputSchema : undefined,
+          }))
+        );
+        cursor = response.nextCursor ?? undefined;
+      } while (cursor);
+
+      return tools;
+    } catch (error) {
+      // Keep-alive STDIO transports often die when Chrome closes; drop the cached client
+      // so the next call spins up a fresh process instead of reusing the broken handle.
+      await this.resetConnectionOnError(server, error);
+      throw error;
+    } finally {
+      if (!autoAuthorize) {
+        await context.client.close().catch(() => {});
+        await closeTransportAndWait(this.logger, context.transport).catch(() => {});
+        await context.oauthSession?.close().catch(() => {});
+      }
+    }
+  }
+
+  // callTool executes a tool using the args provided by the caller.
+  async callTool(server: string, toolName: string, options: CallOptions = {}): Promise<unknown> {
+    try {
+      const { client } = await this.connect(server);
+      const params: CallToolRequest['params'] = {
+        name: toolName,
+        arguments: options.args ?? {},
+      };
+      // Forward the requested timeout to the MCP client so server-side requests don't hit the SDK's
+      // default 60s cap. Keep our own outer race as a second guard.
+      const timeoutMs = normalizeTimeout(options.timeoutMs);
+      const resultPromise = client.callTool(params, undefined, {
+        timeout: timeoutMs,
+        // Long runs (e.g., GPT-5 Pro) emit progress/logging; allow that to refresh the timer.
+        resetTimeoutOnProgress: true,
+        maxTotalTimeout: timeoutMs,
+      });
+      if (!timeoutMs) {
+        return await resultPromise;
+      }
+      return await raceWithTimeout(resultPromise, timeoutMs);
+    } catch (error) {
+      // Runtime timeouts and transport crashes should tear down the cached connection so
+      // the daemon (or direct runtime) can relaunch the MCP server on the next attempt.
+      await this.resetConnectionOnError(server, error);
+      throw error;
+    }
+  }
+
+  // listResources delegates to the MCP resources/list method with passthrough params.
+  async listResources(server: string, options: Partial<ListResourcesRequest['params']> = {}): Promise<unknown> {
+    try {
+      const { client } = await this.connect(server);
+      return await client.listResources(options as ListResourcesRequest['params']);
+    } catch (error) {
+      // Fatal listResources errors usually mean the underlying transport has gone away.
+      await this.resetConnectionOnError(server, error);
+      throw error;
+    }
+  }
+
+  // connect lazily instantiates a client context per server and memoizes it.
+  async connect(server: string, options: ConnectOptions = {}): Promise<ClientContext> {
+    // Reuse cached connections unless the caller explicitly opted out.
+    const normalized = server.trim();
+
+    const useCache = options.skipCache !== true && options.maxOAuthAttempts === undefined;
+
+    if (useCache) {
+      const existing = this.clients.get(normalized);
+      if (existing) {
+        return existing;
+      }
+    }
+
+    const definition = this.definitions.get(normalized);
+    if (!definition) {
+      throw new Error(`Unknown MCP server '${normalized}'.`);
+    }
+
+    const connection = createClientContext(definition, this.logger, this.clientInfo, {
+      maxOAuthAttempts: options.maxOAuthAttempts,
+      oauthTimeoutMs: this.oauthTimeoutMs ?? OAUTH_CODE_TIMEOUT_MS,
+      onDefinitionPromoted: (promoted) => this.definitions.set(promoted.name, promoted),
+      allowCachedAuth: options.allowCachedAuth,
+    });
+
+    if (useCache) {
+      this.clients.set(normalized, connection);
+      try {
+        return await connection;
+      } catch (error) {
+        this.clients.delete(normalized);
+        throw error;
+      }
+    }
+
+    return connection;
+  }
+
+  // close tears down transports (and OAuth sessions) for a single server or all servers.
+  async close(server?: string): Promise<void> {
+    if (server) {
+      const normalized = server.trim();
+      const context = await this.clients.get(normalized);
+      if (!context) {
+        return;
+      }
+      await context.client.close().catch(() => {});
+      await closeTransportAndWait(this.logger, context.transport).catch(() => {});
+      await context.oauthSession?.close().catch(() => {});
+      this.clients.delete(normalized);
+      return;
+    }
+
+    for (const [name, promise] of this.clients.entries()) {
+      try {
+        const context = await promise;
+        await context.client.close().catch(() => {});
+        await closeTransportAndWait(this.logger, context.transport).catch(() => {});
+        await context.oauthSession?.close().catch(() => {});
+      } finally {
+        this.clients.delete(name);
+      }
+    }
+  }
+
+  private async resetConnectionOnError(server: string, error: unknown): Promise<void> {
+    if (!shouldResetConnection(error)) {
+      return;
+    }
+    const normalized = server.trim();
+    if (!this.clients.has(normalized)) {
+      return;
+    }
+    try {
+      // Reuse the existing close() helper so transport shutdown stays consistent with
+      // normal runtime disposal (wait for STDIO children, close OAuth sessions, etc.).
+      await this.close(normalized);
+    } catch (closeError) {
+      const detail = closeError instanceof Error ? closeError.message : String(closeError);
+      this.logger.warn(`Failed to reset '${normalized}' after error: ${detail}`);
+    }
+  }
+}
+
+// createConsoleLogger produces the default runtime logger honoring MCPORTER_LOG_LEVEL.
+function createConsoleLogger(level: LogLevel = resolveLogLevelFromEnv()): RuntimeLogger {
+  return createPrefixedConsoleLogger('mcporter', level);
+}
+
+export { readJsonFile, writeJsonFile } from './fs-json.js';