cssprobe-cli 0.2.25 → 0.3.0

package/dist/mcp/tools.d.ts

@@ -0,0 +1,261 @@
+export declare function getToolDefinitions(): ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            url: {
+                type: "string";
+                description: string;
+            };
+            headed: {
+                type: "boolean";
+                description: string;
+            };
+            viewport: {
+                type: "string";
+                description: string;
+            };
+            browser: {
+                type: "string";
+                enum: string[];
+                description: string;
+            };
+            state: {
+                type: "string";
+                description: string;
+            };
+            selector?: undefined;
+            depth?: undefined;
+            brief?: undefined;
+            expression?: undefined;
+            full_page?: undefined;
+            out?: undefined;
+            css?: undefined;
+            all?: undefined;
+        };
+        required: never[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            selector: {
+                type: "string";
+                description: string;
+            };
+            depth: {
+                type: "number";
+                description: string;
+            };
+            brief: {
+                type: "boolean";
+                description: string;
+            };
+            url?: undefined;
+            headed?: undefined;
+            viewport?: undefined;
+            browser?: undefined;
+            state?: undefined;
+            expression?: undefined;
+            full_page?: undefined;
+            out?: undefined;
+            css?: undefined;
+            all?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            selector: {
+                type: "string";
+                description: string;
+            };
+            depth: {
+                type: "number";
+                description: string;
+            };
+            url?: undefined;
+            headed?: undefined;
+            viewport?: undefined;
+            browser?: undefined;
+            state?: undefined;
+            brief?: undefined;
+            expression?: undefined;
+            full_page?: undefined;
+            out?: undefined;
+            css?: undefined;
+            all?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            selector: {
+                type: "string";
+                description: string;
+            };
+            url?: undefined;
+            headed?: undefined;
+            viewport?: undefined;
+            browser?: undefined;
+            state?: undefined;
+            depth?: undefined;
+            brief?: undefined;
+            expression?: undefined;
+            full_page?: undefined;
+            out?: undefined;
+            css?: undefined;
+            all?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            expression: {
+                type: "string";
+                description: string;
+            };
+            url?: undefined;
+            headed?: undefined;
+            viewport?: undefined;
+            browser?: undefined;
+            state?: undefined;
+            selector?: undefined;
+            depth?: undefined;
+            brief?: undefined;
+            full_page?: undefined;
+            out?: undefined;
+            css?: undefined;
+            all?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            full_page: {
+                type: "boolean";
+                description: string;
+            };
+            out: {
+                type: "string";
+                description: string;
+            };
+            url?: undefined;
+            headed?: undefined;
+            viewport?: undefined;
+            browser?: undefined;
+            state?: undefined;
+            selector?: undefined;
+            depth?: undefined;
+            brief?: undefined;
+            expression?: undefined;
+            css?: undefined;
+            all?: undefined;
+        };
+        required: never[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            css: {
+                type: "string";
+                description: string;
+            };
+            url?: undefined;
+            headed?: undefined;
+            viewport?: undefined;
+            browser?: undefined;
+            state?: undefined;
+            selector?: undefined;
+            depth?: undefined;
+            brief?: undefined;
+            expression?: undefined;
+            full_page?: undefined;
+            out?: undefined;
+            all?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            all: {
+                type: "boolean";
+                description: string;
+            };
+            url?: undefined;
+            headed?: undefined;
+            viewport?: undefined;
+            browser?: undefined;
+            state?: undefined;
+            selector?: undefined;
+            depth?: undefined;
+            brief?: undefined;
+            expression?: undefined;
+            full_page?: undefined;
+            out?: undefined;
+            css?: undefined;
+        };
+        required: never[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            url?: undefined;
+            headed?: undefined;
+            viewport?: undefined;
+            browser?: undefined;
+            state?: undefined;
+            selector?: undefined;
+            depth?: undefined;
+            brief?: undefined;
+            expression?: undefined;
+            full_page?: undefined;
+            out?: undefined;
+            css?: undefined;
+            all?: undefined;
+        };
+        required: never[];
+    };
+})[];
+export declare class MCPToolHandler {
+    private runSession;
+    open(args: Record<string, unknown>): Promise<string>;
+    inspect(args: Record<string, unknown>): Promise<string>;
+    tree(args: Record<string, unknown>): Promise<string>;
+    layout(args: Record<string, unknown>): Promise<string>;
+    findings(args: Record<string, unknown>): Promise<string>;
+    evalExpression(args: Record<string, unknown>): Promise<string>;
+    screenshot(args: Record<string, unknown>): Promise<string>;
+    injectCss(args: Record<string, unknown>): Promise<string>;
+    close(args: Record<string, unknown>): Promise<string>;
+    status(): Promise<string>;
+}

package/dist/mcp/tools.js

