mcpmake 0.1.0

package/dist/generator/spec-generator.js

@@ -0,0 +1,50 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { logger } from '../utils/logger.js';
+const SYSTEM_PROMPT = `You are an API architect. Given a description of an API or service, generate a valid OpenAPI 3.0 specification in JSON format.
+
+Rules:
+- Output ONLY valid JSON (no markdown fences, no explanation)
+- Include realistic endpoints with proper HTTP methods
+- Use descriptive operationIds in camelCase
+- Include request/response schemas with realistic field types
+- Add path parameters, query parameters, and request bodies where appropriate
+- Include at least one security scheme if auth is likely needed
+- Include a servers array with a base URL
+- Keep it practical — 3-10 operations is typical`;
+export async function generateSpecFromDescription(options) {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+        throw new Error('ANTHROPIC_API_KEY environment variable is required for describe mode.\n' +
+            'Set it with: export ANTHROPIC_API_KEY=your-key-here');
+    }
+    const client = new Anthropic({ apiKey });
+    const model = options.model ?? 'claude-sonnet-4-20250514';
+    let userPrompt = `Generate an OpenAPI 3.0 spec for: ${options.description}`;
+    if (options.baseUrl) {
+        userPrompt += `\n\nUse this base URL: ${options.baseUrl}`;
+    }
+    logger.info('Generating OpenAPI spec from description...');
+    const message = await client.messages.create({
+        model,
+        max_tokens: 4096,
+        system: SYSTEM_PROMPT,
+        messages: [{ role: 'user', content: userPrompt }],
+    });
+    const content = message.content[0];
+    if (content.type !== 'text') {
+        throw new Error('Unexpected response format from Claude');
+    }
+    // Extract JSON — strip markdown fences if present
+    let json = content.text.trim();
+    if (json.startsWith('```')) {
+        json = json.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '');
+    }
+    // Validate it's parseable JSON
+    try {
+        JSON.parse(json);
+    }
+    catch {
+        throw new Error('Claude returned invalid JSON. Try again or refine your description.');
+    }
+    return json;
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,64 @@
+import { defineCommand, runMain } from 'citty';
+import { logger } from './utils/logger.js';
+import openapiCommand from './commands/from/openapi.js';
+import harCommand from './commands/from/har.js';
+import urlCommand from './commands/from/url.js';
+import describeCommand from './commands/from/describe.js';
+import postmanCommand from './commands/from/postman.js';
+import websiteCommand from './commands/from/website.js';
+import verifyCommand from './commands/verify.js';
+import updateCommand from './commands/update.js';
+import deployCommand from './commands/deploy.js';
+import publishCommand from './commands/publish.js';
+import mergeCommand from './commands/merge.js';
+import lintCommand from './commands/lint.js';
+import diffCommand from './commands/diff.js';
+import bundleCommand from './commands/bundle.js';
+import ciCommand from './commands/ci.js';
+import rescanCommand from './commands/rescan.js';
+const fromCommand = defineCommand({
+    meta: {
+        name: 'from',
+        description: 'Generate an MCP server from a source',
+    },
+    subCommands: {
+        openapi: openapiCommand,
+        har: harCommand,
+        url: urlCommand,
+        describe: describeCommand,
+        postman: postmanCommand,
+        website: websiteCommand,
+    },
+});
+const main = defineCommand({
+    meta: {
+        name: 'mcpmake',
+        version: '0.1.0',
+        description: 'Generate MCP servers from API specifications',
+    },
+    subCommands: {
+        from: fromCommand,
+        merge: mergeCommand,
+        verify: verifyCommand,
+        update: updateCommand,
+        deploy: deployCommand,
+        publish: publishCommand,
+        lint: lintCommand,
+        diff: diffCommand,
+        bundle: bundleCommand,
+        ci: ciCommand,
+        rescan: rescanCommand,
+    },
+});
+// Last-resort handlers for *unexpected* throws (the command failure sites use
+// `fail()` instead). These fire too late to reliably await a network POST — the
+// process is already tearing down — so we only log and signal a failed exit.
+process.on('uncaughtException', (err) => {
+    logger.error(`Unexpected error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exitCode = 1;
+});
+process.on('unhandledRejection', (reason) => {
+    logger.error(`Unhandled rejection: ${reason instanceof Error ? reason.message : String(reason)}`);
+    process.exitCode = 1;
+});
+runMain(main);

package/dist/parser/har-filter.d.ts

@@ -0,0 +1,8 @@
+import type { Entry } from 'har-format';
+export interface FilterOptions {
+    /** Only include entries from these domains. If empty, include all. */
+    allowedDomains?: string[];
+    /** Include requests that returned errors (4xx/5xx). Default: false */
+    includeErrors?: boolean;
+}
+export declare function filterHarEntries(entries: Entry[], options?: FilterOptions): Entry[];

package/dist/parser/har-filter.js

@@ -0,0 +1,71 @@
+const NOISE_EXTENSIONS = /\.(js|css|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot|map|webp|avif)(\?|$)/i;
+const ANALYTICS_DOMAINS = [
+    'google-analytics.com',
+    'googletagmanager.com',
+    'analytics.',
+    'mixpanel.com',
+    'segment.io',
+    'segment.com',
+    'hotjar.com',
+    'doubleclick.net',
+    'facebook.net',
+    'fbcdn.net',
+    'sentry.io',
+    'newrelic.com',
+    'datadoghq.com',
+    'clarity.ms',
+];
+const SKIP_MIME_TYPES = [
+    'text/html',
+    'text/css',
+    'application/javascript',
+    'text/javascript',
+    'image/',
+    'font/',
+    'audio/',
+    'video/',
+];
+export function filterHarEntries(entries, options = {}) {
+    return entries.filter((entry) => {
+        const url = entry.request.url;
+        let hostname;
+        try {
+            hostname = new URL(url).hostname;
+        }
+        catch {
+            return false;
+        }
+        // Skip non-HTTP methods
+        const method = entry.request.method.toUpperCase();
+        if (method === 'CONNECT' || method === 'OPTIONS')
+            return false;
+        // Skip static assets by extension
+        const pathname = new URL(url).pathname;
+        if (NOISE_EXTENSIONS.test(pathname))
+            return false;
+        // Skip analytics/tracking domains
+        if (ANALYTICS_DOMAINS.some((d) => hostname.includes(d)))
+            return false;
+        // Domain allowlist
+        if (options.allowedDomains?.length) {
+            if (!options.allowedDomains.some((d) => hostname.includes(d)))
+                return false;
+        }
+        // Skip error responses unless requested
+        if (!options.includeErrors && entry.response.status >= 400)
+            return false;
+        // Skip non-API content types in response
+        const responseMime = entry.response.content?.mimeType ?? '';
+        if (SKIP_MIME_TYPES.some((m) => responseMime.startsWith(m))) {
+            // Exception: text/html that's actually an API response (rare but possible)
+            // Keep if response body looks like JSON
+            if (responseMime.startsWith('text/html') && !entry.response.content?.text?.startsWith('{')) {
+                return false;
+            }
+            if (!responseMime.includes('json') && !responseMime.includes('xml')) {
+                return false;
+            }
+        }
+        return true;
+    });
+}

package/dist/parser/har-loader.d.ts

@@ -0,0 +1,2 @@
+import type { Har } from 'har-format';
+export declare function loadHarFile(filePath: string): Promise<Har>;

package/dist/parser/har-loader.js

@@ -0,0 +1,14 @@
+import { readFile, stat } from 'node:fs/promises';
+const MAX_HAR_SIZE_BYTES = 50 * 1024 * 1024; // 50 MB
+export async function loadHarFile(filePath) {
+    const fileInfo = await stat(filePath);
+    if (fileInfo.size > MAX_HAR_SIZE_BYTES) {
+        throw new Error(`HAR file is too large (${Math.round(fileInfo.size / 1024 / 1024)} MB). Maximum is 50 MB.`);
+    }
+    const raw = await readFile(filePath, 'utf-8');
+    const har = JSON.parse(raw);
+    if (!har.log?.entries || !Array.isArray(har.log.entries)) {
+        throw new Error('Invalid HAR file: missing log.entries array');
+    }
+    return har;
+}

package/dist/parser/har-normalizer.d.ts

@@ -0,0 +1,20 @@
+import type { Entry } from 'har-format';
+export interface NormalizedEntry {
+    entry: Entry;
+    normalizedPath: string;
+    baseUrl: string;
+    pathParams: PathParam[];
+    queryParams: QueryParam[];
+}
+export interface PathParam {
+    name: string;
+    position: number;
+    exampleValue: string;
+    inferredType: 'uuid' | 'integer' | 'string';
+}
+export interface QueryParam {
+    name: string;
+    exampleValue: string;
+    inferredType: 'integer' | 'boolean' | 'string';
+}
+export declare function normalizeEntry(entry: Entry): NormalizedEntry;

package/dist/parser/har-normalizer.js

@@ -0,0 +1,78 @@
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const NUMERIC_ID_PATTERN = /^\d+$/;
+const MONGO_ID_PATTERN = /^[0-9a-f]{24}$/i;
+const SHORT_ID_PATTERN = /^[a-zA-Z0-9]{8,22}$/;
+export function normalizeEntry(entry) {
+    const url = new URL(entry.request.url);
+    const baseUrl = `${url.protocol}//${url.host}`;
+    const segments = url.pathname.split('/').filter(Boolean);
+    const pathParams = [];
+    let paramCounter = 0;
+    const normalizedSegments = segments.map((segment, i) => {
+        if (UUID_PATTERN.test(segment)) {
+            const name = deriveParamName(segments, i, paramCounter++);
+            pathParams.push({ name, position: i, exampleValue: segment, inferredType: 'uuid' });
+            return `{${name}}`;
+        }
+        if (NUMERIC_ID_PATTERN.test(segment) && segment.length < 15) {
+            const name = deriveParamName(segments, i, paramCounter++);
+            pathParams.push({ name, position: i, exampleValue: segment, inferredType: 'integer' });
+            return `{${name}}`;
+        }
+        if (MONGO_ID_PATTERN.test(segment)) {
+            const name = deriveParamName(segments, i, paramCounter++);
+            pathParams.push({ name, position: i, exampleValue: segment, inferredType: 'string' });
+            return `{${name}}`;
+        }
+        // Heuristic: if previous segment is a known collection name and this looks like an ID
+        if (i > 0 && isCollectionName(segments[i - 1]) && SHORT_ID_PATTERN.test(segment)) {
+            const prevSegment = segments[i - 1];
+            // Only treat as ID if short enough and not a known sub-resource
+            if (segment.length <= 22 && !isCollectionName(segment)) {
+                const name = singularize(prevSegment) + 'Id';
+                pathParams.push({ name, position: i, exampleValue: segment, inferredType: 'string' });
+                return `{${name}}`;
+            }
+        }
+        return segment;
+    });
+    const normalizedPath = '/' + normalizedSegments.join('/');
+    const queryParams = [];
+    for (const qs of entry.request.queryString) {
+        queryParams.push({
+            name: qs.name,
+            exampleValue: qs.value,
+            inferredType: inferQueryParamType(qs.value),
+        });
+    }
+    return { entry, normalizedPath, baseUrl, pathParams, queryParams };
+}
+function deriveParamName(segments, currentIndex, counter) {
+    if (currentIndex > 0) {
+        const prev = segments[currentIndex - 1];
+        if (isCollectionName(prev)) {
+            return singularize(prev) + 'Id';
+        }
+    }
+    return counter === 0 ? 'id' : `id${counter + 1}`;
+}
+function isCollectionName(segment) {
+    // Common REST patterns: plurals, known resource names
+    return (/^[a-z][a-z0-9_-]*s$/i.test(segment) || ['api', 'v1', 'v2', 'v3'].includes(segment) === false);
+}
+function singularize(word) {
+    if (word.endsWith('ies'))
+        return word.slice(0, -3) + 'y';
+    if (word.endsWith('ses') || word.endsWith('xes') || word.endsWith('zes'))
+        return word.slice(0, -2);
+    if (word.endsWith('s') && !word.endsWith('ss'))
+        return word.slice(0, -1);
+    return word;
+}
+function inferQueryParamType(value) {
+    if (NUMERIC_ID_PATTERN.test(value))
+        return 'integer';
+    if (value === 'true' || value === 'false')
+        return 'boolean';
+    return 'string';
+}

package/dist/parser/index.d.ts

@@ -0,0 +1,10 @@
+export { loadOpenApiSpec } from './openapi-loader.js';
+export type { LoadResult } from './openapi-loader.js';
+export { extractOperations } from './operation-extractor.js';
+export type { ExtractionResult } from './operation-extractor.js';
+export { jsonSchemaToZodCode, buildOperationInputSchema } from './schema-converter.js';
+export { loadHarFile } from './har-loader.js';
+export { filterHarEntries } from './har-filter.js';
+export type { FilterOptions } from './har-filter.js';
+export { normalizeEntry } from './har-normalizer.js';
+export type { NormalizedEntry, PathParam, QueryParam } from './har-normalizer.js';

package/dist/parser/index.js

@@ -0,0 +1,6 @@
+export { loadOpenApiSpec } from './openapi-loader.js';
+export { extractOperations } from './operation-extractor.js';
+export { jsonSchemaToZodCode, buildOperationInputSchema } from './schema-converter.js';
+export { loadHarFile } from './har-loader.js';
+export { filterHarEntries } from './har-filter.js';
+export { normalizeEntry } from './har-normalizer.js';

package/dist/parser/openapi-loader.d.ts

@@ -0,0 +1,6 @@
+import type { OpenAPI } from 'openapi-types';
+export interface LoadResult {
+    api: OpenAPI.Document;
+    specPath: string;
+}
+export declare function loadOpenApiSpec(input: string): Promise<LoadResult>;

package/dist/parser/openapi-loader.js

@@ -0,0 +1,308 @@
+import SwaggerParser from '@apidevtools/swagger-parser';
+import { logger } from '../utils/logger.js';
+/**
+ * Detects if a parsed document is Swagger 2.0 and converts it to OpenAPI 3.0.
+ */
+function isSwagger2(doc) {
+    return typeof doc.swagger === 'string' && doc.swagger.startsWith('2.');
+}
+function convertSwagger2ToOpenApi3(doc) {
+    logger.warn('Converting Swagger 2.0 to OpenAPI 3.0');
+    const scheme = doc.schemes?.[0] ?? 'https';
+    const host = doc.host ?? 'localhost';
+    const basePath = doc.basePath ?? '/';
+    const serverUrl = `${scheme}://${host}${basePath === '/' ? '' : basePath}`;
+    const globalConsumes = doc.consumes ?? ['application/json'];
+    const globalProduces = doc.produces ?? ['application/json'];
+    const components = {};
+    // Map definitions -> components.schemas
+    if (doc.definitions) {
+        components.schemas = doc.definitions;
+    }
+    // Map parameters -> components.parameters
+    if (doc.parameters) {
+        components.parameters = convertParameterDefinitions(doc.parameters);
+    }
+    // Map securityDefinitions -> components.securitySchemes
+    if (doc.securityDefinitions) {
+        components.securitySchemes = convertSecurityDefinitions(doc.securityDefinitions);
+    }
+    // Convert paths
+    const convertedPaths = {};
+    if (doc.paths) {
+        for (const [path, pathItem] of Object.entries(doc.paths)) {
+            convertedPaths[path] = convertPathItem(pathItem, globalConsumes, globalProduces);
+        }
+    }
+    const result = {
+        openapi: '3.0.0',
+        info: doc.info,
+        servers: [{ url: serverUrl }],
+        paths: convertedPaths,
+    };
+    if (Object.keys(components).length > 0) {
+        result.components = components;
+    }
+    if (doc.security) {
+        result.security = doc.security;
+    }
+    if (doc.tags) {
+        result.tags = doc.tags;
+    }
+    if (doc.externalDocs) {
+        result.externalDocs = doc.externalDocs;
+    }
+    return result;
+}
+function convertPathItem(pathItem, globalConsumes, globalProduces) {
+    const methods = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
+    const result = {};
+    // Preserve path-level parameters
+    if (pathItem.parameters) {
+        result.parameters = convertParameters(pathItem.parameters);
+    }
+    for (const method of methods) {
+        const operation = pathItem[method];
+        if (!operation)
+            continue;
+        result[method] = convertOperation(operation, globalConsumes, globalProduces);
+    }
+    return result;
+}
+function convertOperation(operation, globalConsumes, globalProduces) {
+    const consumes = operation.consumes ?? globalConsumes;
+    const produces = operation.produces ?? globalProduces;
+    const converted = {};
+    // Copy simple fields
+    for (const key of ['operationId', 'summary', 'description', 'tags', 'deprecated', 'security']) {
+        if (operation[key] !== undefined) {
+            converted[key] = operation[key];
+        }
+    }
+    // Copy x- extension fields
+    for (const key of Object.keys(operation)) {
+        if (key.startsWith('x-')) {
+            converted[key] = operation[key];
+        }
+    }
+    // Separate body/formData params from regular params
+    const params = (operation.parameters ?? []);
+    const regularParams = [];
+    let bodyParam;
+    const formDataParams = [];
+    for (const p of params) {
+        if (p.in === 'body') {
+            bodyParam = p;
+        }
+        else if (p.in === 'formData') {
+            formDataParams.push(p);
+        }
+        else {
+            regularParams.push(p);
+        }
+    }
+    if (regularParams.length > 0) {
+        converted.parameters = convertParameters(regularParams);
+    }
+    // Build requestBody from body param or formData params
+    if (bodyParam) {
+        const contentType = consumes[0] ?? 'application/json';
+        converted.requestBody = {
+            description: bodyParam.description,
+            required: bodyParam.required ?? false,
+            content: {
+                [contentType]: {
+                    schema: convertSchemaRef(bodyParam.schema),
+                },
+            },
+        };
+    }
+    else if (formDataParams.length > 0) {
+        const hasFile = formDataParams.some((p) => p.type === 'file');
+        const contentType = hasFile ? 'multipart/form-data' : 'application/x-www-form-urlencoded';
+        const properties = {};
+        const required = [];
+        for (const p of formDataParams) {
+            const name = p.name;
+            if (p.type === 'file') {
+                properties[name] = { type: 'string', format: 'binary' };
+            }
+            else {
+                properties[name] = { type: p.type ?? 'string' };
+                if (p.description) {
+                    properties[name].description = p.description;
+                }
+            }
+            if (p.required) {
+                required.push(name);
+            }
+        }
+        converted.requestBody = {
+            content: {
+                [contentType]: {
+                    schema: {
+                        type: 'object',
+                        properties,
+                        ...(required.length > 0 ? { required } : {}),
+                    },
+                },
+            },
+        };
+    }
+    // Convert responses
+    const responses = (operation.responses ?? {});
+    const convertedResponses = {};
+    for (const [status, response] of Object.entries(responses)) {
+        const convertedResponse = {
+            description: response.description ?? '',
+        };
+        if (response.schema) {
+            const contentType = produces[0] ?? 'application/json';
+            convertedResponse.content = {
+                [contentType]: {
+                    schema: convertSchemaRef(response.schema),
+                },
+            };
+        }
+        if (response.headers) {
+            convertedResponse.headers = response.headers;
+        }
+        convertedResponses[status] = convertedResponse;
+    }
+    converted.responses = convertedResponses;
+    return converted;
+}
+function convertParameters(params) {
+    return params.map((p) => {
+        const converted = {
+            name: p.name,
+            in: p.in,
+        };
+        if (p.required !== undefined)
+            converted.required = p.required;
+        if (p.description !== undefined)
+            converted.description = p.description;
+        // Build schema from Swagger 2.0 parameter type fields
+        const schema = {};
+        if (p.type)
+            schema.type = p.type;
+        if (p.format)
+            schema.format = p.format;
+        if (p.enum)
+            schema.enum = p.enum;
+        if (p.default !== undefined)
+            schema.default = p.default;
+        if (p.items)
+            schema.items = p.items;
+        if (p.minimum !== undefined)
+            schema.minimum = p.minimum;
+        if (p.maximum !== undefined)
+            schema.maximum = p.maximum;
+        converted.schema = Object.keys(schema).length > 0 ? schema : { type: 'string' };
+        return converted;
+    });
+}
+function convertParameterDefinitions(params) {
+    const result = {};
+    for (const [name, param] of Object.entries(params)) {
+        const p = param;
+        if (p.in === 'body') {
+            // Body parameters in definitions are unusual; skip them for components.parameters
+            continue;
+        }
+        const converted = {
+            name: p.name ?? name,
+            in: p.in,
+        };
+        if (p.required !== undefined)
+            converted.required = p.required;
+        if (p.description !== undefined)
+            converted.description = p.description;
+        const schema = {};
+        if (p.type)
+            schema.type = p.type;
+        if (p.format)
+            schema.format = p.format;
+        if (p.enum)
+            schema.enum = p.enum;
+        converted.schema = Object.keys(schema).length > 0 ? schema : { type: 'string' };
+        result[name] = converted;
+    }
+    return result;
+}
+function convertSecurityDefinitions(defs) {
+    const result = {};
+    for (const [name, def] of Object.entries(defs)) {
+        const d = def;
+        switch (d.type) {
+            case 'basic':
+                result[name] = { type: 'http', scheme: 'basic' };
+                break;
+            case 'apiKey':
+                result[name] = { type: 'apiKey', name: d.name, in: d.in };
+                break;
+            case 'oauth2': {
+                const scheme = { type: 'oauth2', flows: {} };
+                const flows = scheme.flows;
+                const scopes = (d.scopes ?? {});
+                switch (d.flow) {
+                    case 'implicit':
+                        flows.implicit = { authorizationUrl: d.authorizationUrl, scopes };
+                        break;
+                    case 'password':
+                        flows.password = { tokenUrl: d.tokenUrl, scopes };
+                        break;
+                    case 'application':
+                        flows.clientCredentials = { tokenUrl: d.tokenUrl, scopes };
+                        break;
+                    case 'accessCode':
+                        flows.authorizationCode = {
+                            authorizationUrl: d.authorizationUrl,
+                            tokenUrl: d.tokenUrl,
+                            scopes,
+                        };
+                        break;
+                }
+                result[name] = scheme;
+                break;
+            }
+            default:
+                result[name] = d;
+        }
+    }
+    return result;
+}
+function convertSchemaRef(schema) {
+    if (!schema)
+        return {};
+    // Swagger 2.0 uses #/definitions/Foo, OpenAPI 3.0 uses #/components/schemas/Foo
+    // Since we move definitions -> components.schemas, update $ref paths
+    const result = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (key === '$ref' && typeof value === 'string') {
+            result.$ref = value.replace('#/definitions/', '#/components/schemas/');
+        }
+        else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            result[key] = convertSchemaRef(value);
+        }
+        else if (Array.isArray(value)) {
+            result[key] = value.map((item) => typeof item === 'object' && item !== null
+                ? convertSchemaRef(item)
+                : item);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+export async function loadOpenApiSpec(input) {
+    // First, parse without dereferencing to check for Swagger 2.0
+    const raw = (await SwaggerParser.parse(input));
+    let specToParse = input;
+    if (isSwagger2(raw)) {
+        specToParse = convertSwagger2ToOpenApi3(raw);
+    }
+    const api = (await SwaggerParser.dereference(specToParse));
+    return { api, specPath: input };
+}

package/dist/parser/operation-extractor.d.ts

@@ -0,0 +1,13 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import type { OperationDescriptor } from '../types/index.js';
+export interface ExtractionResult {
+    operations: OperationDescriptor[];
+    baseUrl: string;
+    securitySchemes: Record<string, OpenAPIV3.SecuritySchemeObject>;
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+}
+export declare function extractOperations(api: OpenAPIV3.Document): ExtractionResult;