@nimrobo/mcporter-remote 0.1.0

package/src/daemon/request-utils.ts

@@ -0,0 +1,67 @@
+import type { ServerDefinition } from '../config.js';
+import { keepAliveIdleTimeout } from '../lifecycle.js';
+import type { Runtime } from '../runtime.js';
+import type { DaemonResponse } from './protocol.js';
+
+export interface ServerActivity {
+  connected: boolean;
+  lastUsedAt?: number;
+}
+
+export function ensureManaged(server: string, managedServers: Map<string, ServerDefinition>): void {
+  if (!managedServers.has(server)) {
+    throw new Error(`Server '${server}' is not managed by the daemon.`);
+  }
+}
+
+export function markActivity(server: string, activity: Map<string, ServerActivity>): void {
+  const entry = activity.get(server);
+  if (entry) {
+    entry.connected = true;
+    entry.lastUsedAt = Date.now();
+  } else {
+    activity.set(server, { connected: true, lastUsedAt: Date.now() });
+  }
+}
+
+export async function evictIdleServers(
+  runtime: Runtime,
+  managedServers: Map<string, ServerDefinition>,
+  activity: Map<string, ServerActivity>
+): Promise<void> {
+  const now = Date.now();
+  await Promise.all(
+    Array.from(managedServers.entries()).map(async ([name, definition]) => {
+      const timeout = keepAliveIdleTimeout(definition);
+      if (!timeout) {
+        return;
+      }
+      const entry = activity.get(name);
+      if (!entry?.lastUsedAt) {
+        return;
+      }
+      if (now - entry.lastUsedAt < timeout) {
+        return;
+      }
+      await runtime.close(name).catch(() => {});
+      activity.set(name, { connected: false });
+    })
+  );
+}
+
+export function buildErrorResponse(id: string, code: string, error?: unknown): DaemonResponse {
+  let message = code;
+  if (error instanceof Error) {
+    message = error.message;
+  } else if (typeof error === 'string') {
+    message = error;
+  }
+  return {
+    id,
+    ok: false,
+    error: {
+      code,
+      message,
+    },
+  };
+}

package/src/daemon/runtime-wrapper.ts

