perfgraph 0.1.0

package/dist/mcp/prompts.js

@@ -0,0 +1,225 @@
+/**
+ * MCP diagnostic prompt templates.
+ *
+ * Prompts provide guided starting points for common diagnostic workflows.
+ * When an AI client invokes a prompt, it receives structured messages that
+ * guide it through the analysis process using PerfGraph tools.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Shared: base diagnostic instructions
+// ---------------------------------------------------------------------------
+/**
+ * Instructions injected into every diagnostic prompt to ensure the AI
+ * agent uses PerfGraph effectively.
+ */
+const SYSTEM_CONTEXT = `You are a web performance diagnostician powered by PerfGraph.
+
+WORKFLOW:
+1. Call \`perfgraph_run\` with the target URL to collect and analyze performance data.
+2. Read the results — the tool returns a summary with score, issue counts, and resource URIs.
+3. Read the full report via the \`perfgraph://\` resource URIs returned in the response.
+4. Analyze the findings and provide actionable recommendations.
+
+The report contains:
+- **meta**: URL, analysis timestamp, feature/graph/rule counts
+- **summary**: overall score (good/moderate/poor), issue counts, top issues
+- **issues**: each detected problem with severity (critical/warning/info), confidence (strong/medium/weak), metric values, and remediation text
+- **chains**: causal paths from root cause to impact
+- **recommendations**: prioritized actions with expected impact
+- **features**: raw diagnostic features for cross-referencing
+
+RESPONSE FORMAT:
+Always structure your analysis with:
+1. **Executive Summary** — score, critical count, system status
+2. **Key Findings** — top issues by severity with metrics
+3. **Causal Chains** — root cause → impact paths
+4. **Recommendations** — prioritized actions
+5. **Next Steps** — what to investigate further`;
+// ---------------------------------------------------------------------------
+// Prompt: LCP Performance Analysis
+// ---------------------------------------------------------------------------
+export const LcpAnalysisArgsSchema = z.object({
+    /** Target URL to analyze */
+    url: z.string().min(1, 'url is required'),
+    /** Optional: existing report URI to analyze instead of running a new collection */
+    reportUri: z.string().optional(),
+});
+/**
+ * Guided LCP (Largest Contentful Paint) performance analysis.
+ *
+ * The prompt instructs the AI to run a focused analysis on LCP performance,
+ * examining the LCP breakdown (TTFB, resource delay, render delay, element
+ * render time) and all contributing factors.
+ */
+export function buildLcpAnalysisPrompt(args) {
+    const { url, reportUri } = args;
+    const userMessage = reportUri
+        ? `Analyze the LCP performance from the existing report at ${reportUri}.
+
+Focus specifically on:
+1. **LCP Breakdown** — TTFB, resource load delay, render delay, element render time
+2. **Render-blocking resources** — CSS, JS, scripts blocking the LCP element
+3. **Causal chain** — follow the path from root cause to LCP impact
+4. **Remediations** — what specific actions would improve LCP
+
+Read the report from ${reportUri} and provide a focused LCP analysis with specific metrics and recommendations.`
+        : `Perform a detailed LCP (Largest Contentful Paint) analysis on ${url}.
+
+Follow this workflow:
+1. Call \`perfgraph_run\` with url="${url}" to collect and analyze performance data
+2. Read the report via the returned resource URIs
+3. Focus your analysis specifically on LCP performance:
+
+   a. **LCP Breakdown**: Examine TTFB, resource load delay, render delay, and element render time
+   b. **Contributing Factors**: Check render-blocking resources, critical path depth, JS execution hotspots, and third-party scripts
+   c. **Causal Chain**: Trace the degradation path from root causes to LCP impact
+   d. **Remediations**: Prioritize actions that would most improve LCP
+
+4. For each finding, include:
+   - The metric value and threshold
+   - Severity (critical/warning/info)
+   - Confidence (strong/medium/weak)
+   - Specific remediation action
+
+Provide a structured LCP diagnostic report.`;
+    return {
+        description: `LCP performance analysis for ${url}`,
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `${SYSTEM_CONTEXT}\n\n${userMessage}`,
+                },
+            },
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// Prompt: Full Site Audit
+// ---------------------------------------------------------------------------
+export const AuditArgsSchema = z.object({
+    /** Target URL to audit */
+    url: z.string().min(1, 'url is required'),
+    /** Number of collection runs (default: 1) */
+    runs: z.number().int().min(1).max(5).optional(),
+    /** Whether to focus on a specific category (lcp, js, network, layout) */
+    focus: z.enum(['all', 'lcp', 'js', 'network', 'layout']).optional(),
+});
+/**
+ * Comprehensive full-site performance audit.
+ *
+ * Instructs the AI to perform a thorough analysis across all performance
+ * dimensions and produce a complete diagnostic report.
+ */
+export function buildAuditPrompt(args) {
+    const { url, runs, focus } = args;
+    const focusHint = focus && focus !== 'all'
+        ? `\nFOCUS AREA: ${focus.toUpperCase()}`
+        : '';
+    const userMessage = `Perform a comprehensive performance audit of ${url}${focusHint}.
+
+Workflow:
+1. Call \`perfgraph_run\` with url="${url}"${runs ? `, runs=${runs}` : ''}
+2. Read the full report from the returned resource URIs
+3. Analyze ALL of the following dimensions${focus && focus !== 'all' ? ` (with primary focus on ${focus})` : ''}:
+
+   ${focus === 'all' || !focus ? `
+   a. **LCP (Largest Contentful Paint)** — TTFB, resource delay, render delay, element timing
+   b. **JavaScript** — long tasks, TBT, execution hotspots, parse/compile/evaluate cost
+   c. **Network** — request waterfall, critical path depth, cascade delay, bandwidth contention
+   d. **Layout** — CLS, layout shift clusters, DOM complexity, forced reflows
+   e. **Third-party** — origin attribution, transfer size ratio, blocking scripts` : ''}
+   ${focus === 'lcp' ? `a. **LCP Breakdown** — TTFB, resource delay, render delay, element render time
+   b. **Render-blocking** — CSS/JS/scripts blocking LCP
+   c. **Critical path** — request chain depth to LCP element` : ''}
+   ${focus === 'js' ? `a. **Long tasks** — count, duration, attribution
+   b. **TBT (Total Blocking Time)** — score and contributors
+   c. **Execution hotspots** — top JS files by parse/compile/evaluate time
+   d. **Third-party JS** — overhead from external scripts` : ''}
+   ${focus === 'network' ? `a. **Waterfall depth** — critical chain length and serial requests
+   b. **Cascade delay** — sequential dependency delays
+   c. **Bandwidth contention** — multiplexing opportunities
+   d. **Render-blocking** — blocking request analysis` : ''}
+   ${focus === 'layout' ? `a. **CLS score** — cumulative and individual shifts
+   b. **Layout shift clusters** — timing and affected elements
+   c. **DOM complexity** — total nodes, depth, max children
+   d. **Forced reflows** — layout thrashing patterns` : ''}
+
+4. For every critical and warning issue found, provide:
+   - The metric value and threshold exceeded
+   - Causal chain from root cause to impact
+   - Concrete remediation steps
+   - Expected impact of the fix
+
+5. Prioritize issues by severity and provide an overall site health assessment.
+
+Format the audit as a structured report with clear sections and actionable findings.`;
+    return {
+        description: `Full performance audit of ${url}${focus && focus !== 'all' ? ` (focus: ${focus})` : ''}`,
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `${SYSTEM_CONTEXT}\n\n${userMessage}`,
+                },
+            },
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// Prompt: Summarize Report
+// ---------------------------------------------------------------------------
+export const SummarizeArgsSchema = z.object({
+    /** Resource URI of the report to summarize (e.g., perfgraph://artifacts/<path>/report.toon) */
+    reportUri: z.string().min(1, 'reportUri is required'),
+    /** Detail level for the summary */
+    detail: z.enum(['brief', 'normal', 'detailed']).optional(),
+});
+/**
+ * Summarize an existing PerfGraph report in natural language.
+ *
+ * Takes a report resource URI (as returned by perfgraph_run) and produces
+ * a human-readable summary of the findings.
+ */
+export function buildSummarizePrompt(args) {
+    const { reportUri, detail } = args;
+    const verbosity = detail ?? 'normal';
+    const userMessage = `Read and summarize the PerfGraph performance report at ${reportUri}.
+
+Read the report and provide a ${verbosity === 'brief' ? 'concise (3-5 bullet points)' : verbosity === 'detailed' ? 'comprehensive, section-by-section' : 'balanced'} summary.
+
+Include:
+${verbosity === 'brief' ? `
+- Overall score and critical issue count
+- Top 3 most important findings
+- Single most impactful recommendation` : verbosity === 'detailed' ? `
+- **Executive Summary**: overall score, critical/warning/info counts, system status
+- **All Critical Issues**: full details with metrics, thresholds, and remediations
+- **Causal Chains**: every chain from root cause to impact with confidence levels
+- **All Recommendations**: prioritized with expected impact
+- **Raw Features Summary**: key metric values for LCP, TBT, CLS, etc.` : `
+- Overall score, critical/warning/info breakdown
+- Top 5 issues with severity and confidence
+- Key causal chains
+- Top 3 recommendations with expected impact`}
+
+Base your summary solely on the report data — do not add information not present in the report. Use natural language, not JSON.`;
+    return {
+        description: `Summarize PerfGraph report at ${reportUri}`,
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: `${SYSTEM_CONTEXT}\n\n${userMessage}`,
+                },
+            },
+        ],
+    };
+}
+//# sourceMappingURL=prompts.js.map

