@nimrobo/mcporter-remote 0.1.0

package/src/cli/generate/tools.ts

@@ -0,0 +1,354 @@
+import type { ServerToolInfo } from '../../runtime.js';
+
+export interface ToolMetadata {
+  tool: ServerToolInfo;
+  methodName: string;
+  options: GeneratedOption[];
+}
+
+export interface GeneratedOption {
+  property: string;
+  cliName: string;
+  description?: string;
+  required: boolean;
+  type: 'string' | 'number' | 'boolean' | 'array' | 'unknown';
+  arrayItemType?: 'string' | 'number' | 'boolean' | 'unknown';
+  placeholder: string;
+  exampleValue?: string;
+  enumValues?: string[];
+  defaultValue?: unknown;
+  formatHint?: string;
+}
+
+export function buildToolMetadata(tool: ServerToolInfo): ToolMetadata {
+  const methodName = toProxyMethodName(tool.name);
+  const properties = extractOptions(tool);
+  return {
+    tool,
+    methodName,
+    options: properties,
+  };
+}
+
+export function buildEmbeddedSchemaMap(tools: ToolMetadata[]): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const entry of tools) {
+    if (entry.tool.inputSchema && typeof entry.tool.inputSchema === 'object') {
+      result[entry.tool.name] = entry.tool.inputSchema;
+    }
+  }
+  return result;
+}
+
+export function extractOptions(tool: ServerToolInfo): GeneratedOption[] {
+  const schema = tool.inputSchema;
+  if (!schema || typeof schema !== 'object') {
+    return [];
+  }
+  const record = schema as Record<string, unknown>;
+  if (record.type !== 'object' || typeof record.properties !== 'object') {
+    return [];
+  }
+  // Flatten schema properties into Commander-friendly option descriptors.
+  const properties = record.properties as Record<string, unknown>;
+  const requiredList = Array.isArray(record.required) ? (record.required as string[]) : [];
+  return Object.entries(properties).map(([property, descriptor]) => {
+    const type = inferType(descriptor);
+    const arrayItemType = type === 'array' ? inferArrayItemType(descriptor) : undefined;
+    const enumValues = getEnumValues(descriptor);
+    const defaultValue = getDescriptorDefault(descriptor);
+    const formatInfo = getDescriptorFormatHint(descriptor);
+    const placeholder = buildPlaceholder(property, type, enumValues, formatInfo?.slug);
+    const exampleValue = buildExampleValue(property, type, enumValues, defaultValue);
+    return {
+      property,
+      cliName: toCliOption(property),
+      description: getDescriptorDescription(descriptor),
+      required: requiredList.includes(property),
+      type,
+      arrayItemType,
+      placeholder,
+      exampleValue,
+      enumValues,
+      defaultValue,
+      formatHint: formatInfo?.display,
+    };
+  });
+}
+
+export function getEnumValues(descriptor: unknown): string[] | undefined {
+  if (!descriptor || typeof descriptor !== 'object') {
+    return undefined;
+  }
+  const record = descriptor as Record<string, unknown>;
+  if (Array.isArray(record.enum)) {
+    const values = record.enum.filter((entry): entry is string => typeof entry === 'string');
+    return values.length > 0 ? values : undefined;
+  }
+  if (record.type === 'array' && typeof record.items === 'object' && record.items !== null) {
+    const nested = record.items as Record<string, unknown>;
+    if (Array.isArray(nested.enum)) {
+      const values = nested.enum.filter((entry): entry is string => typeof entry === 'string');
+      return values.length > 0 ? values : undefined;
+    }
+  }
+  return undefined;
+}
+
+export function getDescriptorDefault(descriptor: unknown): unknown {
+  if (!descriptor || typeof descriptor !== 'object') {
+    return undefined;
+  }
+  const record = descriptor as Record<string, unknown>;
+  if (record.default !== undefined) {
+    return record.default;
+  }
+  if (record.type === 'array' && typeof record.items === 'object' && record.items !== null) {
+    return Array.isArray(record.default) ? record.default : undefined;
+  }
+  return undefined;
+}
+
+export function buildPlaceholder(
+  property: string,
+  type: GeneratedOption['type'],
+  enumValues?: string[],
+  formatSlug?: string
+): string {
+  const normalized = property.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`).replace(/_/g, '-');
+  if (enumValues && enumValues.length > 0) {
+    return `<${normalized}:${enumValues.join('|')}>`;
+  }
+  switch (type) {
+    case 'number':
+      return `<${normalized}:number>`;
+    case 'boolean':
+      return `<${normalized}:true|false>`;
+    case 'array':
+      return `<${normalized}:value1,value2>`;
+    default:
+      if (formatSlug) {
+        return `<${normalized}:${formatSlug}>`;
+      }
+      return `<${normalized ?? 'value'}>`;
+  }
+}
+
+export function buildExampleValue(
+  property: string,
+  type: GeneratedOption['type'],
+  enumValues: string[] | undefined,
+  defaultValue: unknown
+): string | undefined {
+  if (enumValues && enumValues.length > 0) {
+    return enumValues[0] as string;
+  }
+  if (defaultValue !== undefined) {
+    try {
+      return typeof defaultValue === 'string' ? defaultValue : JSON.stringify(defaultValue);
+    } catch {
+      return undefined;
+    }
+  }
+  switch (type) {
+    case 'number':
+      return '1';
+    case 'boolean':
+      return 'true';
+    case 'array':
+      return 'value1,value2';
+    default:
+      if (property.toLowerCase().includes('path')) {
+        return '/path/to/file.md';
+      }
+      if (property.toLowerCase().includes('id')) {
+        return 'example-id';
+      }
+      return undefined;
+  }
+}
+
+export function pickExampleLiteral(option: GeneratedOption): string | undefined {
+  if (option.enumValues && option.enumValues.length > 0) {
+    return JSON.stringify(option.enumValues[0]);
+  }
+  if (!option.exampleValue) {
+    return undefined;
+  }
+  if (option.type === 'array') {
+    const values = option.exampleValue
+      .split(',')
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+    if (values.length === 0) {
+      return undefined;
+    }
+    return `[${values.map((entry) => JSON.stringify(entry)).join(', ')}]`;
+  }
+  if (option.type === 'number' || option.type === 'boolean') {
+    return option.exampleValue;
+  }
+  try {
+    const parsed = JSON.parse(option.exampleValue);
+    if (typeof parsed === 'number' || typeof parsed === 'boolean') {
+      return option.exampleValue;
+    }
+  } catch {
+    // fall through to quoted string literal
+  }
+  return JSON.stringify(option.exampleValue);
+}
+
+export function buildFallbackLiteral(option: GeneratedOption): string {
+  switch (option.type) {
+    case 'number':
+      return '1';
+    case 'boolean':
+      return 'true';
+    case 'array':
+      return '["value1"]';
+    default: {
+      if (option.property.toLowerCase().includes('id')) {
+        return JSON.stringify('example-id');
+      }
+      if (option.property.toLowerCase().includes('url')) {
+        return JSON.stringify('https://example.com');
+      }
+      return JSON.stringify('value');
+    }
+  }
+}
+
+export function inferType(descriptor: unknown): GeneratedOption['type'] {
+  if (!descriptor || typeof descriptor !== 'object') {
+    return 'unknown';
+  }
+  const type = (descriptor as Record<string, unknown>).type;
+  const resolveType = (value: unknown): GeneratedOption['type'] | undefined => {
+    if (value === 'integer') {
+      return 'number';
+    }
+    if (value === 'string' || value === 'number' || value === 'boolean' || value === 'array') {
+      return value;
+    }
+    return undefined;
+  };
+  if (Array.isArray(type)) {
+    for (const entry of type) {
+      const resolved = resolveType(entry);
+      if (resolved) {
+        return resolved;
+      }
+    }
+    return 'unknown';
+  }
+  const resolved = resolveType(type);
+  if (resolved) {
+    return resolved;
+  }
+  return 'unknown';
+}
+
+export function inferArrayItemType(descriptor: unknown): GeneratedOption['arrayItemType'] {
+  if (!descriptor || typeof descriptor !== 'object') {
+    return 'unknown';
+  }
+  const record = descriptor as Record<string, unknown>;
+  if (record.type !== 'array' || !record.items || typeof record.items !== 'object') {
+    return 'unknown';
+  }
+  const items = record.items as Record<string, unknown>;
+  const itemType = items.type;
+  const resolveItemType = (value: unknown): GeneratedOption['arrayItemType'] | undefined => {
+    if (value === 'integer') {
+      return 'number';
+    }
+    if (value === 'string' || value === 'number' || value === 'boolean') {
+      return value;
+    }
+    return undefined;
+  };
+  if (Array.isArray(itemType)) {
+    for (const entry of itemType) {
+      const resolved = resolveItemType(entry);
+      if (resolved) {
+        return resolved;
+      }
+    }
+    return 'unknown';
+  }
+  const resolved = resolveItemType(itemType);
+  if (resolved) {
+    return resolved;
+  }
+  return 'unknown';
+}
+
+export function getDescriptorDescription(descriptor: unknown): string | undefined {
+  if (typeof descriptor !== 'object' || descriptor === null) {
+    return undefined;
+  }
+  const record = descriptor as Record<string, unknown>;
+  return typeof record.description === 'string' ? (record.description as string) : undefined;
+}
+
+export function getDescriptorFormatHint(descriptor: unknown): { display: string; slug: string } | undefined {
+  if (typeof descriptor !== 'object' || descriptor === null) {
+    return undefined;
+  }
+  const record = descriptor as Record<string, unknown>;
+  const formatRaw = typeof record.format === 'string' ? record.format : undefined;
+  const description = typeof record.description === 'string' ? record.description : undefined;
+
+  const iso8601FromDescription =
+    !formatRaw && description && /\biso[-\s]*8601\b/i.test(description) ? 'iso-8601' : undefined;
+  const isoFormatFromDescription =
+    !formatRaw && !iso8601FromDescription && description && /\biso\s+format\b/i.test(description)
+      ? 'iso-8601'
+      : undefined;
+
+  const formatFromDescription = iso8601FromDescription ?? isoFormatFromDescription;
+
+  const slug = formatRaw ?? formatFromDescription;
+  if (!slug) {
+    return undefined;
+  }
+
+  let display: string;
+  switch (slug) {
+    case 'date-time':
+    case 'iso-8601':
+      display = 'ISO 8601';
+      break;
+    case 'uuid':
+      display = 'UUID';
+      break;
+    default:
+      display = slug.replace(/[_-]/g, ' ');
+      display = display.charAt(0).toUpperCase() + display.slice(1);
+      break;
+  }
+  return {
+    display: display.replace(/\b\w/g, (char) => char.toUpperCase()),
+    slug,
+  };
+}
+
+export function toProxyMethodName(toolName: string): string {
+  return toolName
+    .replace(/[-_](\w)/g, (_, char: string) => char.toUpperCase())
+    .replace(/^(\w)/, (match) => match.toLowerCase());
+}
+
+export function toCliOption(property: string): string {
+  return property.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`).replace(/_/g, '-');
+}
+
+export const toolsTestHelpers = {
+  getEnumValues,
+  getDescriptorDefault,
+  buildPlaceholder,
+  buildExampleValue,
+  pickExampleLiteral,
+  buildFallbackLiteral,
+};

