mcpmake 0.1.0

package/dist/transformer/llm-namer.d.ts

@@ -0,0 +1,6 @@
+import type { OperationDescriptor } from '../types/index.js';
+/**
+ * Use Claude to generate better tool names and descriptions
+ * from HAR-captured request/response patterns.
+ */
+export declare function improveToolNames(operations: OperationDescriptor[], model?: string): Promise<OperationDescriptor[]>;

package/dist/transformer/llm-namer.js

@@ -0,0 +1,59 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { logger } from '../utils/logger.js';
+/**
+ * Use Claude to generate better tool names and descriptions
+ * from HAR-captured request/response patterns.
+ */
+export async function improveToolNames(operations, model) {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+        logger.warn('ANTHROPIC_API_KEY not set — skipping LLM tool naming');
+        return operations;
+    }
+    const client = new Anthropic({ apiKey });
+    const operationSummaries = operations.map((op) => ({
+        method: op.method,
+        path: op.path,
+        currentId: op.operationId,
+        summary: op.summary,
+        paramNames: op.parameters.map((p) => p.name),
+        hasBody: !!op.requestBody,
+        tags: op.tags,
+    }));
+    const prompt = `Given these API operations captured from network traffic, suggest better operationId names and descriptions. Return a JSON array with one object per operation: { "index": number, "operationId": "camelCase name", "summary": "one-line description" }. Keep names concise (camelCase, under 40 chars). Only output JSON, no explanation.
+
+Operations:
+${JSON.stringify(operationSummaries, null, 2)}`;
+    try {
+        logger.info('Improving tool names with Claude...');
+        const message = await client.messages.create({
+            model: model ?? 'claude-sonnet-4-20250514',
+            max_tokens: 2048,
+            messages: [{ role: 'user', content: prompt }],
+        });
+        const content = message.content[0];
+        if (content.type !== 'text')
+            return operations;
+        let json = content.text.trim();
+        if (json.startsWith('```')) {
+            json = json.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '');
+        }
+        const improvements = JSON.parse(json);
+        const result = operations.map((op, i) => {
+            const improvement = improvements.find((imp) => imp.index === i);
+            if (!improvement)
+                return op;
+            return {
+                ...op,
+                operationId: improvement.operationId || op.operationId,
+                summary: improvement.summary || op.summary,
+            };
+        });
+        logger.info(`Improved ${improvements.length} tool names`);
+        return result;
+    }
+    catch (err) {
+        logger.warn(`LLM naming failed, using defaults: ${err instanceof Error ? err.message : err}`);
+        return operations;
+    }
+}

package/dist/transformer/naming.d.ts

@@ -0,0 +1,4 @@
+export declare function toToolName(operationId: string): string;
+export declare function toToolTitle(operationId: string): string;
+export declare function toFileName(operationId: string): string;
+export declare function toFunctionName(operationId: string): string;

package/dist/transformer/naming.js

@@ -0,0 +1,30 @@
+export function toToolName(operationId) {
+    return toSnakeCase(operationId);
+}
+export function toToolTitle(operationId) {
+    const snake = toSnakeCase(operationId);
+    return snake
+        .split('_')
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(' ');
+}
+export function toFileName(operationId) {
+    return toSnakeCase(operationId)
+        .replace(/_/g, '-')
+        .replace(/\.\./g, '')
+        .replace(/[/\\]/g, '')
+        .replace(/[^a-z0-9\-]/g, '');
+}
+export function toFunctionName(operationId) {
+    const snake = toSnakeCase(operationId);
+    return snake.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+function toSnakeCase(str) {
+    return str
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/([A-Z])([A-Z][a-z])/g, '$1_$2')
+        .replace(/[\s\-]+/g, '_')
+        .toLowerCase()
+        .replace(/^_+|_+$/g, '')
+        .replace(/_+/g, '_');
+}

package/dist/transformer/operation-filter.d.ts

