@nimrobo/mcporter-remote 0.1.0

package/src/index.ts

@@ -0,0 +1,14 @@
+export type { CommandSpec, ServerDefinition } from './config.js';
+export { loadServerDefinitions } from './config.js';
+export type { CallResult, ConnectionIssue, ImageContent } from './result-utils.js';
+export { createCallResult, describeConnectionIssue, wrapCallResult } from './result-utils.js';
+export type {
+  CallOptions,
+  ListToolsOptions,
+  Runtime,
+  RuntimeLogger,
+  ServerToolInfo,
+} from './runtime.js';
+export { callOnce, createRuntime } from './runtime.js';
+export type { ServerProxyOptions } from './server-proxy.js';
+export { createServerProxy } from './server-proxy.js';

package/src/lifecycle.ts

@@ -0,0 +1,138 @@
+import type { CommandSpec, RawLifecycle, ServerDefinition, ServerLifecycle } from './config-schema.js';
+
+const DEFAULT_KEEP_ALIVE = new Set(['chrome-devtools', 'mobile-mcp', 'playwright']);
+
+const includeOverride = parseList(process.env.MCPORTER_KEEPALIVE);
+const excludeOverride = parseList(process.env.MCPORTER_DISABLE_KEEPALIVE ?? process.env.MCPORTER_NO_KEEPALIVE);
+
+interface OverrideSet {
+  readonly all: boolean;
+  readonly names: Set<string>;
+}
+
+interface CommandSignature {
+  readonly label: string;
+  readonly fragments: string[];
+}
+
+const KEEP_ALIVE_COMMANDS: CommandSignature[] = [
+  { label: 'chrome-devtools', fragments: ['chrome-devtools-mcp'] },
+  { label: 'mobile-mcp', fragments: ['@mobilenext/mobile-mcp', 'mobile-mcp'] },
+  { label: 'playwright', fragments: ['@playwright/mcp', 'playwright/mcp'] },
+];
+
+const CHROME_DEVTOOLS_URL_PLACEHOLDERS = [String.raw`\${CHROME_DEVTOOLS_URL}`, '$env:CHROME_DEVTOOLS_URL'];
+
+export function resolveLifecycle(
+  name: string,
+  rawLifecycle: RawLifecycle | undefined,
+  command: CommandSpec
+): ServerLifecycle | undefined {
+  const normalizedName = name.toLowerCase();
+  const canonicalName = canonicalKeepAliveName(command);
+  const candidateNames = new Set<string>([normalizedName]);
+  if (canonicalName) {
+    candidateNames.add(canonicalName);
+  }
+  const forcedDisable = excludeOverride.all || matchesOverride(excludeOverride.names, candidateNames);
+  const forcedEnable = includeOverride.all || matchesOverride(includeOverride.names, candidateNames);
+
+  if (forcedEnable) {
+    return { mode: 'keep-alive' };
+  }
+  if (forcedDisable) {
+    return undefined;
+  }
+
+  const lifecycle = rawLifecycle ? coerceLifecycle(rawLifecycle) : undefined;
+  if (lifecycle) {
+    return lifecycle;
+  }
+  if (commandRequiresDynamicChromePort(command)) {
+    // Each Chrome DevTools MCP instance is tied to a specific Chrome port. Opt out of keep-alive so
+    // the runtime (and daemon) relaunches the bridge whenever CHROME_DEVTOOLS_URL changes.
+    return { mode: 'ephemeral' };
+  }
+  if (Array.from(candidateNames).some((candidate) => DEFAULT_KEEP_ALIVE.has(candidate))) {
+    return { mode: 'keep-alive' };
+  }
+  return undefined;
+}
+
+export function canonicalKeepAliveName(command: CommandSpec): string | undefined {
+  if (command.kind !== 'stdio') {
+    return undefined;
+  }
+  const tokens = [command.command, ...command.args].map((token) => token.toLowerCase());
+  const match = KEEP_ALIVE_COMMANDS.find((signature) =>
+    signature.fragments.some((fragment) => tokens.some((token) => token.includes(fragment)))
+  );
+  return match?.label;
+}
+
+function commandRequiresDynamicChromePort(command: CommandSpec): boolean {
+  if (command.kind !== 'stdio') {
+    return false;
+  }
+  const tokens = [command.command, ...command.args];
+  return tokens.some((token) => CHROME_DEVTOOLS_URL_PLACEHOLDERS.some((placeholder) => token.includes(placeholder)));
+}
+
+function parseList(value: string | undefined): OverrideSet {
+  if (!value) {
+    return { all: false, names: new Set() };
+  }
+  const names = value
+    .split(',')
+    .map((token) => token.trim().toLowerCase())
+    .filter((token) => token.length > 0);
+  if (names.includes('*')) {
+    return { all: true, names: new Set() };
+  }
+  return { all: false, names: new Set(names) };
+}
+
+function matchesOverride(names: Set<string>, candidates: Set<string>): boolean {
+  for (const candidate of candidates) {
+    if (names.has(candidate)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function coerceLifecycle(raw: RawLifecycle): ServerLifecycle | undefined {
+  if (typeof raw === 'string') {
+    if (raw === 'keep-alive') {
+      return { mode: 'keep-alive' };
+    }
+    if (raw === 'ephemeral') {
+      return { mode: 'ephemeral' };
+    }
+    return undefined;
+  }
+  if (raw.mode === 'keep-alive') {
+    const timeout =
+      typeof raw.idleTimeoutMs === 'number' && Number.isFinite(raw.idleTimeoutMs) && raw.idleTimeoutMs > 0
+        ? Math.trunc(raw.idleTimeoutMs)
+        : undefined;
+    return timeout ? { mode: 'keep-alive', idleTimeoutMs: timeout } : { mode: 'keep-alive' };
+  }
+  if (raw.mode === 'ephemeral') {
+    return { mode: 'ephemeral' };
+  }
+  return undefined;
+}
+
+export function isKeepAliveServer(definition: ServerDefinition | undefined): boolean {
+  return definition?.lifecycle?.mode === 'keep-alive';
+}
+
+export function keepAliveIdleTimeout(definition: ServerDefinition): number | undefined {
+  if (definition.lifecycle?.mode !== 'keep-alive') {
+    return undefined;
+  }
+  return definition.lifecycle.idleTimeoutMs;
+}
+
+export { DEFAULT_KEEP_ALIVE };

package/src/logging.ts

@@ -0,0 +1,93 @@
+const LOG_LEVEL_ORDER = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+} as const;
+
+type LogLevelKey = keyof typeof LOG_LEVEL_ORDER;
+
+const LOG_LEVEL_ALIASES: Record<string, LogLevelKey> = {
+  warning: 'warn',
+  verbose: 'debug',
+};
+
+export type LogLevel = LogLevelKey;
+
+export interface Logger {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string, error?: unknown): void;
+  debug?(message: string): void;
+}
+
+// parseLogLevel normalizes arbitrary input into one of the supported log level keywords.
+export function parseLogLevel(value: string | undefined, defaultLevel: LogLevel = 'warn'): LogLevel {
+  if (!value) {
+    return defaultLevel;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) {
+    return defaultLevel;
+  }
+  const alias = LOG_LEVEL_ALIASES[normalized];
+  const candidate = alias ?? (normalized in LOG_LEVEL_ORDER ? (normalized as LogLevel) : undefined);
+  if (!candidate) {
+    const allowed = [...Object.keys(LOG_LEVEL_ORDER), ...Object.keys(LOG_LEVEL_ALIASES)]
+      .filter((key, index, array) => array.indexOf(key) === index)
+      .join(', ');
+    throw new Error(`Invalid log level '${value}'. Expected one of: ${allowed}.`);
+  }
+  return candidate;
+}
+
+// resolveLogLevelFromEnv reads MCPORTER_LOG_LEVEL and falls back to the provided default when invalid.
+export function resolveLogLevelFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+  defaultLevel: LogLevel = 'warn'
+): LogLevel {
+  try {
+    return parseLogLevel(env.MCPORTER_LOG_LEVEL, defaultLevel);
+  } catch (error) {
+    const raw = env.MCPORTER_LOG_LEVEL;
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`[mcporter] Ignoring invalid MCPORTER_LOG_LEVEL value '${raw ?? ''}': ${message}`);
+    return defaultLevel;
+  }
+}
+
+// shouldLog determines whether a candidate level passes the configured threshold.
+function shouldLog(level: LogLevel, threshold: LogLevel): boolean {
+  return LOG_LEVEL_ORDER[level] >= LOG_LEVEL_ORDER[threshold];
+}
+
+// createPrefixedConsoleLogger wraps console.* with a consistent prefix and level filtering.
+export function createPrefixedConsoleLogger(prefix: string, level: LogLevel): Logger {
+  const threshold = parseLogLevel(level);
+  const format = (message: string) => `[${prefix}] ${message}`;
+  return {
+    debug(message) {
+      if (shouldLog('debug', threshold)) {
+        console.debug(format(message));
+      }
+    },
+    info(message) {
+      if (shouldLog('info', threshold)) {
+        console.log(format(message));
+      }
+    },
+    warn(message) {
+      if (shouldLog('warn', threshold)) {
+        console.warn(format(message));
+      }
+    },
+    error(message, error) {
+      if (shouldLog('error', threshold)) {
+        console.error(format(message));
+        if (error) {
+          console.error(error);
+        }
+      }
+    },
+  };
+}

