@nimrobo/mcporter-remote 0.1.0

package/src/cli/config/help.ts

@@ -0,0 +1,213 @@
+import { boldText, dimText, extraDimText } from '../terminal.js';
+import { printConfigUsageExamples } from './render.js';
+import { COLOR_ENABLED } from './shared.js';
+
+export type ConfigSubcommand = 'list' | 'get' | 'add' | 'remove' | 'import' | 'login' | 'logout' | 'doctor';
+
+export type ConfigHelpEntry = {
+  readonly name: string;
+  readonly summary: string;
+  readonly usage: string;
+  readonly description: string;
+  readonly flags?: Array<{ flag: string; description: string }>;
+  readonly examples?: string[];
+};
+
+export const CONFIG_HELP_ENTRIES: Record<ConfigSubcommand, ConfigHelpEntry> = {
+  list: {
+    name: 'list [options] [filter]',
+    summary: 'Show merged servers',
+    usage: 'mcporter config list [options] [filter]',
+    description: 'Lists configured servers. Defaults to local entries, but you can view imports and emit JSON.',
+    flags: [
+      { flag: '--json', description: 'Print JSON payloads instead of ANSI text.' },
+      { flag: '--source <local|import>', description: 'Filter to local definitions or imported entries only.' },
+      { flag: 'filter (positional)', description: 'Substring match applied to server names.' },
+    ],
+    examples: ['pnpm mcporter config list', 'pnpm mcporter config list --json --source import cursor'],
+  },
+  get: {
+    name: 'get <name> [--json]',
+    summary: 'Inspect a single server',
+    usage: 'mcporter config get <name> [--json]',
+    description: 'Shows one server definition, including transport, headers, and env overrides.',
+    flags: [{ flag: '--json', description: 'Emit the server entry as JSON.' }],
+    examples: ['pnpm mcporter config get linear', 'pnpm mcporter config get claude --json'],
+  },
+  add: {
+    name: 'add [options] <name> [target]',
+    summary: 'Persist a server definition',
+    usage: 'mcporter config add [options] <name> [target]',
+    description:
+      'Adds HTTP or stdio servers to the local config. Accepts URLs, commands, env vars, and OAuth metadata.',
+    flags: [
+      { flag: '--url <https://host>', description: 'Set the HTTP/S base URL (implies http transport).' },
+      { flag: '--command <binary>', description: 'Set the stdio executable (implies stdio transport).' },
+      { flag: '--stdio <binary>', description: 'Alias for --command.' },
+      { flag: '--transport <http|sse|stdio>', description: 'Force a specific transport (validates target).' },
+      { flag: '--arg <value>', description: 'Pass through additional stdio arguments (repeatable).' },
+      { flag: '--description <text>', description: 'Set a human-friendly summary.' },
+      { flag: '--env KEY=value', description: 'Attach environment variables (repeatable).' },
+      { flag: '--header KEY=value', description: 'Attach HTTP headers (repeatable).' },
+      { flag: '--token-cache-dir <path>', description: 'Override where OAuth tokens are persisted.' },
+      { flag: '--client-name <name>', description: 'Customize the OAuth client identifier.' },
+      { flag: '--oauth-redirect-url <url>', description: 'Set a custom OAuth redirect URL.' },
+      { flag: '--auth <strategy>', description: 'Force the auth type (e.g., oauth).' },
+      { flag: '--copy-from <import:name>', description: 'Start with an imported definition by name.' },
+      { flag: '--persist <config-path>', description: 'Write to an alternate mcporter.json path.' },
+      {
+        flag: '--scope <home|project>',
+        description: 'Choose whether to write to the home or project config (default: project).',
+      },
+      { flag: '--dry-run', description: 'Print the would-be entry without writing to disk.' },
+      { flag: '--', description: 'Forward every subsequent token as a stdio arg.' },
+    ],
+    examples: [
+      'pnpm mcporter config add linear https://mcp.linear.app/mcp',
+      'pnpm mcporter config add cursor --command "npx -y cursor" --arg --stdio',
+    ],
+  },
+  remove: {
+    name: 'remove <name>',
+    summary: 'Delete a local entry',
+    usage: 'mcporter config remove <name>',
+    description: 'Removes a server definition from the active mcporter.json file.',
+    examples: ['pnpm mcporter config remove linear'],
+  },
+  import: {
+    name: 'import <kind> [options]',
+    summary: 'Inspect or copy imported servers',
+    usage: 'mcporter config import <kind> [options]',
+    description:
+      'Shows entries from Cursor, Claude, Codex, and other supported imports. Optionally copies them locally.',
+    flags: [
+      { flag: '--path <file>', description: 'Manually point at a config file path.' },
+      { flag: '--filter <substring>', description: 'Match server names by substring before listing/copying.' },
+      { flag: '--copy', description: 'Write the filtered entries into the local config.' },
+      { flag: '--json', description: 'Emit JSON instead of plain text listings.' },
+    ],
+    examples: ['pnpm mcporter config import cursor --copy', 'pnpm mcporter config import claude --filter notion'],
+  },
+  login: {
+    name: 'login <name|url> [options]',
+    summary: 'Run the OAuth/auth flow',
+    usage: 'mcporter config login <name|url> [options]',
+    description: 'Delegates to `mcporter auth`, so you can pass ephemeral flags like --http-url/--stdio/--reset.',
+    examples: ['pnpm mcporter config login linear', 'pnpm mcporter config login https://example.com/mcp --reset'],
+  },
+  logout: {
+    name: 'logout <name>',
+    summary: 'Clear cached credentials',
+    usage: 'mcporter config logout <name>',
+    description: 'Deletes the token cache directory for an OAuth-enabled server.',
+    examples: ['pnpm mcporter config logout linear'],
+  },
+  doctor: {
+    name: 'doctor',
+    summary: 'Validate config files',
+    usage: 'mcporter config doctor',
+    description: 'Validates config files, warns about missing token caches, and prints config locations.',
+    examples: ['pnpm mcporter config doctor'],
+  },
+};
+
+export const CONFIG_HELP_ORDER: ConfigSubcommand[] = [
+  'list',
+  'get',
+  'add',
+  'remove',
+  'import',
+  'login',
+  'logout',
+  'doctor',
+];
+
+export function isHelpToken(token: string): boolean {
+  return token === '--help' || token === '-h';
+}
+
+export function consumeInlineHelpTokens(args: string[]): boolean {
+  let found = false;
+  for (let index = args.length - 1; index >= 0; index -= 1) {
+    const token = args[index];
+    if (token && isHelpToken(token)) {
+      args.splice(index, 1);
+      found = true;
+    }
+  }
+  return found;
+}
+
+export function printConfigHelp(subcommand?: string): void {
+  const colorize = COLOR_ENABLED();
+  if (!subcommand) {
+    printConfigOverview(colorize);
+    return;
+  }
+  const resolved = resolveHelpSubcommand(subcommand);
+  if (!resolved) {
+    console.log(`Unknown config subcommand '${subcommand}'. Available commands: ${CONFIG_HELP_ORDER.join(', ')}.`);
+    return;
+  }
+  printSubcommandHelp(resolved, colorize);
+}
+
+function resolveHelpSubcommand(token: string | undefined): ConfigSubcommand | undefined {
+  if (!token) {
+    return undefined;
+  }
+  const normalized = token.toLowerCase() as ConfigSubcommand;
+  return normalized in CONFIG_HELP_ENTRIES ? normalized : undefined;
+}
+
+function printConfigOverview(colorize: boolean): void {
+  const title = colorize ? boldText('mcporter config') : 'mcporter config';
+  const subtitle = colorize
+    ? dimText('Manage configured MCP servers, imports, and ad-hoc discoveries.')
+    : 'Manage configured MCP servers, imports, and ad-hoc discoveries.';
+  const commandsHeader = colorize ? boldText('Commands') : 'Commands';
+  const examplesHeader = colorize ? boldText('Examples') : 'Examples';
+  const lines: string[] = [title, subtitle, '', commandsHeader];
+  const maxName = Math.max(...CONFIG_HELP_ORDER.map((key) => CONFIG_HELP_ENTRIES[key].name.length));
+  for (const key of CONFIG_HELP_ORDER) {
+    const entry = CONFIG_HELP_ENTRIES[key];
+    const padded = entry.name.padEnd(maxName);
+    const renderedName = colorize ? boldText(padded) : padded;
+    const renderedDesc = colorize ? dimText(entry.summary) : entry.summary;
+    lines.push(`  ${renderedName}  ${renderedDesc}`);
+  }
+  lines.push('', examplesHeader);
+  for (const example of printConfigUsageExamples()) {
+    lines.push(`  ${colorize ? extraDimText(example) : example}`);
+  }
+  const pointer = "Run 'mcporter config <command> --help' for detailed flag info.";
+  lines.push('', colorize ? extraDimText(pointer) : pointer);
+  console.log(lines.join('\n'));
+}
+
+function printSubcommandHelp(subcommand: ConfigSubcommand, colorize: boolean): void {
+  const entry = CONFIG_HELP_ENTRIES[subcommand];
+  const title = colorize ? boldText(`mcporter config ${subcommand}`) : `mcporter config ${subcommand}`;
+  const description = colorize ? dimText(entry.description) : entry.description;
+  const usageHeader = colorize ? boldText('Usage') : 'Usage';
+  const lines: string[] = [title, description, '', usageHeader, `  ${entry.usage}`];
+  if (entry.flags && entry.flags.length > 0) {
+    const flagsHeader = colorize ? boldText('Flags') : 'Flags';
+    const maxFlag = Math.max(...entry.flags.map((flag) => flag.flag.length));
+    lines.push('', flagsHeader);
+    for (const flag of entry.flags) {
+      const padded = flag.flag.padEnd(maxFlag);
+      const renderedFlag = colorize ? boldText(padded) : padded;
+      const renderedDesc = colorize ? dimText(flag.description) : flag.description;
+      lines.push(`  ${renderedFlag}  ${renderedDesc}`);
+    }
+  }
+  if (entry.examples && entry.examples.length > 0) {
+    const examplesHeader = colorize ? boldText('Examples') : 'Examples';
+    lines.push('', examplesHeader);
+    for (const example of entry.examples) {
+      lines.push(`  ${colorize ? extraDimText(example) : example}`);
+    }
+  }
+  console.log(lines.join('\n'));
+}

