recker 1.0.72 → 1.0.73

package/dist/mcp/tools/seo.js

@@ -1,6 +1,114 @@
+import { promises as fs } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createHash } from 'node:crypto';
 import { createClient } from '../../core/client.js';
 import { analyzeSeo } from '../../seo/analyzer.js';
 import { seoSpider } from '../../seo/seo-spider.js';
+const DEFAULT_SEO_CACHE_TTL_SEC = 6 * 60 * 60;
+const SEO_REPORT_DIR = join(tmpdir(), 'recker', 'seo');
+function normalizeStringArray(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const items = value.map(item => String(item).trim()).filter(Boolean);
+    if (items.length === 0)
+        return undefined;
+    return items;
+}
+function safeHost(url) {
+    try {
+        const parsed = new URL(url);
+        const host = parsed.hostname || parsed.host;
+        return host.replace(/[^a-z0-9.-]/gi, '_') || 'unknown';
+    }
+    catch {
+        return url.replace(/[^a-z0-9.-]/gi, '_').slice(0, 64) || 'unknown';
+    }
+}
+function hashArgs(value) {
+    return createHash('sha1').update(JSON.stringify(value)).digest('hex').slice(0, 12);
+}
+function resolveReportPersistence(args, options) {
+    const output = typeof args.output === 'string' ? args.output : undefined;
+    const outputDir = typeof args.outputDir === 'string' ? args.outputDir : undefined;
+    const persist = args.persist === true;
+    const persistenceEnabled = Boolean(output || outputDir || persist);
+    const cacheEnabled = persistenceEnabled ? (typeof args.cache === 'boolean' ? args.cache : true) : false;
+    const forceRefresh = args.forceRefresh === true;
+    const cacheTtlInput = typeof args.cacheTtlSec === 'number'
+        ? args.cacheTtlSec
+        : Number.isFinite(Number(args.cacheTtlSec))
+            ? Number(args.cacheTtlSec)
+            : undefined;
+    const cacheTtlSec = cacheEnabled
+        ? Math.max(0, cacheTtlInput ?? DEFAULT_SEO_CACHE_TTL_SEC)
+        : 0;
+    if (!persistenceEnabled) {
+        return {
+            enabled: false,
+            reportPath: null,
+            cacheEnabled: false,
+            cacheTtlSec: 0,
+            forceRefresh,
+        };
+    }
+    const host = safeHost(options.url);
+    const hash = hashArgs(options.cacheKey);
+    const fileName = `${options.toolSlug}--${host}--${hash}.json`;
+    const reportPath = output
+        ? output
+        : outputDir
+            ? join(outputDir, fileName)
+            : join(SEO_REPORT_DIR, fileName);
+    return {
+        enabled: true,
+        reportPath,
+        cacheEnabled,
+        cacheTtlSec,
+        forceRefresh,
+    };
+}
+async function readCachedReport(path, ttlSec) {
+    if (!path || ttlSec <= 0)
+        return null;
+    try {
+        const stats = await fs.stat(path);
+        const ageSec = (Date.now() - stats.mtimeMs) / 1000;
+        if (ageSec > ttlSec) {
+            return null;
+        }
+        const text = await fs.readFile(path, 'utf8');
+        const report = JSON.parse(text);
+        if (report && typeof report === 'object') {
+            delete report.reportMeta;
+            delete report.note;
+        }
+        return {
+            report,
+            ageSec,
+            bytes: stats.size,
+            savedAt: new Date(stats.mtimeMs).toISOString(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function writeReport(path, payload) {
+    await fs.mkdir(dirname(path), { recursive: true });
+    await fs.writeFile(path, payload, 'utf8');
+    return { bytes: Buffer.byteLength(payload), savedAt: new Date().toISOString() };
+}
+function buildReportMeta(params) {
+    return {
+        reportPath: params.reportPath ?? null,
+        cacheHit: params.cacheHit ?? false,
+        source: params.source,
+        ...(params.cacheAgeSec !== undefined ? { cacheAgeSec: params.cacheAgeSec } : {}),
+        ...(params.savedAt ? { savedAt: params.savedAt } : {}),
+        ...(params.reportBytes !== undefined ? { reportBytes: params.reportBytes } : {}),
+    };
+}
 function formatCheck(check) {
     const icon = check.status === 'pass' ? '✓' : check.status === 'fail' ? '✗' : '⚠';
     let line = `${icon} [${check.status.toUpperCase()}] ${check.name}: ${check.message}`;
@@ -75,14 +183,46 @@ function generateQuickWins(report) {
 }
 async function seoAnalyze(args) {
     const url = String(args.url || '');
-    const categories = args.categories;
+    const categories = normalizeStringArray(args.categories);
     if (!url) {
         return {
             content: [{ type: 'text', text: 'Error: url is required' }],
             isError: true,
         };
     }
+    const persistence = resolveReportPersistence(args, {
+        toolSlug: 'seo',
+        url,
+        cacheKey: {
+            url,
+            categories: categories ? [...categories].sort() : [],
+        },
+    });
     try {
+        if (persistence.enabled && persistence.cacheEnabled && !persistence.forceRefresh && persistence.reportPath) {
+            const cached = await readCachedReport(persistence.reportPath, persistence.cacheTtlSec);
+            if (cached) {
+                const reportMeta = buildReportMeta({
+                    reportPath: persistence.reportPath,
+                    cacheHit: true,
+                    cacheAgeSec: cached.ageSec,
+                    savedAt: cached.savedAt,
+                    reportBytes: cached.bytes,
+                    source: 'cached',
+                });
+                const output = {
+                    ...cached.report,
+                    reportMeta,
+                    note: `Cache hit: report loaded from ${persistence.reportPath}`,
+                };
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(output, null, 2),
+                        }],
+                };
+            }
+        }
         const client = createClient({ timeout: 30000 });
         const response = await client.get(url);
         const html = await response.text();
@@ -135,10 +275,56 @@ async function seoAnalyze(args) {
             images: report.images,
             technical: report.technical,
         };
+        const reportPayload = JSON.stringify(output, null, 2);
+        let reportMeta = buildReportMeta({
+            reportPath: persistence.reportPath,
+            cacheHit: false,
+            source: 'fresh',
+        });
+        let note = persistence.enabled
+            ? `Report generated (not yet saved).`
+            : 'Report generated (not persisted). Set persist=true to save and enable caching.';
+        if (persistence.enabled && persistence.reportPath) {
+            try {
+                const saved = await writeReport(persistence.reportPath, reportPayload);
+                reportMeta = buildReportMeta({
+                    reportPath: persistence.reportPath,
+                    cacheHit: false,
+                    savedAt: saved.savedAt,
+                    reportBytes: saved.bytes,
+                    source: 'fresh',
+                });
+                note = `Report saved to ${persistence.reportPath}`;
+            }
+            catch (error) {
+                const message = `Failed to save report to ${persistence.reportPath}: ${error.message}`;
+                const failedOutput = {
+                    ...output,
+                    reportMeta,
+                    note: message,
+                };
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(failedOutput, null, 2),
+                        }],
+                    isError: true,
+                };
+            }
+        }
+        else {
+            reportMeta = buildReportMeta({
+                reportPath: null,
+                cacheHit: false,
+                reportBytes: Buffer.byteLength(reportPayload),
+                savedAt: new Date().toISOString(),
+                source: 'fresh',
+            });
+        }
         return {
             content: [{
                     type: 'text',
-                    text: JSON.stringify(output, null, 2),
+                    text: JSON.stringify({ ...output, reportMeta, note }, null, 2),
                 }],
         };
     }