package/dist/mcp/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../src/mcp/prompts.ts"],"names":[],"mappings":"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"}

package/dist/mcp/resources.d.ts

@@ -0,0 +1,48 @@
+/**
+ * MCP resources for PerfGraph.
+ *
+ * Registers resource templates and static resources that allow AI agents
+ * to read collected data and diagnostic reports via MCP.
+ *
+ * Resource URI scheme:
+ *   perfgraph://artifacts/{encoded-path}/{filename}
+ *
+ * Where {encoded-path} is the run directory path encoded with `/` → `_` substitution.
+ *
+ * @packageDocumentation
+ */
+export interface ResourceContent {
+    uri: string;
+    text: string;
+    mimeType?: string;
+}
+/**
+ * Read a resource by its PerfGraph URI.
+ *
+ * Format: perfgraph://artifacts/{encoded-path}/{filename}
+ *
+ * The encoded-path uses `_` as path separator (safe for URIs).
+ */
+export declare function readResource(uri: string): ResourceContent;
+/**
+ * List known artifacts in a PerfGraph run directory.
+ */
+export declare function listArtifacts(uri: string): ResourceContent[];
+/**
+ * Encode a filesystem path for use in a perfgraph:// URI.
+ *
+ * Replaces path separators with `_` to produce a valid URI segment.
+ */
+export declare function encodePath(filePath: string): string;
+/**
+ * Resolve a webtr:// resource URI and return its content in TOON format.
+ *
+ * URI scheme: webtr://runs/{runRef}/toon
+ *
+ * The {runRef} is the run directory path with `_` as separator (same
+ * encoding as perfgraph://artifacts/ URIs). Reads the run's report
+ * and features JSON, then encodes them as TOON for token-efficient
+ * LLM consumption.
+ */
+export declare function toon(uri: string): ResourceContent;
+//# sourceMappingURL=resources.d.ts.map