package/src/cli/generate/types.ts

@@ -0,0 +1 @@
+export type CommandInput = { command: string; args?: string[] } | string;

package/src/cli/generate-cli-runner.ts

@@ -0,0 +1,82 @@
+import { readCliMetadata } from '../cli-metadata.js';
+import type { FlagMap } from './flag-utils.js';
+import { parseGenerateFlags } from './generate/flags.js';
+import { inferNameFromCommand } from './generate/name-utils.js';
+import { performGenerateFromArtifact, performGenerateFromRequest } from './generate/output.js';
+import { buildInlineServerDefinition } from './generate/server-utils.js';
+import { buildGenerateCliCommand, resolveGenerateRequestFromArtifact } from './generate/template-data.js';
+
+// handleGenerateCli parses flags and generates the requested standalone CLI.
+export async function handleGenerateCli(args: string[], globalFlags: FlagMap): Promise<void> {
+  const parsed = parseGenerateFlags(args);
+  if (parsed.includeTools && parsed.excludeTools) {
+    throw new Error('--include-tools and --exclude-tools cannot be used together.');
+  }
+  if (parsed.includeTools && parsed.includeTools.length === 0) {
+    throw new Error('--include-tools requires at least one tool name.');
+  }
+  if (parsed.excludeTools && parsed.excludeTools.length === 0) {
+    throw new Error('--exclude-tools requires at least one tool name.');
+  }
+  if (parsed.from && (parsed.command || parsed.description || parsed.name)) {
+    throw new Error('--from cannot be combined with --command/--description/--name.');
+  }
+  if (parsed.dryRun && !parsed.from) {
+    throw new Error('--dry-run currently requires --from <artifact>.');
+  }
+
+  if (parsed.from) {
+    const metadata = await readCliMetadata(parsed.from);
+    const request = resolveGenerateRequestFromArtifact(parsed, metadata, globalFlags);
+    if (parsed.dryRun) {
+      const command = buildGenerateCliCommand(
+        {
+          serverRef: request.serverRef,
+          configPath: request.configPath,
+          rootDir: request.rootDir,
+          outputPath: request.outputPath,
+          bundle: request.bundle,
+          compile: request.compile,
+          runtime: request.runtime ?? 'node',
+          timeoutMs: request.timeoutMs ?? 30_000,
+          minify: request.minify ?? false,
+          includeTools: request.includeTools,
+          excludeTools: request.excludeTools,
+        },
+        metadata.server.definition,
+        globalFlags
+      );
+      console.log('Dry run — would execute:');
+      console.log(`  ${command}`);
+      return;
+    }
+    await performGenerateFromArtifact(metadata, request);
+    return;
+  }
+
+  const inferredName = parsed.name ?? (parsed.command ? inferNameFromCommand(parsed.command) : undefined);
+  const serverRef =
+    parsed.server ??
+    (parsed.command && inferredName
+      ? JSON.stringify(buildInlineServerDefinition(inferredName, parsed.command, parsed.description))
+      : undefined);
+  if (!serverRef) {
+    throw new Error(
+      'Provide --server with a definition or a command we can infer a name from (use --name to override).'
+    );
+  }
+  await performGenerateFromRequest({
+    serverRef,
+    configPath: globalFlags['--config'],
+    rootDir: globalFlags['--root'],
+    outputPath: parsed.output,
+    runtime: parsed.runtime,
+    bundler: parsed.bundler,
+    bundle: parsed.bundle,
+    timeoutMs: parsed.timeout,
+    compile: parsed.compile,
+    minify: parsed.minify ?? false,
+    includeTools: parsed.includeTools,
+    excludeTools: parsed.excludeTools,
+  });
+}