@@ -0,0 +1,135 @@
+import type { ListResourcesRequest } from '@modelcontextprotocol/sdk/types.js';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import type { ServerDefinition } from '../config.js';
+import { isKeepAliveServer } from '../lifecycle.js';
+import type { CallOptions, ListToolsOptions, Runtime } from '../runtime.js';
+import type { DaemonClient } from './client.js';
+
+interface KeepAliveRuntimeOptions {
+  readonly daemonClient: DaemonClient | null;
+  readonly keepAliveServers: Set<string>;
+}
+
+export function createKeepAliveRuntime(base: Runtime, options: KeepAliveRuntimeOptions): Runtime {
+  if (!options.daemonClient || options.keepAliveServers.size === 0) {
+    return base;
+  }
+  return new KeepAliveRuntime(base, options.daemonClient, options.keepAliveServers);
+}
+
+class KeepAliveRuntime implements Runtime {
+  constructor(
+    private readonly base: Runtime,
+    private readonly daemon: DaemonClient,
+    private readonly keepAliveServers: Set<string>
+  ) {}
+
+  listServers(): string[] {
+    return this.base.listServers();
+  }
+
+  getDefinitions(): ServerDefinition[] {
+    return this.base.getDefinitions();
+  }
+
+  getDefinition(server: string): ServerDefinition {
+    return this.base.getDefinition(server);
+  }
+
+  registerDefinition(definition: ServerDefinition, options?: { overwrite?: boolean }): void {
+    this.base.registerDefinition(definition, options);
+    if (isKeepAliveServer(definition)) {
+      this.keepAliveServers.add(definition.name);
+    } else {
+      this.keepAliveServers.delete(definition.name);
+    }
+  }
+
+  async listTools(server: string, options?: ListToolsOptions): Promise<Awaited<ReturnType<Runtime['listTools']>>> {
+    if (this.shouldUseDaemon(server)) {
+      return (await this.invokeWithRestart(server, 'listTools', () =>
+        this.daemon.listTools({
+          server,
+          includeSchema: options?.includeSchema,
+          autoAuthorize: options?.autoAuthorize,
+        })
+      )) as Awaited<ReturnType<Runtime['listTools']>>;
+    }
+    return this.base.listTools(server, options);
+  }
+
+  async callTool(server: string, toolName: string, options?: CallOptions): Promise<unknown> {
+    if (this.shouldUseDaemon(server)) {
+      return this.invokeWithRestart(server, 'callTool', () =>
+        this.daemon.callTool({
+          server,
+          tool: toolName,
+          args: options?.args,
+          timeoutMs: options?.timeoutMs,
+        })
+      );
+    }
+    return this.base.callTool(server, toolName, options);
+  }
+
+  async listResources(server: string, options?: Partial<ListResourcesRequest['params']>): Promise<unknown> {
+    if (this.shouldUseDaemon(server)) {
+      return this.invokeWithRestart(server, 'listResources', () =>
+        this.daemon.listResources({ server, params: options ?? {} })
+      );
+    }
+    return this.base.listResources(server, options);
+  }
+
+  async connect(server: string): Promise<Awaited<ReturnType<Runtime['connect']>>> {
+    return this.base.connect(server);
+  }
+
+  async close(server?: string): Promise<void> {
+    if (!server) {
+      await this.base.close();
+      return;
+    }
+    if (this.shouldUseDaemon(server)) {
+      await this.daemon.closeServer({ server }).catch(() => {});
+      return;
+    }
+    await this.base.close(server);
+  }
+
+  private shouldUseDaemon(server: string): boolean {
+    return this.keepAliveServers.has(server);
+  }
+
+  private async invokeWithRestart<T>(server: string, operation: string, action: () => Promise<T>): Promise<T> {
+    try {
+      return await action();
+    } catch (error) {
+      if (!shouldRestartDaemonServer(error)) {
+        throw error;
+      }
+      // The daemon keeps STDIO transports warm; if a call fails due to a fatal error,
+      // force-close the cached server so the retry launches a fresh Chrome instance.
+      logDaemonRetry(server, operation, error);
+      await this.daemon.closeServer({ server }).catch(() => {});
+      return action();
+    }
+  }
+}
+
+const NON_FATAL_CODES = new Set([ErrorCode.InvalidRequest, ErrorCode.MethodNotFound, ErrorCode.InvalidParams]);
+
+function shouldRestartDaemonServer(error: unknown): boolean {
+  if (!error) {
+    return false;
+  }
+  if (error instanceof McpError) {
+    return !NON_FATAL_CODES.has(error.code);
+  }
+  return true;
+}
+
+function logDaemonRetry(server: string, operation: string, error: unknown): void {
+  const reason = error instanceof Error ? error.message : String(error);
+  console.log(`[mcporter] Restarting '${server}' before retrying ${operation}: ${reason}`);
+}

package/src/env.ts