@@ -0,0 +1,13 @@
+import type { OperationDescriptor } from '../types/index.js';
+export interface FilterOptions {
+    include?: string[];
+    exclude?: string[];
+}
+/**
+ * Filter operations by tag or path pattern.
+ * Patterns can be:
+ *   - A tag name: "pets" matches operations tagged with "pets"
+ *   - A path prefix: "/users*" matches /users, /users/{id}, etc.
+ *   - A glob-like pattern: "*admin*" matches any operation with "admin" in path or tags
+ */
+export declare function filterOperations(operations: OperationDescriptor[], options: FilterOptions): OperationDescriptor[];

package/dist/transformer/operation-filter.js

@@ -0,0 +1,52 @@
+/**
+ * Filter operations by tag or path pattern.
+ * Patterns can be:
+ *   - A tag name: "pets" matches operations tagged with "pets"
+ *   - A path prefix: "/users*" matches /users, /users/{id}, etc.
+ *   - A glob-like pattern: "*admin*" matches any operation with "admin" in path or tags
+ */
+export function filterOperations(operations, options) {
+    let result = operations;
+    if (options.include?.length) {
+        result = result.filter((op) => options.include.some((pattern) => matchesOperation(op, pattern)));
+    }
+    if (options.exclude?.length) {
+        result = result.filter((op) => !options.exclude.some((pattern) => matchesOperation(op, pattern)));
+    }
+    return result;
+}
+function matchesOperation(op, pattern) {
+    const lowerPattern = pattern.toLowerCase();
+    // Check tag match
+    if (op.tags.some((t) => t.toLowerCase() === lowerPattern))
+        return true;
+    // Check path match with simple glob support
+    if (matchGlob(op.path.toLowerCase(), lowerPattern))
+        return true;
+    // Check operationId match
+    if (op.operationId.toLowerCase().includes(lowerPattern))
+        return true;
+    return false;
+}
+function matchGlob(str, pattern) {
+    // Simple glob matching without regex to avoid ReDoS.
+    // Split pattern by '*' and check that all parts appear in order.
+    const parts = pattern.split('*');
+    let pos = 0;
+    for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        if (part === '')
+            continue;
+        const idx = str.indexOf(part, pos);
+        if (idx === -1)
+            return false;
+        // First segment must match at start, last at end
+        if (i === 0 && idx !== 0)
+            return false;
+        pos = idx + part.length;
+    }
+    // If pattern doesn't end with *, the string must end at pos
+    if (!pattern.endsWith('*') && pos !== str.length)
+        return false;
+    return true;
+}

package/dist/transformer/resource-builder.d.ts

@@ -0,0 +1,12 @@
+import type { OperationDescriptor } from '../types/index.js';
+import type { ResourceDefinition, PromptDefinition } from '../types/index.js';
+/**
+ * Generate MCP resources from GET operations.
+ * - List endpoints (no path params) → static resources
+ * - Detail endpoints (with path params) → URI template resources
+ */
+export declare function buildResources(operations: OperationDescriptor[]): ResourceDefinition[];
+/**
+ * Generate MCP prompts — one per tag as a "workflow" prompt.
+ */
+export declare function buildPrompts(operations: OperationDescriptor[]): PromptDefinition[];

package/dist/transformer/resource-builder.js

