@nimrobo/mcporter-remote 0.1.0

package/src/result-utils.ts

@@ -0,0 +1,278 @@
+import { analyzeConnectionError, type ConnectionIssue } from './error-classifier.js';
+
+export interface ImageContent {
+  data: string;
+  mimeType: string;
+}
+
+export interface CallResult<T = unknown> {
+  raw: T;
+  text(joiner?: string): string | null;
+  markdown(joiner?: string): string | null;
+  json<J = unknown>(): J | null;
+  images(): ImageContent[] | null;
+  content(): unknown[] | null;
+  structuredContent(): unknown;
+}
+
+interface ExtractedEnvelope {
+  content: unknown[] | null;
+  structuredContent: unknown;
+}
+
+interface CollectedCallContent {
+  content: unknown[] | null;
+  structuredContent: unknown;
+  textEntries: string[];
+  markdownEntries: string[];
+  jsonCandidates: unknown[];
+  images: ImageContent[];
+}
+
+function extractEnvelope(raw: unknown): ExtractedEnvelope {
+  if (!raw || typeof raw !== 'object') {
+    return { content: null, structuredContent: null };
+  }
+
+  const obj = raw as Record<string, unknown>;
+  let content: unknown[] | null = null;
+  let structuredContent: unknown = null;
+
+  if ('content' in obj && Array.isArray(obj.content)) {
+    content = obj.content as unknown[];
+  }
+  if ('structuredContent' in obj) {
+    structuredContent = obj.structuredContent;
+  }
+
+  if ('raw' in obj && obj.raw && typeof obj.raw === 'object') {
+    const nested = obj.raw as Record<string, unknown>;
+    if (!content && 'content' in nested && Array.isArray(nested.content)) {
+      content = nested.content as unknown[];
+    }
+    if (structuredContent === null && 'structuredContent' in nested) {
+      structuredContent = nested.structuredContent;
+    }
+  }
+
+  return { content, structuredContent };
+}
+
+// asString converts known content/value shapes into plain strings.
+function asString(value: unknown): string | null {
+  if (typeof value === 'string') {
+    return value;
+  }
+  if (value && typeof value === 'object' && 'text' in value) {
+    const text = (value as Record<string, unknown>).text;
+    return typeof text === 'string' ? text : null;
+  }
+  return null;
+}
+
+function collectCallContent(raw: unknown): CollectedCallContent {
+  const envelope = extractEnvelope(raw);
+  const textEntries: string[] = [];
+  const markdownEntries: string[] = [];
+  const jsonCandidates: unknown[] = [];
+  const images: ImageContent[] = [];
+
+  if (!envelope.content) {
+    return {
+      content: envelope.content,
+      structuredContent: envelope.structuredContent,
+      textEntries,
+      markdownEntries,
+      jsonCandidates,
+      images,
+    };
+  }
+
+  for (const entry of envelope.content) {
+    if (typeof entry === 'string') {
+      const parsed = tryParseJson(entry);
+      if (parsed !== null) {
+        jsonCandidates.push(parsed);
+      }
+      continue;
+    }
+    if (!entry || typeof entry !== 'object' || !('type' in entry)) {
+      continue;
+    }
+
+    const typedEntry = entry as Record<string, unknown>;
+    if (typedEntry.type === 'json') {
+      const parsed = tryParseJson(entry);
+      if (parsed !== null) {
+        jsonCandidates.push(parsed);
+      }
+      continue;
+    }
+    if (typedEntry.type === 'image') {
+      const data = typedEntry.data;
+      const mimeType = typedEntry.mimeType ?? 'image/png';
+      if (typeof data === 'string' && typeof mimeType === 'string') {
+        images.push({ data, mimeType });
+      }
+      continue;
+    }
+    if (typedEntry.type !== 'text' && typedEntry.type !== 'markdown') {
+      continue;
+    }
+
+    const text = asString(entry);
+    if (!text) {
+      continue;
+    }
+    textEntries.push(text);
+    if (typedEntry.type === 'markdown') {
+      markdownEntries.push(text);
+    }
+    const parsed = tryParseJson(text);
+    if (parsed !== null) {
+      jsonCandidates.push(parsed);
+    }
+  }
+
+  return {
+    content: envelope.content,
+    structuredContent: envelope.structuredContent,
+    textEntries,
+    markdownEntries,
+    jsonCandidates,
+    images,
+  };
+}
+
+function collectText(entries: string[], joiner: string): string | null {
+  if (entries.length === 0) {
+    return null;
+  }
+  return entries.join(joiner);
+}
+
+function collectImages(images: ImageContent[]): ImageContent[] | null {
+  if (images.length === 0) {
+    return null;
+  }
+  return images;
+}
+
+// tryParseJson pulls JSON payloads out of structured responses or raw strings.
+function tryParseJson(value: unknown): unknown {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  if (typeof value === 'object') {
+    if ('json' in (value as Record<string, unknown>)) {
+      return (value as Record<string, unknown>).json ?? null;
+    }
+    if ('data' in (value as Record<string, unknown>)) {
+      return (value as Record<string, unknown>).data ?? null;
+    }
+  }
+  if (typeof value === 'string') {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+// createCallResult wraps a tool response with helpers for common content types.
+export function createCallResult<T = unknown>(raw: T): CallResult<T> {
+  let cachedContent: CollectedCallContent | undefined;
+  const getCollectedContent = (): CollectedCallContent => {
+    if (cachedContent) {
+      return cachedContent;
+    }
+    cachedContent = collectCallContent(raw);
+    return cachedContent;
+  };
+
+  return {
+    raw,
+    text(joiner = '\n') {
+      if (raw == null) {
+        return null;
+      }
+      if (typeof raw === 'string') {
+        return raw;
+      }
+
+      const collected = getCollectedContent();
+      const combinedText = collectText(collected.textEntries, joiner);
+      if (combinedText) {
+        return combinedText;
+      }
+      return asString(collected.structuredContent);
+    },
+    markdown(joiner = '\n') {
+      const collected = getCollectedContent();
+      const structured = collected.structuredContent;
+      if (structured && typeof structured === 'object') {
+        const markdown = (structured as Record<string, unknown>).markdown;
+        if (typeof markdown === 'string') {
+          return markdown;
+        }
+      }
+      return collectText(collected.markdownEntries, joiner);
+    },
+    json<J = unknown>() {
+      const collected = getCollectedContent();
+      const parsedStructured = tryParseJson(collected.structuredContent);
+      if (parsedStructured !== null) {
+        return parsedStructured as J;
+      }
+      if (collected.jsonCandidates.length === 1) {
+        return collected.jsonCandidates[0] as J;
+      }
+      if (collected.jsonCandidates.length > 1) {
+        return collected.jsonCandidates as J;
+      }
+      if (typeof raw === 'string') {
+        const parsedRaw = tryParseJson(raw);
+        if (parsedRaw !== null) {
+          return parsedRaw as J;
+        }
+      }
+      const textContent = this.text?.();
+      if (typeof textContent === 'string') {
+        const parsedText = tryParseJson(textContent);
+        if (parsedText !== null) {
+          return parsedText as J;
+        }
+      }
+      const markdownContent = this.markdown?.();
+      if (typeof markdownContent === 'string') {
+        const parsedMarkdown = tryParseJson(markdownContent);
+        if (parsedMarkdown !== null) {
+          return parsedMarkdown as J;
+        }
+      }
+      return null;
+    },
+    images() {
+      const collected = getCollectedContent();
+      return collectImages(collected.images);
+    },
+    content() {
+      return getCollectedContent().content;
+    },
+    structuredContent() {
+      return getCollectedContent().structuredContent;
+    },
+  };
+}
+
+export type { ConnectionIssue } from './error-classifier.js';
+
+export function describeConnectionIssue(error: unknown): ConnectionIssue {
+  return analyzeConnectionError(error);
+}
+
+export function wrapCallResult<T = unknown>(raw: T): { raw: T; callResult: CallResult<T> } {
+  return { raw, callResult: createCallResult(raw) };
+}

package/src/runtime/errors.ts

@@ -0,0 +1,17 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+
+const NON_FATAL_MCP_ERROR_CODES = new Set([
+  ErrorCode.InvalidRequest,
+  ErrorCode.MethodNotFound,
+  ErrorCode.InvalidParams,
+]);
+
+export function shouldResetConnection(error: unknown): boolean {
+  if (!error) {
+    return false;
+  }
+  if (error instanceof McpError) {
+    return !NON_FATAL_MCP_ERROR_CODES.has(error.code);
+  }
+  return error instanceof Error;
+}

package/src/runtime/oauth.ts

@@ -0,0 +1,112 @@
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { Logger } from '../logging.js';
+import type { OAuthSession } from '../oauth.js';
+import { isUnauthorizedError } from '../runtime-oauth-support.js';
+
+export const DEFAULT_OAUTH_CODE_TIMEOUT_MS = 60_000;
+
+export class OAuthTimeoutError extends Error {
+  public readonly timeoutMs: number;
+  public readonly serverName: string;
+
+  constructor(serverName: string, timeoutMs: number) {
+    const seconds = Math.round(timeoutMs / 1000);
+    super(`OAuth authorization for '${serverName}' timed out after ${seconds}s; aborting.`);
+    this.name = 'OAuthTimeoutError';
+    this.timeoutMs = timeoutMs;
+    this.serverName = serverName;
+  }
+}
+
+export async function connectWithAuth(
+  client: Client,
+  transport: Transport & {
+    close(): Promise<void>;
+    finishAuth?: (authorizationCode: string) => Promise<void>;
+  },
+  session: OAuthSession | undefined,
+  logger: Logger,
+  options: { serverName?: string; maxAttempts?: number; oauthTimeoutMs?: number } = {}
+): Promise<void> {
+  const { serverName, maxAttempts = 3, oauthTimeoutMs = DEFAULT_OAUTH_CODE_TIMEOUT_MS } = options;
+  let attempt = 0;
+  while (true) {
+    try {
+      await client.connect(transport);
+      return;
+    } catch (error) {
+      if (!isUnauthorizedError(error) || !session) {
+        throw error;
+      }
+      attempt += 1;
+      if (attempt > maxAttempts) {
+        throw error;
+      }
+      logger.warn(`OAuth authorization required for '${serverName ?? 'unknown'}'. Waiting for browser approval...`);
+      try {
+        const code = await waitForAuthorizationCodeWithTimeout(
+          session,
+          logger,
+          serverName,
+          oauthTimeoutMs ?? DEFAULT_OAUTH_CODE_TIMEOUT_MS
+        );
+        if (typeof transport.finishAuth === 'function') {
+          await transport.finishAuth(code);
+          logger.info('Authorization code accepted. Retrying connection...');
+        } else {
+          logger.warn('Transport does not support finishAuth; cannot complete OAuth flow automatically.');
+          throw error;
+        }
+      } catch (authError) {
+        logger.error('OAuth authorization failed while waiting for callback.', authError);
+        throw authError;
+      }
+    }
+  }
+}
+
+// Race the pending OAuth browser handshake so the runtime can't sit on an unresolved promise forever.
+export function waitForAuthorizationCodeWithTimeout(
+  session: OAuthSession,
+  logger: Logger,
+  serverName?: string,
+  timeoutMs = DEFAULT_OAUTH_CODE_TIMEOUT_MS
+): Promise<string> {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    return session.waitForAuthorizationCode();
+  }
+  const displayName = serverName ?? 'unknown';
+  return new Promise<string>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      const error = new OAuthTimeoutError(displayName, timeoutMs);
+      logger.warn(error.message);
+      reject(error);
+    }, timeoutMs);
+    session.waitForAuthorizationCode().then(
+      (code) => {
+        clearTimeout(timer);
+        resolve(code);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      }
+    );
+  });
+}
+
+export function parseOAuthTimeout(raw: string | undefined): number {
+  if (!raw) {
+    return DEFAULT_OAUTH_CODE_TIMEOUT_MS;
+  }
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return DEFAULT_OAUTH_CODE_TIMEOUT_MS;
+  }
+  return parsed;
+}
+
+export function resolveOAuthTimeoutFromEnv(): number {
+  return parseOAuthTimeout(process.env.MCPORTER_OAUTH_TIMEOUT_MS ?? process.env.MCPORTER_OAUTH_TIMEOUT);
+}

