@iflow-mcp/jakeliume-webpeel 0.22.0

package/dist/mcp/handlers/see.d.ts

@@ -0,0 +1,5 @@
+/**
+ * handleSee — take a screenshot, optionally with design analysis or comparison.
+ */
+import { type McpHandler } from './types.js';
+export declare const handleSee: McpHandler;

package/dist/mcp/handlers/see.js

@@ -0,0 +1,75 @@
+/**
+ * handleSee — take a screenshot, optionally with design analysis or comparison.
+ */
+import { textResult, safeStringify, timeout } from './types.js';
+export const handleSee = async (args, _ctx) => {
+    const url = args['url'];
+    if (!url || typeof url !== 'string')
+        throw new Error('url is required');
+    if (url.length > 2048)
+        throw new Error('URL too long (max 2048 characters)');
+    const mode = args['mode'] || 'screenshot';
+    const compareUrl = args['compare_url'];
+    const fullPage = args['full_page'] || false;
+    const viewportArg = args['viewport'];
+    // Resolve viewport dimensions
+    let width = 1280;
+    let height = 720;
+    if (viewportArg && typeof viewportArg === 'object' && !Array.isArray(viewportArg)) {
+        const vp = viewportArg;
+        width = vp.width ?? 1280;
+        height = vp.height ?? 720;
+    }
+    else if (viewportArg === 'mobile') {
+        width = 390;
+        height = 844;
+    }
+    else if (viewportArg === 'tablet') {
+        width = 768;
+        height = 1024;
+    }
+    // Secondary object check (handles smart router viewport object)
+    if (args['viewport'] && typeof args['viewport'] === 'object') {
+        const vp = args['viewport'];
+        if (vp.width)
+            width = vp.width;
+        if (vp.height)
+            height = vp.height;
+    }
+    if (mode === 'design') {
+        const { browserDesignAnalysis } = await import('../../core/fetcher.js');
+        const result = await Promise.race([
+            browserDesignAnalysis(url, { width, height }),
+            timeout(90000, 'Design analysis'),
+        ]);
+        return textResult(safeStringify({ url: result.finalUrl, mode: 'design', analysis: result.analysis }));
+    }
+    if (mode === 'compare' && compareUrl) {
+        const { browserDiff } = await import('../../core/fetcher.js');
+        const diff = await Promise.race([
+            browserDiff(url, compareUrl, { width, height, fullPage }),
+            timeout(90000, 'Design compare'),
+        ]);
+        return textResult(safeStringify({
+            url,
+            compare_url: compareUrl,
+            mode: 'compare',
+            diffPixels: diff.diffPixels,
+            totalPixels: diff.totalPixels,
+            diffPercent: diff.diffPercent,
+            screenshot: diff.diffBuffer.toString('base64'),
+        }));
+    }
+    // Default: screenshot
+    const { takeScreenshot } = await import('../../core/screenshot.js');
+    const result = await Promise.race([
+        takeScreenshot(url, { fullPage, width, height, format: 'png' }),
+        timeout(60000, 'Screenshot'),
+    ]);
+    return textResult(safeStringify({
+        url: result.url,
+        mode: 'screenshot',
+        screenshot: result.screenshot,
+        format: result.format,
+    }));
+};

package/dist/mcp/handlers/types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared types for MCP handlers.
+ * Both the standalone MCP server and HTTP MCP route import from here.
+ */
+export interface McpToolResult {
+    content: Array<{
+        type: 'text';
+        text: string;
+    } | {
+        type: 'image';
+        data: string;
+        mimeType: string;
+    }>;
+    isError?: boolean;
+}
+export interface McpContext {
+    accountId?: string;
+    /** pg.Pool passed by the HTTP route for webpeel_watch */
+    pool?: unknown;
+}
+export type McpHandler = (args: Record<string, unknown>, ctx?: McpContext) => Promise<McpToolResult>;
+/** Wrap a JSON-serialized string in a text content block. */
+export declare function textResult(text: string): McpToolResult;
+/** Wrap an error message in a text content block with isError=true. */
+export declare function errorResult(message: string): McpToolResult;
+/** Safely JSON-stringify any value; falls back to String() on error. */
+export declare function safeStringify(obj: unknown): string;
+/** Generic timeout promise. */
+export declare function timeout<T>(ms: number, label: string): Promise<T>;

package/dist/mcp/handlers/types.js