@@ -165,6 +351,41 @@ async function seoSpiderCrawl(args) {
         };
     }
     try {
+        const persistence = resolveReportPersistence(args, {
+            toolSlug: 'seo-spider',
+            url,
+            cacheKey: {
+                url,
+                maxPages,
+                maxDepth,
+                concurrency,
+                transport,
+            },
+        });
+        if (persistence.enabled && persistence.cacheEnabled && !persistence.forceRefresh && persistence.reportPath) {
+            const cached = await readCachedReport(persistence.reportPath, persistence.cacheTtlSec);
+            if (cached) {
+                const reportMeta = buildReportMeta({
+                    reportPath: persistence.reportPath,
+                    cacheHit: true,
+                    cacheAgeSec: cached.ageSec,
+                    savedAt: cached.savedAt,
+                    reportBytes: cached.bytes,
+                    source: 'cached',
+                });
+                const output = {
+                    ...cached.report,
+                    reportMeta,
+                    note: `Cache hit: report loaded from ${persistence.reportPath}`,
+                };
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(output, null, 2),
+                        }],
+                };
+            }
+        }
         const result = await seoSpider(url, {
             seo: true,
             maxPages,
@@ -226,10 +447,56 @@ async function seoSpiderCrawl(args) {
         if (recommendations.length > 0) {
             output.recommendations = recommendations;
         }
+        const reportPayload = JSON.stringify(output, null, 2);
+        let reportMeta = buildReportMeta({
+            reportPath: persistence.reportPath,
+            cacheHit: false,
+            source: 'fresh',
+        });
+        let note = persistence.enabled
+            ? 'Report generated (not yet saved).'
+            : 'Report generated (not persisted). Set persist=true to save and enable caching.';
+        if (persistence.enabled && persistence.reportPath) {
+            try {
+                const saved = await writeReport(persistence.reportPath, reportPayload);
+                reportMeta = buildReportMeta({
+                    reportPath: persistence.reportPath,
+                    cacheHit: false,
+                    savedAt: saved.savedAt,
+                    reportBytes: saved.bytes,
+                    source: 'fresh',
+                });
+                note = `Report saved to ${persistence.reportPath}`;
+            }
+            catch (error) {
+                const message = `Failed to save report to ${persistence.reportPath}: ${error.message}`;
+                const failedOutput = {
+                    ...output,
+                    reportMeta,
+                    note: message,
+                };
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(failedOutput, null, 2),
+                        }],
+                    isError: true,
+                };
+            }
+        }
+        else {
+            reportMeta = buildReportMeta({
+                reportPath: null,
+                cacheHit: false,
+                reportBytes: Buffer.byteLength(reportPayload),
+                savedAt: new Date().toISOString(),
+                source: 'fresh',
+            });
+        }
         return {
             content: [{
                     type: 'text',
-                    text: JSON.stringify(output, null, 2),
+                    text: JSON.stringify({ ...output, reportMeta, note }, null, 2),
                 }],
         };
     }