package/src/cli/config/import.ts

@@ -0,0 +1,97 @@
+import path from 'node:path';
+import type { RawEntry } from '../../config.js';
+import { writeRawConfig } from '../../config.js';
+import { pathsForImport, readExternalEntries } from '../../config-imports.js';
+import { expandHome } from '../../env.js';
+import { CliUsageError } from '../errors.js';
+import { cloneConfig, loadOrCreateConfig } from './shared.js';
+import type { ConfigCliOptions } from './types.js';
+
+export interface ImportFlags {
+  path?: string;
+  filter?: string;
+  copy?: boolean;
+  format: 'text' | 'json';
+}
+
+export async function handleImportCommand(options: ConfigCliOptions, args: string[]): Promise<void> {
+  const kind = args.shift();
+  if (!kind) {
+    throw new CliUsageError('Usage: mcporter config import <kind>');
+  }
+  const flags = extractImportFlags(args);
+  const rootDir = options.loadOptions.rootDir ?? process.cwd();
+  const paths = flags.path ? [path.resolve(expandHome(flags.path))] : pathsForImport(kind as never, rootDir);
+  const entries: Array<{ name: string; entry: RawEntry; source: string }> = [];
+  const seenNames = new Set<string>();
+  for (const candidate of paths) {
+    const resolved = expandHome(candidate);
+    const map = await readExternalEntries(resolved, { projectRoot: rootDir, importKind: kind as never });
+    if (!map) {
+      continue;
+    }
+    for (const [name, entry] of map) {
+      if (flags.filter && !name.includes(flags.filter)) {
+        continue;
+      }
+      if (seenNames.has(name)) {
+        continue;
+      }
+      seenNames.add(name);
+      entries.push({ name, entry, source: resolved });
+    }
+  }
+  if (entries.length === 0) {
+    console.log('No entries found.');
+    return;
+  }
+  if (flags.format === 'json') {
+    console.log(JSON.stringify({ entries }, null, 2));
+  } else {
+    for (const item of entries) {
+      console.log(`${item.name} (${item.source})`);
+    }
+  }
+  if (flags.copy) {
+    const { config, path: configPath } = await loadOrCreateConfig(options.loadOptions);
+    const nextConfig = cloneConfig(config);
+    if (!nextConfig.mcpServers) {
+      nextConfig.mcpServers = {};
+    }
+    for (const item of entries) {
+      nextConfig.mcpServers[item.name] = structuredClone(item.entry);
+    }
+    await writeRawConfig(configPath, nextConfig);
+    console.log(`Copied ${entries.length} entr${entries.length === 1 ? 'y' : 'ies'} to ${configPath}`);
+  }
+}
+
+function extractImportFlags(args: string[]): ImportFlags {
+  const flags: ImportFlags = { format: 'text' };
+  let index = 0;
+  while (index < args.length) {
+    const token = args[index];
+    switch (token) {
+      case '--path':
+        flags.path = args[index + 1];
+        args.splice(index, 2);
+        continue;
+      case '--filter':
+        flags.filter = args[index + 1];
+        args.splice(index, 2);
+        continue;
+      case '--copy':
+        flags.copy = true;
+        args.splice(index, 1);
+        continue;
+      case '--json':
+        flags.format = 'json';
+        args.splice(index, 1);
+        continue;
+      default:
+        index += 1;
+        break;
+    }
+  }
+  return flags;
+}

