mcpmake 0.1.0 → 0.2.0

package/dist/analyzer/hybrid-detector.js

@@ -1,96 +0,0 @@
-/**
- * Hybrid Detector: classifies form elements as either API-backed or browser-only.
- *
- * After crawling a site, we have both DOM forms (from dom-parser) and network
- * requests captured during the crawl (HAR entries). This module correlates them:
- * - If a form submission triggers a JSON API call, mark it as 'api' (use HTTP fetch)
- * - If a form has no corresponding API call, mark it as 'browser' (use Playwright)
- */
-import { logger } from '../utils/logger.js';
-const JSON_MIME_TYPES = [
-    'application/json',
-    'application/ld+json',
-    'application/vnd.api+json',
-    'text/json',
-];
-/**
- * Classify each form as either API-backed or browser-only.
- *
- * Matching heuristics:
- * 1. If the form's action URL matches a HAR entry URL, and that entry
- *    has a JSON response, classify as 'api'.
- * 2. If a HAR entry was a POST/PUT/PATCH to the same path as the form action,
- *    classify as 'api'.
- * 3. If a HAR entry's URL path contains the form action's path segment,
- *    and the entry has a JSON response, classify as 'api'.
- * 4. Otherwise, classify as 'browser'.
- */
-export function classifyForms(forms, harEntries) {
-    // Pre-filter HAR entries to only JSON-responding API calls
-    const apiEntries = harEntries.filter((entry) => {
-        const responseMime = entry.response.content?.mimeType ?? '';
-        return JSON_MIME_TYPES.some((m) => responseMime.includes(m));
-    });
-    logger.debug(`Hybrid detector: ${forms.length} forms, ${apiEntries.length} JSON API entries`);
-    return forms.map((form) => {
-        const match = findMatchingApiEntry(form, apiEntries);
-        if (match) {
-            logger.debug(`Form ${form.formId} → API endpoint: ${match}`);
-            return {
-                formId: form.formId,
-                strategy: 'api',
-                apiEndpoint: match,
-            };
-        }
-        logger.debug(`Form ${form.formId} → browser-only`);
-        return {
-            formId: form.formId,
-            strategy: 'browser',
-        };
-    });
-}
-/**
- * Try to find a HAR entry that corresponds to the given form submission.
- * Returns the API endpoint URL if found, or undefined.
- */
-function findMatchingApiEntry(form, apiEntries) {
-    if (!form.action)
-        return undefined;
-    let formActionPath;
-    try {
-        const actionUrl = new URL(form.action);
-        formActionPath = actionUrl.pathname;
-    }
-    catch {
-        // Relative URL — use as-is
-        formActionPath = form.action;
-    }
-    // Normalize: remove trailing slash
-    formActionPath = formActionPath.replace(/\/$/, '');
-    if (!formActionPath || formActionPath === '')
-        return undefined;
-    for (const entry of apiEntries) {
-        const entryMethod = entry.request.method.toUpperCase();
-        // Only match mutating methods for form submissions
-        if (!['POST', 'PUT', 'PATCH', 'DELETE'].includes(entryMethod) && form.method === 'post') {
-            continue;
-        }
-        let entryPath;
-        try {
-            entryPath = new URL(entry.request.url).pathname.replace(/\/$/, '');
-        }
-        catch {
-            continue;
-        }
-        // Exact path match
-        if (entryPath === formActionPath) {
-            return entry.request.url;
-        }
-        // Path containment: the form action path is a prefix of the entry path
-        // (e.g., form action="/api/users" matches entry "/api/users/register")
-        if (entryPath.startsWith(formActionPath + '/') || formActionPath.startsWith(entryPath + '/')) {
-            return entry.request.url;
-        }
-    }
-    return undefined;
-}

package/dist/analyzer/index.d.ts