@@ -0,0 +1,107 @@
+import os from 'node:os';
+
+const ENV_DEFAULT_PATTERN = /^\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-|:|-)?([^}]*)\}$/;
+const ENV_INTERPOLATION_PATTERN = /\\?\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+const ENV_DIRECT_PREFIX = '$env:';
+
+// expandHome replaces a leading '~' with the current user's home directory.
+export function expandHome(input: string): string {
+  if (!input.startsWith('~')) {
+    return input;
+  }
+  const home = os.homedir();
+  if (input === '~') {
+    return home;
+  }
+  if (input.startsWith('~/')) {
+    return `${home}/${input.slice(2)}`;
+  }
+  return input;
+}
+
+// resolveEnvValue interprets ${VAR:-default} syntax and other primitive values for env overrides.
+export function resolveEnvValue(raw: unknown): string {
+  if (typeof raw !== 'string') {
+    return String(raw);
+  }
+
+  const match = ENV_DEFAULT_PATTERN.exec(raw);
+  if (match) {
+    const envName = match[1];
+    const defaultValue = match[2] ?? '';
+    if (!envName) {
+      return raw;
+    }
+    const existing = process.env[envName];
+    if (existing && existing !== '') {
+      return existing;
+    }
+    return defaultValue;
+  }
+
+  if (raw.startsWith('$')) {
+    return resolveEnvPlaceholders(raw);
+  }
+
+  return raw;
+}
+
+// resolveEnvPlaceholders replaces ${VAR} or $env:VAR references using process.env, enforcing required values.
+export function resolveEnvPlaceholders(value: string): string {
+  if (value.startsWith(ENV_DIRECT_PREFIX)) {
+    const envName = value.slice(ENV_DIRECT_PREFIX.length);
+    const envValue = process.env[envName];
+    if (envValue === undefined) {
+      throw new Error(`Environment variable '${envName}' is required for MCP header substitution.`);
+    }
+    return envValue;
+  }
+
+  const missing = new Set<string>();
+  const replaced = value.replace(ENV_INTERPOLATION_PATTERN, (placeholder, envName: string) => {
+    const envValue = process.env[envName];
+    if (envValue === undefined) {
+      missing.add(envName);
+      return placeholder;
+    }
+    return envValue;
+  });
+
+  if (missing.size > 0) {
+    const names = [...missing].sort().join(', ');
+    throw new Error(`Environment variable(s) ${names} must be set for MCP header substitution.`);
+  }
+
+  return replaced;
+}
+
+// withEnvOverrides temporarily populates process.env keys while executing the provided callback.
+export async function withEnvOverrides<T>(
+  envOverrides: Record<string, string> | undefined,
+  fn: () => Promise<T> | T
+): Promise<T> {
+  if (!envOverrides || Object.keys(envOverrides).length === 0) {
+    return await fn();
+  }
+
+  const applied: string[] = [];
+  for (const [key, rawValue] of Object.entries(envOverrides)) {
+    if (process.env[key]) {
+      continue;
+    }
+    const resolved = resolveEnvValue(rawValue);
+    if (resolved === '') {
+      continue;
+    }
+    process.env[key] = resolved;
+    applied.push(key);
+  }
+
+  try {
+    return await fn();
+  } finally {
+    for (const key of applied) {
+      delete process.env[key];
+    }
+  }
+}

package/src/error-classifier.ts