package/src/cli/config/index.ts

@@ -0,0 +1 @@
+export { __configCommandInternals, handleConfigCli } from '../config-command.js';

package/src/cli/config/list.ts

@@ -0,0 +1,81 @@
+import { loadServerDefinitions } from '../../config.js';
+import type { ServerDefinition } from '../../config-schema.js';
+import { CliUsageError } from '../errors.js';
+import { dimText } from '../terminal.js';
+import { printImportSummary, printServerSummary, serializeDefinition } from './render.js';
+import { COLOR_ENABLED, logConfigLocations, resolveConfigLocations } from './shared.js';
+import type { ConfigCliOptions } from './types.js';
+
+export interface ListFlags {
+  format: 'text' | 'json';
+  source?: 'local' | 'import';
+}
+
+export async function handleListCommand(options: ConfigCliOptions, args: string[]): Promise<void> {
+  const flags = extractListFlags(args);
+  const filter = args.shift();
+  const servers = await loadServerDefinitions(options.loadOptions);
+  let filtered = servers;
+  if (flags.source) {
+    filtered = filtered.filter((server) => (server.source?.kind ?? 'local') === flags.source);
+  }
+  if (filter) {
+    filtered = filtered.filter((server) => filterMatches(filter, server));
+  }
+  if (flags.format === 'json') {
+    const payload = filtered.map((server) => serializeDefinition(server));
+    console.log(JSON.stringify({ servers: payload }, null, 2));
+    return;
+  }
+  const colorize = COLOR_ENABLED();
+  if (filtered.length === 0) {
+    console.log(
+      colorize
+        ? dimText('No local servers match the provided filters.')
+        : 'No local servers match the provided filters.'
+    );
+  } else {
+    for (const server of filtered) {
+      printServerSummary(server);
+    }
+  }
+  if ((!flags.source || flags.source === 'local') && flags.format === 'text') {
+    printImportSummary(servers.filter((server) => server.source?.kind === 'import'));
+  }
+  if (flags.format === 'text') {
+    const summary = await resolveConfigLocations(options.loadOptions);
+    logConfigLocations(summary, { leadingNewline: true });
+  }
+}
+
+function extractListFlags(args: string[]): ListFlags {
+  const flags: ListFlags = { format: 'text', source: 'local' };
+  let index = 0;
+  while (index < args.length) {
+    const token = args[index];
+    if (token === '--json') {
+      flags.format = 'json';
+      args.splice(index, 1);
+      continue;
+    }
+    if (token === '--source') {
+      const value = args[index + 1];
+      if (value !== 'local' && value !== 'import') {
+        throw new CliUsageError("--source must be either 'local' or 'import'.");
+      }
+      flags.source = value;
+      args.splice(index, 2);
+      continue;
+    }
+    index += 1;
+  }
+  return flags;
+}
+
+function filterMatches(filter: string, server: ServerDefinition): boolean {
+  if (filter.startsWith('source:')) {
+    const origin = server.source?.kind ?? 'local';
+    return `source:${origin}` === filter;
+  }
+  return server.name.includes(filter);
+}