@@ -0,0 +1,238 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCPToolHandler = void 0;
+exports.getToolDefinitions = getToolDefinitions;
+const commands_1 = require("../cli/commands");
+const session_ops_1 = require("../cli/session-ops");
+const GUIDANCE_PATTERN = /No active session|Browser is not open|Daemon failed to become ready/;
+function getToolDefinitions() {
+    return [
+        {
+            name: 'cssprobe_open',
+            description: 'Open a browser session (non-blocking). Required before any inspect/layout/findings call. ' +
+                'Use headed: true when the target page needs a manual login.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    url: { type: 'string', description: 'URL, file:// path, or local HTML file path (default: about:blank)' },
+                    headed: { type: 'boolean', description: 'show the browser window (default: false)' },
+                    viewport: { type: 'string', description: 'viewport size as WxH (e.g. 1280x720)' },
+                    browser: { type: 'string', enum: ['chromium', 'firefox', 'webkit'], description: 'browser engine (default: chromium)' },
+                    state: { type: 'string', description: 'path to a saved state file (cookies + localStorage)' },
+                },
+                required: [],
+            },
+        },
+        {
+            name: 'cssprobe_inspect',
+            description: 'Inspect the runtime CSS of an element: DOM tree, computed styles, layout diagram and ' +
+                'confidence-classified findings in one call.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    selector: { type: 'string', description: 'CSS selector for the root element (e.g. ".sidebar")' },
+                    depth: { type: 'number', description: 'DOM tree depth (default: auto, max 20)' },
+                    brief: { type: 'boolean', description: 'compact output: tree sketch + warnings/errors only' },
+                },
+                required: ['selector'],
+            },
+        },
+        {
+            name: 'cssprobe_tree',
+            description: 'Show the DOM tree structure under a selector.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    selector: { type: 'string', description: 'CSS selector for the root element' },
+                    depth: { type: 'number', description: 'tree depth (default: auto, max 20)' },
+                },
+                required: ['selector'],
+            },
+        },
+        {
+            name: 'cssprobe_layout',
+            description: 'Show the ASCII layout diagram (element positions and sizes) for a selector.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    selector: { type: 'string', description: 'CSS selector for the root element' },
+                },
+                required: ['selector'],
+            },
+        },
+        {
+            name: 'cssprobe_findings',
+            description: 'Show only issues/warnings/errors with confidence levels for a selector.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    selector: { type: 'string', description: 'CSS selector for the root element' },
+                },
+                required: ['selector'],
+            },
+        },
+        {
+            name: 'cssprobe_eval',
+            description: 'Evaluate a JavaScript expression in the browser page context and return the result.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    expression: { type: 'string', description: 'JavaScript expression to evaluate' },
+                },
+                required: ['expression'],
+            },
+        },
+        {
+            name: 'cssprobe_screenshot',
+            description: 'Take a screenshot of the page and save it as a PNG file; returns the file path.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    full_page: { type: 'boolean', description: 'capture the full scrollable page (default: viewport only)' },
+                    out: { type: 'string', description: 'output file path (default: ~/.cssprobe-cli/screenshots/<timestamp>.png)' },
+                },
+                required: [],
+            },
+        },
+        {
+            name: 'cssprobe_inject_css',
+            description: 'Inject CSS into the current page (useful for live experiments).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    css: { type: 'string', description: 'CSS code to inject' },
+                },
+                required: ['css'],
+            },
+        },
+        {
+            name: 'cssprobe_close',
+            description: 'Close the browser session. Pass all: true to close sessions across all workspaces.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    all: { type: 'boolean', description: 'close all sessions across all workspaces' },
+                },
+                required: [],
+            },
+        },
+        {
+            name: 'cssprobe_status',
+            description: 'Show the current session status (alive / dead / none).',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+                required: [],
+            },
+        },
+    ];
+}
+function toMessage(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+class MCPToolHandler {
+    async runSession(commandName, parsed) {
+        const command = commands_1.commands[commandName];
+        if (!command)
+            throw new Error(`Unknown command: ${commandName}`);
+        try {
+            const result = await (0, session_ops_1.runSessionCommand)(commandName, command, parsed);
+            if (commandName === 'screenshot' && typeof result.text === 'string' && result.text.startsWith('data:image/png;base64,')) {
+                const saved = (0, session_ops_1.saveScreenshotFile)(result.text, parsed.out);
+                return `Screenshot saved: ${saved}`;
+            }
+            return result.text;
+        }
+        catch (e) {
+            const msg = toMessage(e);
+            if (GUIDANCE_PATTERN.test(msg))
+                return msg;
+            throw e;
+        }
+    }
+    async open(args) {
+        const opts = {
+            url: typeof args.url === 'string' ? args.url : undefined,
+            browser: typeof args.browser === 'string' ? args.browser : undefined,
+            headed: args.headed === true,
+            state: typeof args.state === 'string' ? args.state : undefined,
+        };
+        if (typeof args.viewport === 'string') {
+            const parts = args.viewport.split('x');
+            const width = parseInt(parts[0] || '', 10);
+            const height = parseInt(parts[1] || '', 10);
+            if (parts.length === 2 && !isNaN(width) && !isNaN(height)) {
+                opts.viewport = { width, height };
+            }
+            else {
+                return 'Invalid viewport format. Use WxH (e.g. 1280x720).';
+            }
+        }
+        try {
+            const result = await (0, session_ops_1.openSession)(opts);
+            return [
+                `Browser opened at ${result.url}`,
+                `Session ID: ${result.sessionId}`,
+                `PID: ${result.pid ?? 'unknown'}`,
+                `Viewport: ${result.viewport.width}x${result.viewport.height}`,
+            ].join('\n');
+        }
+        catch (e) {
+            const msg = toMessage(e);
+            if (GUIDANCE_PATTERN.test(msg))
+                return msg;
+            throw e;
+        }
+    }
+    async inspect(args) {
+        return this.runSession('inspect', {
+            selector: args.selector,
+            depth: args.depth,
+            brief: args.brief,
+        });
+    }
+    async tree(args) {
+        return this.runSession('tree', { selector: args.selector, depth: args.depth });
+    }
+    async layout(args) {
+        return this.runSession('layout', { selector: args.selector });
+    }
+    async findings(args) {
+        return this.runSession('findings', { selector: args.selector });
+    }
+    async evalExpression(args) {
+        return this.runSession('eval', { expression: args.expression });
+    }
+    async screenshot(args) {
+        return this.runSession('screenshot', { 'full-page': args.full_page, out: args.out });
+    }
+    async injectCss(args) {
+        return this.runSession('inject-css', { css: args.css });
+    }
+    async close(args) {
+        try {
+            const result = await (0, session_ops_1.closeSession)(args.all === true);
+            return result.sessions
+                .map(s => (s.closed ? `Closed: ${s.sessionId}` : `Failed: ${s.sessionId} (${s.error})`))
+                .join('\n');
+        }
+        catch (e) {
+            const msg = toMessage(e);
+            if (GUIDANCE_PATTERN.test(msg))
+                return msg;
+            throw e;
+        }
+    }
+    async status() {
+        const result = await (0, session_ops_1.getSessionStatus)();
+        if (!result.config)
+            return 'No active session. Run cssprobe_open to start one.';
+        const config = result.config;
+        const lines = [`Session: ${result.sessionId}`, `Status: ${result.alive ? 'alive' : 'dead'}`];
+        if (result.alive && config.browser?.browserName)
+            lines.push(`Browser: ${config.browser.browserName}`);
+        return lines.join('\n');
+    }
+}
+exports.MCPToolHandler = MCPToolHandler;
+//# sourceMappingURL=tools.js.map

package/llms.txt

@@ -0,0 +1,15 @@
+# cssprobe-cli
+
+> Runtime CSS probe — inspect layout, scroll, colors, backgrounds, fonts in a live browser. Returns DOM tree, ASCII layout diagram and confidence-classified findings for humans and AI agents.
+
+## Documentation
+
+- [README](https://raw.githubusercontent.com/mack-peng/cssprobe-cli/main/README.md): overview, quick start, configuration
+- [MCP server usage](https://raw.githubusercontent.com/mack-peng/cssprobe-cli/main/README.md): `cssprobe-cli mcp-install` — native tools for Claude Code / Cursor / Codex / opencode / Gemini / Hermes (10 tools: open, inspect, tree, layout, findings, eval, screenshot, inject_css, close, status)
+- [Installation guide](https://raw.githubusercontent.com/mack-peng/cssprobe-cli/main/docs/guide/installation.md): agent-friendly install and skill wiring (Claude Code, Cursor, Codex, …)
+- [npm package](https://www.npmjs.com/package/cssprobe-cli): `npm install -g cssprobe-cli`
+
+## Optional
+
+- [GitHub repository](https://github.com/mack-peng/cssprobe-cli): source code, issues, releases
+- [cssgraph](https://github.com/mack-peng/cssgraph): companion static CSS knowledge graph for AI agents

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "cssprobe-cli",
-  "version": "0.2.25",
+  "version": "0.3.0",
+  "mcpName": "io.github.mack-peng/cssprobe-cli",
   "description": "Runtime CSS probe — inspect layout, colors, backgrounds, fonts and more in a live browser. AI agents and shell automation.",
   "keywords": [
     "css",
@@ -30,7 +31,9 @@
     "docs",
     "README.md",
     "LICENSE",
-    "AGENTS.md"
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "llms.txt"
   ],
   "engines": {
     "node": ">=18"