mcpmake 0.1.0

package/dist/parser/operation-extractor.js

@@ -0,0 +1,155 @@
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
+export function extractOperations(api) {
+    const operations = [];
+    const baseUrl = api.servers?.[0]?.url ?? '';
+    const securitySchemes = (api.components?.securitySchemes ?? {});
+    const globalSecurity = api.security ?? [];
+    for (const [path, pathItem] of Object.entries(api.paths ?? {})) {
+        if (!pathItem)
+            continue;
+        const item = pathItem;
+        const pathParams = (item.parameters ?? []);
+        for (const method of HTTP_METHODS) {
+            const operation = item[method];
+            if (!operation)
+                continue;
+            const opParams = (operation.parameters ?? []);
+            const mergedParams = mergeParameters(pathParams, opParams);
+            const operationId = operation.operationId ?? synthesizeOperationId(method, path);
+            const mcpExtensions = extractMcpExtensions(operation);
+            operations.push({
+                operationId,
+                method,
+                path,
+                summary: operation.summary,
+                description: operation.description,
+                tags: operation.tags ?? [],
+                parameters: mergedParams.map(toParameterDescriptor),
+                requestBody: extractRequestBody(operation.requestBody),
+                responses: extractResponses(operation.responses),
+                security: extractSecurity(operation.security ?? globalSecurity),
+                deprecated: operation.deprecated ?? false,
+                mcpExtensions,
+            });
+        }
+    }
+    return {
+        operations,
+        baseUrl,
+        securitySchemes,
+        info: {
+            title: api.info.title,
+            version: api.info.version,
+            description: api.info.description,
+        },
+    };
+}
+function mergeParameters(pathLevel, opLevel) {
+    const byKey = new Map();
+    for (const p of pathLevel)
+        byKey.set(`${p.in}:${p.name}`, p);
+    for (const p of opLevel)
+        byKey.set(`${p.in}:${p.name}`, p); // op-level overrides
+    return [...byKey.values()];
+}
+function toParameterDescriptor(p) {
+    return {
+        name: p.name,
+        in: p.in,
+        required: p.required ?? p.in === 'path',
+        description: p.description,
+        schema: (p.schema ?? { type: 'string' }),
+    };
+}
+function extractRequestBody(body) {
+    if (!body?.content)
+        return undefined;
+    const preferredTypes = [
+        'application/json',
+        'application/x-www-form-urlencoded',
+        'multipart/form-data',
+    ];
+    let contentType;
+    for (const ct of preferredTypes) {
+        if (body.content[ct]) {
+            contentType = ct;
+            break;
+        }
+    }
+    if (!contentType) {
+        contentType = Object.keys(body.content)[0];
+    }
+    if (!contentType)
+        return undefined;
+    const mediaType = body.content[contentType];
+    return {
+        required: body.required ?? false,
+        description: body.description,
+        contentType,
+        schema: (mediaType.schema ?? {}),
+    };
+}
+function extractResponses(responses) {
+    const result = [];
+    for (const [statusCode, responseObj] of Object.entries(responses)) {
+        const response = responseObj;
+        let contentType;
+        let schema;
+        if (response.content) {
+            contentType = Object.keys(response.content)[0];
+            if (contentType) {
+                schema = response.content[contentType].schema;
+            }
+        }
+        result.push({
+            statusCode,
+            description: response.description,
+            contentType,
+            schema,
+        });
+    }
+    return result;
+}
+function extractSecurity(security) {
+    const result = [];
+    for (const req of security) {
+        for (const [schemeName, scopes] of Object.entries(req)) {
+            result.push({ schemeName, scopes });
+        }
+    }
+    return result;
+}
+function synthesizeOperationId(method, path) {
+    const cleaned = path.replace(/[{}]/g, '').replace(/\//g, '_').replace(/^_/, '').replace(/_$/, '');
+    return `${method}_${cleaned}`;
+}
+function extractMcpExtensions(operation) {
+    const name = operation['x-mcp-name'];
+    const description = operation['x-mcp-description'];
+    const emit = operation['x-mcp-emit'];
+    const scope = operation['x-mcp-scope'];
+    const deprecationMessage = operation['x-mcp-deprecation-message'];
+    const deprecationReplacement = operation['x-mcp-deprecation-replacement'];
+    const jqFilter = operation['x-mcp-jq-filter'];
+    const unknownValues = operation['x-mcp-unknown-values'];
+    if (!name &&
+        !description &&
+        !emit &&
+        !scope &&
+        !deprecationMessage &&
+        !deprecationReplacement &&
+        !jqFilter &&
+        !unknownValues) {
+        return undefined;
+    }
+    return {
+        name,
+        description,
+        emit,
+        scope,
+        deprecationMessage,
+        deprecationReplacement,
+        jqFilter,
+        unknownValues,
+    };
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Applies an OpenAPI Overlay document to a spec, modifying it in place.
+ *
+ * Supports simplified JSONPath-like targets:
+ * - `$.paths['/users'].get`       exact path + method
+ * - `$.paths['/users'].get.x-foo` exact nested field
+ * - `$.paths['/admin/*']`         wildcard match on path prefix
+ * - `$.components.schemas.User`   schema-level targeting
+ */
+export declare function applyOverlay(spec: Record<string, unknown>, overlayPath: string): Promise<void>;

package/dist/parser/overlay-loader.js

@@ -0,0 +1,184 @@
+import { readFile } from 'node:fs/promises';
+import { parse as parseYaml } from 'yaml';
+import { logger } from '../utils/logger.js';
+/**
+ * Applies an OpenAPI Overlay document to a spec, modifying it in place.
+ *
+ * Supports simplified JSONPath-like targets:
+ * - `$.paths['/users'].get`       exact path + method
+ * - `$.paths['/users'].get.x-foo` exact nested field
+ * - `$.paths['/admin/*']`         wildcard match on path prefix
+ * - `$.components.schemas.User`   schema-level targeting
+ */
+export async function applyOverlay(spec, overlayPath) {
+    const raw = await readFile(overlayPath, 'utf-8');
+    const overlay = parseOverlay(raw);
+    logger.info(`Applying overlay: ${overlayPath} (${overlay.actions.length} actions)`);
+    for (const action of overlay.actions) {
+        applyAction(spec, action);
+    }
+}
+function parseOverlay(content) {
+    let doc;
+    try {
+        doc = parseYaml(content);
+    }
+    catch {
+        doc = JSON.parse(content);
+    }
+    if (!doc.actions || !Array.isArray(doc.actions)) {
+        throw new Error('Overlay document must contain an "actions" array');
+    }
+    return doc;
+}
+function applyAction(spec, action) {
+    const segments = parseTarget(action.target);
+    if (segments.length === 0)
+        return;
+    // Handle wildcard matching
+    const wildcardIdx = segments.findIndex((s) => s.includes('*'));
+    if (wildcardIdx >= 0) {
+        applyWildcardAction(spec, segments, wildcardIdx, action);
+    }
+    else {
+        applySingleAction(spec, segments, action);
+    }
+}
+function applySingleAction(spec, segments, action) {
+    if (action.remove) {
+        // Navigate to parent, then delete the last key
+        const parent = navigateTo(spec, segments.slice(0, -1));
+        if (parent && typeof parent === 'object') {
+            const lastKey = segments[segments.length - 1];
+            delete parent[lastKey];
+            logger.info(`Overlay: removed ${segments.join('.')}`);
+        }
+    }
+    else if (action.update) {
+        const target = navigateTo(spec, segments);
+        if (target && typeof target === 'object') {
+            deepMerge(target, action.update);
+            logger.info(`Overlay: updated ${segments.join('.')}`);
+        }
+        else {
+            // If target doesn't exist, try creating it by setting on parent
+            const parent = navigateTo(spec, segments.slice(0, -1));
+            if (parent && typeof parent === 'object') {
+                const lastKey = segments[segments.length - 1];
+                parent[lastKey] = action.update;
+                logger.info(`Overlay: created ${segments.join('.')}`);
+            }
+            else {
+                logger.warn(`Overlay: target not found: ${segments.join('.')}`);
+            }
+        }
+    }
+}
+function applyWildcardAction(spec, segments, wildcardIdx, action) {
+    // Navigate to parent of the wildcard segment
+    const parentSegments = segments.slice(0, wildcardIdx);
+    const parent = navigateTo(spec, parentSegments);
+    if (!parent || typeof parent !== 'object')
+        return;
+    const wildcardPattern = segments[wildcardIdx];
+    const remainingSegments = segments.slice(wildcardIdx + 1);
+    // Match keys against the wildcard pattern
+    const regex = wildcardToRegex(wildcardPattern);
+    const matchedKeys = Object.keys(parent).filter((key) => regex.test(key));
+    for (const key of matchedKeys) {
+        const fullSegments = [...parentSegments, key, ...remainingSegments];
+        applySingleAction(spec, fullSegments, action);
+    }
+}
+/**
+ * Parses a JSONPath-like target string into segments.
+ * `$.paths['/users'].get` -> ['paths', '/users', 'get']
+ */
+function parseTarget(target) {
+    const segments = [];
+    let current = target;
+    // Remove leading $. or $
+    if (current.startsWith('$.')) {
+        current = current.slice(2);
+    }
+    else if (current.startsWith('$')) {
+        current = current.slice(1);
+    }
+    while (current.length > 0) {
+        if (current.startsWith('[')) {
+            // Bracket notation: ['key'] or ['/path']
+            const closeIdx = current.indexOf(']');
+            if (closeIdx < 0)
+                break;
+            let key = current.slice(1, closeIdx);
+            // Strip surrounding quotes
+            if ((key.startsWith("'") && key.endsWith("'")) ||
+                (key.startsWith('"') && key.endsWith('"'))) {
+                key = key.slice(1, -1);
+            }
+            segments.push(key);
+            current = current.slice(closeIdx + 1);
+            if (current.startsWith('.'))
+                current = current.slice(1);
+        }
+        else {
+            // Dot notation: get the next segment up to . or [
+            const dotIdx = current.indexOf('.');
+            const bracketIdx = current.indexOf('[');
+            let end;
+            if (dotIdx < 0 && bracketIdx < 0) {
+                end = current.length;
+            }
+            else if (dotIdx < 0) {
+                end = bracketIdx;
+            }
+            else if (bracketIdx < 0) {
+                end = dotIdx;
+            }
+            else {
+                end = Math.min(dotIdx, bracketIdx);
+            }
+            const segment = current.slice(0, end);
+            if (segment.length > 0) {
+                segments.push(segment);
+            }
+            current = current.slice(end);
+            if (current.startsWith('.'))
+                current = current.slice(1);
+        }
+    }
+    return segments;
+}
+function navigateTo(obj, segments) {
+    let current = obj;
+    for (const segment of segments) {
+        if (current === null || current === undefined || typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+function deepMerge(target, source) {
+    for (const [key, value] of Object.entries(source)) {
+        if (typeof value === 'object' &&
+            value !== null &&
+            !Array.isArray(value) &&
+            typeof target[key] === 'object' &&
+            target[key] !== null &&
+            !Array.isArray(target[key])) {
+            deepMerge(target[key], value);
+        }
+        else {
+            target[key] = value;
+        }
+    }
+}
+function wildcardToRegex(pattern) {
+    const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, (match) => {
+        if (match === '*')
+            return '.*';
+        return `\\${match}`;
+    });
+    return new RegExp(`^${escaped}$`);
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Postman Collection v2.1 to HAR Entry converter.
+ * Converts Postman items into HAR entries that feed into the existing HAR pipeline.
+ */
+import type { Entry } from 'har-format';
+export declare function loadPostmanCollection(filePath: string): Promise<{
+    entries: Entry[];
+    collectionName: string;
+}>;

package/dist/parser/postman-loader.js

@@ -0,0 +1,106 @@
+/**
+ * Postman Collection v2.1 to HAR Entry converter.
+ * Converts Postman items into HAR entries that feed into the existing HAR pipeline.
+ */
+import { readFile } from 'node:fs/promises';
+export async function loadPostmanCollection(filePath) {
+    const raw = await readFile(filePath, 'utf-8');
+    const collection = JSON.parse(raw);
+    if (!collection.info || !collection.item) {
+        throw new Error('Invalid Postman collection: missing info or item fields');
+    }
+    // Resolve variables
+    const vars = new Map();
+    for (const v of collection.variable ?? []) {
+        vars.set(v.key, v.value);
+    }
+    const entries = [];
+    flattenItems(collection.item, entries, vars);
+    return { entries, collectionName: collection.info.name };
+}
+function flattenItems(items, entries, vars) {
+    for (const item of items) {
+        if (item.item) {
+            flattenItems(item.item, entries, vars);
+        }
+        if (item.request) {
+            const entry = convertToHarEntry(item, vars);
+            if (entry)
+                entries.push(entry);
+        }
+    }
+}
+function convertToHarEntry(item, vars) {
+    const req = item.request;
+    const url = resolveUrl(req.url, vars);
+    if (!url)
+        return null;
+    const method = req.method ?? 'GET';
+    const headers = (req.header ?? []).map((h) => ({
+        name: h.key,
+        value: resolveVars(h.value, vars),
+    }));
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    const queryString = [...parsedUrl.searchParams.entries()].map(([name, value]) => ({
+        name,
+        value,
+    }));
+    const postData = req.body?.raw
+        ? {
+            mimeType: headers.find((h) => h.name.toLowerCase() === 'content-type')?.value ?? 'application/json',
+            text: resolveVars(req.body.raw, vars),
+        }
+        : undefined;
+    return {
+        startedDateTime: new Date().toISOString(),
+        time: 0,
+        request: {
+            method: method.toUpperCase(),
+            url,
+            httpVersion: 'HTTP/1.1',
+            headers,
+            queryString,
+            cookies: [],
+            headersSize: -1,
+            bodySize: postData?.text ? Buffer.byteLength(postData.text) : 0,
+            ...(postData ? { postData } : {}),
+        },
+        response: {
+            status: 200,
+            statusText: 'OK',
+            httpVersion: 'HTTP/1.1',
+            headers: [{ name: 'content-type', value: 'application/json' }],
+            cookies: [],
+            content: { size: 0, mimeType: 'application/json' },
+            redirectURL: '',
+            headersSize: -1,
+            bodySize: 0,
+        },
+        cache: {},
+        timings: { send: 0, wait: 0, receive: 0 },
+    };
+}
+function resolveUrl(url, vars) {
+    if (typeof url === 'string')
+        return resolveVars(url, vars);
+    if (url.raw)
+        return resolveVars(url.raw, vars);
+    const protocol = url.protocol ?? 'https';
+    const host = url.host?.join('.') ?? 'localhost';
+    const path = url.path?.join('/') ?? '';
+    const base = `${protocol}://${host}/${path}`;
+    const parsed = new URL(resolveVars(base, vars));
+    for (const q of url.query ?? []) {
+        parsed.searchParams.set(q.key, resolveVars(q.value, vars));
+    }
+    return parsed.toString();
+}
+function resolveVars(str, vars) {
+    return str.replace(/\{\{(\w+)\}\}/g, (_, key) => vars.get(key) ?? `{{${key}}}`);
+}

package/dist/parser/schema-converter.d.ts

@@ -0,0 +1,12 @@
+import type { OperationDescriptor, JsonSchema } from '../types/index.js';
+/**
+ * Wrap array root schemas in an object for MCP outputSchema compatibility.
+ * MCP outputSchema requires an object root, not a bare array.
+ */
+export declare function wrapArrayRoot(schema: JsonSchema): JsonSchema;
+export declare function jsonSchemaToZodCode(schema: JsonSchema): string;
+/**
+ * Convert a schema to Zod code, wrapping array roots for outputSchema.
+ */
+export declare function jsonSchemaToOutputZodCode(schema: JsonSchema): string;
+export declare function buildOperationInputSchema(op: OperationDescriptor): string;

package/dist/parser/schema-converter.js

@@ -0,0 +1,117 @@
+import { jsonSchemaToZod } from 'json-schema-to-zod';
+import { sanitizeIdentifier } from '../utils/sanitize.js';
+import { logger } from '../utils/logger.js';
+const MAX_SCHEMA_DEPTH = 15;
+/**
+ * Pre-process a JSON Schema to simplify common patterns before Zod conversion.
+ * Handles: single-item allOf (unwrap), nullable types, circular refs, array root wrapping.
+ */
+function simplifySchema(schema, depth = 0, seen = new WeakSet()) {
+    if (!schema || typeof schema !== 'object')
+        return schema;
+    // Circular reference detection
+    if (seen.has(schema)) {
+        return { type: 'object', description: 'Truncated: circular reference' };
+    }
+    seen.add(schema);
+    // Depth limit
+    if (depth > MAX_SCHEMA_DEPTH) {
+        return { type: 'object', description: 'Truncated: max depth exceeded' };
+    }
+    // Unwrap single-item allOf (common in OpenAPI after $ref resolution)
+    if (schema.allOf && Array.isArray(schema.allOf) && schema.allOf.length === 1) {
+        const inner = schema.allOf[0];
+        const { allOf, ...rest } = schema;
+        return simplifySchema({ ...inner, ...rest }, depth + 1, seen);
+    }
+    // Handle nullable shorthand: { type: "string", nullable: true }
+    if (schema.nullable === true && schema.type) {
+        const { nullable, ...rest } = schema;
+        return { oneOf: [rest, { type: 'null' }] };
+    }
+    // Recursively simplify nested schemas
+    if (schema.properties && typeof schema.properties === 'object') {
+        const simplified = {};
+        for (const [key, value] of Object.entries(schema.properties)) {
+            simplified[key] = simplifySchema(value, depth + 1, seen);
+        }
+        return { ...schema, properties: simplified };
+    }
+    if (schema.items && typeof schema.items === 'object') {
+        return { ...schema, items: simplifySchema(schema.items, depth + 1, seen) };
+    }
+    return schema;
+}
+/**
+ * Wrap array root schemas in an object for MCP outputSchema compatibility.
+ * MCP outputSchema requires an object root, not a bare array.
+ */
+export function wrapArrayRoot(schema) {
+    if (schema.type === 'array') {
+        return {
+            type: 'object',
+            properties: { items: schema },
+            required: ['items'],
+        };
+    }
+    return schema;
+}
+export function jsonSchemaToZodCode(schema) {
+    try {
+        const simplified = simplifySchema(schema);
+        return jsonSchemaToZod(simplified, { module: 'none' });
+    }
+    catch {
+        return 'z.any()';
+    }
+}
+/**
+ * Convert a schema to Zod code, wrapping array roots for outputSchema.
+ */
+export function jsonSchemaToOutputZodCode(schema) {
+    return jsonSchemaToZodCode(wrapArrayRoot(schema));
+}
+export function buildOperationInputSchema(op) {
+    const fields = [];
+    const seenNames = new Set();
+    for (const param of op.parameters) {
+        if (param.in === 'header')
+            continue;
+        let safeName = sanitizeIdentifier(param.name);
+        // Parameter collision resolution
+        if (seenNames.has(safeName)) {
+            safeName = `${safeName}_${param.in}`;
+            logger.warn(`Parameter name collision: "${param.name}" renamed to "${safeName}"`);
+        }
+        seenNames.add(safeName);
+        const zodType = jsonSchemaToZodCode(param.schema);
+        let field = zodType;
+        if (!param.required) {
+            field = `${field}.optional()`;
+        }
+        if (param.description) {
+            field = `${field}.describe(${JSON.stringify(param.description)})`;
+        }
+        fields.push(`  ${safeName}: ${field}`);
+    }
+    if (op.requestBody) {
+        let bodyName = 'body';
+        if (seenNames.has(bodyName)) {
+            bodyName = 'requestBody';
+        }
+        seenNames.add(bodyName);
+        const bodyZod = jsonSchemaToZodCode(op.requestBody.schema);
+        let field = bodyZod;
+        if (!op.requestBody.required) {
+            field = `${field}.optional()`;
+        }
+        if (op.requestBody.description) {
+            field = `${field}.describe(${JSON.stringify(op.requestBody.description)})`;
+        }
+        fields.push(`  ${bodyName}: ${field}`);
+    }
+    if (fields.length === 0) {
+        return 'z.object({})';
+    }
+    return `z.object({\n${fields.join(',\n')},\n})`;
+}

package/dist/plugins/adapter.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Plugin adapter interface for mcpmake.
+ *
+ * Third-party packages implement this interface to add new input formats.
+ * Adapters convert their source format into OperationDescriptor[] —
+ * the shared intermediate format that feeds into the tool builder and emitter.
+ *
+ * Example:
+ *   export default class GraphQLAdapter implements McpmakeAdapter {
+ *     name = 'graphql';
+ *     description = 'Generate from GraphQL schema';
+ *     async parse(input: string) { ... return operations; }
+ *   }
+ */
+import type { OperationDescriptor, AuthScheme, EnvVarDescriptor } from '../types/index.js';
+export interface AdapterResult {
+    operations: OperationDescriptor[];
+    baseUrl: string;
+    authSchemes: AuthScheme[];
+    envVars: EnvVarDescriptor[];
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+}
+export interface McpmakeAdapter {
+    /** Unique adapter name (used as CLI subcommand: `mcpmake from <name>`) */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** File extensions this adapter handles (e.g., ['.graphql', '.gql']) */
+    extensions?: string[];
+    /**
+     * Parse the input source and return operations.
+     * @param input — file path, URL, or other source identifier
+     * @param options — adapter-specific options from CLI args
+     */
+    parse(input: string, options?: Record<string, unknown>): Promise<AdapterResult>;
+}

package/dist/plugins/adapter.js

@@ -0,0 +1,15 @@
+/**
+ * Plugin adapter interface for mcpmake.
+ *
+ * Third-party packages implement this interface to add new input formats.
+ * Adapters convert their source format into OperationDescriptor[] —
+ * the shared intermediate format that feeds into the tool builder and emitter.
+ *
+ * Example:
+ *   export default class GraphQLAdapter implements McpmakeAdapter {
+ *     name = 'graphql';
+ *     description = 'Generate from GraphQL schema';
+ *     async parse(input: string) { ... return operations; }
+ *   }
+ */
+export {};

package/dist/plugins/loader.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Plugin loader — discovers and loads McpmakeAdapter implementations.
+ *
+ * Plugins are loaded from:
+ * 1. Built-in adapters (openapi, har, url, describe)
+ * 2. npm packages named `mcpmake-adapter-*`
+ * 3. Local files specified via --adapter flag
+ */
+import type { McpmakeAdapter } from './adapter.js';
+/**
+ * Register a plugin adapter.
+ */
+export declare function registerAdapter(adapter: McpmakeAdapter): void;
+/**
+ * Get a registered adapter by name.
+ */
+export declare function getAdapter(name: string): McpmakeAdapter | undefined;
+/**
+ * List all registered adapters.
+ */
+export declare function listAdapters(): McpmakeAdapter[];
+/**
+ * Load an adapter from a file path or npm package name.
+ */
+export declare function loadAdapterFromPath(pathOrPackage: string): Promise<McpmakeAdapter>;