package/src/cli/config/remove.ts

@@ -0,0 +1,20 @@
+import { writeRawConfig } from '../../config.js';
+import { CliUsageError } from '../errors.js';
+import { cloneConfig, findServerNameWithFuzzyMatch, loadOrCreateConfig } from './shared.js';
+import type { ConfigCliOptions } from './types.js';
+
+export async function handleRemoveCommand(options: ConfigCliOptions, args: string[]): Promise<void> {
+  const name = args.shift();
+  if (!name) {
+    throw new CliUsageError('Usage: mcporter config remove <name>');
+  }
+  const { config, path: configPath } = await loadOrCreateConfig(options.loadOptions);
+  const targetName = findServerNameWithFuzzyMatch(name, Object.keys(config.mcpServers ?? {}));
+  if (!targetName) {
+    throw new CliUsageError(`Server '${name}' does not exist in ${configPath}.`);
+  }
+  const nextConfig = cloneConfig(config);
+  delete nextConfig.mcpServers[targetName];
+  await writeRawConfig(configPath, nextConfig);
+  console.log(`Removed '${targetName}' from ${configPath}`);
+}

package/src/cli/config/render.ts

@@ -0,0 +1,119 @@
+import type { ServerDefinition } from '../../config-schema.js';
+import { boldText, dimText } from '../terminal.js';
+import { COLOR_ENABLED } from './shared.js';
+
+export type SerializedServerDefinition = {
+  name: string;
+  description?: string;
+  source: NonNullable<ServerDefinition['source']> | { kind: 'local'; path: string };
+  auth?: ServerDefinition['auth'];
+  tokenCacheDir?: string;
+  clientName?: string;
+  oauthRedirectUrl?: string;
+  oauthScope?: string;
+  env?: Record<string, string>;
+  transport: 'http' | 'stdio';
+  baseUrl?: string;
+  headers?: Record<string, string>;
+  command?: string;
+  args?: string[];
+  cwd?: string;
+};
+
+export function serializeDefinition(definition: ServerDefinition): SerializedServerDefinition {
+  const origin = definition.source ?? { kind: 'local', path: '' };
+  if (definition.command.kind === 'http') {
+    return {
+      name: definition.name,
+      description: definition.description,
+      source: origin,
+      auth: definition.auth,
+      tokenCacheDir: definition.tokenCacheDir,
+      clientName: definition.clientName,
+      oauthRedirectUrl: definition.oauthRedirectUrl,
+      oauthScope: definition.oauthScope,
+      env: definition.env,
+      transport: 'http',
+      baseUrl: definition.command.url.href,
+      headers: definition.command.headers,
+    };
+  }
+  return {
+    name: definition.name,
+    description: definition.description,
+    source: origin,
+    auth: definition.auth,
+    tokenCacheDir: definition.tokenCacheDir,
+    clientName: definition.clientName,
+    oauthRedirectUrl: definition.oauthRedirectUrl,
+    oauthScope: definition.oauthScope,
+    env: definition.env,
+    transport: 'stdio',
+    command: definition.command.command,
+    args: definition.command.args,
+    cwd: definition.command.cwd,
+  };
+}
+
+export function printServerSummary(definition: ServerDefinition): void {
+  const colorize = COLOR_ENABLED();
+  const origin = definition.source;
+  const header = colorize ? boldText(definition.name) : definition.name;
+  const label = (text: string): string => (colorize ? dimText(text) : text);
+  console.log(header);
+  if (origin) {
+    console.log(`  ${label('Source')}: ${origin.kind}${origin.path ? ` (${origin.path})` : ''}`);
+  } else {
+    console.log(`  ${label('Source')}: local`);
+  }
+  if (definition.command.kind === 'http') {
+    console.log(`  ${label('Transport')}: http (${definition.command.url.href})`);
+  } else {
+    const renderedArgs = definition.command.args.length > 0 ? ` ${definition.command.args.join(' ')}` : '';
+    console.log(`  ${label('Transport')}: stdio (${definition.command.command}${renderedArgs})`);
+    console.log(`  ${label('CWD')}: ${definition.command.cwd}`);
+  }
+  if (definition.description) {
+    console.log(`  ${label('Description')}: ${definition.description}`);
+  }
+  if (definition.auth === 'oauth') {
+    console.log(`  ${label('Auth')}: oauth`);
+  }
+}
+
+export function printImportSummary(importServers: ServerDefinition[]): void {
+  if (importServers.length === 0) {
+    return;
+  }
+  const colorize = COLOR_ENABLED();
+  const grouped = new Map<string, string[]>();
+  for (const server of importServers) {
+    const sourcePath = server.source?.path ?? '<unknown>';
+    const list = grouped.get(sourcePath) ?? [];
+    list.push(server.name);
+    grouped.set(sourcePath, list);
+  }
+  console.log('');
+  const header = colorize
+    ? boldText('Other sources available via --source import')
+    : 'Other sources available via --source import';
+  console.log(header);
+  for (const [path, names] of grouped) {
+    names.sort();
+    const sample = names.slice(0, 3).join(', ');
+    const suffix = names.length > 3 ? ', …' : '';
+    const countLabel = `${names.length} server${names.length === 1 ? '' : 's'}`;
+    const pathLabel = colorize ? dimText(path) : path;
+    console.log(`  ${pathLabel} — ${countLabel} (${sample}${suffix})`);
+  }
+  const guidance = 'Use `mcporter config import <kind>` to copy them locally.';
+  console.log(colorize ? dimText(guidance) : guidance);
+}
+
+export function printConfigUsageExamples(): string[] {
+  return [
+    'pnpm mcporter config list --json',
+    'pnpm mcporter config add linear https://mcp.linear.app/mcp',
+    'pnpm mcporter config import cursor --copy',
+  ];
+}