package/src/cli/help-output.ts

@@ -0,0 +1,207 @@
+import fsPromises from 'node:fs/promises';
+import { MCPORTER_VERSION } from '../runtime.js';
+import { boldText, dimText, extraDimText, supportsAnsiColor } from './terminal.js';
+
+type HelpEntry = {
+  name: string;
+  summary: string;
+  usage: string;
+};
+
+type HelpSection = {
+  title: string;
+  entries: HelpEntry[];
+};
+
+export function printHelp(message?: string): void {
+  if (message) {
+    console.error(message);
+    console.error('');
+  }
+  const colorize = supportsAnsiColor;
+  const sections = buildCommandSections(colorize);
+  const globalFlags = formatGlobalFlags(colorize);
+  const quickStart = formatQuickStart(colorize);
+  const footer = formatHelpFooter(colorize);
+  const title = colorize
+    ? `${boldText('mcporter')} ${dimText('— Model Context Protocol CLI & generator')}`
+    : 'mcporter — Model Context Protocol CLI & generator';
+  const lines = [
+    title,
+    '',
+    'Usage: mcporter <command> [options]',
+    '',
+    ...sections,
+    '',
+    globalFlags,
+    '',
+    quickStart,
+    '',
+    footer,
+  ];
+  console.error(lines.join('\n'));
+}
+
+function buildCommandSections(colorize: boolean): string[] {
+  const sections: HelpSection[] = [
+    {
+      title: 'Core commands',
+      entries: [
+        {
+          name: 'list',
+          summary: 'List configured servers (add --schema for tool docs)',
+          usage: 'mcporter list [name] [--schema] [--json]',
+        },
+        {
+          name: 'call',
+          summary: 'Call a tool by selector (server.tool) or HTTP URL; key=value flags supported',
+          usage: 'mcporter call <selector> [key=value ...]',
+        },
+        {
+          name: 'auth',
+          summary: 'Complete OAuth for a server without listing tools',
+          usage: 'mcporter auth <server | url> [--reset]',
+        },
+      ],
+    },
+    {
+      title: 'Generator & tooling',
+      entries: [
+        {
+          name: 'generate-cli',
+          summary: 'Emit a standalone CLI (supports HTTP, stdio, and inline commands)',
+          usage: 'mcporter generate-cli --server <name> | --command <ref> [options]',
+        },
+        {
+          name: 'inspect-cli',
+          summary: 'Show metadata and regen instructions for a generated CLI',
+          usage: 'mcporter inspect-cli <path> [--json]',
+        },
+        {
+          name: 'emit-ts',
+          summary: 'Generate TypeScript client/types for a server',
+          usage: 'mcporter emit-ts <server> --mode client|types [options]',
+        },
+      ],
+    },
+    {
+      title: 'Configuration',
+      entries: [
+        {
+          name: 'config',
+          summary: 'Inspect or edit config files (list, get, add, remove, import, login, logout)',
+          usage: 'mcporter config <command> [options]',
+        },
+      ],
+    },
+    {
+      title: 'Daemon',
+      entries: [
+        {
+          name: 'daemon',
+          summary: 'Manage the keep-alive daemon (start | status | stop | restart)',
+          usage: 'mcporter daemon <subcommand>',
+        },
+      ],
+    },
+  ];
+  return sections.flatMap((section) => formatCommandSection(section, colorize));
+}
+
+function formatCommandSection(section: HelpSection, colorize: boolean): string[] {
+  const maxNameLength = Math.max(...section.entries.map((entry) => entry.name.length));
+  const header = colorize ? boldText(section.title) : section.title;
+  const lines = [header];
+  section.entries.forEach((entry) => {
+    const paddedName = entry.name.padEnd(maxNameLength);
+    const renderedName = colorize ? boldText(paddedName) : paddedName;
+    const summary = colorize ? dimText(entry.summary) : entry.summary;
+    lines.push(`  ${renderedName}  ${summary}`);
+    lines.push(`    ${extraDimText('usage:')} ${entry.usage}`);
+  });
+  return [...lines, ''];
+}
+
+function formatGlobalFlags(colorize: boolean): string {
+  const title = colorize ? boldText('Global flags') : 'Global flags';
+  const entries = [
+    {
+      flag: '--config <path>',
+      summary: 'Path to mcporter.json (defaults to ./config/mcporter.json)',
+    },
+    {
+      flag: '--root <path>',
+      summary: 'Working directory for stdio servers',
+    },
+    {
+      flag: '--log-level <debug|info|warn|error>',
+      summary: 'Adjust CLI logging (defaults to warn)',
+    },
+    {
+      flag: '--oauth-timeout <ms>',
+      summary: 'Time to wait for browser-based OAuth before giving up (default 60000)',
+    },
+  ];
+  const formatted = entries.map((entry) => `  ${entry.flag.padEnd(34)}${entry.summary}`);
+  return [title, ...formatted].join('\n');
+}
+
+function formatQuickStart(colorize: boolean): string {
+  const title = colorize ? boldText('Quick start') : 'Quick start';
+  const entries = [
+    ['mcporter list', 'show configured servers'],
+    ['mcporter list linear --schema', 'view Linear tool docs'],
+    ['mcporter call linear.list_issues limit:5', 'invoke a tool with key=value arguments'],
+    ['mcporter generate-cli --command https://host/mcp --compile ./my-cli', 'build a standalone CLI/binary'],
+  ];
+  const formatted = entries.map(([cmd, note]) => {
+    const comment = colorize ? dimText(`# ${note}`) : `# ${note}`;
+    return `  ${cmd}\n    ${comment}`;
+  });
+  return [title, ...formatted].join('\n');
+}
+
+function formatHelpFooter(colorize: boolean): string {
+  const pointer = 'Run `mcporter <command> --help` for detailed flags.';
+  const autoLoad =
+    'mcporter auto-loads servers from ./config/mcporter.json and editor imports (Cursor, Claude, Codex, etc.).';
+  if (!colorize) {
+    return `${pointer}\n${autoLoad}`;
+  }
+  return `${dimText(pointer)}\n${extraDimText(autoLoad)}`;
+}
+
+export function isHelpToken(token: string): boolean {
+  return token === '--help' || token === '-h' || token === 'help';
+}
+
+export function consumeHelpTokens(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 isVersionToken(token: string): boolean {
+  return token === '--version' || token === '-v' || token === '-V';
+}
+
+export async function printVersion(): Promise<void> {
+  console.log(await resolveCliVersion());
+}
+
+async function resolveCliVersion(): Promise<string> {
+  try {
+    const packageJsonPath = new URL('../../package.json', import.meta.url);
+    const buffer = await fsPromises.readFile(packageJsonPath, 'utf8');
+    const pkg = JSON.parse(buffer) as { version?: string };
+    return pkg.version ?? MCPORTER_VERSION;
+  } catch {
+    return MCPORTER_VERSION;
+  }
+}