@@ -1,12 +0,0 @@
-export { crawlSite } from './site-crawler.js';
-export type { CrawlOptions, CrawlResult } from './site-crawler.js';
-export { parsePage } from './dom-parser.js';
-export { buildSelectorSet, validateSelector } from './selector-builder.js';
-export { captureFullPageScreenshot, captureViewportScreenshot, hashScreenshot, } from './screenshot-capture.js';
-export type { ScreenshotResult } from './screenshot-capture.js';
-export { analyzeSemantics } from './semantic-analyzer.js';
-export { detectAuthFlow } from './auth-detector.js';
-export { classifyForms } from './hybrid-detector.js';
-export type { HybridClassification } from './hybrid-detector.js';
-export { goalDirectedCrawl } from './goal-crawler.js';
-export type { GoalCrawlOptions } from './goal-crawler.js';

package/dist/analyzer/index.js

@@ -1,8 +0,0 @@
-export { crawlSite } from './site-crawler.js';
-export { parsePage } from './dom-parser.js';
-export { buildSelectorSet, validateSelector } from './selector-builder.js';
-export { captureFullPageScreenshot, captureViewportScreenshot, hashScreenshot, } from './screenshot-capture.js';
-export { analyzeSemantics } from './semantic-analyzer.js';
-export { detectAuthFlow } from './auth-detector.js';
-export { classifyForms } from './hybrid-detector.js';
-export { goalDirectedCrawl } from './goal-crawler.js';

package/dist/analyzer/screenshot-capture.d.ts

@@ -1,29 +0,0 @@
-/**
- * Captures and hashes screenshots during site analysis.
- * Screenshots serve as the baseline for rescan comparison
- * and are returned with every tool call at runtime.
- */
-import type { Page } from 'playwright';
-export interface ScreenshotResult {
-    /** Raw PNG buffer */
-    data: Buffer;
-    /** SHA-256 hash for deduplication */
-    hash: string;
-    /** Viewport dimensions at capture time */
-    viewport: {
-        width: number;
-        height: number;
-    };
-}
-/**
- * Take a full-page screenshot and compute its hash.
- */
-export declare function captureFullPageScreenshot(page: Page): Promise<ScreenshotResult>;
-/**
- * Take a viewport-only screenshot (what the user sees).
- */
-export declare function captureViewportScreenshot(page: Page): Promise<ScreenshotResult>;
-/**
- * Compute SHA-256 hash of a screenshot buffer.
- */
-export declare function hashScreenshot(data: Buffer): string;

package/dist/analyzer/screenshot-capture.js

@@ -1,42 +0,0 @@
-/**
- * Captures and hashes screenshots during site analysis.
- * Screenshots serve as the baseline for rescan comparison
- * and are returned with every tool call at runtime.
- */
-import crypto from 'node:crypto';
-/**
- * Take a full-page screenshot and compute its hash.
- */
-export async function captureFullPageScreenshot(page) {
-    const data = await page.screenshot({
-        type: 'png',
-        fullPage: true,
-    });
-    const viewport = page.viewportSize() ?? { width: 1280, height: 720 };
-    return {
-        data,
-        hash: hashScreenshot(data),
-        viewport,
-    };
-}
-/**
- * Take a viewport-only screenshot (what the user sees).
- */
-export async function captureViewportScreenshot(page) {
-    const data = await page.screenshot({
-        type: 'png',
-        fullPage: false,
-    });
-    const viewport = page.viewportSize() ?? { width: 1280, height: 720 };
-    return {
-        data,
-        hash: hashScreenshot(data),
-        viewport,
-    };
-}
-/**
- * Compute SHA-256 hash of a screenshot buffer.
- */
-export function hashScreenshot(data) {
-    return crypto.createHash('sha256').update(data).digest('hex');
-}

package/dist/analyzer/selector-builder.d.ts

