fe-inspector-mcp 0.2.0 → 0.3.0

package/dist/index.js

@@ -2,10 +2,14 @@
 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 { createRequire } from 'module';
 import { runInspection, getInspectorMeta } from './inspector/index.js';
 import { generateTextReport, generateJsonReport } from './reporter/index.js';
 import { reviewDesign, formatReview } from './design-review.js';
-const { version, name } = { version: '0.2.0', name: 'fe-inspector-mcp' };
+// 从 package.json 动态读取版本号
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+const { version, name } = { version: pkg.version, name: pkg.name };
 const server = new Server({ name, version }, { capabilities: { tools: {} } });
 // ── Tool definitions ──
 server.setRequestHandler(ListToolsRequestSchema, async () => {

package/dist/inspector/a11y.js

@@ -1,4 +1,5 @@
-import { load } from 'cheerio';
+import { parseHtml } from '../utils/parser.js';
+import { buildSelector } from '../utils/dom.js';
 const category = 'a11y';
 const rules = [
     {
@@ -118,16 +119,8 @@ const rules = [
         },
     },
 ];
-function buildSelector($el) {
-    const tag = typeof $el.prop === 'function' ? ($el.prop('tagName')?.toLowerCase() || 'div') : 'div';
-    const id = $el.attr?.('id');
-    if (id)
-        return `#${id}`;
-    const cls = ($el.attr?.('class') || '').split(/\s+/).filter(Boolean).slice(0, 2).join('.');
-    return cls ? `${tag}.${cls}` : tag;
-}
 export function inspectA11y(html) {
-    const $ = load(html);
+    const $ = parseHtml(html);
     const results = [];
     for (const rule of rules) {
         results.push(...rule.check($));

package/dist/inspector/aesthetic.js

@@ -1,4 +1,5 @@
-import { load } from 'cheerio';
+import { parseHtml } from '../utils/parser.js';
+import { buildSelector } from '../utils/dom.js';
 const category = 'aesthetic';
 const rules = [
     {
@@ -122,16 +123,8 @@ const rules = [
         },
     },
 ];
-function buildSelector($el) {
-    const tag = typeof $el.prop === 'function' ? ($el.prop('tagName')?.toLowerCase() || 'div') : 'div';
-    const id = $el.attr?.('id');
-    if (id)
-        return `#${id}`;
-    const cls = ($el.attr?.('class') || '').split(/\s+/).filter(Boolean).slice(0, 2).join('.');
-    return cls ? `${tag}.${cls}` : tag;
-}
 export function inspectAesthetic(html) {
-    const $ = load(html);
+    const $ = parseHtml(html);
     const results = [];
     for (const rule of rules) {
         results.push(...rule.check($));

package/dist/inspector/index.js

@@ -1,7 +1,9 @@
+import { parseHtml } from '../utils/parser.js';
 import { inspectAesthetic, aestheticMeta } from './aesthetic.js';
 import { inspectA11y, a11yMeta } from './a11y.js';
 import { inspectResponsive, responsiveMeta } from './responsive.js';
 import { inspectInteraction, interactionMeta } from './interaction.js';
+import { inspectPerformance, performanceMeta } from './performance.js';
 const inspectors = {
     aesthetic: {
         ...aestheticMeta,
@@ -19,10 +21,16 @@ const inspectors = {
         ...interactionMeta,
         inspect: inspectInteraction,
     },
+    performance: {
+        ...performanceMeta,
+        inspect: inspectPerformance,
+    },
 };
 export function runInspection(input) {
     const { html, url } = input;
     const categories = input.categories || Object.keys(inspectors);
+    // 使用缓存解析 HTML，避免重复解析
+    const $ = parseHtml(html);
     const categoryResults = {};
     let total = 0;
     let passed = 0;

package/dist/inspector/interaction.js

@@ -1,4 +1,5 @@
-import { load } from 'cheerio';
+import { parseHtml } from '../utils/parser.js';
+import { buildSelector } from '../utils/dom.js';
 const category = 'interaction';
 const rules = [
     {
@@ -117,16 +118,8 @@ const rules = [
         },
     },
 ];
-function buildSelector($el) {
-    const tag = typeof $el.prop === 'function' ? ($el.prop('tagName')?.toLowerCase() || 'div') : 'div';
-    const id = $el.attr?.('id');
-    if (id)
-        return `#${id}`;
-    const cls = ($el.attr?.('class') || '').split(/\s+/).filter(Boolean).slice(0, 2).join('.');
-    return cls ? `${tag}.${cls}` : tag;
-}
 export function inspectInteraction(html) {
-    const $ = load(html);
+    const $ = parseHtml(html);
     const results = [];
     for (const rule of rules) {
         results.push(...rule.check($));

package/dist/inspector/performance.d.ts

@@ -0,0 +1,8 @@
+import type { Detection } from '../types.js';
+export declare function inspectPerformance(html: string): Detection[];
+export declare const performanceMeta: {
+    category: "performance";
+    label: string;
+    description: string;
+    ruleCount: number;
+};

package/dist/inspector/performance.js

@@ -0,0 +1,157 @@
+import { parseHtml } from '../utils/parser.js';
+import { buildSelector } from '../utils/dom.js';
+const category = 'performance';
+const rules = [
+    {
+        id: 'pf-001',
+        title: 'Large image without width/height',
+        check: ($) => {
+            const results = [];
+            $('img').each((_i, el) => {
+                const width = $(el).attr('width');
+                const height = $(el).attr('height');
+                if (!width && !height) {
+                    results.push({
+                        ruleId: 'pf-001',
+                        severity: 'warning',
+                        title: 'Image missing dimensions',
+                        message: 'Image has no width/height attributes — causes layout shift (CLS).',
+                        element: buildSelector($(el)),
+                        recommendation: 'Add explicit width and height attributes to prevent Cumulative Layout Shift.',
+                    });
+                }
+            });
+            return results;
+        },
+    },
+    {
+        id: 'pf-002',
+        title: 'Render-blocking external CSS/JS in <head>',
+        check: ($) => {
+            const results = [];
+            // Check for render-blocking stylesheets
+            $('head link[rel="stylesheet"]').each((_i, el) => {
+                const href = $(el).attr('href');
+                const media = $(el).attr('media');
+                if (href && !media) {
+                    results.push({
+                        ruleId: 'pf-002',
+                        severity: 'warning',
+                        title: 'Render-blocking stylesheet',
+                        message: `Stylesheet ${href} blocks rendering.`,
+                        element: buildSelector($(el)),
+                        recommendation: 'Use media="print" for non-critical CSS, or load asynchronously.',
+                    });
+                }
+            });
+            // Check for render-blocking scripts
+            $('head script[src]').each((_i, el) => {
+                const defer = $(el).attr('defer');
+                const async = $(el).attr('async');
+                if (!defer && !async) {
+                    results.push({
+                        ruleId: 'pf-002',
+                        severity: 'warning',
+                        title: 'Render-blocking script',
+                        message: 'Script in <head> without defer/async blocks rendering.',
+                        element: buildSelector($(el)),
+                        recommendation: 'Add defer or async attribute to non-critical scripts.',
+                    });
+                }
+            });
+            return results;
+        },
+    },
+    {
+        id: 'pf-003',
+        title: 'Image not optimized (no loading=lazy below fold)',
+        check: ($) => {
+            const results = [];
+            const images = $('img').toArray();
+            // Skip first 2 images (likely above fold)
+            images.slice(2).forEach((el, index) => {
+                const loading = $(el).attr('loading');
+                if (!loading || loading !== 'lazy') {
+                    results.push({
+                        ruleId: 'pf-003',
+                        severity: 'info',
+                        title: 'Below-fold image missing lazy loading',
+                        message: `Image #${index + 3} should use loading="lazy".`,
+                        element: buildSelector($(el)),
+                        recommendation: 'Add loading="lazy" to images below the fold for faster initial load.',
+                    });
+                }
+            });
+            return results;
+        },
+    },
+    {
+        id: 'pf-004',
+        title: 'Too many HTTP requests (css/js/img count)',
+        check: ($) => {
+            const results = [];
+            const cssCount = $('link[href][rel="stylesheet"]').length;
+            const jsCount = $('script[src]').length;
+            const imgCount = $('img[src]').length;
+            const total = cssCount + jsCount + imgCount;
+            if (total > 30) {
+                results.push({
+                    ruleId: 'pf-004',
+                    severity: 'info',
+                    title: 'Too many HTTP requests',
+                    message: `Found ${total} external resources (${cssCount} CSS, ${jsCount} JS, ${imgCount} images).`,
+                    element: 'head',
+                    recommendation: 'Bundle CSS/JS files and use image sprites or lazy loading to reduce requests.',
+                });
+            }
+            return results;
+        },
+    },
+    {
+        id: 'pf-005',
+        title: 'DOM depth too deep (> 15 levels)',
+        check: ($) => {
+            const results = [];
+            function getMaxDepth(el, currentDepth) {
+                let maxDepth = currentDepth;
+                const children = $(el).children().toArray();
+                for (const child of children) {
+                    const childDepth = getMaxDepth(child, currentDepth + 1);
+                    if (childDepth > maxDepth) {
+                        maxDepth = childDepth;
+                    }
+                }
+                return maxDepth;
+            }
+            const body = $('body').get(0);
+            if (body) {
+                const depth = getMaxDepth(body, 0);
+                if (depth > 15) {
+                    results.push({
+                        ruleId: 'pf-005',
+                        severity: 'info',
+                        title: 'DOM depth too deep',
+                        message: `DOM nesting depth is ${depth} levels (max recommended: 15).`,
+                        element: 'body',
+                        recommendation: 'Flatten HTML structure — deep nesting slows rendering and hurts maintainability.',
+                    });
+                }
+            }
+            return results;
+        },
+    },
+];
+export function inspectPerformance(html) {
+    const $ = parseHtml(html);
+    const results = [];
+    for (const rule of rules) {
+        results.push(...rule.check($));
+    }
+    return results;
+}
+export const performanceMeta = {
+    category,
+    label: 'Performance',
+    description: 'Page speed — image optimization, render blocking, DOM depth, HTTP requests',
+    ruleCount: rules.length,
+};

package/dist/inspector/responsive.js

@@ -1,4 +1,5 @@
-import { load } from 'cheerio';
+import { parseHtml } from '../utils/parser.js';
+import { buildSelector } from '../utils/dom.js';
 const category = 'responsive';
 const rules = [
     {
@@ -125,16 +126,8 @@ const rules = [
         },
     },
 ];
-function buildSelector($el) {
-    const tag = typeof $el.prop === 'function' ? ($el.prop('tagName')?.toLowerCase() || 'div') : 'div';
-    const id = $el.attr?.('id');
-    if (id)
-        return `#${id}`;
-    const cls = ($el.attr?.('class') || '').split(/\s+/).filter(Boolean).slice(0, 2).join('.');
-    return cls ? `${tag}.${cls}` : tag;
-}
 export function inspectResponsive(html) {
-    const $ = load(html);
+    const $ = parseHtml(html);
     const results = [];
     for (const rule of rules) {
         results.push(...rule.check($));

package/dist/types.d.ts

@@ -1,4 +1,7 @@
 export type Severity = 'error' | 'warning' | 'info';
+export type CheerioElement = any;
+export type CheerioSelection = any;
+export type CheerioAPI = any;
 export interface Detection {
     ruleId: string;
     severity: Severity;
@@ -7,7 +10,7 @@ export interface Detection {
     element?: string;
     recommendation: string;
 }
-export type InspectCategory = 'aesthetic' | 'a11y' | 'responsive' | 'interaction';
+export type InspectCategory = 'aesthetic' | 'a11y' | 'responsive' | 'interaction' | 'performance';
 export interface InspectReport {
     url?: string;
     totalElements: number;

package/dist/utils/dom.d.ts

@@ -0,0 +1,7 @@
+import type { CheerioSelection } from '../types.js';
+/**
+ * 构建元素的 CSS 选择器
+ * @param $el Cheerio 元素对象
+ * @returns CSS 选择器字符串
+ */
+export declare function buildSelector($el: CheerioSelection): string;

package/dist/utils/dom.js

@@ -0,0 +1,13 @@
+/**
+ * 构建元素的 CSS 选择器
+ * @param $el Cheerio 元素对象
+ * @returns CSS 选择器字符串
+ */
+export function buildSelector($el) {
+    const tag = typeof $el.prop === 'function' ? ($el.prop('tagName')?.toLowerCase() || 'div') : 'div';
+    const id = $el.attr?.('id');
+    if (id)
+        return `#${id}`;
+    const cls = ($el.attr?.('class') || '').split(/\s+/).filter(Boolean).slice(0, 2).join('.');
+    return cls ? `${tag}.${cls}` : tag;
+}

package/dist/utils/parser.d.ts

@@ -0,0 +1,31 @@
+/**
+ * HTML 解析缓存
+ * 避免同一个 HTML 字符串被多次解析
+ */
+declare class ParserCache {
+    private cache;
+    private maxSize;
+    constructor(maxSize?: number);
+    /**
+     * 获取解析后的 Cheerio 实例
+     * @param html HTML 字符串
+     * @returns CheerioAPI 实例
+     */
+    parse(html: string): any;
+    /**
+     * 清空缓存
+     */
+    clear(): void;
+    /**
+     * 获取缓存大小
+     */
+    get size(): number;
+}
+export declare const parserCache: ParserCache;
+/**
+ * 解析 HTML 并缓存结果
+ * @param html HTML 字符串
+ * @returns CheerioAPI 实例
+ */
+export declare function parseHtml(html: string): any;
+export {};

package/dist/utils/parser.js

@@ -0,0 +1,56 @@
+// ── HTML 解析缓存模块 ──
+import { load } from 'cheerio';
+/**
+ * HTML 解析缓存
+ * 避免同一个 HTML 字符串被多次解析
+ */
+class ParserCache {
+    cache = new Map();
+    maxSize;
+    constructor(maxSize = 10) {
+        this.maxSize = maxSize;
+    }
+    /**
+     * 获取解析后的 Cheerio 实例
+     * @param html HTML 字符串
+     * @returns CheerioAPI 实例
+     */
+    parse(html) {
+        const cached = this.cache.get(html);
+        if (cached) {
+            return cached;
+        }
+        // 如果缓存已满，删除最旧的条目
+        if (this.cache.size >= this.maxSize) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey !== undefined) {
+                this.cache.delete(firstKey);
+            }
+        }
+        const $ = load(html);
+        this.cache.set(html, $);
+        return $;
+    }
+    /**
+     * 清空缓存
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * 获取缓存大小
+     */
+    get size() {
+        return this.cache.size;
+    }
+}
+// 导出全局缓存实例
+export const parserCache = new ParserCache();
+/**
+ * 解析 HTML 并缓存结果
+ * @param html HTML 字符串
+ * @returns CheerioAPI 实例
+ */
+export function parseHtml(html) {
+    return parserCache.parse(html);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fe-inspector-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MCP Server for frontend quality inspection — catches aesthetic flaws, a11y issues, responsive breaks, and interaction bugs in AI-generated HTML.",
   "type": "module",
   "bin": {
@@ -15,6 +15,9 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -38,6 +41,7 @@
     "@types/cheerio": "^0.22.35",
     "@types/node": "^22.20.1",
     "tsx": "^4.19.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.10"
   }
 }