@@ -330,6 +597,7 @@ Returns:
 - Warnings and recommendations
 - OpenGraph/social meta analysis
 - Request timing breakdown
+- Optional report persistence and caching for AI agent workflows
 
 Perfect for analyzing your localhost dev server or any public URL. Categories include: meta, content, links, images, technical, security, performance, mobile, accessibility, schema, structural, i18n, PWA, social, e-commerce, local SEO, Core Web Vitals, readability, crawlability, internal linking, and best practices.`,
         inputSchema: {
@@ -344,6 +612,30 @@ Perfect for analyzing your localhost dev server or any public URL. Categories in
                     items: { type: 'string' },
                     description: 'Filter by specific categories (e.g., ["meta", "security", "performance"]). Leave empty for all.',
                 },
+                output: {
+                    type: 'string',
+                    description: 'Save report to explicit file path',
+                },
+                outputDir: {
+                    type: 'string',
+                    description: 'Save report to directory with auto-generated filename',
+                },
+                persist: {
+                    type: 'boolean',
+                    description: 'Save report to default temp path (os.tmpdir()/recker/seo)',
+                },
+                cache: {
+                    type: 'boolean',
+                    description: 'Reuse existing saved report if present and within TTL (default: true when persistence enabled)',
+                },
+                cacheTtlSec: {
+                    type: 'number',
+                    description: `Cache TTL in seconds (default: ${DEFAULT_SEO_CACHE_TTL_SEC})`,
+                },
+                forceRefresh: {
+                    type: 'boolean',
+                    description: 'Bypass cache and recompute even if a saved report exists',
+                },
             },
             required: ['url'],
         },
@@ -357,7 +649,7 @@ Detects site-wide issues:
 - Orphan pages (no internal links pointing to them)
 - Pages with low SEO scores
 
-Returns per-page scores and prioritized recommendations for improving overall site SEO. Great for auditing a full site before launch or finding issues across your dev environment.`,
+Returns per-page scores and prioritized recommendations for improving overall site SEO. Great for auditing a full site before launch or finding issues across your dev environment. Supports optional report persistence and caching for AI agent workflows.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -386,6 +678,30 @@ Returns per-page scores and prioritized recommendations for improving overall si
                     description: 'HTTP transport: auto (try undici, fallback to curl on WAF block), undici (fast), curl (curl-impersonate for protected sites)',
                     default: 'auto',
                 },
+                output: {
+                    type: 'string',
+                    description: 'Save report to explicit file path',
+                },
+                outputDir: {
+                    type: 'string',
+                    description: 'Save report to directory with auto-generated filename',
+                },
+                persist: {
+                    type: 'boolean',
+                    description: 'Save report to default temp path (os.tmpdir()/recker/seo)',
+                },
+                cache: {
+                    type: 'boolean',
+                    description: 'Reuse existing saved report if present and within TTL (default: true when persistence enabled)',
+                },
+                cacheTtlSec: {
+                    type: 'number',
+                    description: `Cache TTL in seconds (default: ${DEFAULT_SEO_CACHE_TTL_SEC})`,
+                },
+                forceRefresh: {
+                    type: 'boolean',
+                    description: 'Bypass cache and recompute even if a saved report exists',
+                },
             },
             required: ['url'],
         },

package/dist/version.js

@@ -1,4 +1,4 @@
-const VERSION = '1.0.72';
+const VERSION = '1.0.73';
 let _version = null;
 export async function getVersion() {
     if (_version)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recker",
-  "version": "1.0.72",
+  "version": "1.0.73",
   "description": "Multi-Protocol SDK for the AI Era - HTTP, WebSocket, DNS, FTP, SFTP, Telnet, HLS unified with AI providers and MCP tools",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",