@stackkedjohn/mcp-factory-cli 0.1.0

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@stackkedjohn/mcp-factory-cli",
+  "version": "0.1.0",
+  "description": "Generate production-ready MCP servers from API documentation",
+  "type": "module",
+  "main": "dist/cli.js",
+  "bin": {
+    "mcp-factory": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node --test dist/**/*.test.js",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "api",
+    "codegen",
+    "cli",
+    "model-context-protocol",
+    "openapi",
+    "swagger",
+    "code-generation"
+  ],
+  "author": "John Lohr",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/StackkedJohn/mcp-factory.git"
+  },
+  "homepage": "https://github.com/StackkedJohn/mcp-factory#readme",
+  "bugs": {
+    "url": "https://github.com/StackkedJohn/mcp-factory/issues"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.72.1",
+    "commander": "^14.0.3",
+    "handlebars": "^4.7.8",
+    "yaml": "^2.8.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { createCommand } from './commands/create.js';
+import { validateCommand } from './commands/validate.js';
+import { listCommand } from './commands/list.js';
+import { installCommand } from './commands/install.js';
+
+const program = new Command();
+
+program
+  .name('mcp-factory')
+  .description('Generate production-ready MCP servers from API documentation')
+  .version('0.1.0');
+
+program
+  .command('create')
+  .description('Generate MCP server from API documentation')
+  .argument('<input>', 'Path to API spec file or URL')
+  .option('--ai-parse', 'Use AI to parse unstructured documentation')
+  .option('-o, --output <dir>', 'Output directory for generated server')
+  .action(createCommand);
+
+program
+  .command('validate')
+  .description('Validate API specification without generating code')
+  .argument('<input>', 'Path to API spec file')
+  .action(validateCommand);
+
+program
+  .command('list')
+  .description('List all generated MCP servers')
+  .action(listCommand);
+
+program
+  .command('install')
+  .description('Install MCP server to Claude Desktop/Code configuration')
+  .argument('<server-name>', 'Name of the server to install')
+  .action(installCommand);
+
+program.parse();

package/src/commands/create.ts

@@ -0,0 +1,65 @@
+import * as path from 'path';
+import { detectFormat } from '../parsers/detector.js';
+import { parseOpenAPI } from '../parsers/openapi.js';
+import { parsePostman } from '../parsers/postman.js';
+import { parseWithAI } from '../parsers/ai-parser.js';
+import { analyzePatterns } from '../generator/analyzer.js';
+import { generateServer } from '../generator/engine.js';
+import { addServer } from '../registry/manager.js';
+import { logger } from '../utils/logger.js';
+import { ParseError } from '../utils/errors.js';
+
+export async function createCommand(
+  input: string,
+  options: { aiParse?: boolean; output?: string }
+): Promise<void> {
+  try {
+    logger.info(`Detecting format for: ${input}`);
+
+    // Detect format
+    const detection = await detectFormat(input);
+    logger.info(`Detected format: ${detection.format}`);
+
+    // Parse to APISchema
+    let schema;
+    if (detection.format === 'openapi' || detection.format === 'swagger') {
+      schema = parseOpenAPI(detection.content);
+    } else if (detection.format === 'postman') {
+      schema = parsePostman(detection.content);
+    } else if (options.aiParse) {
+      logger.info('Using AI parser for unstructured docs...');
+      schema = await parseWithAI(JSON.stringify(detection.content));
+    } else {
+      throw new ParseError('Could not detect format. Use --ai-parse for unstructured docs.');
+    }
+
+    logger.success(`Parsed API: ${schema.name}`);
+
+    // Analyze patterns
+    const patterns = analyzePatterns(schema);
+    logger.info(`Detected patterns: auth=${patterns.authPattern}, pagination=${patterns.paginationStyle || 'none'}`);
+
+    // Generate server
+    const outputDir = options.output || path.join(process.cwd(), `${schema.name}-mcp`);
+    logger.info(`Generating server in: ${outputDir}`);
+
+    await generateServer(schema, patterns, outputDir);
+
+    // Add to registry
+    await addServer(schema.name, outputDir);
+
+    logger.success(`Generated MCP server: ${schema.name}`);
+    logger.info(`Next steps:`);
+    logger.info(`  cd ${outputDir}`);
+    logger.info(`  npm install`);
+    logger.info(`  npm run build`);
+    logger.info(`  npm test`);
+
+  } catch (error) {
+    if (error instanceof Error) {
+      logger.error(error.message);
+      process.exit(1);
+    }
+    throw error;
+  }
+}

package/src/commands/install.ts

@@ -0,0 +1,92 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import { getServer } from '../registry/manager.js';
+import { logger } from '../utils/logger.js';
+
+export async function installCommand(serverName: string): Promise<void> {
+  try {
+    // Get server from registry
+    const server = await getServer(serverName);
+    if (!server) {
+      logger.error(`Server not found: ${serverName}`);
+      logger.info('Run "mcp-factory list" to see available servers');
+      process.exit(1);
+    }
+
+    // Check if server build exists
+    const buildPath = path.join(server.path, 'build', 'index.js');
+    try {
+      await fs.access(buildPath);
+    } catch {
+      logger.error(`Server not built yet. Run:`);
+      logger.info(`  cd ${server.path}`);
+      logger.info(`  npm install && npm run build`);
+      process.exit(1);
+    }
+
+    // Determine Claude config paths
+    const configPaths = [
+      path.join(os.homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'),
+      path.join(os.homedir(), '.claude', 'config.json'),
+    ];
+
+    let installed = false;
+
+    for (const configPath of configPaths) {
+      try {
+        await fs.access(configPath);
+        await installToConfig(configPath, serverName, buildPath);
+        installed = true;
+
+        const configName = configPath.includes('claude_desktop_config.json')
+          ? 'Claude Desktop'
+          : 'Claude Code';
+        logger.success(`Installed ${serverName} to ${configName}`);
+
+      } catch {
+        // Config file doesn't exist, skip
+      }
+    }
+
+    if (!installed) {
+      logger.warn('No Claude configuration files found');
+      logger.info('Expected locations:');
+      configPaths.forEach(p => logger.info(`  ${p}`));
+    } else {
+      logger.info('\nNext steps:');
+      logger.info('  1. Edit the config file and add your API credentials');
+      logger.info('  2. Restart Claude Desktop/Code to load the server');
+    }
+
+  } catch (error) {
+    if (error instanceof Error) {
+      logger.error(error.message);
+      process.exit(1);
+    }
+    throw error;
+  }
+}
+
+async function installToConfig(
+  configPath: string,
+  serverName: string,
+  buildPath: string
+): Promise<void> {
+  const content = await fs.readFile(configPath, 'utf-8');
+  const config = JSON.parse(content);
+
+  if (!config.mcpServers) {
+    config.mcpServers = {};
+  }
+
+  config.mcpServers[serverName] = {
+    command: 'node',
+    args: [buildPath],
+    env: {
+      API_KEY: 'YOUR_API_KEY_HERE',
+    },
+  };
+
+  await fs.writeFile(configPath, JSON.stringify(config, null, 2));
+}

package/src/commands/list.ts

@@ -0,0 +1,28 @@
+import { listServers } from '../registry/manager.js';
+import { logger } from '../utils/logger.js';
+
+export async function listCommand(): Promise<void> {
+  try {
+    const servers = await listServers();
+
+    if (servers.length === 0) {
+      logger.info('No MCP servers generated yet');
+      return;
+    }
+
+    logger.info(`Generated MCP servers (${servers.length}):\n`);
+
+    for (const server of servers) {
+      console.log(`  ${server.name}`);
+      console.log(`    Path: ${server.path}`);
+      console.log(`    Created: ${new Date(server.createdAt).toLocaleString()}\n`);
+    }
+
+  } catch (error) {
+    if (error instanceof Error) {
+      logger.error(error.message);
+      process.exit(1);
+    }
+    throw error;
+  }
+}

package/src/commands/validate.ts

@@ -0,0 +1,29 @@
+import { detectFormat } from '../parsers/detector.js';
+import { parseOpenAPI } from '../parsers/openapi.js';
+import { logger } from '../utils/logger.js';
+
+export async function validateCommand(input: string): Promise<void> {
+  try {
+    logger.info(`Validating: ${input}`);
+
+    const detection = await detectFormat(input);
+    logger.success(`Format detected: ${detection.format}`);
+
+    if (detection.format === 'openapi' || detection.format === 'swagger') {
+      const schema = parseOpenAPI(detection.content);
+      logger.success(`Valid API specification: ${schema.name}`);
+      logger.info(`Base URL: ${schema.baseUrl}`);
+      logger.info(`Endpoints: ${schema.endpoints.length}`);
+      logger.info(`Auth type: ${schema.auth.type}`);
+    } else {
+      logger.warn('Format detected but parsing not implemented yet');
+    }
+
+  } catch (error) {
+    if (error instanceof Error) {
+      logger.error(`Validation failed: ${error.message}`);
+      process.exit(1);
+    }
+    throw error;
+  }
+}

package/src/generator/analyzer.ts

@@ -0,0 +1,20 @@
+import { APISchema, DetectedPatterns } from '../schema/api-schema.js';
+
+export function analyzePatterns(schema: APISchema): DetectedPatterns {
+  return {
+    authPattern: schema.auth.type,
+    paginationStyle: schema.pagination?.style,
+    rateLimitStrategy: schema.rateLimit?.strategy || 'none',
+    errorFormat: detectErrorFormat(schema),
+    hasWebhooks: false,
+  };
+}
+
+function detectErrorFormat(schema: APISchema): 'standard' | 'custom' {
+  // Check if any endpoint has custom error schemas
+  const hasCustomErrors = schema.endpoints.some(
+    endpoint => endpoint.errors.length > 0 && endpoint.errors.some(e => e.schema)
+  );
+
+  return hasCustomErrors ? 'custom' : 'standard';
+}

package/src/generator/engine.ts

@@ -0,0 +1,73 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import Handlebars from 'handlebars';
+import { APISchema, DetectedPatterns } from '../schema/api-schema.js';
+import { GenerationError } from '../utils/errors.js';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Register Handlebars helper for equality check
+Handlebars.registerHelper('eq', (a, b) => a === b);
+
+export interface GenerationContext {
+  name: string;
+  baseUrl: string;
+  auth: any;
+  endpoints: any[];
+  patterns: DetectedPatterns;
+  absolutePath?: string;
+}
+
+export async function generateServer(
+  schema: APISchema,
+  patterns: DetectedPatterns,
+  outputDir: string
+): Promise<void> {
+  const context: GenerationContext = {
+    name: schema.name,
+    baseUrl: schema.baseUrl,
+    auth: schema.auth,
+    endpoints: schema.endpoints,
+    patterns,
+    absolutePath: path.resolve(outputDir),
+  };
+
+  // Create output directory structure
+  await fs.mkdir(path.join(outputDir, 'src'), { recursive: true });
+
+  // Get template directory
+  const templateDir = path.join(__dirname, '..', '..', 'templates');
+
+  // Generate files from templates
+  await generateFile(templateDir, outputDir, 'package.json.hbs', 'package.json', context);
+  await generateFile(templateDir, outputDir, 'tsconfig.json.hbs', 'tsconfig.json', context);
+  await generateFile(templateDir, outputDir, 'README.md.hbs', 'README.md', context);
+  await generateFile(templateDir, outputDir, 'index.ts.hbs', 'src/index.ts', context);
+  await generateFile(templateDir, outputDir, 'client.ts.hbs', 'src/client.ts', context);
+  await generateFile(templateDir, outputDir, 'tools.ts.hbs', 'src/tools.ts', context);
+  await generateFile(templateDir, outputDir, 'types.ts.hbs', 'src/types.ts', context);
+  await generateFile(templateDir, outputDir, 'validation.ts.hbs', 'src/validation.ts', context);
+  await generateFile(templateDir, outputDir, 'test.ts.hbs', 'test.ts', context);
+}
+
+async function generateFile(
+  templateDir: string,
+  outputDir: string,
+  templateFile: string,
+  outputFile: string,
+  context: GenerationContext
+): Promise<void> {
+  try {
+    const templatePath = path.join(templateDir, templateFile);
+    const templateContent = await fs.readFile(templatePath, 'utf-8');
+    const template = Handlebars.compile(templateContent);
+    const output = template(context);
+
+    const outputPath = path.join(outputDir, outputFile);
+    await fs.writeFile(outputPath, output, 'utf-8');
+  } catch (error) {
+    throw new GenerationError(`Failed to generate ${outputFile}: ${error}`);
+  }
+}

package/src/parsers/ai-parser.ts

@@ -0,0 +1,10 @@
+import { APISchema } from '../schema/api-schema.js';
+import { ParseError } from '../utils/errors.js';
+
+export async function parseWithAI(content: string): Promise<APISchema> {
+  if (!process.env.ANTHROPIC_API_KEY) {
+    throw new ParseError('ANTHROPIC_API_KEY environment variable required for AI parsing');
+  }
+
+  throw new ParseError('AI-powered parsing not yet implemented');
+}

package/src/parsers/detector.ts

@@ -0,0 +1,49 @@
+import * as fs from 'fs/promises';
+import * as yaml from 'yaml';
+import { ParseError } from '../utils/errors.js';
+
+export type InputFormat = 'openapi' | 'swagger' | 'postman' | 'unknown';
+
+export interface DetectionResult {
+  format: InputFormat;
+  content: any;
+}
+
+export async function detectFormat(input: string): Promise<DetectionResult> {
+  let content: string;
+
+  // Check if input is a file path
+  try {
+    content = await fs.readFile(input, 'utf-8');
+  } catch {
+    throw new ParseError(`Could not read file: ${input}`);
+  }
+
+  // Try parsing as JSON
+  let parsed: any;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    // Try parsing as YAML
+    try {
+      parsed = yaml.parse(content);
+    } catch {
+      throw new ParseError('Could not parse input as JSON or YAML');
+    }
+  }
+
+  // Detect format from parsed content
+  if (parsed.openapi) {
+    return { format: 'openapi', content: parsed };
+  }
+
+  if (parsed.swagger) {
+    return { format: 'swagger', content: parsed };
+  }
+
+  if (parsed.info?.schema?.includes('postman')) {
+    return { format: 'postman', content: parsed };
+  }
+
+  return { format: 'unknown', content: parsed };
+}