@@ -1,19 +0,0 @@
-/**
- * Builds multi-strategy selector sets for DOM elements.
- *
- * Generates selectors in priority order (most stable first):
- * data-testid > id > aria-label > name > role > CSS path > XPath
- */
-import type { Page, ElementHandle } from 'playwright';
-import type { SelectorSet } from '../types/site.js';
-/**
- * Build a SelectorSet for a given element on the page.
- * Tries multiple strategies and picks the most stable one as primary.
- */
-export declare function buildSelectorSet(page: Page, element: ElementHandle): Promise<SelectorSet>;
-/**
- * Validate that a selector still resolves to an element on the page.
- * Tries the primary selector first, then fallbacks.
- * Returns the first working selector or null if all fail.
- */
-export declare function validateSelector(page: Page, selectorSet: SelectorSet): Promise<string | null>;

package/dist/analyzer/selector-builder.js

@@ -1,199 +0,0 @@
-/**
- * Builds multi-strategy selector sets for DOM elements.
- *
- * Generates selectors in priority order (most stable first):
- * data-testid > id > aria-label > name > role > CSS path > XPath
- */
-/**
- * Build a SelectorSet for a given element on the page.
- * Tries multiple strategies and picks the most stable one as primary.
- */
-export async function buildSelectorSet(page, element) {
-    const candidates = [];
-    const attrs = await element.evaluate((node) => {
-        const el = node;
-        return {
-            tagName: el.tagName.toLowerCase(),
-            id: el.id || null,
-            name: el.getAttribute('name'),
-            type: el.getAttribute('type'),
-            testId: el.getAttribute('data-testid') || el.getAttribute('data-test-id'),
-            ariaLabel: el.getAttribute('aria-label'),
-            role: el.getAttribute('role') || null,
-            placeholder: el.getAttribute('placeholder'),
-            textContent: el.textContent?.trim().slice(0, 80) || null,
-            className: el.className || null,
-        };
-    });
-    // 1. data-testid (most stable — intentionally placed for testing)
-    if (attrs.testId) {
-        candidates.push({
-            selector: `[data-testid="${cssEscape(attrs.testId)}"]`,
-            strategy: 'data-testid',
-            confidence: 0.95,
-        });
-    }
-    // 2. id (stable if present, but may be auto-generated)
-    if (attrs.id && !looksAutoGenerated(attrs.id)) {
-        candidates.push({
-            selector: `#${cssEscape(attrs.id)}`,
-            strategy: 'id',
-            confidence: 0.9,
-        });
-    }
-    // 3. aria-label (stable for accessible sites)
-    if (attrs.ariaLabel) {
-        candidates.push({
-            selector: `${attrs.tagName}[aria-label="${cssEscape(attrs.ariaLabel)}"]`,
-            strategy: 'aria-label',
-            confidence: 0.85,
-        });
-    }
-    // 4. name attribute (stable for form elements)
-    if (attrs.name) {
-        const typeQualifier = attrs.type ? `[type="${attrs.type}"]` : '';
-        candidates.push({
-            selector: `${attrs.tagName}[name="${cssEscape(attrs.name)}"]${typeQualifier}`,
-            strategy: 'name',
-            confidence: 0.85,
-        });
-    }
-    // 5. role + text (for buttons/links with visible text)
-    if (attrs.role && attrs.textContent) {
-        const shortText = attrs.textContent.slice(0, 40);
-        candidates.push({
-            selector: `${attrs.tagName}[role="${attrs.role}"]:has-text("${cssEscape(shortText)}")`,
-            strategy: 'role',
-            confidence: 0.7,
-        });
-    }
-    // 6. CSS path (always available but fragile)
-    const cssPath = await buildCssPath(element);
-    if (cssPath) {
-        candidates.push({
-            selector: cssPath,
-            strategy: 'css-path',
-            confidence: 0.4,
-        });
-    }
-    // Sort by confidence descending
-    candidates.sort((a, b) => b.confidence - a.confidence);
-    if (candidates.length === 0) {
-        // Absolute fallback: XPath
-        const xpath = await buildXPath(element);
-        return {
-            primary: xpath,
-            fallbacks: [],
-            strategy: 'xpath',
-            confidence: 0.2,
-        };
-    }
-    const primary = candidates[0];
-    const fallbacks = candidates.slice(1).map((c) => c.selector);
-    return {
-        primary: primary.selector,
-        fallbacks,
-        strategy: primary.strategy,
-        confidence: primary.confidence,
-    };
-}
-/**
- * Validate that a selector still resolves to an element on the page.
- * Tries the primary selector first, then fallbacks.
- * Returns the first working selector or null if all fail.
- */
-export async function validateSelector(page, selectorSet) {
-    const allSelectors = [selectorSet.primary, ...selectorSet.fallbacks];
-    for (const selector of allSelectors) {
-        try {
-            const el = await page.$(selector);
-            if (el)
-                return selector;
-        }
-        catch {
-            // Selector syntax may be invalid — skip
-        }
-    }
-    return null;
-}
-// ─── Internal helpers ───────────────────────────────────────────────
-/** Build a CSS path from element to a unique ancestor. */
-async function buildCssPath(element) {
-    try {
-        return await element.evaluate((node) => {
-            const parts = [];
-            let current = node;
-            const maxDepth = 5;
-            let depth = 0;
-            while (current && current !== document.body && depth < maxDepth) {
-                let part = current.tagName.toLowerCase();
-                if (current.id) {
-                    // CSS.escape keeps the selector valid (and injection-safe) for ids
-                    // containing quotes/brackets/etc. from untrusted crawled pages.
-                    part = `#${CSS.escape(current.id)}`;
-                    parts.unshift(part);
-                    break;
-                }
-                const parent = current.parentElement;
-                if (parent) {
-                    const siblings = Array.from(parent.children).filter((c) => c.tagName === current.tagName);
-                    if (siblings.length > 1) {
-                        const index = siblings.indexOf(current) + 1;
-                        part += `:nth-of-type(${index})`;
-                    }
-                }
-                parts.unshift(part);
-                current = parent;
-                depth++;
-            }
-            return parts.join(' > ');
-        });
-    }
-    catch {
-        return null;
-    }
-}
-/** Build an XPath for the element (absolute fallback). */
-async function buildXPath(element) {
-    try {
-        return await element.evaluate((node) => {
-            const parts = [];
-            let current = node;
-            while (current && current.nodeType === Node.ELEMENT_NODE) {
-                let index = 1;
-                let sibling = current.previousElementSibling;
-                while (sibling) {
-                    if (sibling.tagName === current.tagName)
-                        index++;
-                    sibling = sibling.previousElementSibling;
-                }
-                parts.unshift(`${current.tagName.toLowerCase()}[${index}]`);
-                current = current.parentElement;
-            }
-            return '/' + parts.join('/');
-        });
-    }
-    catch {
-        return '//body';
-    }
-}
-/** Check if an ID looks auto-generated (random hash, UUID-like, etc.) */
-function looksAutoGenerated(id) {
-    // Random hex strings (8+ chars of only hex)
-    if (/^[a-f0-9]{8,}$/i.test(id))
-        return true;
-    // React-style IDs like :r0:, :r1a:
-    if (/^:r[a-z0-9]+:$/.test(id))
-        return true;
-    // Contains UUID-like segments
-    if (/[a-f0-9]{8}-[a-f0-9]{4}/.test(id))
-        return true;
-    // Very long IDs are usually auto-generated
-    if (id.length > 40)
-        return true;
-    return false;
-}
-/** Escape a string for use in CSS selectors. */
-function cssEscape(str) {
-    return str.replace(/["'\\[\](){}:.,!#$%^&*+=|~<>?/;@]/g, '\\$&');
-}

package/dist/analyzer/semantic-analyzer.d.ts

@@ -1,13 +0,0 @@
-/**
- * LLM-powered semantic analysis of crawled pages.
- *
- * Sends page structure to Claude (Haiku for cost efficiency) and infers
- * human-readable semantic names and descriptions for forms, buttons, and links.
- */
-import type { PageDescriptor } from '../types/site.js';
-/**
- * Enrich PageDescriptors with LLM-inferred semantic names and descriptions.
- *
- * When ANTHROPIC_API_KEY is not set, returns pages unchanged with a warning.
- */
-export declare function analyzeSemantics(pages: PageDescriptor[], _screenshots?: Map<string, Buffer>): Promise<PageDescriptor[]>;

package/dist/analyzer/semantic-analyzer.js

@@ -1,145 +0,0 @@
-/**
- * LLM-powered semantic analysis of crawled pages.
- *
- * Sends page structure to Claude (Haiku for cost efficiency) and infers
- * human-readable semantic names and descriptions for forms, buttons, and links.
- */
-import Anthropic from '@anthropic-ai/sdk';
-import { logger } from '../utils/logger.js';
-const MODEL = 'claude-haiku-4-5-20251001';
-const MAX_TOKENS = 4096;
-/**
- * Enrich PageDescriptors with LLM-inferred semantic names and descriptions.
- *
- * When ANTHROPIC_API_KEY is not set, returns pages unchanged with a warning.
- */
-export async function analyzeSemantics(pages, _screenshots) {
-    const apiKey = process.env.ANTHROPIC_API_KEY;
-    if (!apiKey) {
-        logger.warn('ANTHROPIC_API_KEY not set — skipping semantic analysis');
-        return pages;
-    }
-    const client = new Anthropic({ apiKey });
-    // Build compact page summaries for the prompt
-    const summaries = pages.map((page, pageIndex) => ({
-        pageIndex,
-        url: page.url,
-        title: page.title,
-        forms: page.forms.map((form, formIndex) => ({
-            formIndex,
-            formId: form.formId,
-            method: form.method,
-            action: form.action,
-            fieldNames: form.fields.map((f) => f.name),
-            fieldTypes: form.fields.map((f) => f.fieldType),
-            labels: form.fields.map((f) => f.label ?? f.name),
-            submitText: form.submitButton?.humanLabel,
-        })),
-        buttons: page.buttons.map((btn, buttonIndex) => ({
-            buttonIndex,
-            buttonId: btn.buttonId,
-            text: btn.text,
-            ariaLabel: btn.ariaLabel,
-            type: btn.type,
-            href: btn.href,
-        })),
-        links: page.links.map((link, linkIndex) => ({
-            linkIndex,
-            linkId: link.linkId,
-            text: link.text,
-            href: link.href,
-            isNavigation: link.isNavigation,
-        })),
-    }));
-    const prompt = `You are analyzing a website's interactive elements to generate MCP tool names. Given the page structure below, infer semantic names and descriptions for each element.
-
-Rules:
-- Form semanticName: snake_case, e.g. "login_form", "search_form", "checkout_form"
-- Button semanticAction: snake_case verb, e.g. "add_to_cart", "submit_order", "toggle_menu"
-- Link semanticAction: snake_case, e.g. "navigate_to_checkout", "view_product_details"
-- Page semanticName: snake_case, e.g. "login_page", "product_listing"
-- Descriptions: one sentence explaining what the element does
-- Only output valid JSON matching the schema, no explanation
-
-Schema:
-{
-  "pages": [{
-    "pageIndex": number,
-    "semanticName": string,
-    "description": string,
-    "forms": [{ "formIndex": number, "semanticName": string, "description": string }],
-    "buttons": [{ "buttonIndex": number, "semanticAction": string, "description": string }],
-    "links": [{ "linkIndex": number, "semanticAction": string }]
-  }]
-}
-
-Pages:
-${JSON.stringify(summaries, null, 2)}`;
-    try {
-        logger.info('Analyzing page semantics with LLM...');
-        const message = await client.messages.create({
-            model: MODEL,
-            max_tokens: MAX_TOKENS,
-            messages: [{ role: 'user', content: prompt }],
-        });
-        const content = message.content[0];
-        if (content.type !== 'text')
-            return pages;
-        let json = content.text.trim();
-        if (json.startsWith('```')) {
-            json = json.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '');
-        }
-        const result = JSON.parse(json);
-        // Apply inferred names back to the page descriptors
-        const enriched = pages.map((page, pageIndex) => {
-            const pageResult = result.pages.find((p) => p.pageIndex === pageIndex);
-            if (!pageResult)
-                return page;
-            const updatedPage = {
-                ...page,
-                semanticName: pageResult.semanticName ?? page.semanticName,
-                description: pageResult.description ?? page.description,
-            };
-            updatedPage.forms = page.forms.map((form, formIndex) => {
-                const formResult = pageResult.forms.find((f) => f.formIndex === formIndex);
-                if (!formResult)
-                    return form;
-                return {
-                    ...form,
-                    semanticName: formResult.semanticName,
-                    description: formResult.description,
-                };
-            });
-            updatedPage.buttons = page.buttons.map((btn, buttonIndex) => {
-                const btnResult = pageResult.buttons.find((b) => b.buttonIndex === buttonIndex);
-                if (!btnResult)
-                    return btn;
-                return {
-                    ...btn,
-                    semanticAction: btnResult.semanticAction,
-                    description: btnResult.description,
-                };
-            });
-            updatedPage.links = page.links.map((link, linkIndex) => {
-                const linkResult = pageResult.links.find((l) => l.linkIndex === linkIndex);
-                if (!linkResult)
-                    return link;
-                return {
-                    ...link,
-                    semanticAction: linkResult.semanticAction,
-                };
-            });
-            return updatedPage;
-        });
-        const totalNamed = enriched.reduce((n, p) => n +
-            p.forms.filter((f) => f.semanticName).length +
-            p.buttons.filter((b) => b.semanticAction).length +
-            p.links.filter((l) => l.semanticAction).length, 0);
-        logger.info(`Semantic analysis complete: ${totalNamed} elements named`);
-        return enriched;
-    }
-    catch (err) {
-        logger.warn(`Semantic analysis failed, using defaults: ${err instanceof Error ? err.message : err}`);
-        return pages;
-    }
-}

package/dist/analyzer/site-crawler.d.ts

@@ -1,38 +0,0 @@
-/**
- * Crawls a website using Playwright, visiting pages breadth-first
- * and extracting interactive elements from each page.
- */
-import type { Entry } from 'har-format';
-import type { SiteDescriptor } from '../types/site.js';
-export interface CrawlOptions {
-    /** Target URL to start crawling from */
-    url: string;
-    /** Maximum crawl depth (default: 2) */
-    depth?: number;
-    /** Maximum number of pages to visit (default: 20) */
-    maxPages?: number;
-    /** Idle timeout in ms before auto-closing (default: 5 min) */
-    timeout?: number;
-    /** Run browser in headless mode (default: false) */
-    headless?: boolean;
-    /** Viewport dimensions */
-    viewport?: {
-        width: number;
-        height: number;
-    };
-    /** Whether to capture screenshots during analysis (default: true) */
-    captureScreenshots?: boolean;
-    /** Whether to capture HAR entries during crawl (for hybrid mode) */
-    captureHar?: boolean;
-}
-export interface CrawlResult {
-    siteDescriptor: SiteDescriptor;
-    /** Screenshots keyed by pageId */
-    screenshots: Map<string, Buffer>;
-    /** HAR entries captured during the crawl (only when captureHar is true) */
-    harEntries?: Entry[];
-}
-/**
- * Crawl a website and return a SiteDescriptor with all discovered pages.
- */
-export declare function crawlSite(options: CrawlOptions): Promise<CrawlResult>;