@@ -0,0 +1,158 @@
+import { UnauthorizedError } from '@modelcontextprotocol/sdk/client/auth.js';
+
+export type ConnectionIssueKind = 'auth' | 'offline' | 'http' | 'stdio-exit' | 'other';
+
+export interface ConnectionIssue {
+  kind: ConnectionIssueKind;
+  rawMessage: string;
+  statusCode?: number;
+  stdioExitCode?: number;
+  stdioSignal?: string;
+}
+
+const AUTH_STATUSES = new Set([401, 403]);
+const OFFLINE_PATTERNS = [
+  'fetch failed',
+  'econnrefused',
+  'connection refused',
+  'connection closed',
+  'connection reset',
+  'socket hang up',
+  'connect timeout',
+  'network is unreachable',
+  'timed out',
+  'timeout',
+  'timeout after',
+  'getaddrinfo',
+  'enotfound',
+  'enoent',
+  'eai_again',
+  'econnaborted',
+  'ehostunreach',
+  'no such host',
+  'failed to start',
+  'spawn enoent',
+];
+const HTTP_STATUS_FALLBACK = /\bhttps?:\/\/[^\s]+(?:\s+returned\s+)?(?:status|code)?\s*(\d{3})\b/i;
+const STATUS_DIRECT_PATTERN = /\b(?:status(?:\s+code)?|http(?:\s+(?:status|code|error))?)[:\s]*(\d{3})\b/i;
+const STDIO_EXIT_PATTERN = /exit(?:ed)?(?:\s+with)?(?:\s+(?:code|status))\s+(-?\d+)/i;
+const STDIO_SIGNAL_PATTERN = /signal\s+([A-Z0-9]+)/i;
+
+export function analyzeConnectionError(error: unknown): ConnectionIssue {
+  const rawMessage = extractMessage(error);
+  if (error instanceof UnauthorizedError) {
+    return { kind: 'auth', rawMessage };
+  }
+  const stdio = extractStdioExit(rawMessage);
+  if (stdio) {
+    return { kind: 'stdio-exit', rawMessage, ...stdio };
+  }
+  const statusCode = extractStatusCode(rawMessage);
+  const normalized = rawMessage.toLowerCase();
+  if (AUTH_STATUSES.has(statusCode ?? -1) || containsAuthToken(normalized)) {
+    return { kind: 'auth', rawMessage, statusCode };
+  }
+  if (statusCode && statusCode >= 400) {
+    return { kind: 'http', rawMessage, statusCode };
+  }
+  if (OFFLINE_PATTERNS.some((pattern) => normalized.includes(pattern))) {
+    return { kind: 'offline', rawMessage };
+  }
+  return { kind: 'other', rawMessage };
+}
+
+export function isAuthIssue(issue: ConnectionIssue): boolean {
+  return issue.kind === 'auth';
+}
+
+function extractMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message ?? '';
+  }
+  if (typeof error === 'string') {
+    return error;
+  }
+  if (error === undefined || error === null) {
+    return '';
+  }
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return '';
+  }
+}
+
+function extractStatusCode(message: string): number | undefined {
+  const candidates = [
+    message.match(/status code\s*\((\d{3})\)/i)?.[1],
+    message.match(STATUS_DIRECT_PATTERN)?.[1],
+    message.match(HTTP_STATUS_FALLBACK)?.[1],
+  ].filter(Boolean) as string[];
+  for (const candidate of candidates) {
+    const parsed = Number.parseInt(candidate, 10);
+    if (Number.isFinite(parsed)) {
+      return parsed;
+    }
+  }
+  const trimmed = message.trim();
+  if (trimmed.startsWith('{')) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      const candidate = findStatusInObject(parsed);
+      if (typeof candidate === 'number') {
+        return candidate;
+      }
+      if (typeof candidate === 'string') {
+        const numeric = Number.parseInt(candidate, 10);
+        if (Number.isFinite(numeric)) {
+          return numeric;
+        }
+      }
+    } catch {
+      // fall through when the payload is not JSON
+    }
+  }
+  return undefined;
+}
+
+function containsAuthToken(normalizedMessage: string): boolean {
+  return (
+    normalizedMessage.includes('401') ||
+    normalizedMessage.includes('unauthorized') ||
+    normalizedMessage.includes('invalid_token') ||
+    normalizedMessage.includes('forbidden')
+  );
+}
+
+function extractStdioExit(message: string): { stdioExitCode?: number; stdioSignal?: string } | undefined {
+  if (!message.toLowerCase().includes('stdio') && !STDIO_EXIT_PATTERN.test(message)) {
+    return undefined;
+  }
+  const exitMatch = message.match(STDIO_EXIT_PATTERN);
+  const signalMatch = message.match(STDIO_SIGNAL_PATTERN);
+  if (!exitMatch && !signalMatch) {
+    return undefined;
+  }
+  const exitCode = exitMatch ? Number.parseInt(exitMatch[1] ?? '', 10) : undefined;
+  return {
+    stdioExitCode: Number.isFinite(exitCode) ? exitCode : undefined,
+    stdioSignal: signalMatch?.[1],
+  };
+}
+
+function findStatusInObject(value: unknown): unknown {
+  if (!value || typeof value !== 'object') {
+    return undefined;
+  }
+  const record = value as Record<string, unknown>;
+  if (typeof record.status === 'number' || typeof record.status === 'string') {
+    return record.status;
+  }
+  if (typeof record.code === 'number' || typeof record.code === 'string') {
+    return record.code;
+  }
+  if (typeof record.error === 'object' && record.error !== null) {
+    return findStatusInObject(record.error);
+  }
+  return undefined;
+}

package/src/fs-json.ts

