mcpmake 0.1.0

package/dist/commands/from/website.js

@@ -0,0 +1,284 @@
+import { defineConfigurableCommand } from '../../config/configurable-command.js';
+import { crawlSite } from '../../analyzer/site-crawler.js';
+import { goalDirectedCrawl } from '../../analyzer/goal-crawler.js';
+import { classifyForms } from '../../analyzer/hybrid-detector.js';
+import { analyzeSemantics } from '../../analyzer/semantic-analyzer.js';
+import { detectAuthFlow } from '../../analyzer/auth-detector.js';
+import { generateSiteTools } from '../../site-transformer/tool-generator.js';
+import { filterHarEntries } from '../../parser/har-filter.js';
+import { normalizeEntry } from '../../parser/har-normalizer.js';
+import { clusterEntries } from '../../transformer/har-clusterer.js';
+import { clustersToOperations } from '../../transformer/har-to-operations.js';
+import { deduplicateEntries } from '../../transformer/har-dedup.js';
+import { buildAllTools } from '../../transformer/tool-builder.js';
+import { emitSiteProject } from '../../emitter/index.js';
+import { logger } from '../../utils/logger.js';
+import { fail } from '../../utils/fail.js';
+function toPackageName(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+export default defineConfigurableCommand('website', {
+    meta: {
+        name: 'website',
+        description: "Generate a Playwright-based MCP server by analyzing a website's DOM",
+    },
+    args: {
+        url: {
+            type: 'positional',
+            description: 'URL of the website to analyze',
+            required: true,
+        },
+        output: {
+            type: 'string',
+            alias: 'o',
+            description: 'Output directory for generated project',
+            required: true,
+        },
+        name: {
+            type: 'string',
+            alias: 'n',
+            description: 'Server name (defaults to hostname)',
+        },
+        depth: {
+            type: 'string',
+            description: 'Crawl depth (default: 2)',
+            default: '2',
+        },
+        'max-pages': {
+            type: 'string',
+            description: 'Maximum pages to crawl (default: 20)',
+            default: '20',
+        },
+        timeout: {
+            type: 'string',
+            description: 'Idle timeout in seconds (default: 300)',
+            default: '300',
+        },
+        transport: {
+            type: 'string',
+            alias: 't',
+            description: 'Transport mode: "stdio" (default) or "http"',
+            default: 'stdio',
+        },
+        headless: {
+            type: 'boolean',
+            description: 'Run browser in headless mode during analysis',
+            default: false,
+        },
+        force: {
+            type: 'boolean',
+            alias: 'f',
+            description: 'Overwrite existing output directory',
+            default: false,
+        },
+        'dry-run': {
+            type: 'boolean',
+            description: 'Preview generated files without writing',
+            default: false,
+        },
+        'improve-names': {
+            type: 'boolean',
+            description: 'Use LLM to infer semantic names for forms, buttons, and links',
+            default: false,
+        },
+        'max-sessions': {
+            type: 'string',
+            description: 'Maximum concurrent browser sessions for the generated server (default: 10)',
+            default: '10',
+        },
+        hybrid: {
+            type: 'boolean',
+            description: 'Hybrid mode: use HTTP fetch for API-backed forms and Playwright for browser-only forms',
+            default: false,
+        },
+        goal: {
+            type: 'string',
+            description: 'Goal-directed crawl: use an LLM to navigate toward a goal instead of BFS crawling (requires ANTHROPIC_API_KEY)',
+        },
+    },
+    async run({ args }) {
+        const url = args.url;
+        const depth = parseInt(args.depth ?? '2', 10);
+        const maxPages = parseInt(args['max-pages'] ?? '20', 10);
+        const timeoutMs = parseInt(args.timeout ?? '300', 10) * 1000;
+        const maxSessions = parseInt(args['max-sessions'] ?? '10', 10);
+        const hybridMode = args.hybrid ?? false;
+        const goal = args.goal;
+        // Validate URL
+        let parsedUrl;
+        try {
+            parsedUrl = new URL(url);
+        }
+        catch (err) {
+            return await fail(`Invalid URL: ${url}`, err);
+        }
+        logger.info(`Analyzing website: ${url}`);
+        let siteDescriptor;
+        let screenshots;
+        let harEntries;
+        if (goal) {
+            // Goal-directed crawl: use LLM to navigate toward the goal
+            logger.info(`Goal-directed crawl: "${goal}"`);
+            const result = await goalDirectedCrawl({
+                url,
+                goal,
+                maxSteps: maxPages,
+                headless: args.headless ?? false,
+            });
+            siteDescriptor = result.siteDescriptor;
+            screenshots = result.screenshots;
+        }
+        else {
+            // Standard BFS crawl (with optional HAR capture for hybrid mode)
+            logger.info(`Crawl depth: ${depth}, Max pages: ${maxPages}`);
+            const result = await crawlSite({
+                url,
+                depth,
+                maxPages,
+                timeout: timeoutMs,
+                headless: args.headless ?? false,
+                captureHar: hybridMode,
+            });
+            siteDescriptor = result.siteDescriptor;
+            screenshots = result.screenshots;
+            harEntries = result.harEntries;
+        }
+        const totalForms = siteDescriptor.pages.reduce((n, p) => n + p.forms.length, 0);
+        const totalButtons = siteDescriptor.pages.reduce((n, p) => n + p.buttons.length, 0);
+        const totalLinks = siteDescriptor.pages.reduce((n, p) => n + p.links.length, 0);
+        logger.info(`Discovered: ${siteDescriptor.pages.length} pages, ${totalForms} forms, ${totalButtons} buttons, ${totalLinks} links`);
+        logger.info(`Screenshots captured: ${screenshots.size}`);
+        if (siteDescriptor.pages.length === 0) {
+            await fail('No pages could be analyzed. Check the URL and try again.');
+        }
+        // Semantic analysis (optional, requires ANTHROPIC_API_KEY)
+        if (args['improve-names']) {
+            siteDescriptor.pages = await analyzeSemantics(siteDescriptor.pages, screenshots);
+        }
+        // Auth flow detection
+        const authFlow = detectAuthFlow(siteDescriptor.pages);
+        if (authFlow) {
+            siteDescriptor.authFlow = authFlow;
+        }
+        // Generate browser-based tools from site descriptor
+        const siteTools = generateSiteTools(siteDescriptor);
+        // Hybrid mode: classify forms and merge API tools with browser tools
+        let tools;
+        let hybridClassifications;
+        if (hybridMode && harEntries && harEntries.length > 0) {
+            logger.info(`Hybrid mode: analyzing ${harEntries.length} captured network requests`);
+            // Classify all forms
+            const allForms = siteDescriptor.pages.flatMap((p) => p.forms);
+            hybridClassifications = classifyForms(allForms, harEntries);
+            const apiFormIds = new Set(hybridClassifications.filter((c) => c.strategy === 'api').map((c) => c.formId));
+            const apiCount = apiFormIds.size;
+            const browserCount = hybridClassifications.length - apiCount;
+            logger.info(`Hybrid classification: ${apiCount} API-backed forms, ${browserCount} browser-only forms`);
+            // Build API tools from HAR entries
+            const targetHost = new URL(url).hostname;
+            const filteredHar = filterHarEntries(harEntries, {
+                allowedDomains: [targetHost],
+                includeErrors: false,
+            });
+            if (filteredHar.length > 0) {
+                const normalized = filteredHar.map(normalizeEntry);
+                const deduped = deduplicateEntries(normalized);
+                const clusters = clusterEntries(deduped);
+                const { operations } = clustersToOperations(clusters);
+                const apiTools = buildAllTools(operations);
+                // Remove browser-based form tools that have API equivalents
+                const browserTools = siteTools.filter((tool) => {
+                    if (tool.form && apiFormIds.has(tool.form.formId)) {
+                        return false; // Prefer the API tool
+                    }
+                    return true;
+                });
+                // Convert API ToolDefinitions to SiteToolDefinitions for uniform output
+                const apiSiteTools = apiTools.map((apiTool) => ({
+                    name: apiTool.name,
+                    title: apiTool.title,
+                    description: `[API] ${apiTool.description}`,
+                    inputSchemaCode: apiTool.inputSchemaCode,
+                    fileName: apiTool.fileName,
+                    functionName: apiTool.functionName,
+                    toolType: 'page-action',
+                    selectors: [],
+                    returnsScreenshot: false,
+                    annotations: apiTool.annotations,
+                }));
+                tools = [...browserTools, ...apiSiteTools];
+                // Deduplicate by name
+                const seenNames = new Set();
+                tools = tools.filter((tool) => {
+                    if (seenNames.has(tool.name))
+                        return false;
+                    seenNames.add(tool.name);
+                    return true;
+                });
+            }
+            else {
+                tools = siteTools;
+            }
+        }
+        else {
+            tools = siteTools;
+        }
+        logger.info(`Generated ${tools.length} MCP tools`);
+        if (tools.length === 0) {
+            await fail('No interactive elements found on the site.');
+        }
+        // Build manifest
+        const serverName = args.name ?? toPackageName(parsedUrl.hostname);
+        const transport = args.transport === 'http' ? 'http' : 'stdio';
+        const browserConfig = {
+            headless: true,
+            idleTimeoutMs: 5 * 60 * 1000,
+            viewport: { width: 1280, height: 720 },
+            maxSessions,
+        };
+        const manifest = {
+            serverName,
+            serverVersion: '1.0.0',
+            baseUrl: siteDescriptor.baseUrl,
+            transport: transport,
+            siteDescriptor,
+            tools,
+            envVars: [
+                {
+                    name: 'BASE_URL',
+                    description: 'Target website URL',
+                    required: true,
+                    example: siteDescriptor.baseUrl,
+                },
+            ],
+            browserConfig,
+        };
+        // Emit the project
+        logger.info(`Generating Playwright MCP server: ${serverName}`);
+        await emitSiteProject(manifest, {
+            outputDir: args.output,
+            force: args.force ?? false,
+            dryRun: args['dry-run'] ?? false,
+        });
+        logger.success(`Site MCP server generated at: ${args.output}`);
+        logger.info('');
+        logger.info(`Pages analyzed: ${siteDescriptor.pages.length}`);
+        logger.info(`Tools generated: ${tools.length}`);
+        logger.info('');
+        logger.info('Tools:');
+        for (const tool of tools) {
+            const typeTag = `[${tool.toolType}]`;
+            logger.info(`  ${tool.name} ${typeTag} — ${tool.description.slice(0, 60)}`);
+        }
+        logger.info('');
+        logger.info('Next steps:');
+        logger.info(`  cd ${args.output}`);
+        logger.info('  npm install');
+        logger.info('  npx playwright install chromium');
+        logger.info('  npm run build');
+        logger.info('  npm start');
+    },
+});

package/dist/commands/lint.d.ts

@@ -0,0 +1,24 @@
+export interface LintResult {
+    level: 'error' | 'warn' | 'info';
+    rule: string;
+    tool: string;
+    message: string;
+}
+declare const _default: import("citty").CommandDef<{
+    spec: {
+        type: "positional";
+        description: string;
+        required: true;
+    };
+    format: {
+        type: "string";
+        description: string;
+        default: string;
+    };
+    level: {
+        type: "string";
+        description: string;
+        default: string;
+    };
+}>;
+export default _default;

package/dist/commands/lint.js

@@ -0,0 +1,184 @@
+import { defineCommand } from 'citty';
+import { loadOpenApiSpec } from '../parser/openapi-loader.js';
+import { extractOperations } from '../parser/operation-extractor.js';
+import { buildAllTools } from '../transformer/tool-builder.js';
+import { logger } from '../utils/logger.js';
+import { fail } from '../utils/fail.js';
+const MCP_BUILT_INS = new Set([
+    'ping',
+    'initialize',
+    'notifications/initialized',
+    'notifications/cancelled',
+    'notifications/progress',
+    'tools/list',
+    'tools/call',
+    'resources/list',
+    'resources/read',
+    'resources/subscribe',
+    'resources/unsubscribe',
+    'prompts/list',
+    'prompts/get',
+    'logging/setLevel',
+    'completion/complete',
+    'sampling/createMessage',
+    'roots/list',
+]);
+function lintTools(tools) {
+    const results = [];
+    // duplicate-names: check for collisions
+    const nameCount = new Map();
+    for (const tool of tools) {
+        nameCount.set(tool.name, (nameCount.get(tool.name) ?? 0) + 1);
+    }
+    for (const [name, count] of nameCount) {
+        if (count > 1) {
+            results.push({
+                level: 'error',
+                rule: 'duplicate-names',
+                tool: name,
+                message: `Tool name "${name}" is used ${count} times — names must be unique`,
+            });
+        }
+    }
+    for (const tool of tools) {
+        // tool-name-length
+        if (tool.name.length > 128) {
+            results.push({
+                level: 'error',
+                rule: 'tool-name-length',
+                tool: tool.name,
+                message: `Name is ${tool.name.length} chars — exceeds MCP spec limit of 128`,
+            });
+        }
+        else if (tool.name.length > 60) {
+            results.push({
+                level: 'warn',
+                rule: 'tool-name-length',
+                tool: tool.name,
+                message: `Name is ${tool.name.length} chars — exceeds Cursor limit of 60`,
+            });
+        }
+        // description-quality
+        if (!tool.description || tool.description.trim().length === 0) {
+            results.push({
+                level: 'warn',
+                rule: 'description-quality',
+                tool: tool.name,
+                message: 'Description is empty — AI clients need good descriptions to pick the right tool',
+            });
+        }
+        else if (tool.description.trim().length < 10) {
+            results.push({
+                level: 'warn',
+                rule: 'description-quality',
+                tool: tool.name,
+                message: `Description is only ${tool.description.trim().length} chars — consider adding more detail`,
+            });
+        }
+        // description-length
+        if (tool.description && tool.description.length > 1024) {
+            results.push({
+                level: 'warn',
+                rule: 'description-length',
+                tool: tool.name,
+                message: `Description is ${tool.description.length} chars — over 1024 wastes context window`,
+            });
+        }
+        // parameter-count
+        const paramCount = tool.pathParams.length +
+            tool.queryParams.length +
+            tool.headerParams.length +
+            (tool.hasRequestBody ? 1 : 0);
+        if (paramCount > 10) {
+            results.push({
+                level: 'warn',
+                rule: 'parameter-count',
+                tool: tool.name,
+                message: `Has ${paramCount} parameters — more than 10 is complex for AI to fill correctly`,
+            });
+        }
+        // missing-annotations
+        if (!tool.annotations) {
+            results.push({
+                level: 'info',
+                rule: 'missing-annotations',
+                tool: tool.name,
+                message: 'No readOnlyHint/destructiveHint annotations set — consider adding for safety',
+            });
+        }
+        // reserved-names
+        if (MCP_BUILT_INS.has(tool.name)) {
+            results.push({
+                level: 'error',
+                rule: 'reserved-names',
+                tool: tool.name,
+                message: `"${tool.name}" conflicts with MCP built-in method name`,
+            });
+        }
+    }
+    return results;
+}
+export default defineCommand({
+    meta: {
+        name: 'lint',
+        description: 'Lint an OpenAPI spec for MCP compatibility issues',
+    },
+    args: {
+        spec: {
+            type: 'positional',
+            description: 'Path or URL to an OpenAPI spec',
+            required: true,
+        },
+        format: {
+            type: 'string',
+            description: 'Output format: "text" (default) or "json"',
+            default: 'text',
+        },
+        level: {
+            type: 'string',
+            description: 'Minimum level to show: "info", "warn", or "error"',
+            default: 'info',
+        },
+    },
+    async run({ args }) {
+        logger.info(`Linting spec: ${args.spec}`);
+        const { api } = await loadOpenApiSpec(args.spec);
+        const { operations } = extractOperations(api);
+        if (operations.length === 0) {
+            await fail('No operations found in the spec.');
+        }
+        const tools = buildAllTools(operations);
+        logger.info(`Analyzing ${tools.length} tools...\n`);
+        const allResults = lintTools(tools);
+        // Filter by level
+        const levelOrder = { info: 0, warn: 1, error: 2 };
+        const minLevel = levelOrder[args.level ?? 'info'] ?? 0;
+        const results = allResults.filter((r) => levelOrder[r.level] >= minLevel);
+        if (args.format === 'json') {
+            console.log(JSON.stringify(results, null, 2));
+        }
+        else {
+            const icons = { error: 'ERROR', warn: 'WARN ', info: 'INFO ' };
+            for (const r of results) {
+                const icon = icons[r.level];
+                console.log(`  ${icon}  [${r.rule}] ${r.tool}: ${r.message}`);
+            }
+            // Summary
+            const errors = allResults.filter((r) => r.level === 'error').length;
+            const warns = allResults.filter((r) => r.level === 'warn').length;
+            const infos = allResults.filter((r) => r.level === 'info').length;
+            console.log('');
+            console.log(`  ${tools.length} tools, ${allResults.length} issues: ${errors} errors, ${warns} warnings, ${infos} info`);
+            if (errors > 0) {
+                console.log('');
+            }
+            else if (allResults.length === 0) {
+                logger.success('No issues found');
+            }
+        }
+        // Exit code 1 if any errors
+        if (allResults.some((r) => r.level === 'error')) {
+            await fail('Lint failed with errors');
+        }
+    },
+});

package/dist/commands/merge.d.ts

@@ -0,0 +1,18 @@
+declare const _default: import("citty").CommandDef<{
+    spec1: {
+        type: "positional";
+        description: string;
+        required: true;
+    };
+    spec2: {
+        type: "positional";
+        description: string;
+        required: true;
+    };
+    output: {
+        type: "string";
+        alias: string;
+        description: string;
+    };
+}>;
+export default _default;

package/dist/commands/merge.js

@@ -0,0 +1,161 @@
+import { defineCommand } from 'citty';
+import { writeFile } from 'node:fs/promises';
+import { stringify as yamlStringify } from 'yaml';
+import { loadOpenApiSpec } from '../parser/openapi-loader.js';
+import { logger } from '../utils/logger.js';
+export default defineCommand({
+    meta: {
+        name: 'merge',
+        description: 'Merge two OpenAPI specs into one',
+    },
+    args: {
+        spec1: {
+            type: 'positional',
+            description: 'Path to the first OpenAPI spec (used as base for info/servers)',
+            required: true,
+        },
+        spec2: {
+            type: 'positional',
+            description: 'Path to the second OpenAPI spec to merge in',
+            required: true,
+        },
+        output: {
+            type: 'string',
+            alias: 'o',
+            description: 'Output file path (default: stdout)',
+        },
+    },
+    async run({ args }) {
+        logger.info(`Merging specs: ${args.spec1} + ${args.spec2}`);
+        const { api: api1 } = await loadOpenApiSpec(args.spec1);
+        const { api: api2 } = await loadOpenApiSpec(args.spec2);
+        const spec1 = api1;
+        const spec2 = api2;
+        const merged = mergeSpecs(spec1, spec2);
+        const output = yamlStringify(merged, { lineWidth: 120 });
+        if (args.output) {
+            await writeFile(args.output, output, 'utf-8');
+            logger.success(`Merged spec written to: ${args.output}`);
+        }
+        else {
+            process.stdout.write(output);
+        }
+    },
+});
+function mergeSpecs(base, other) {
+    const merged = {
+        openapi: base.openapi ?? '3.0.0',
+        info: base.info,
+        servers: base.servers,
+        paths: { ...base.paths },
+        components: {
+            schemas: {},
+            securitySchemes: {},
+            ...(base.components ?? {}),
+        },
+    };
+    // Merge paths
+    const basePaths = base.paths ?? {};
+    const otherPaths = other.paths ?? {};
+    for (const [path, pathItem] of Object.entries(otherPaths)) {
+        if (basePaths[path]) {
+            // Check for method-level conflicts
+            const baseItem = basePaths[path];
+            const otherItem = pathItem;
+            const methods = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
+            for (const method of methods) {
+                if (baseItem[method] && otherItem[method]) {
+                    throw new Error(`Path conflict: ${method.toUpperCase()} ${path} exists in both specs`);
+                }
+            }
+            // No method conflicts — merge path items
+            merged.paths[path] = { ...baseItem, ...otherItem };
+        }
+        else {
+            merged.paths[path] = pathItem;
+        }
+    }
+    // Merge components.schemas
+    const baseSchemas = base.components?.schemas ?? {};
+    const otherSchemas = other.components?.schemas ?? {};
+    for (const [name, schema] of Object.entries(otherSchemas)) {
+        if (baseSchemas[name]) {
+            throw new Error(`Schema conflict: "${name}" exists in both specs`);
+        }
+        merged.components.schemas[name] = schema;
+    }
+    // Merge components.securitySchemes
+    const baseSecSchemes = base.components?.securitySchemes ?? {};
+    const otherSecSchemes = other.components?.securitySchemes ?? {};
+    for (const [name, scheme] of Object.entries(otherSecSchemes)) {
+        if (baseSecSchemes[name]) {
+            // If both have the same security scheme name, check if they're identical
+            const baseScheme = JSON.stringify(baseSecSchemes[name]);
+            const otherScheme = JSON.stringify(scheme);
+            if (baseScheme !== otherScheme) {
+                throw new Error(`Security scheme conflict: "${name}" differs between specs`);
+            }
+            // Same scheme — skip silently
+        }
+        else {
+            merged.components.securitySchemes[name] = scheme;
+        }
+    }
+    // Merge other component types if present
+    const componentTypes = [
+        'parameters',
+        'requestBodies',
+        'responses',
+        'headers',
+        'examples',
+        'links',
+        'callbacks',
+    ];
+    for (const compType of componentTypes) {
+        const baseComp = base.components?.[compType];
+        const otherComp = other.components?.[compType];
+        if (otherComp) {
+            if (!baseComp) {
+                merged.components[compType] = { ...otherComp };
+            }
+            else {
+                for (const [name, value] of Object.entries(otherComp)) {
+                    if (baseComp[name]) {
+                        throw new Error(`Component conflict in ${compType}: "${name}" exists in both specs`);
+                    }
+                    merged.components[compType][name] = value;
+                }
+            }
+        }
+    }
+    // Merge tags (deduplicate by name)
+    if (base.tags || other.tags) {
+        const tagMap = new Map();
+        for (const tag of base.tags ?? []) {
+            tagMap.set(tag.name, tag);
+        }
+        for (const tag of other.tags ?? []) {
+            if (!tagMap.has(tag.name)) {
+                tagMap.set(tag.name, tag);
+            }
+        }
+        merged.tags = [...tagMap.values()];
+    }
+    // Merge top-level security (union)
+    if (base.security || other.security) {
+        const seen = new Set();
+        const mergedSecurity = [];
+        for (const req of [...(base.security ?? []), ...(other.security ?? [])]) {
+            const key = JSON.stringify(req);
+            if (!seen.has(key)) {
+                seen.add(key);
+                mergedSecurity.push(req);
+            }
+        }
+        merged.security = mergedSecurity;
+    }
+    const pathCount = Object.keys(merged.paths).length;
+    const schemaCount = Object.keys(merged.components?.schemas ?? {}).length;
+    logger.info(`Merged result: ${pathCount} paths, ${schemaCount} schemas`);
+    return merged;
+}