package/src/oauth-manual.ts

@@ -0,0 +1,103 @@
+import { URL } from 'node:url';
+
+export interface ParsedManualOAuthCallback {
+  readonly code?: string;
+  readonly state?: string;
+  readonly error?: string;
+  readonly errorDescription?: string;
+  readonly callbackUrl?: string;
+}
+
+export function parseManualOAuthCallback(input: string): ParsedManualOAuthCallback {
+  const normalized = normalizeManualInput(input);
+  const candidates = extractUrlCandidates(normalized);
+
+  for (const candidate of candidates) {
+    const parsed = tryParseUrlPayload(candidate);
+    if (parsed) {
+      return parsed;
+    }
+  }
+
+  const inline = tryParseQueryPayload(normalized);
+  if (inline) {
+    return inline;
+  }
+
+  throw new Error(
+    'Could not extract OAuth callback details. Paste the full redirected URL, the raw query string, or browser text containing the URL.'
+  );
+}
+
+function normalizeManualInput(input: string): string {
+  return input
+    .trim()
+    .replace(/^['"`<([]+/, '')
+    .replace(/['"`>\])\s.,;:!?]+$/, '')
+    .replace(/&amp;/gi, '&');
+}
+
+function extractUrlCandidates(input: string): string[] {
+  const matches = input.match(/https?:\/\/[^\s"'<>]+/gi) ?? [];
+  if (matches.length > 0) {
+    return matches.map((match) => sanitizeUrlCandidate(match));
+  }
+  if (input.startsWith('http://') || input.startsWith('https://')) {
+    return [sanitizeUrlCandidate(input)];
+  }
+  return [];
+}
+
+function sanitizeUrlCandidate(value: string): string {
+  return value.replace(/[),.;]+$/, '').replace(/&amp;/gi, '&');
+}
+
+function tryParseUrlPayload(value: string): ParsedManualOAuthCallback | undefined {
+  try {
+    const url = new URL(value);
+    return extractPayload(url, value);
+  } catch {
+    return undefined;
+  }
+}
+
+function tryParseQueryPayload(value: string): ParsedManualOAuthCallback | undefined {
+  const query = value.startsWith('?') ? value.slice(1) : value;
+  if (!query.includes('=')) {
+    return undefined;
+  }
+  const params = new URLSearchParams(query);
+  const payload = extractParams(params);
+  return payload ? { ...payload } : undefined;
+}
+
+function extractPayload(url: URL, callbackUrl: string): ParsedManualOAuthCallback | undefined {
+  const direct = extractParams(url.searchParams);
+  if (direct) {
+    return { ...direct, callbackUrl };
+  }
+  if (url.hash.startsWith('#')) {
+    const hashParams = new URLSearchParams(url.hash.slice(1));
+    const hashed = extractParams(hashParams);
+    if (hashed) {
+      return { ...hashed, callbackUrl };
+    }
+  }
+  return undefined;
+}
+
+function extractParams(params: URLSearchParams): Omit<ParsedManualOAuthCallback, 'callbackUrl'> | undefined {
+  const code = params.get('code') ?? undefined;
+  const state = params.get('state') ?? undefined;
+  const error = params.get('error') ?? undefined;
+  const errorDescription = params.get('error_description') ?? undefined;
+  if (!code && !error) {
+    return undefined;
+  }
+  return {
+    code: code?.trim() || undefined,
+    state: state?.trim() || undefined,
+    error: error?.trim() || undefined,
+    errorDescription: errorDescription?.trim() || undefined,
+  };
+}

package/src/oauth-persistence.ts

@@ -0,0 +1,316 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import type { OAuthClientInformationMixed, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
+import type { ServerDefinition } from './config.js';
+import { readJsonFile, writeJsonFile } from './fs-json.js';
+import type { Logger } from './logging.js';
+import { clearVaultEntry, loadVaultEntry, saveVaultEntry } from './oauth-vault.js';
+
+export type OAuthClearScope = 'all' | 'client' | 'tokens' | 'verifier' | 'state';
+
+export interface OAuthPersistence {
+  describe(): string;
+  readTokens(): Promise<OAuthTokens | undefined>;
+  saveTokens(tokens: OAuthTokens): Promise<void>;
+  readClientInfo(): Promise<OAuthClientInformationMixed | undefined>;
+  saveClientInfo(info: OAuthClientInformationMixed): Promise<void>;
+  readCodeVerifier(): Promise<string | undefined>;
+  saveCodeVerifier(value: string): Promise<void>;
+  readState(): Promise<string | undefined>;
+  saveState(value: string): Promise<void>;
+  clear(scope: OAuthClearScope): Promise<void>;
+}
+
+class DirectoryPersistence implements OAuthPersistence {
+  private readonly tokenPath: string;
+  private readonly clientInfoPath: string;
+  private readonly codeVerifierPath: string;
+  private readonly statePath: string;
+
+  constructor(
+    private readonly root: string,
+    private readonly logger?: Logger
+  ) {
+    this.tokenPath = path.join(root, 'tokens.json');
+    this.clientInfoPath = path.join(root, 'client.json');
+    this.codeVerifierPath = path.join(root, 'code_verifier.txt');
+    this.statePath = path.join(root, 'state.txt');
+  }
+
+  describe(): string {
+    return this.root;
+  }
+
+  private async ensureDir() {
+    await fs.mkdir(this.root, { recursive: true });
+  }
+
+  async readTokens(): Promise<OAuthTokens | undefined> {
+    return readJsonFile<OAuthTokens>(this.tokenPath);
+  }
+
+  async saveTokens(tokens: OAuthTokens): Promise<void> {
+    await this.ensureDir();
+    await writeJsonFile(this.tokenPath, tokens);
+    this.logger?.debug?.(`Saved tokens to ${this.tokenPath}`);
+  }
+
+  async readClientInfo(): Promise<OAuthClientInformationMixed | undefined> {
+    return readJsonFile<OAuthClientInformationMixed>(this.clientInfoPath);
+  }
+
+  async saveClientInfo(info: OAuthClientInformationMixed): Promise<void> {
+    await this.ensureDir();
+    await writeJsonFile(this.clientInfoPath, info);
+  }
+
+  async readCodeVerifier(): Promise<string | undefined> {
+    try {
+      return (await fs.readFile(this.codeVerifierPath, 'utf8')).trim();
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return undefined;
+      }
+      throw error;
+    }
+  }
+
+  async saveCodeVerifier(value: string): Promise<void> {
+    await this.ensureDir();
+    await fs.writeFile(this.codeVerifierPath, value, 'utf8');
+  }
+
+  async readState(): Promise<string | undefined> {
+    return readJsonFile<string>(this.statePath);
+  }
+
+  async saveState(value: string): Promise<void> {
+    await this.ensureDir();
+    await writeJsonFile(this.statePath, value);
+  }
+
+  async clear(scope: OAuthClearScope): Promise<void> {
+    const files: string[] = [];
+    if (scope === 'all' || scope === 'tokens') {
+      files.push(this.tokenPath);
+    }
+    if (scope === 'all' || scope === 'client') {
+      files.push(this.clientInfoPath);
+    }
+    if (scope === 'all' || scope === 'verifier') {
+      files.push(this.codeVerifierPath);
+    }
+    if (scope === 'all' || scope === 'state') {
+      files.push(this.statePath);
+    }
+    await Promise.all(
+      files.map(async (file) => {
+        try {
+          await fs.unlink(file);
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+            throw error;
+          }
+        }
+      })
+    );
+  }
+}
+
+class VaultPersistence implements OAuthPersistence {
+  constructor(private readonly definition: ServerDefinition) {}
+
+  describe(): string {
+    return '~/.mcporter/credentials.json (vault)';
+  }
+
+  async readTokens(): Promise<OAuthTokens | undefined> {
+    return (await loadVaultEntry(this.definition))?.tokens;
+  }
+
+  async saveTokens(tokens: OAuthTokens): Promise<void> {
+    await saveVaultEntry(this.definition, { tokens });
+  }
+
+  async readClientInfo(): Promise<OAuthClientInformationMixed | undefined> {
+    return (await loadVaultEntry(this.definition))?.clientInfo;
+  }
+
+  async saveClientInfo(info: OAuthClientInformationMixed): Promise<void> {
+    await saveVaultEntry(this.definition, { clientInfo: info });
+  }
+
+  async readCodeVerifier(): Promise<string | undefined> {
+    return (await loadVaultEntry(this.definition))?.codeVerifier;
+  }
+
+  async saveCodeVerifier(value: string): Promise<void> {
+    await saveVaultEntry(this.definition, { codeVerifier: value });
+  }
+
+  async readState(): Promise<string | undefined> {
+    return (await loadVaultEntry(this.definition))?.state;
+  }
+
+  async saveState(value: string): Promise<void> {
+    await saveVaultEntry(this.definition, { state: value });
+  }
+
+  async clear(scope: OAuthClearScope): Promise<void> {
+    await clearVaultEntry(this.definition, scope);
+  }
+}
+
+class CompositePersistence implements OAuthPersistence {
+  constructor(private readonly stores: OAuthPersistence[]) {}
+
+  describe(): string {
+    return this.stores.map((store) => store.describe()).join(' + ');
+  }
+
+  async readTokens(): Promise<OAuthTokens | undefined> {
+    for (const store of this.stores) {
+      const result = await store.readTokens();
+      if (result) {
+        return result;
+      }
+    }
+    return undefined;
+  }
+
+  async saveTokens(tokens: OAuthTokens): Promise<void> {
+    await Promise.all(this.stores.map((store) => store.saveTokens(tokens)));
+  }
+
+  async readClientInfo(): Promise<OAuthClientInformationMixed | undefined> {
+    for (const store of this.stores) {
+      const result = await store.readClientInfo();
+      if (result) {
+        return result;
+      }
+    }
+    return undefined;
+  }
+
+  async saveClientInfo(info: OAuthClientInformationMixed): Promise<void> {
+    await Promise.all(this.stores.map((store) => store.saveClientInfo(info)));
+  }
+
+  async readCodeVerifier(): Promise<string | undefined> {
+    for (const store of this.stores) {
+      const result = await store.readCodeVerifier();
+      if (result) {
+        return result;
+      }
+    }
+    return undefined;
+  }
+
+  async saveCodeVerifier(value: string): Promise<void> {
+    await Promise.all(this.stores.map((store) => store.saveCodeVerifier(value)));
+  }
+
+  async readState(): Promise<string | undefined> {
+    for (const store of this.stores) {
+      const result = await store.readState();
+      if (result) {
+        return result;
+      }
+    }
+    return undefined;
+  }
+
+  async saveState(value: string): Promise<void> {
+    await Promise.all(this.stores.map((store) => store.saveState(value)));
+  }
+
+  async clear(scope: OAuthClearScope): Promise<void> {
+    await Promise.all(this.stores.map((store) => store.clear(scope)));
+  }
+}
+
+export async function buildOAuthPersistence(definition: ServerDefinition, logger?: Logger): Promise<OAuthPersistence> {
+  const vault = new VaultPersistence(definition);
+  const stores: OAuthPersistence[] = [vault];
+
+  if (definition.tokenCacheDir) {
+    stores.unshift(new DirectoryPersistence(definition.tokenCacheDir, logger));
+  }
+
+  // Migrate legacy default per-server cache (~/.mcporter/<name>) into the vault if present.
+  const legacyDir = path.join(os.homedir(), '.mcporter', definition.name);
+  if (!definition.tokenCacheDir && legacyDir) {
+    const legacy = new DirectoryPersistence(legacyDir, logger);
+    const legacyTokens = await legacy.readTokens();
+    const legacyClient = await legacy.readClientInfo();
+    const legacyVerifier = await legacy.readCodeVerifier();
+    const legacyState = await legacy.readState();
+    if (legacyTokens || legacyClient || legacyVerifier || legacyState) {
+      if (legacyTokens) {
+        await vault.saveTokens(legacyTokens);
+      }
+      if (legacyClient) {
+        await vault.saveClientInfo(legacyClient);
+      }
+      if (legacyVerifier) {
+        await vault.saveCodeVerifier(legacyVerifier);
+      }
+      if (legacyState) {
+        await vault.saveState(legacyState);
+      }
+      logger?.info?.(`Migrated legacy OAuth cache for '${definition.name}' into vault.`);
+    }
+  }
+
+  return stores.length === 1 ? vault : new CompositePersistence(stores);
+}
+
+export async function clearOAuthCaches(
+  definition: ServerDefinition,
+  logger?: Logger,
+  scope: OAuthClearScope = 'all'
+): Promise<void> {
+  const persistence = await buildOAuthPersistence(definition, logger);
+  await persistence.clear(scope);
+
+  const legacyDir = path.join(os.homedir(), '.mcporter', definition.name);
+  if (legacyDir && (!definition.tokenCacheDir || legacyDir !== definition.tokenCacheDir)) {
+    const legacy = new DirectoryPersistence(legacyDir, logger);
+    await legacy.clear(scope);
+  }
+
+  if (definition.tokenCacheDir) {
+    await fs.rm(definition.tokenCacheDir, { recursive: true, force: true });
+  }
+
+  // Known provider-specific legacy paths (gmail server writes to ~/.gmail-mcp/credentials.json).
+  const legacyFiles: string[] = [];
+  if (definition.name.toLowerCase() === 'gmail') {
+    legacyFiles.push(path.join(os.homedir(), '.gmail-mcp', 'credentials.json'));
+  }
+  await Promise.all(
+    legacyFiles.map(async (file) => {
+      try {
+        await fs.unlink(file);
+        logger?.info?.(`Cleared legacy OAuth cache file ${file}`);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+          throw error;
+        }
+      }
+    })
+  );
+}
+
+export async function readCachedAccessToken(
+  definition: ServerDefinition,
+  logger?: Logger
+): Promise<string | undefined> {
+  const persistence = await buildOAuthPersistence(definition, logger);
+  const tokens = await persistence.readTokens();
+  if (tokens && typeof tokens.access_token === 'string' && tokens.access_token.trim().length > 0) {
+    return tokens.access_token;
+  }
+  return undefined;
+}