@@ -0,0 +1,80 @@
+import { escapeTemplateLiteral, escapeStringLiteral, sanitizeIdentifier, } from '../utils/sanitize.js';
+import { toToolName } from './naming.js';
+/**
+ * Generate MCP resources from GET operations.
+ * - List endpoints (no path params) → static resources
+ * - Detail endpoints (with path params) → URI template resources
+ */
+export function buildResources(operations) {
+    const resources = [];
+    for (const op of operations) {
+        if (op.method !== 'get')
+            continue;
+        const name = toToolName(op.operationId);
+        const description = escapeTemplateLiteral(op.summary ?? `${op.method.toUpperCase()} ${op.path}`);
+        if (!op.path.includes('{')) {
+            // Static resource — list endpoint
+            resources.push({
+                name,
+                uri: `api://${name}`,
+                path: op.path,
+                description,
+            });
+        }
+        else {
+            // Template resource — detail endpoint with path params
+            const pathParams = op.parameters.filter((p) => p.in === 'path').map((p) => p.name);
+            const uriTemplate = `api://${name}/${pathParams.map((p) => `{${p}}`).join('/')}`;
+            // Pre-compute URL body to avoid Handlebars/curly-brace conflicts.
+            // Resource handler receives (uri: URL, extra) — extract params from uri.pathname.
+            const urlLines = [];
+            urlLines.push(`      const pathParts = uri.pathname.split('/').filter(Boolean);`);
+            urlLines.push(`      let url = \`\${config.baseUrl}${escapeStringLiteral(op.path)}\`;`);
+            // Replace path params using positional extraction from the URI
+            const pathSegments = op.path.split('/').filter(Boolean);
+            for (let i = 0; i < pathSegments.length; i++) {
+                const seg = pathSegments[i];
+                if (seg.startsWith('{') && seg.endsWith('}')) {
+                    const safe = sanitizeIdentifier(seg.slice(1, -1));
+                    urlLines.push(`      if (pathParts[${i}]) url = url.replace('${escapeStringLiteral(seg)}', encodeURIComponent(pathParts[${i}]));`);
+                }
+            }
+            resources.push({
+                name,
+                uri: uriTemplate,
+                path: op.path,
+                description,
+                isTemplate: true,
+                templateParams: pathParams,
+                urlBody: urlLines.join('\n'),
+            });
+        }
+    }
+    return resources;
+}
+/**
+ * Generate MCP prompts — one per tag as a "workflow" prompt.
+ */
+export function buildPrompts(operations) {
+    const tagGroups = new Map();
+    for (const op of operations) {
+        const tag = op.tags[0] ?? 'default';
+        const existing = tagGroups.get(tag);
+        if (existing)
+            existing.push(op);
+        else
+            tagGroups.set(tag, [op]);
+    }
+    const prompts = [];
+    for (const [tag, ops] of tagGroups) {
+        const toolList = ops
+            .map((op) => `- ${toToolName(op.operationId)}: ${op.summary ?? op.path}`)
+            .join('\\n');
+        prompts.push({
+            name: `${tag}_workflow`,
+            description: escapeTemplateLiteral(`Work with ${tag} — available operations`),
+            template: escapeTemplateLiteral(`You have the following ${tag} tools available:\\n${toolList}\\n\\nWhat would you like to do?`),
+        });
+    }
+    return prompts;
+}

package/dist/transformer/schema-merger.d.ts

@@ -0,0 +1,14 @@
+import type { JsonSchema } from '../types/index.js';
+/**
+ * Merge multiple JSON schemas into one that covers all observed fields.
+ * Uses a union approach: if a field appears in any sample, it's included
+ * (marked optional if not present in all samples).
+ */
+export declare function mergeSchemas(schemas: JsonSchema[]): JsonSchema;
+/**
+ * Merge request body schemas from multiple HAR entries in a cluster.
+ */
+export declare function mergeRequestBodySchemas(bodies: Array<{
+    text: string;
+    mimeType: string;
+}>): JsonSchema | undefined;

package/dist/transformer/schema-merger.js