package/src/runtime/transport.ts

@@ -0,0 +1,198 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { ServerDefinition } from '../config.js';
+import { resolveEnvValue, withEnvOverrides } from '../env.js';
+import type { Logger } from '../logging.js';
+import { createOAuthSession, type OAuthSession } from '../oauth.js';
+import { readCachedAccessToken } from '../oauth-persistence.js';
+import { materializeHeaders } from '../runtime-header-utils.js';
+import { isUnauthorizedError, maybeEnableOAuth } from '../runtime-oauth-support.js';
+import { closeTransportAndWait } from '../runtime-process-utils.js';
+import { connectWithAuth, OAuthTimeoutError } from './oauth.js';
+import { resolveCommandArgument, resolveCommandArguments } from './utils.js';
+
+const STDIO_TRACE_ENABLED = process.env.MCPORTER_STDIO_TRACE === '1';
+
+function attachStdioTraceLogging(_transport: StdioClientTransport, _label?: string): void {
+  // STDIO instrumentation is handled via sdk-patches side effects. This helper remains
+  // so runtime callers can opt-in without sprinkling conditional checks everywhere.
+}
+
+export interface ClientContext {
+  readonly client: Client;
+  readonly transport: Transport & { close(): Promise<void> };
+  readonly definition: ServerDefinition;
+  readonly oauthSession?: OAuthSession;
+}
+
+export interface CreateClientContextOptions {
+  readonly maxOAuthAttempts?: number;
+  readonly oauthTimeoutMs?: number;
+  readonly onDefinitionPromoted?: (definition: ServerDefinition) => void;
+  readonly allowCachedAuth?: boolean;
+}
+
+export async function createClientContext(
+  definition: ServerDefinition,
+  logger: Logger,
+  clientInfo: { name: string; version: string },
+  options: CreateClientContextOptions = {}
+): Promise<ClientContext> {
+  const client = new Client(clientInfo);
+  let activeDefinition = definition;
+
+  if (options.allowCachedAuth && activeDefinition.auth === 'oauth' && activeDefinition.command.kind === 'http') {
+    try {
+      const cached = await readCachedAccessToken(activeDefinition, logger);
+      if (cached) {
+        const existingHeaders = activeDefinition.command.headers ?? {};
+        if (!('Authorization' in existingHeaders)) {
+          activeDefinition = {
+            ...activeDefinition,
+            command: {
+              ...activeDefinition.command,
+              headers: {
+                ...existingHeaders,
+                Authorization: `Bearer ${cached}`,
+              },
+            },
+          };
+          logger.debug?.(`Using cached OAuth access token for '${activeDefinition.name}' (non-interactive).`);
+        }
+      }
+    } catch (error) {
+      logger.debug?.(
+        `Failed to read cached OAuth token for '${activeDefinition.name}': ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+  }
+
+  return withEnvOverrides(activeDefinition.env, async () => {
+    if (activeDefinition.command.kind === 'stdio') {
+      const resolvedEnvOverrides =
+        activeDefinition.env && Object.keys(activeDefinition.env).length > 0
+          ? Object.fromEntries(
+              Object.entries(activeDefinition.env)
+                .map(([key, raw]) => [key, resolveEnvValue(raw)])
+                .filter(([, value]) => value !== '')
+            )
+          : undefined;
+      const mergedEnv =
+        resolvedEnvOverrides && Object.keys(resolvedEnvOverrides).length > 0
+          ? { ...process.env, ...resolvedEnvOverrides }
+          : { ...process.env };
+      const transport = new StdioClientTransport({
+        command: resolveCommandArgument(activeDefinition.command.command),
+        args: resolveCommandArguments(activeDefinition.command.args),
+        cwd: activeDefinition.command.cwd,
+        env: mergedEnv,
+      });
+      if (STDIO_TRACE_ENABLED) {
+        attachStdioTraceLogging(transport, activeDefinition.name ?? activeDefinition.command.command);
+      }
+      try {
+        await client.connect(transport);
+      } catch (error) {
+        await closeTransportAndWait(logger, transport).catch(() => {});
+        throw error;
+      }
+      return { client, transport, definition: activeDefinition, oauthSession: undefined };
+    }
+
+    while (true) {
+      const command = activeDefinition.command;
+      if (command.kind !== 'http') {
+        throw new Error(`Server '${activeDefinition.name}' is not configured for HTTP transport.`);
+      }
+      let oauthSession: OAuthSession | undefined;
+      const shouldEstablishOAuth = activeDefinition.auth === 'oauth' && options.maxOAuthAttempts !== 0;
+      if (shouldEstablishOAuth) {
+        oauthSession = await createOAuthSession(activeDefinition, logger);
+      }
+
+      const resolvedHeaders = materializeHeaders(command.headers, activeDefinition.name);
+      const requestInit: RequestInit | undefined = resolvedHeaders
+        ? { headers: resolvedHeaders as HeadersInit }
+        : undefined;
+      const baseOptions = {
+        requestInit,
+        authProvider: oauthSession?.provider,
+      };
+
+      const attemptConnect = async () => {
+        const streamableTransport = new StreamableHTTPClientTransport(command.url, baseOptions);
+        try {
+          await connectWithAuth(client, streamableTransport, oauthSession, logger, {
+            serverName: activeDefinition.name,
+            maxAttempts: options.maxOAuthAttempts,
+            oauthTimeoutMs: options.oauthTimeoutMs,
+          });
+          return {
+            client,
+            transport: streamableTransport,
+            definition: activeDefinition,
+            oauthSession,
+          } as ClientContext;
+        } catch (error) {
+          await closeTransportAndWait(logger, streamableTransport).catch(() => {});
+          throw error;
+        }
+      };
+
+      try {
+        return await attemptConnect();
+      } catch (primaryError) {
+        if (isUnauthorizedError(primaryError)) {
+          await oauthSession?.close().catch(() => {});
+          oauthSession = undefined;
+          if (options.maxOAuthAttempts !== 0) {
+            const promoted = maybeEnableOAuth(activeDefinition, logger);
+            if (promoted) {
+              activeDefinition = promoted;
+              options.onDefinitionPromoted?.(promoted);
+              continue;
+            }
+          }
+        }
+        if (primaryError instanceof OAuthTimeoutError) {
+          await oauthSession?.close().catch(() => {});
+          throw primaryError;
+        }
+        if (primaryError instanceof Error) {
+          logger.info(`Falling back to SSE transport for '${activeDefinition.name}': ${primaryError.message}`);
+        }
+        const sseTransport = new SSEClientTransport(command.url, {
+          ...baseOptions,
+        });
+        try {
+          await connectWithAuth(client, sseTransport, oauthSession, logger, {
+            serverName: activeDefinition.name,
+            maxAttempts: options.maxOAuthAttempts,
+            oauthTimeoutMs: options.oauthTimeoutMs,
+          });
+          return { client, transport: sseTransport, definition: activeDefinition, oauthSession };
+        } catch (sseError) {
+          await closeTransportAndWait(logger, sseTransport).catch(() => {});
+          await oauthSession?.close().catch(() => {});
+          if (sseError instanceof OAuthTimeoutError) {
+            throw sseError;
+          }
+          if (isUnauthorizedError(sseError) && options.maxOAuthAttempts !== 0) {
+            const promoted = maybeEnableOAuth(activeDefinition, logger);
+            if (promoted) {
+              activeDefinition = promoted;
+              options.onDefinitionPromoted?.(promoted);
+              continue;
+            }
+          }
+          throw sseError;
+        }
+      }
+    }
+  });
+}

package/src/runtime/utils.ts

@@ -0,0 +1,54 @@
+import { resolveEnvPlaceholders } from '../env.js';
+
+const ENV_PLACEHOLDER_PATTERN = /\$\{[A-Za-z_][A-Za-z0-9_]*\}/;
+
+export function resolveCommandArgument(value: string): string {
+  if (!value) {
+    return value;
+  }
+  if (!value.includes('$')) {
+    return value;
+  }
+  const needsInterpolation = value.startsWith('$env:') || ENV_PLACEHOLDER_PATTERN.test(value);
+  if (!needsInterpolation) {
+    return value;
+  }
+  return resolveEnvPlaceholders(value);
+}
+
+export function resolveCommandArguments(args: readonly string[]): string[] {
+  if (!args || args.length === 0) {
+    return [];
+  }
+  return args.map((arg) => resolveCommandArgument(arg));
+}
+
+export function normalizeTimeout(raw?: number): number | undefined {
+  if (raw == null) {
+    return undefined;
+  }
+  if (!Number.isFinite(raw)) {
+    return undefined;
+  }
+  const coerced = Math.trunc(raw);
+  return coerced > 0 ? coerced : undefined;
+}
+
+export function raceWithTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      // Reject with a Timeout error; higher-level catch blocks decide whether to recycle the transport.
+      reject(new Error('Timeout'));
+    }, timeoutMs);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      }
+    );
+  });
+}

package/src/runtime-header-utils.ts

@@ -0,0 +1,23 @@
+import { resolveEnvPlaceholders } from './env.js';
+
+// materializeHeaders resolves environment placeholders in server header definitions.
+export function materializeHeaders(
+  headers: Record<string, string> | undefined,
+  serverName: string
+): Record<string, string> | undefined {
+  if (!headers) {
+    return undefined;
+  }
+
+  const resolved: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    try {
+      resolved[key] = resolveEnvPlaceholders(value);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to resolve header '${key}' for server '${serverName}': ${message}`);
+    }
+  }
+
+  return resolved;
+}