@@ -0,0 +1,28 @@
+/**
+ * Shared types for MCP handlers.
+ * Both the standalone MCP server and HTTP MCP route import from here.
+ */
+/** Wrap a JSON-serialized string in a text content block. */
+export function textResult(text) {
+    return { content: [{ type: 'text', text }] };
+}
+/** Wrap an error message in a text content block with isError=true. */
+export function errorResult(message) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify({ error: message }) }],
+        isError: true,
+    };
+}
+/** Safely JSON-stringify any value; falls back to String() on error. */
+export function safeStringify(obj) {
+    try {
+        return JSON.stringify(obj, null, 2);
+    }
+    catch {
+        return String(obj);
+    }
+}
+/** Generic timeout promise. */
+export function timeout(ms, label) {
+    return new Promise((_, reject) => setTimeout(() => reject(new Error(`${label} timed out after ${ms / 1000}s`)), ms));
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * MCP Server for WebPeel — stdio transport.
+ * Thin wrapper: imports from the shared handler registry in ./handlers/.
+ * All tool logic lives in src/mcp/handlers/*.ts.
+ */
+export {};

package/dist/mcp/server.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * MCP Server for WebPeel — stdio transport.
+ * Thin wrapper: imports from the shared handler registry in ./handlers/.
+ * All tool logic lives in src/mcp/handlers/*.ts.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { getHandler } from './handlers/index.js';
+import { toolDefinitions } from './handlers/definitions.js';
+// Read version from package.json
+let pkgVersion = '0.3.1';
+try {
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = dirname(__filename);
+    const pkg = JSON.parse(readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf-8'));
+    pkgVersion = pkg.version;
+}
+catch { /* fallback */ }
+// ── Server setup ───────────────────────────────────────────────────────────
+const server = new Server({ name: 'webpeel', version: pkgVersion }, { capabilities: { tools: {} } });
+// ── tools/list — return the 7 public tool definitions ─────────────────────
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: toolDefinitions,
+}));
+// ── tools/call — dispatch to shared handler registry ──────────────────────
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: rawArgs } = request.params;
+    const args = (rawArgs || {});
+    try {
+        const handler = getHandler(name);
+        if (!handler)
+            throw new Error(`Unknown tool: ${name}`);
+        // Standalone has no accountId / pool context
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return (await handler(args));
+    }
+    catch (error) {
+        const err = error;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        error: err.name || 'Error',
+                        message: err.message || 'Unknown error',
+                    }),
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// ── Main — stdio or HTTP mode ──────────────────────────────────────────────
+async function main() {
+    const isHttpMode = process.env['MCP_HTTP_MODE'] === 'true' ||
+        process.env['HTTP_STREAMABLE_SERVER'] === 'true';
+    if (isHttpMode) {
+        const { StreamableHTTPServerTransport } = await import('@modelcontextprotocol/sdk/server/streamableHttp.js');
+        const express = await import('express');
+        const httpApp = express.default();
+        httpApp.use(express.default.json({ limit: '1mb' }));
+        httpApp.post('/v2/mcp', async (req, res) => {
+            const r = req;
+            const s = res;
+            try {
+                const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+                await server.connect(transport);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                await transport.handleRequest(r, s, r.body);
+                transport.close().catch(() => { });
+            }
+            catch {
+                if (!s.headersSent) {
+                    s.status(500).json({
+                        jsonrpc: '2.0',
+                        error: { code: -32603, message: 'Internal error' },
+                        id: null,
+                    });
+                }
+            }
+        });
+        httpApp.get('/v2/mcp', (_req, res) => {
+            res.status(405).json({
+                jsonrpc: '2.0',
+                error: { code: -32000, message: 'Use POST to send MCP messages.' },
+                id: null,
+            });
+        });
+        const port = parseInt(process.env['MCP_PORT'] || '3100', 10);
+        httpApp.listen(port, () => {
+            process.stderr.write(`WebPeel MCP server (HTTP) listening on port ${port}\n`);
+        });
+    }
+    else {
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        process.stderr.write('WebPeel MCP server running on stdio\n');
+    }
+}
+main().catch((error) => {
+    process.stderr.write(`Fatal error: ${error}\n`);
+    process.exit(1);
+});

package/dist/mcp/smart-router.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Smart Router — Natural language intent parser for WebPeel.
+ * Rule-based keyword matching. No LLM required.
+ */
+export interface ParsedIntent {
+    intent: 'read' | 'see' | 'find' | 'extract' | 'monitor' | 'act';
+    url?: string;
+    query?: string;
+    params: Record<string, unknown>;
+}
+/** Extract the first URL from a task string (http/https or domain-like). */
+export declare function extractUrl(task: string): string | undefined;
+/** Extract all URLs from a task string. */
+export declare function extractAllUrls(task: string): string[];
+/** Detect the primary intent from a task string. */
+export declare function detectIntent(task: string): ParsedIntent['intent'];
+/**
+ * Parse a natural language task string into a structured intent.
+ *
+ * @param task - Plain English description of what you want to do.
+ * @returns ParsedIntent with intent, optional url, optional query, and params.
+ */
+export declare function parseIntent(task: string): ParsedIntent;