@@ -0,0 +1,65 @@
+import { inferJsonSchema } from './har-schema-inferrer.js';
+/**
+ * Merge multiple JSON schemas into one that covers all observed fields.
+ * Uses a union approach: if a field appears in any sample, it's included
+ * (marked optional if not present in all samples).
+ */
+export function mergeSchemas(schemas) {
+    if (schemas.length === 0)
+        return { type: 'object' };
+    if (schemas.length === 1)
+        return schemas[0];
+    // Only merge object schemas
+    if (!schemas.every((s) => s.type === 'object'))
+        return schemas[0];
+    const allProperties = new Map();
+    const requiredCounts = new Map();
+    for (const schema of schemas) {
+        const props = (schema.properties ?? {});
+        const required = new Set(schema.required ?? []);
+        for (const [key, propSchema] of Object.entries(props)) {
+            const existing = allProperties.get(key);
+            if (existing)
+                existing.push(propSchema);
+            else
+                allProperties.set(key, [propSchema]);
+            if (required.has(key)) {
+                requiredCounts.set(key, (requiredCounts.get(key) ?? 0) + 1);
+            }
+        }
+    }
+    const mergedProperties = {};
+    const mergedRequired = [];
+    for (const [key, propSchemas] of allProperties) {
+        // Use the most common type
+        mergedProperties[key] = propSchemas[0];
+        // Only required if present in ALL samples
+        if ((requiredCounts.get(key) ?? 0) === schemas.length) {
+            mergedRequired.push(key);
+        }
+    }
+    return {
+        type: 'object',
+        properties: mergedProperties,
+        ...(mergedRequired.length > 0 ? { required: mergedRequired } : {}),
+    };
+}
+/**
+ * Merge request body schemas from multiple HAR entries in a cluster.
+ */
+export function mergeRequestBodySchemas(bodies) {
+    const schemas = [];
+    for (const body of bodies) {
+        if (!body.text || !body.mimeType.includes('json'))
+            continue;
+        try {
+            schemas.push(inferJsonSchema(JSON.parse(body.text)));
+        }
+        catch {
+            continue;
+        }
+    }
+    if (schemas.length === 0)
+        return undefined;
+    return mergeSchemas(schemas);
+}

package/dist/transformer/tool-builder.d.ts

@@ -0,0 +1,3 @@
+import type { OperationDescriptor, ToolDefinition } from '../types/index.js';
+export declare function buildToolDefinition(op: OperationDescriptor): ToolDefinition;
+export declare function buildAllTools(operations: OperationDescriptor[]): ToolDefinition[];

package/dist/transformer/tool-builder.js