@@ -0,0 +1,21 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+// readJsonFile reads a JSON file and returns undefined when the file does not exist.
+export async function readJsonFile<T = unknown>(filePath: string): Promise<T | undefined> {
+  try {
+    const content = await fs.readFile(filePath, 'utf8');
+    return JSON.parse(content) as T;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+// writeJsonFile writes a JSON object to disk, ensuring parent directories are created first.
+export async function writeJsonFile(filePath: string, data: unknown): Promise<void> {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, JSON.stringify(data, null, 2), 'utf8');
+}

package/src/generate-cli.ts

@@ -0,0 +1,211 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  bundleOutput,
+  compileBundleWithBun,
+  computeCompileTarget,
+  resolveBundleTarget,
+} from './cli/generate/artifacts.js';
+import { ensureInvocationDefaults, fetchTools, resolveServerDefinition } from './cli/generate/definition.js';
+import { resolveRuntimeKind } from './cli/generate/runtime.js';
+import { readPackageMetadata, writeTemplate } from './cli/generate/template.js';
+import type { ToolMetadata } from './cli/generate/tools.js';
+import { buildToolMetadata, toolsTestHelpers } from './cli/generate/tools.js';
+import { type CliArtifactMetadata, serializeDefinition } from './cli-metadata.js';
+import type { ServerToolInfo } from './runtime.js';
+
+export interface GenerateCliOptions {
+  readonly serverRef: string;
+  readonly configPath?: string;
+  readonly rootDir?: string;
+  readonly outputPath?: string;
+  readonly runtime?: 'node' | 'bun';
+  readonly bundler?: 'rolldown' | 'bun';
+  readonly bundle?: boolean | string;
+  readonly timeoutMs?: number;
+  readonly minify?: boolean;
+  readonly compile?: boolean | string;
+  readonly includeTools?: string[];
+  readonly excludeTools?: string[];
+}
+
+// generateCli produces a standalone CLI (and optional bundle/binary) for a given MCP server.
+export async function generateCli(
+  options: GenerateCliOptions
+): Promise<{ outputPath: string; bundlePath?: string; compilePath?: string }> {
+  const runtimeKind = await resolveRuntimeKind(options.runtime, options.compile);
+  const bundlerKind = options.bundler ?? (runtimeKind === 'bun' ? 'bun' : 'rolldown');
+  if (bundlerKind === 'bun' && runtimeKind !== 'bun') {
+    throw new Error('--bundler bun currently requires --runtime bun.');
+  }
+  const timeoutMs = options.timeoutMs ?? 30_000;
+  const { definition: baseDefinition, name } = await resolveServerDefinition(
+    options.serverRef,
+    options.configPath,
+    options.rootDir
+  );
+  const { tools: allTools, derivedDescription } = await fetchTools(
+    baseDefinition,
+    name,
+    options.configPath,
+    options.rootDir
+  );
+  const tools = applyToolFilters(allTools, options.includeTools, options.excludeTools);
+  const definition =
+    baseDefinition.description || !derivedDescription
+      ? baseDefinition
+      : { ...baseDefinition, description: derivedDescription };
+  const toolMetadata: ToolMetadata[] = tools.map((tool) => buildToolMetadata(tool));
+  const generator = await readPackageMetadata();
+  const baseInvocation = ensureInvocationDefaults(
+    {
+      serverRef: options.serverRef,
+      configPath: options.configPath,
+      rootDir: options.rootDir,
+      runtime: runtimeKind,
+      bundler: bundlerKind,
+      outputPath: options.outputPath,
+      bundle: options.bundle,
+      compile: options.compile,
+      timeoutMs,
+      minify: options.minify ?? false,
+      includeTools: options.includeTools,
+      excludeTools: options.excludeTools,
+    },
+    definition
+  );
+  const embeddedMetadata: CliArtifactMetadata = {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    generator,
+    server: {
+      name,
+      source: definition.source,
+      definition: serializeDefinition(definition),
+    },
+    artifact: {
+      path: '',
+      kind: 'template',
+    },
+    invocation: baseInvocation,
+  };
+
+  let templateTmpDir: string | undefined;
+  let templateOutputPath = options.outputPath;
+  if (!templateOutputPath && options.compile) {
+    const tmpPrefix = path.join(process.cwd(), 'tmp', 'mcporter-cli-');
+    await fs.mkdir(path.dirname(tmpPrefix), { recursive: true });
+    templateTmpDir = await fs.mkdtemp(tmpPrefix);
+    templateOutputPath = path.join(templateTmpDir, `${name}.ts`);
+  }
+
+  const outputPath = await writeTemplate({
+    outputPath: templateOutputPath,
+    runtimeKind,
+    timeoutMs,
+    definition,
+    serverName: name,
+    tools: toolMetadata,
+    generator,
+    metadata: embeddedMetadata,
+  });
+
+  let bundlePath: string | undefined;
+  let compilePath: string | undefined;
+
+  try {
+    const shouldBundle = Boolean(options.bundle ?? options.compile);
+    if (shouldBundle) {
+      const targetPath = resolveBundleTarget({
+        bundle: options.bundle,
+        compile: options.compile,
+        outputPath,
+      });
+      bundlePath = await bundleOutput({
+        sourcePath: outputPath,
+        runtimeKind,
+        targetPath,
+        minify: options.minify ?? false,
+        bundler: bundlerKind,
+      });
+
+      if (options.compile) {
+        if (runtimeKind !== 'bun') {
+          throw new Error('--compile is only supported when --runtime bun');
+        }
+        const compileTarget = computeCompileTarget(options.compile, bundlePath, name);
+        await compileBundleWithBun(bundlePath, compileTarget);
+        compilePath = compileTarget;
+        if (!options.bundle) {
+          await fs.rm(bundlePath).catch(() => {});
+          bundlePath = undefined;
+        }
+      }
+    }
+  } finally {
+    if (templateTmpDir) {
+      await fs.rm(templateTmpDir, { recursive: true, force: true }).catch(() => {});
+    }
+  }
+
+  return { outputPath: options.outputPath ?? outputPath, bundlePath, compilePath };
+}
+
+function applyToolFilters(tools: ServerToolInfo[], includeTools?: string[], excludeTools?: string[]): ServerToolInfo[] {
+  if (includeTools && excludeTools) {
+    throw new Error('Internal error: both includeTools and excludeTools provided to generateCli.');
+  }
+  if (includeTools && includeTools.length === 0) {
+    throw new Error('--include-tools requires at least one tool name.');
+  }
+  if (excludeTools && excludeTools.length === 0) {
+    throw new Error('--exclude-tools requires at least one tool name.');
+  }
+
+  if (!includeTools && !excludeTools) {
+    return tools;
+  }
+
+  const toolMap = new Map(tools.map((tool) => [tool.name, tool]));
+
+  if (includeTools && includeTools.length > 0) {
+    const result: ServerToolInfo[] = [];
+    const missing: string[] = [];
+
+    for (const name of includeTools) {
+      const match = toolMap.get(name);
+      if (match) {
+        result.push(match);
+      } else {
+        missing.push(name);
+      }
+    }
+
+    if (missing.length > 0) {
+      throw new Error(
+        `Requested tools not found on server: ${missing.join(', ')}. Available tools: ${tools.map((tool) => tool.name).join(', ')}`
+      );
+    }
+
+    if (result.length === 0) {
+      throw new Error('No tools remain after applying --include-tools filter.');
+    }
+
+    return result;
+  }
+
+  if (excludeTools && excludeTools.length > 0) {
+    const excludeSet = new Set(excludeTools);
+    const filtered = tools.filter((tool) => !excludeSet.has(tool.name));
+    if (filtered.length === 0) {
+      throw new Error(
+        `All tools were excluded. Exclude list: ${[...excludeSet].join(', ')}. Available tools: ${tools.map((tool) => tool.name).join(', ')}`
+      );
+    }
+    return filtered;
+  }
+
+  return tools;
+}
+
+export const __test = { ...toolsTestHelpers, applyToolFilters };