package/dist/mcp/smart-router.js

@@ -0,0 +1,178 @@
+/**
+ * Smart Router — Natural language intent parser for WebPeel.
+ * Rule-based keyword matching. No LLM required.
+ */
+// Multi-word phrases must be checked before single-word keywords to avoid false matches
+const MULTI_WORD_PATTERNS = [
+    { intent: 'act', pattern: /\bsign[\s-]up\b/ },
+    { intent: 'find', pattern: /\blook\s+up\b/ },
+    { intent: 'extract', pattern: /\bget\s+data\b/ },
+    { intent: 'read', pattern: /\bwhat\s+does\b/ },
+    // Question-as-search: "what is X", "how much does Y cost", "who is Z", etc.
+    // Must come AFTER "what does" (read) so that pattern takes priority.
+    { intent: 'find', pattern: /^\s*(?:what\s+(?:is|are|was|were|can|will|would|could|should)|how\s+(?:much|many|do|does|did|to|can|are|is)|who\s+(?:is|are|was)|when\s+(?:is|was|does|do)|where\s+(?:is|can|do|are)|why\s+(?:is|does|do|can)|which\s+(?:is|are))\b/i },
+];
+// Single-word keywords in descending priority order
+// act > monitor > extract > see > find > read
+const KEYWORD_INTENTS = [
+    {
+        intent: 'act',
+        keywords: ['click', 'fill', 'submit', 'navigate', 'type', 'login', 'interact', 'press', 'select'],
+    },
+    {
+        intent: 'monitor',
+        keywords: ['watch', 'monitor', 'track', 'alert', 'notify', 'change', 'diff'],
+    },
+    {
+        intent: 'extract',
+        keywords: ['extract', 'scrape', 'pull', 'fields', 'schema', 'price', 'structured', 'brand', 'logo', 'colors'],
+    },
+    {
+        intent: 'see',
+        keywords: ['screenshot', 'see', 'show', 'look', 'visual', 'image', 'capture', 'design', 'compare'],
+    },
+    {
+        intent: 'find',
+        keywords: ['find', 'search', 'google', 'research', 'discover', 'map', 'sitemap'],
+    },
+    {
+        intent: 'read',
+        keywords: ['read', 'fetch', 'get', 'content', 'text', 'markdown', 'summarize', 'summary', 'answer', 'question'],
+    },
+];
+// TLD pattern used for domain detection
+const KNOWN_TLDS = 'com|org|net|io|co|dev|ai|app|info|uk|de|fr|jp|cn|us|edu|gov|me|tv|cc|ly|gg|sh|tech|online|site|xyz|store|cloud|api|blog|news';
+const DOMAIN_RE = new RegExp(`\\b(?:[a-zA-Z0-9-]+\\.)+(?:${KNOWN_TLDS})\\b(?:\\/[^\\s"'<>)]*)?`, 'i');
+const DOMAIN_RE_GLOBAL = new RegExp(`\\b(?:[a-zA-Z0-9-]+\\.)+(?:${KNOWN_TLDS})\\b(?:\\/[^\\s"'<>)]*)?`, 'gi');
+/** Strip trailing punctuation from a URL string. */
+function stripTrailing(url) {
+    return url.replace(/[.,;:!?]+$/, '');
+}
+/** Extract the first URL from a task string (http/https or domain-like). */
+export function extractUrl(task) {
+    // Prefer explicit http/https URLs
+    const httpMatch = task.match(/https?:\/\/[^\s"'<>)]+/);
+    if (httpMatch)
+        return stripTrailing(httpMatch[0]);
+    // Fall back to domain-like patterns
+    const domainMatch = task.match(DOMAIN_RE);
+    if (domainMatch)
+        return stripTrailing(`https://${domainMatch[0]}`);
+    return undefined;
+}
+/** Extract all URLs from a task string. */
+export function extractAllUrls(task) {
+    const urls = [];
+    const httpMatches = task.match(/https?:\/\/[^\s"'<>)]+/g);
+    if (httpMatches) {
+        // If explicit URLs found, don't also add domain-only matches
+        return httpMatches.map(stripTrailing);
+    }
+    let m;
+    DOMAIN_RE_GLOBAL.lastIndex = 0;
+    while ((m = DOMAIN_RE_GLOBAL.exec(task)) !== null) {
+        urls.push(stripTrailing(`https://${m[0]}`));
+    }
+    return urls;
+}
+/** For find intent: strip the URL and intent verbs, returning the bare query. */
+function extractFindQuery(task, url) {
+    let q = task;
+    // Remove http/https URL
+    if (url?.startsWith('http')) {
+        q = q.replace(url, '');
+    }
+    else if (url) {
+        // Remove the raw domain portion
+        const raw = url.replace(/^https?:\/\//, '');
+        q = q.replace(new RegExp(raw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'gi'), '');
+    }
+    // Remove domain-like patterns that didn't become the primary URL
+    q = q.replace(DOMAIN_RE_GLOBAL, '');
+    // Remove intent verbs and stop words
+    q = q
+        .replace(/\b(find|search\s+(?:for\s+|the\s+)?|google|look\s+up|research|discover|map|sitemap|for)\b/gi, '')
+        .replace(/\s{2,}/g, ' ')
+        .trim();
+    return q || undefined;
+}
+/** Extract viewport, format, and other params from natural language. */
+function extractParams(task) {
+    const params = {};
+    const lower = task.toLowerCase();
+    if (/\bon\s+mobile\b/.test(lower)) {
+        params['viewport'] = { width: 390, height: 844 };
+    }
+    else if (/\bon\s+tablet\b/.test(lower)) {
+        params['viewport'] = { width: 768, height: 1024 };
+    }
+    if (/\bfull[\s-]?page\b/.test(lower)) {
+        params['fullPage'] = true;
+    }
+    if (/\bas\s+json\b/.test(lower) || /\bstructured\b/.test(lower)) {
+        params['format'] = 'json';
+    }
+    if (/\bsummar(?:y|ize|izing)\b/.test(lower)) {
+        params['summary'] = true;
+    }
+    return params;
+}
+/**
+ * Strip all URLs from a string so they don't pollute keyword detection.
+ * e.g. "https://youtube.com/watch?v=abc" → "" (removes "watch" from the URL)
+ */
+function stripUrlsForKeywordCheck(task) {
+    // Remove http/https URLs first
+    let stripped = task.replace(/https?:\/\/[^\s"'<>)]+/gi, ' ');
+    // Remove bare domain-like patterns
+    stripped = stripped.replace(DOMAIN_RE_GLOBAL, ' ');
+    return stripped;
+}
+/** Detect the primary intent from a task string. */
+export function detectIntent(task) {
+    const lower = task.toLowerCase();
+    // Strip URLs so that URL paths (e.g. "/watch") don't trigger wrong intents
+    const keywordTarget = stripUrlsForKeywordCheck(lower);
+    // Multi-word patterns take priority (checked against URL-stripped version)
+    for (const { intent, pattern } of MULTI_WORD_PATTERNS) {
+        if (pattern.test(keywordTarget))
+            return intent;
+    }
+    // Single-word keywords in priority order
+    for (const { intent, keywords } of KEYWORD_INTENTS) {
+        if (keywords.some((kw) => keywordTarget.includes(kw)))
+            return intent;
+    }
+    // Default: bare URL (or no recognized verb) → read
+    return 'read';
+}
+/**
+ * Parse a natural language task string into a structured intent.
+ *
+ * @param task - Plain English description of what you want to do.
+ * @returns ParsedIntent with intent, optional url, optional query, and params.
+ */
+export function parseIntent(task) {
+    const intent = detectIntent(task);
+    const url = extractUrl(task);
+    const params = extractParams(task);
+    // Enrich 'see' intent with mode and compare_url
+    if (intent === 'see') {
+        const lower = task.toLowerCase();
+        if (/\bcompare\b/.test(lower)) {
+            params['mode'] = 'compare';
+            const all = extractAllUrls(task);
+            if (all.length >= 2)
+                params['compare_url'] = all[1];
+        }
+        else if (/\bdesign\b/.test(lower) || /\bdesign[\s-]?analysis\b/.test(lower)) {
+            params['mode'] = 'design';
+        }
+    }
+    // Extract query for find intent
+    let query;
+    if (intent === 'find') {
+        query = extractFindQuery(task, url);
+    }
+    return { intent, url, query, params };
+}

package/dist/server/app.d.ts

@@ -0,0 +1,14 @@
+/**
+ * WebPeel API Server
+ * Express-based REST API for hosted deployments
+ */
+import { Express } from 'express';
+import './types.js';
+export interface ServerConfig {
+    port?: number;
+    corsOrigins?: string[];
+    rateLimitWindowMs?: number;
+    usePostgres?: boolean;
+}
+export declare function createApp(config?: ServerConfig): Express;
+export declare function startServer(config?: ServerConfig): void;