@@ -0,0 +1,114 @@
+import { buildOperationInputSchema, jsonSchemaToOutputZodCode, } from '../parser/schema-converter.js';
+import { toToolName, toToolTitle, toFileName, toFunctionName } from './naming.js';
+import { escapeTemplateLiteral, escapeStringLiteral, sanitizeIdentifier, sanitizePathTemplate, } from '../utils/sanitize.js';
+export function buildToolDefinition(op) {
+    const inputSchemaCode = buildOperationInputSchema(op);
+    const descParts = [];
+    if (op.summary)
+        descParts.push(op.summary);
+    if (op.description && op.description !== op.summary)
+        descParts.push(op.description);
+    if (op.deprecated)
+        descParts.push('[DEPRECATED]');
+    if (op.mcpExtensions?.deprecationMessage) {
+        descParts.push(`[DEPRECATED: ${op.mcpExtensions.deprecationMessage}]`);
+    }
+    if (op.mcpExtensions?.deprecationReplacement) {
+        descParts.push(`Use ${op.mcpExtensions.deprecationReplacement} instead.`);
+    }
+    const description = escapeTemplateLiteral(descParts.join(' — ') || `${op.method.toUpperCase()} ${op.path}`);
+    const pathParams = op.parameters.filter((p) => p.in === 'path').map((p) => p.name);
+    const queryParams = op.parameters.filter((p) => p.in === 'query').map((p) => p.name);
+    // Apply x-mcp-* extension overrides
+    const mcpName = op.mcpExtensions?.name;
+    const mcpDesc = op.mcpExtensions?.description;
+    // Output schema from 200 response
+    const successResponse = op.responses.find((r) => r.statusCode === '200' || r.statusCode === '201');
+    const outputSchemaCode = successResponse?.schema
+        ? jsonSchemaToOutputZodCode(successResponse.schema)
+        : undefined;
+    // Annotations from HTTP method semantics
+    const annotations = buildAnnotations(op.method);
+    return {
+        name: mcpName ? sanitizeIdentifier(mcpName) : toToolName(op.operationId),
+        title: mcpName ? mcpName : toToolTitle(op.operationId),
+        description: mcpDesc ? escapeTemplateLiteral(mcpDesc) : description,
+        inputSchemaCode,
+        outputSchemaCode,
+        operationId: op.operationId,
+        method: op.method,
+        pathTemplate: op.path,
+        pathParams,
+        queryParams,
+        headerParams: op.parameters.filter((p) => p.in === 'header').map((p) => p.name),
+        hasRequestBody: !!op.requestBody,
+        requestBodyContentType: op.requestBody?.contentType ?? 'application/json',
+        fileName: toFileName(op.operationId),
+        functionName: toFunctionName(op.operationId),
+        buildUrlBody: generateBuildUrlBody(op.path, pathParams, queryParams),
+        annotations,
+        isAsync: op.responses.some((r) => r.statusCode === '202'),
+        isDestructive: op.method === 'delete',
+        jqFilter: op.mcpExtensions?.jqFilter,
+    };
+}
+function buildAnnotations(method) {
+    switch (method) {
+        case 'get':
+        case 'head':
+        case 'options':
+            return { readOnlyHint: true };
+        case 'delete':
+            return { destructiveHint: true };
+        case 'put':
+            return { idempotentHint: true };
+        default:
+            return undefined;
+    }
+}
+function generateBuildUrlBody(pathTemplate, pathParams, queryParams) {
+    const safePath = sanitizePathTemplate(pathTemplate);
+    const lines = [];
+    lines.push(`  let url = baseUrl + '${escapeStringLiteral(safePath)}';`);
+    for (const p of pathParams) {
+        const safeP = sanitizeIdentifier(p);
+        lines.push(`  url = url.replace('${escapeStringLiteral(`{${safeP}}`)}', encodeURIComponent(String(params['${escapeStringLiteral(safeP)}'])));`);
+    }
+    if (queryParams.length > 0) {
+        lines.push('  const query = new URLSearchParams();');
+        for (const q of queryParams) {
+            const safeQ = sanitizeIdentifier(q);
+            lines.push(`  if (params['${escapeStringLiteral(safeQ)}'] !== undefined) query.set('${escapeStringLiteral(safeQ)}', String(params['${escapeStringLiteral(safeQ)}']));`);
+        }
+        lines.push('  const qs = query.toString();');
+        lines.push('  return qs ? `${url}?${qs}` : url;');
+    }
+    else {
+        lines.push('  return url;');
+    }
+    return lines.join('\n');
+}
+export function buildAllTools(operations) {
+    // Filter out operations marked with x-mcp-emit: skip
+    const filtered = operations.filter((op) => op.mcpExtensions?.emit !== 'skip');
+    const tools = filtered.map(buildToolDefinition);
+    // Handle name collisions by appending method
+    const nameCount = new Map();
+    for (const t of tools) {
+        nameCount.set(t.name, (nameCount.get(t.name) ?? 0) + 1);
+    }
+    for (const tool of tools) {
+        if ((nameCount.get(tool.name) ?? 0) > 1) {
+            tool.name = `${tool.name}_${tool.method}`;
+            tool.fileName = `${tool.fileName}-${tool.method}`;
+            tool.functionName = `${tool.functionName}${tool.method.charAt(0).toUpperCase() + tool.method.slice(1)}`;
+        }
+    }
+    // Enforce MCP spec name length limit (128 chars)
+    for (const tool of tools) {
+        if (tool.name.length > 128) {
+            tool.name = tool.name.slice(0, 128);
+        }
+    }
+    return tools;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,131 @@
+export type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete' | 'head' | 'options';
+export interface ParameterDescriptor {
+    name: string;
+    in: 'path' | 'query' | 'header' | 'cookie';
+    required: boolean;
+    description?: string;
+    schema: JsonSchema;
+}
+export interface RequestBodyDescriptor {
+    required: boolean;
+    description?: string;
+    contentType: string;
+    schema: JsonSchema;
+}
+export interface ResponseDescriptor {
+    statusCode: string;
+    description?: string;
+    contentType?: string;
+    schema?: JsonSchema;
+}
+export interface SecurityRequirement {
+    schemeName: string;
+    scopes: string[];
+}
+export interface McpExtensions {
+    name?: string;
+    description?: string;
+    emit?: 'tool' | 'resource' | 'prompt' | 'skip';
+    scope?: 'read' | 'write' | 'destructive';
+    /** Deprecation message surfaced in tool description */
+    deprecationMessage?: string;
+    /** Replacement tool name for deprecated operations */
+    deprecationReplacement?: string;
+    /** JQ filter expression to trim API responses before returning to agent */
+    jqFilter?: string;
+    /** Allow unknown enum values for forward compatibility */
+    unknownValues?: 'allow' | 'reject';
+}
+export interface OperationDescriptor {
+    operationId: string;
+    method: HttpMethod;
+    path: string;
+    summary?: string;
+    description?: string;
+    tags: string[];
+    parameters: ParameterDescriptor[];
+    requestBody?: RequestBodyDescriptor;
+    responses: ResponseDescriptor[];
+    security: SecurityRequirement[];
+    deprecated: boolean;
+    mcpExtensions?: McpExtensions;
+}
+export interface ToolAnnotations {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+}
+export interface ToolDefinition {
+    name: string;
+    title: string;
+    description: string;
+    inputSchemaCode: string;
+    outputSchemaCode?: string;
+    operationId: string;
+    method: HttpMethod;
+    pathTemplate: string;
+    pathParams: string[];
+    queryParams: string[];
+    headerParams: string[];
+    hasRequestBody: boolean;
+    requestBodyContentType: string;
+    fileName: string;
+    functionName: string;
+    buildUrlBody: string;
+    annotations?: ToolAnnotations;
+    isAsync?: boolean;
+    isDestructive?: boolean;
+    /** JQ filter to apply to API response before returning to agent */
+    jqFilter?: string;
+}
+export type AuthType = 'apiKey' | 'http-bearer' | 'http-basic' | 'oauth2';
+export interface AuthScheme {
+    type: AuthType;
+    envVarName: string;
+    headerName?: string;
+    in?: 'header' | 'query' | 'cookie';
+    description?: string;
+}
+export interface EnvVarDescriptor {
+    name: string;
+    description: string;
+    required: boolean;
+    example?: string;
+}
+export type TransportMode = 'stdio' | 'http';
+/**
+ * Deployment target for the generated TypeScript server.
+ * `node` (default) emits a Node.js server (stdio or node:http); `cloudflare`
+ * emits a stateless Cloudflare Workers Fetch handler.
+ */
+export type EmitTarget = 'node' | 'cloudflare';
+export interface ResourceDefinition {
+    name: string;
+    uri: string;
+    path: string;
+    description: string;
+    isTemplate?: boolean;
+    templateParams?: string[];
+    urlBody?: string;
+}
+export interface PromptDefinition {
+    name: string;
+    description: string;
+    template: string;
+}
+export interface ProjectManifest {
+    serverName: string;
+    serverVersion: string;
+    baseUrl: string;
+    transport: TransportMode;
+    tools: ToolDefinition[];
+    resources?: ResourceDefinition[];
+    prompts?: PromptDefinition[];
+    authSchemes: AuthScheme[];
+    envVars: EnvVarDescriptor[];
+    dynamicDiscovery?: boolean;
+    staticToolCount?: number;
+    /** Deployment target (default `node`). `cloudflare` emits a Workers project. */
+    target?: EmitTarget;
+}
+export type JsonSchema = Record<string, unknown>;

package/dist/types/index.js

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