@nimrobo/mcporter-remote 0.1.0

package/src/config-normalize.ts

@@ -0,0 +1,220 @@
+import type { CommandSpec, RawEntry, ServerDefinition, ServerLoggingOptions, ServerSource } from './config-schema.js';
+import { expandHome } from './env.js';
+import { resolveLifecycle } from './lifecycle.js';
+
+export function normalizeServerEntry(
+  name: string,
+  raw: RawEntry,
+  baseDir: string,
+  source: ServerSource,
+  sources: readonly ServerSource[]
+): ServerDefinition {
+  const description = raw.description;
+  const env = raw.env ? { ...raw.env } : undefined;
+  const auth = normalizeAuth(raw.auth);
+  const tokenCacheDir = normalizePath(raw.tokenCacheDir ?? raw.token_cache_dir);
+  const clientName = raw.clientName ?? raw.client_name;
+  const oauthRedirectUrl = raw.oauthRedirectUrl ?? raw.oauth_redirect_url ?? undefined;
+  const oauthScope = raw.oauthScope ?? raw.oauth_scope ?? undefined;
+  const oauthCommandRaw = raw.oauthCommand ?? raw.oauth_command;
+  const oauthCommand = oauthCommandRaw ? { args: [...oauthCommandRaw.args] } : undefined;
+  const headers = buildHeaders(raw);
+
+  const httpUrl = getUrl(raw);
+  const stdio = getCommand(raw);
+
+  let command: CommandSpec;
+
+  if (httpUrl) {
+    command = {
+      kind: 'http',
+      url: new URL(httpUrl),
+      headers: ensureHttpAcceptHeader(headers),
+    };
+  } else if (stdio) {
+    command = {
+      kind: 'stdio',
+      command: stdio.command,
+      args: stdio.args,
+      cwd: baseDir,
+    };
+  } else {
+    throw new Error(`Server '${name}' is missing a baseUrl/url or command definition in mcporter.json`);
+  }
+
+  const lifecycle = resolveLifecycle(name, raw.lifecycle, command);
+  const logging = normalizeLogging(raw.logging);
+
+  const defaultedOauthCommand =
+    !oauthCommand && name.toLowerCase() === 'gmail' && command.kind === 'stdio'
+      ? { args: ['auth', 'http://localhost:3000/oauth2callback'] }
+      : oauthCommand;
+
+  return {
+    name,
+    description,
+    command,
+    env,
+    auth,
+    tokenCacheDir,
+    clientName,
+    oauthRedirectUrl,
+    oauthScope,
+    oauthCommand: defaultedOauthCommand,
+    source,
+    sources,
+    lifecycle,
+    logging,
+  };
+}
+
+export const __configInternals = {
+  ensureHttpAcceptHeader,
+};
+
+function normalizeAuth(auth: string | undefined): string | undefined {
+  if (!auth) {
+    return undefined;
+  }
+  if (auth.toLowerCase() === 'oauth') {
+    return 'oauth';
+  }
+  return undefined;
+}
+
+function normalizePath(input: string | undefined): string | undefined {
+  if (!input) {
+    return undefined;
+  }
+  return expandHome(input);
+}
+
+function getUrl(raw: RawEntry): string | undefined {
+  return raw.baseUrl ?? raw.base_url ?? raw.url ?? raw.serverUrl ?? raw.server_url ?? undefined;
+}
+
+function getCommand(raw: RawEntry): { command: string; args: string[] } | undefined {
+  const commandValue = raw.command ?? raw.executable;
+  if (Array.isArray(commandValue)) {
+    if (commandValue.length === 0 || typeof commandValue[0] !== 'string') {
+      return undefined;
+    }
+    return { command: commandValue[0], args: commandValue.slice(1) };
+  }
+  if (typeof commandValue === 'string' && commandValue.length > 0) {
+    const args = Array.isArray(raw.args) ? raw.args : [];
+    if (args.length > 0) {
+      return { command: commandValue, args };
+    }
+    const tokens = parseCommandString(commandValue);
+    if (tokens.length === 0) {
+      return undefined;
+    }
+    const [commandToken, ...rest] = tokens;
+    if (!commandToken) {
+      return undefined;
+    }
+    return { command: commandToken, args: rest };
+  }
+  return undefined;
+}
+
+function buildHeaders(raw: RawEntry): Record<string, string> | undefined {
+  const headers: Record<string, string> = {};
+
+  if (raw.headers) {
+    Object.assign(headers, raw.headers);
+  }
+
+  const bearerToken = raw.bearerToken ?? raw.bearer_token;
+  if (bearerToken) {
+    headers.Authorization = `Bearer ${bearerToken}`;
+  }
+
+  const bearerTokenEnv = raw.bearerTokenEnv ?? raw.bearer_token_env;
+  if (bearerTokenEnv) {
+    headers.Authorization = `$env:${bearerTokenEnv}`;
+  }
+
+  return Object.keys(headers).length > 0 ? headers : undefined;
+}
+
+function ensureHttpAcceptHeader(headers?: Record<string, string>): Record<string, string> | undefined {
+  const requiredAccept = 'application/json, text/event-stream';
+  const normalized = headers ? { ...headers } : {};
+  const acceptKey = Object.keys(normalized).find((key) => key.toLowerCase() === 'accept');
+  const currentValue = acceptKey ? normalized[acceptKey] : undefined;
+  if (!currentValue || !hasRequiredAcceptTokens(currentValue)) {
+    normalized[acceptKey ?? 'accept'] = requiredAccept;
+  }
+  return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+
+function hasRequiredAcceptTokens(value: string): boolean {
+  const lower = value.toLowerCase();
+  return lower.includes('application/json') && lower.includes('text/event-stream');
+}
+
+function parseCommandString(value: string): string[] {
+  const result: string[] = [];
+  let current = '';
+  let inSingleQuote = false;
+  let inDoubleQuote = false;
+  let escapeNext = false;
+
+  for (const char of value.trim()) {
+    if (escapeNext) {
+      current += char;
+      escapeNext = false;
+      continue;
+    }
+
+    if (char === '\\') {
+      escapeNext = true;
+      continue;
+    }
+
+    if (char === "'" && !inDoubleQuote) {
+      inSingleQuote = !inSingleQuote;
+      continue;
+    }
+
+    if (char === '"' && !inSingleQuote) {
+      inDoubleQuote = !inDoubleQuote;
+      continue;
+    }
+
+    if (char === ' ' && !inSingleQuote && !inDoubleQuote) {
+      if (current.length > 0) {
+        result.push(current);
+        current = '';
+      }
+      continue;
+    }
+
+    current += char;
+  }
+
+  if (escapeNext) {
+    current += '\\';
+  }
+
+  if (current.length > 0) {
+    result.push(current);
+  }
+
+  return result;
+}
+
+export { ensureHttpAcceptHeader };
+
+function normalizeLogging(raw?: { daemon?: { enabled?: boolean } }): ServerLoggingOptions | undefined {
+  if (!raw) {
+    return undefined;
+  }
+  if (raw.daemon) {
+    const logging: ServerLoggingOptions = { daemon: { enabled: raw.daemon.enabled } };
+    return logging;
+  }
+  return undefined;
+}

package/src/config-schema.ts

@@ -0,0 +1,175 @@
+import { z } from 'zod';
+
+export const ImportKindSchema = z
+  .enum(['cursor', 'claude-code', 'claude-desktop', 'codex', 'windsurf', 'opencode', 'vscode'])
+  .describe('Supported editor/client configurations to import MCP servers from');
+
+export type ImportKind = z.infer<typeof ImportKindSchema>;
+
+export const DEFAULT_IMPORTS: ImportKind[] = [
+  'cursor',
+  'claude-code',
+  'claude-desktop',
+  'codex',
+  'windsurf',
+  'opencode',
+  'vscode',
+];
+
+const RawLifecycleSchema = z
+  .union([
+    z.literal('keep-alive').describe('Keep the server connection alive'),
+    z.literal('ephemeral').describe('Connect only when needed'),
+    z.object({
+      mode: z.union([z.literal('keep-alive'), z.literal('ephemeral')]).describe('Connection lifecycle mode'),
+      idleTimeoutMs: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Idle timeout in milliseconds before disconnecting'),
+    }),
+  ])
+  .describe('Server connection lifecycle: keep-alive maintains persistent connections, ephemeral connects on-demand');
+
+export type RawLifecycle = z.infer<typeof RawLifecycleSchema>;
+
+const RawLoggingSchema = z
+  .object({
+    daemon: z
+      .object({
+        enabled: z.boolean().optional().describe('Enable daemon logging for this server'),
+      })
+      .optional()
+      .describe('Daemon-specific logging configuration'),
+  })
+  .optional()
+  .describe('Logging configuration for the server');
+
+export const RawEntrySchema = z
+  .object({
+    description: z.string().optional().describe('Human-readable description of the server'),
+    baseUrl: z.string().optional().describe('Base URL for HTTP/SSE transport (camelCase)'),
+    base_url: z.string().optional().describe('Base URL for HTTP/SSE transport (snake_case)'),
+    url: z.string().optional().describe('Server URL for HTTP/SSE transport'),
+    serverUrl: z.string().optional().describe('Server URL for HTTP/SSE transport (camelCase)'),
+    server_url: z.string().optional().describe('Server URL for HTTP/SSE transport (snake_case)'),
+    command: z
+      .union([z.string(), z.array(z.string())])
+      .optional()
+      .describe('Command to spawn for stdio transport (string or array of arguments)'),
+    executable: z.string().optional().describe('Executable path for stdio transport'),
+    args: z.array(z.string()).optional().describe('Arguments to pass to the stdio command'),
+    headers: z
+      .record(z.string(), z.string())
+      .optional()
+      .describe('HTTP headers for requests. Supports $VAR and $env:VAR placeholders'),
+    env: z
+      .record(z.string(), z.string())
+      .optional()
+      .describe('Environment variables for stdio commands. Supports $VAR and fallback syntax'),
+    auth: z.string().optional().describe('Authentication method (e.g., "oauth")'),
+    tokenCacheDir: z.string().optional().describe('Directory for caching OAuth tokens (camelCase)'),
+    token_cache_dir: z.string().optional().describe('Directory for caching OAuth tokens (snake_case)'),
+    clientName: z.string().optional().describe('Client identifier for server telemetry (camelCase)'),
+    client_name: z.string().optional().describe('Client identifier for server telemetry (snake_case)'),
+    oauthRedirectUrl: z.string().optional().describe('Custom OAuth redirect URL (camelCase)'),
+    oauth_redirect_url: z.string().optional().describe('Custom OAuth redirect URL (snake_case)'),
+    oauthScope: z.string().optional().describe('OAuth scope override (camelCase)'),
+    oauth_scope: z.string().optional().describe('OAuth scope override (snake_case)'),
+    oauthCommand: z
+      .object({
+        args: z.array(z.string()).describe('Arguments for the OAuth command'),
+      })
+      .optional()
+      .describe('Custom OAuth command configuration for stdio servers (camelCase)'),
+    oauth_command: z
+      .object({
+        args: z.array(z.string()).describe('Arguments for the OAuth command'),
+      })
+      .optional()
+      .describe('Custom OAuth command configuration for stdio servers (snake_case)'),
+    bearerToken: z.string().optional().describe('Static bearer token for authentication (camelCase)'),
+    bearer_token: z.string().optional().describe('Static bearer token for authentication (snake_case)'),
+    bearerTokenEnv: z.string().optional().describe('Environment variable name containing the bearer token (camelCase)'),
+    bearer_token_env: z
+      .string()
+      .optional()
+      .describe('Environment variable name containing the bearer token (snake_case)'),
+    lifecycle: RawLifecycleSchema.optional(),
+    logging: RawLoggingSchema,
+  })
+  .describe('MCP server definition supporting both HTTP/SSE and stdio transports');
+
+export const RawConfigSchema = z
+  .object({
+    mcpServers: z.record(z.string(), RawEntrySchema).describe('Map of server names to their configurations'),
+    imports: z
+      .array(ImportKindSchema)
+      .optional()
+      .describe('Editor configurations to import servers from. Omit to use defaults, or set to [] to disable imports'),
+  })
+  .describe('mcporter configuration file schema');
+
+export type RawEntry = z.infer<typeof RawEntrySchema>;
+export type RawConfig = z.infer<typeof RawConfigSchema>;
+
+export interface HttpCommand {
+  readonly kind: 'http';
+  readonly url: URL;
+  readonly headers?: Record<string, string>;
+}
+
+export interface StdioCommand {
+  readonly kind: 'stdio';
+  readonly command: string;
+  readonly args: string[];
+  readonly cwd: string;
+}
+
+export type CommandSpec = HttpCommand | StdioCommand;
+
+export interface ServerSource {
+  readonly kind: 'local' | 'import';
+  readonly path: string;
+  readonly importKind?: ImportKind;
+}
+
+export type ServerLifecycle =
+  | {
+      mode: 'keep-alive';
+      idleTimeoutMs?: number;
+    }
+  | {
+      mode: 'ephemeral';
+    };
+
+export interface ServerLoggingOptions {
+  readonly daemon?: {
+    readonly enabled?: boolean;
+  };
+}
+
+export interface ServerDefinition {
+  readonly name: string;
+  readonly description?: string;
+  readonly command: CommandSpec;
+  readonly env?: Record<string, string>;
+  readonly auth?: string;
+  readonly tokenCacheDir?: string;
+  readonly clientName?: string;
+  readonly oauthRedirectUrl?: string;
+  readonly oauthScope?: string;
+  readonly oauthCommand?: {
+    readonly args: string[];
+  };
+  readonly source?: ServerSource;
+  readonly sources?: readonly ServerSource[];
+  readonly lifecycle?: ServerLifecycle;
+  readonly logging?: ServerLoggingOptions;
+}
+
+export interface LoadConfigOptions {
+  readonly configPath?: string;
+  readonly rootDir?: string;
+}

package/src/config.ts

@@ -0,0 +1,136 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  listConfigLayerPaths as discoverConfigLayerPaths,
+  resolveConfigPath as discoverConfigPath,
+} from './config/path-discovery.js';
+import { loadConfigLayers, readConfigFile } from './config/read-config.js';
+import { pathsForImport, readExternalEntries } from './config-imports.js';
+import { normalizeServerEntry } from './config-normalize.js';
+import {
+  DEFAULT_IMPORTS,
+  type LoadConfigOptions,
+  type RawConfig,
+  type RawEntry,
+  RawEntrySchema,
+  type ServerDefinition,
+  type ServerSource,
+} from './config-schema.js';
+import { expandHome } from './env.js';
+
+export { toFileUrl } from './config-imports.js';
+export { __configInternals } from './config-normalize.js';
+export type {
+  CommandSpec,
+  HttpCommand,
+  LoadConfigOptions,
+  RawConfig,
+  RawEntry,
+  ServerDefinition,
+  ServerLifecycle,
+  ServerLoggingOptions,
+  ServerSource,
+  StdioCommand,
+} from './config-schema.js';
+
+export async function loadServerDefinitions(options: LoadConfigOptions = {}): Promise<ServerDefinition[]> {
+  const rootDir = options.rootDir ?? process.cwd();
+  const layers = await loadConfigLayers(options, rootDir);
+
+  const merged = new Map<string, { raw: RawEntry; baseDir: string; source: ServerSource; sources: ServerSource[] }>();
+
+  for (const layer of layers) {
+    const configuredImports = layer.config.imports;
+    const imports = configuredImports
+      ? configuredImports.length === 0
+        ? configuredImports
+        : [...configuredImports, ...DEFAULT_IMPORTS.filter((kind) => !configuredImports.includes(kind))]
+      : DEFAULT_IMPORTS;
+
+    for (const importKind of imports) {
+      const candidates = pathsForImport(importKind, rootDir);
+      for (const candidate of candidates) {
+        const resolved = expandHome(candidate);
+        const entries = await readExternalEntries(resolved, { projectRoot: rootDir, importKind: importKind });
+        if (!entries) {
+          continue;
+        }
+        for (const [name, rawEntry] of entries) {
+          if (merged.has(name)) {
+            continue;
+          }
+          const source: ServerSource = { kind: 'import', path: resolved, importKind };
+          const existing = merged.get(name);
+          // Keep the first-seen source as canonical while tracking all alternates
+          if (existing) {
+            existing.sources.push(source);
+            continue;
+          }
+          merged.set(name, {
+            raw: rawEntry,
+            baseDir: path.dirname(resolved),
+            source,
+            sources: [source],
+          });
+        }
+      }
+    }
+
+    for (const [name, entryRaw] of Object.entries(layer.config.mcpServers)) {
+      const source: ServerSource = { kind: 'local', path: layer.path };
+      const parsed = RawEntrySchema.parse(entryRaw);
+      const existing = merged.get(name);
+      // Local definitions win; stash any prior imports after the local path
+      if (existing) {
+        const sources = [source, ...existing.sources];
+        merged.set(name, { raw: parsed, baseDir: path.dirname(layer.path), source, sources });
+        continue;
+      }
+      merged.set(name, {
+        raw: parsed,
+        baseDir: path.dirname(layer.path),
+        source,
+        sources: [source],
+      });
+    }
+  }
+
+  const servers: ServerDefinition[] = [];
+  for (const [name, { raw, baseDir: entryBaseDir, source, sources }] of merged) {
+    servers.push(normalizeServerEntry(name, raw, entryBaseDir, source, sources));
+  }
+
+  return servers;
+}
+
+export async function loadRawConfig(
+  options: LoadConfigOptions = {}
+): Promise<{ config: RawConfig; path: string; explicit: boolean }> {
+  const rootDir = options.rootDir ?? process.cwd();
+  const resolved = resolveConfigPath(options.configPath, rootDir);
+  const config = await readConfigFile(resolved.path, resolved.explicit);
+  return { config, ...resolved };
+}
+
+export async function listConfigLayerPaths(
+  options: LoadConfigOptions = {},
+  rootDir: string = process.cwd()
+): Promise<string[]> {
+  return await discoverConfigLayerPaths(options, rootDir);
+}
+
+export async function writeRawConfig(targetPath: string, config: RawConfig): Promise<void> {
+  await fs.mkdir(path.dirname(targetPath), { recursive: true });
+  const serialized = `${JSON.stringify(config, null, 2)}\n`;
+  await fs.writeFile(targetPath, serialized, 'utf8');
+}
+
+export function resolveConfigPath(
+  configPath: string | undefined,
+  rootDir: string
+): {
+  path: string;
+  explicit: boolean;
+} {
+  return discoverConfigPath(configPath, rootDir);
+}