@stackkedjohn/mcp-factory-cli 0.1.0

package/README.md

@@ -0,0 +1,100 @@
+# MCP Factory
+
+Generate production-ready MCP servers from API documentation in one command.
+
+## Installation
+
+```bash
+npm install -g @mcp-factory/cli
+```
+
+## Quick Start
+
+```bash
+# Generate MCP server from OpenAPI spec
+mcp-factory create openapi.json
+
+# Install to Claude Desktop/Code
+cd my-api-mcp
+npm install && npm run build
+mcp-factory install my-api
+
+# List generated servers
+mcp-factory list
+```
+
+## Commands
+
+### create
+
+Generate an MCP server from API documentation:
+
+```bash
+mcp-factory create <input> [options]
+
+Options:
+  --ai-parse        Use AI to parse unstructured documentation
+  -o, --output <dir>  Output directory for generated server
+```
+
+**Supported input formats:**
+- OpenAPI 3.x (JSON/YAML)
+- Swagger 2.0 (JSON/YAML)
+- Postman collections (coming soon)
+- Unstructured docs with `--ai-parse` (coming soon)
+
+### validate
+
+Validate API specification without generating code:
+
+```bash
+mcp-factory validate <input>
+```
+
+### list
+
+List all generated MCP servers:
+
+```bash
+mcp-factory list
+```
+
+### install
+
+Install generated server to Claude Desktop/Code configuration:
+
+```bash
+mcp-factory install <server-name>
+```
+
+## Generated Server Structure
+
+```
+my-api-mcp/
+├── src/
+│   ├── index.ts      # MCP server entry point
+│   ├── client.ts     # HTTP client with auth
+│   └── tools.ts      # Tool implementations
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Development
+
+```bash
+# Clone and setup
+git clone <repo>
+cd mcp-factory
+npm install
+
+# Build
+npm run build
+
+# Test with sample
+node dist/cli.js create test-fixtures/weather-api.json
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,33 @@
+#!/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/dist/commands/create.d.ts

@@ -0,0 +1,4 @@
+export declare function createCommand(input: string, options: {
+    aiParse?: boolean;
+    output?: string;
+}): Promise<void>;

package/dist/commands/create.js

@@ -0,0 +1,56 @@
+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, options) {
+    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/dist/commands/install.d.ts

@@ -0,0 +1 @@
+export declare function installCommand(serverName: string): Promise<void>;

package/dist/commands/install.js

@@ -0,0 +1,79 @@
+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) {
+    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, serverName, buildPath) {
+    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/dist/commands/list.d.ts

@@ -0,0 +1 @@
+export declare function listCommand(): Promise<void>;

package/dist/commands/list.js

@@ -0,0 +1,24 @@
+import { listServers } from '../registry/manager.js';
+import { logger } from '../utils/logger.js';
+export async function listCommand() {
+    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/dist/commands/validate.d.ts

@@ -0,0 +1 @@
+export declare function validateCommand(input: string): Promise<void>;

package/dist/commands/validate.js

@@ -0,0 +1,27 @@
+import { detectFormat } from '../parsers/detector.js';
+import { parseOpenAPI } from '../parsers/openapi.js';
+import { logger } from '../utils/logger.js';
+export async function validateCommand(input) {
+    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/dist/generator/analyzer.d.ts

@@ -0,0 +1,2 @@
+import { APISchema, DetectedPatterns } from '../schema/api-schema.js';
+export declare function analyzePatterns(schema: APISchema): DetectedPatterns;

package/dist/generator/analyzer.js

@@ -0,0 +1,14 @@
+export function analyzePatterns(schema) {
+    return {
+        authPattern: schema.auth.type,
+        paginationStyle: schema.pagination?.style,
+        rateLimitStrategy: schema.rateLimit?.strategy || 'none',
+        errorFormat: detectErrorFormat(schema),
+        hasWebhooks: false,
+    };
+}
+function detectErrorFormat(schema) {
+    // 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/dist/generator/engine.d.ts

@@ -0,0 +1,10 @@
+import { APISchema, DetectedPatterns } from '../schema/api-schema.js';
+export interface GenerationContext {
+    name: string;
+    baseUrl: string;
+    auth: any;
+    endpoints: any[];
+    patterns: DetectedPatterns;
+    absolutePath?: string;
+}
+export declare function generateServer(schema: APISchema, patterns: DetectedPatterns, outputDir: string): Promise<void>;

package/dist/generator/engine.js

@@ -0,0 +1,46 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import Handlebars from 'handlebars';
+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 async function generateServer(schema, patterns, outputDir) {
+    const context = {
+        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, outputDir, templateFile, outputFile, context) {
+    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/dist/parsers/ai-parser.d.ts

@@ -0,0 +1,2 @@
+import { APISchema } from '../schema/api-schema.js';
+export declare function parseWithAI(content: string): Promise<APISchema>;

package/dist/parsers/ai-parser.js

@@ -0,0 +1,7 @@
+import { ParseError } from '../utils/errors.js';
+export async function parseWithAI(content) {
+    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/dist/parsers/detector.d.ts

@@ -0,0 +1,6 @@
+export type InputFormat = 'openapi' | 'swagger' | 'postman' | 'unknown';
+export interface DetectionResult {
+    format: InputFormat;
+    content: any;
+}
+export declare function detectFormat(input: string): Promise<DetectionResult>;

package/dist/parsers/detector.js

@@ -0,0 +1,38 @@
+import * as fs from 'fs/promises';
+import * as yaml from 'yaml';
+import { ParseError } from '../utils/errors.js';
+export async function detectFormat(input) {
+    let content;
+    // 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;
+    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 };
+}

package/dist/parsers/openapi.d.ts

@@ -0,0 +1,5 @@
+import { APISchema } from '../schema/api-schema.js';
+/**
+ * Parse OpenAPI 3.x or Swagger 2.0 specification into unified APISchema
+ */
+export declare function parseOpenAPI(spec: any): APISchema;