package/dist/mcp/resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../../src/mcp/resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAWH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CA+BzD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,EAAE,CAmD5D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;;;;GASG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAyCjD"}

package/dist/mcp/resources.js

@@ -0,0 +1,149 @@
+/**
+ * MCP resources for PerfGraph.
+ *
+ * Registers resource templates and static resources that allow AI agents
+ * to read collected data and diagnostic reports via MCP.
+ *
+ * Resource URI scheme:
+ *   perfgraph://artifacts/{encoded-path}/{filename}
+ *
+ * Where {encoded-path} is the run directory path encoded with `/` → `_` substitution.
+ *
+ * @packageDocumentation
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { encode } from '@toon-format/toon';
+/**
+ * Read a resource by its PerfGraph URI.
+ *
+ * Format: perfgraph://artifacts/{encoded-path}/{filename}
+ *
+ * The encoded-path uses `_` as path separator (safe for URIs).
+ */
+export function readResource(uri) {
+    const parsed = /^perfgraph:\/\/artifacts\/(.+?)\/(.+)$/.exec(uri);
+    if (!parsed) {
+        throw new Error(`Invalid resource URI: ${uri}`);
+    }
+    const encodedPath = parsed[1];
+    const filename = parsed[2];
+    // Decode: `_` → `\` (Windows) or `/` (standard separator)
+    const decodedPath = encodedPath.split('_').join('/');
+    const filePath = resolve(decodedPath, filename);
+    if (!existsSync(filePath)) {
+        throw new Error(`Resource not found: ${filePath}`);
+    }
+    const content = readFileSync(filePath, 'utf-8');
+    // Determine mimeType from filename
+    let mimeType = 'application/octet-stream';
+    if (filename.endsWith('.json') || filename.endsWith('.toon')) {
+        mimeType = 'application/json';
+    }
+    else if (filename.endsWith('.json.gz')) {
+        mimeType = 'application/gzip';
+    }
+    else if (filename.endsWith('.txt')) {
+        mimeType = 'text/plain';
+    }
+    return { uri, text: content, mimeType };
+}
+/**
+ * List known artifacts in a PerfGraph run directory.
+ */
+export function listArtifacts(uri) {
+    const parsed = /^perfgraph:\/\/artifacts\/(.+)$/.exec(uri);
+    if (!parsed) {
+        throw new Error(`Invalid resource URI: ${uri}`);
+    }
+    const encodedPath = parsed[1];
+    const decodedPath = encodedPath.split('_').join('/');
+    const dirPath = resolve(decodedPath);
+    if (!existsSync(dirPath)) {
+        return [];
+    }
+    // Common PerfGraph artifacts
+    const artifacts = [
+        'report.toon',
+        'features.toon',
+        'graph.toon',
+        'ir.json',
+        'insights.toon',
+        'manifest.toon',
+        'trace.json',
+        'network.json',
+        'performance.json',
+        'lighthouse.json',
+        'runtime.json',
+        'console.json',
+        'dom.json',
+        'coverage.json',
+        'warnings.json',
+        'network-summary.toon',
+        'lighthouse-summary.toon',
+        'coverage-summary.toon',
+    ];
+    const results = [];
+    for (const artifact of artifacts) {
+        const filePath = resolve(dirPath, artifact);
+        if (existsSync(filePath)) {
+            const content = readFileSync(filePath, 'utf-8');
+            results.push({
+                uri: `perfgraph://artifacts/${encodedPath}/${artifact}`,
+                text: content,
+                mimeType: 'application/json',
+            });
+        }
+    }
+    return results;
+}
+/**
+ * Encode a filesystem path for use in a perfgraph:// URI.
+ *
+ * Replaces path separators with `_` to produce a valid URI segment.
+ */
+export function encodePath(filePath) {
+    return filePath.replace(/[\\/]/g, '_');
+}
+/**
+ * Resolve a webtr:// resource URI and return its content in TOON format.
+ *
+ * URI scheme: webtr://runs/{runRef}/toon
+ *
+ * The {runRef} is the run directory path with `_` as separator (same
+ * encoding as perfgraph://artifacts/ URIs). Reads the run's report
+ * and features JSON, then encodes them as TOON for token-efficient
+ * LLM consumption.
+ */
+export function toon(uri) {
+    const parsed = /^webtr:\/\/runs\/(.+?)\/toon$/.exec(uri);
+    if (!parsed) {
+        throw new Error(`Invalid TOON resource URI: ${uri}`);
+    }
+    const runRef = parsed[1];
+    const decodedPath = runRef.split('_').join('/');
+    const dirPath = resolve(decodedPath);
+    if (!existsSync(dirPath)) {
+        throw new Error(`Run directory not found: ${dirPath}`);
+    }
+    // Load report and/or features from the run directory
+    const reportFile = resolve(dirPath, 'report.toon');
+    const featuresFile = resolve(dirPath, 'features.toon');
+    const graphFile = resolve(dirPath, 'graph.toon');
+    const data = {};
+    if (existsSync(reportFile)) {
+        data.report = JSON.parse(readFileSync(reportFile, 'utf-8'));
+    }
+    if (existsSync(featuresFile)) {
+        data.features = JSON.parse(readFileSync(featuresFile, 'utf-8'));
+    }
+    if (existsSync(graphFile)) {
+        data.graph = JSON.parse(readFileSync(graphFile, 'utf-8'));
+    }
+    if (Object.keys(data).length === 0) {
+        throw new Error(`No run data found in: ${dirPath}`);
+    }
+    const text = encode(data);
+    return { uri, text, mimeType: 'text/plain' };
+}
+//# sourceMappingURL=resources.js.map

package/dist/mcp/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../../src/mcp/resources.ts"],"names":[],"mappings":"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"}

package/dist/mcp/server.d.ts

@@ -0,0 +1,34 @@
+/**
+ * PerfGraph MCP Server.
+ *
+ * Exposes PerfGraph's full performance diagnostic pipeline through
+ * the Model Context Protocol. Primary usage is the `perfgraph_run` tool
+ * (one-shot URL → report). Advanced users can invoke individual pipeline
+ * steps via dedicated tools.
+ *
+ * Resources are available at `perfgraph://artifacts/{encoded-path}/{filename}`
+ * for reading collected data and generated reports.
+ *
+ * Usage (AI client config):
+ * ```json
+ * {
+ *   "mcpServers": {
+ *     "perfgraph": {
+ *       "command": "node",
+ *       "args": ["dist/index.js", "mcp"]
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * Start the MCP stdio server.
+ *
+ * Registers all tools and resources, then listens for JSON-RPC messages
+ * on stdin/stdout. Never resolves — the server runs until the process
+ * is killed.
+ */
+export declare function startMcpServer(): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/mcp/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AA6CH;;;;;;GAMG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CA0gBpD"}