@pyrokine/mcp-chrome 1.1.0 → 1.3.0

package/dist/tools/extract.d.ts

@@ -8,232 +8,9 @@
  * - screenshot: 截图
  * - state: 页面状态（精简的可交互元素列表）
  */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 /**
- * extract 工具定义
+ * 注册 extract 工具
  */
-export declare const extractToolDefinition: {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: "object";
-        properties: {
-            type: {
-                type: string;
-                enum: string[];
-                description: string;
-            };
-            target: {
-                description: string;
-                oneOf: readonly [{
-                    readonly type: "object";
-                    readonly title: "可访问性树定位";
-                    readonly description: "通过 ARIA role 和 name 定位元素";
-                    readonly properties: {
-                        readonly role: {
-                            readonly type: "string";
-                            readonly description: "ARIA role（如 button、link、textbox）";
-                        };
-                        readonly name: {
-                            readonly type: "string";
-                            readonly description: "可访问名称（可选）";
-                        };
-                    };
-                    readonly required: readonly ["role"];
-                    readonly additionalProperties: false;
-                }, {
-                    readonly type: "object";
-                    readonly title: "文本内容定位";
-                    readonly description: "通过元素文本内容定位";
-                    readonly properties: {
-                        readonly text: {
-                            readonly type: "string";
-                            readonly description: "文本内容";
-                        };
-                        readonly exact: {
-                            readonly type: "boolean";
-                            readonly description: "是否精确匹配（默认 false）";
-                        };
-                    };
-                    readonly required: readonly ["text"];
-                    readonly additionalProperties: false;
-                }, {
-                    readonly type: "object";
-                    readonly title: "Label 定位";
-                    readonly description: "通过表单 label 文本定位关联的输入元素";
-                    readonly properties: {
-                        readonly label: {
-                            readonly type: "string";
-                            readonly description: "label 文本";
-                        };
-                        readonly exact: {
-                            readonly type: "boolean";
-                            readonly description: "是否精确匹配（默认 false）";
-                        };
-                    };
-                    readonly required: readonly ["label"];
-                    readonly additionalProperties: false;
-                }, {
-                    readonly type: "object";
-                    readonly title: "Placeholder 定位";
-                    readonly description: "通过输入框的 placeholder 属性定位";
-                    readonly properties: {
-                        readonly placeholder: {
-                            readonly type: "string";
-                            readonly description: "placeholder 文本";
-                        };
-                        readonly exact: {
-                            readonly type: "boolean";
-                            readonly description: "是否精确匹配（默认 false）";
-                        };
-                    };
-                    readonly required: readonly ["placeholder"];
-                    readonly additionalProperties: false;
-                }, {
-                    readonly type: "object";
-                    readonly title: "Title 属性定位";
-                    readonly description: "通过元素的 title 属性定位";
-                    readonly properties: {
-                        readonly title: {
-                            readonly type: "string";
-                            readonly description: "title 属性值";
-                        };
-                        readonly exact: {
-                            readonly type: "boolean";
-                            readonly description: "是否精确匹配（默认 false）";
-                        };
-                    };
-                    readonly required: readonly ["title"];
-                    readonly additionalProperties: false;
-                }, {
-                    readonly type: "object";
-                    readonly title: "Alt 属性定位";
-                    readonly description: "通过图片的 alt 属性定位";
-                    readonly properties: {
-                        readonly alt: {
-                            readonly type: "string";
-                            readonly description: "alt 属性值";
-                        };
-                        readonly exact: {
-                            readonly type: "boolean";
-                            readonly description: "是否精确匹配（默认 false）";
-                        };
-                    };
-                    readonly required: readonly ["alt"];
-                    readonly additionalProperties: false;
-                }, {
-                    readonly type: "object";
-                    readonly title: "TestId 定位";
-                    readonly description: "通过 data-testid 属性定位";
-                    readonly properties: {
-                        readonly testId: {
-                            readonly type: "string";
-                            readonly description: "data-testid 值";
-                        };
-                    };
-                    readonly required: readonly ["testId"];
-                    readonly additionalProperties: false;
-                }, {
-                    readonly type: "object";
-                    readonly title: "CSS 选择器定位";
-                    readonly description: "通过 CSS 选择器定位";
-                    readonly properties: {
-                        readonly css: {
-                            readonly type: "string";
-                            readonly description: "CSS 选择器";
-                        };
-                    };
-                    readonly required: readonly ["css"];
-                    readonly additionalProperties: false;
-                }, {
-                    readonly type: "object";
-                    readonly title: "CSS + 文本组合定位";
-                    readonly description: "通过 CSS 选择器 + 文本内容组合定位（先 CSS 筛选，再按文本过滤）";
-                    readonly properties: {
-                        readonly css: {
-                            readonly type: "string";
-                            readonly description: "CSS 选择器";
-                        };
-                        readonly text: {
-                            readonly type: "string";
-                            readonly description: "文本内容";
-                        };
-                        readonly exact: {
-                            readonly type: "boolean";
-                            readonly description: "是否精确匹配（默认 false）";
-                        };
-                    };
-                    readonly required: readonly ["css", "text"];
-                    readonly additionalProperties: false;
-                }, {
-                    readonly type: "object";
-                    readonly title: "XPath 定位";
-                    readonly description: "通过 XPath 表达式定位";
-                    readonly properties: {
-                        readonly xpath: {
-                            readonly type: "string";
-                            readonly description: "XPath 表达式";
-                        };
-                    };
-                    readonly required: readonly ["xpath"];
-                    readonly additionalProperties: false;
-                }, {
-                    readonly type: "object";
-                    readonly title: "坐标定位";
-                    readonly description: "通过页面坐标定位";
-                    readonly properties: {
-                        readonly x: {
-                            readonly type: "number";
-                            readonly description: "X 坐标（像素）";
-                        };
-                        readonly y: {
-                            readonly type: "number";
-                            readonly description: "Y 坐标（像素）";
-                        };
-                    };
-                    readonly required: readonly ["x", "y"];
-                    readonly additionalProperties: false;
-                }];
-            };
-            attribute: {
-                type: string;
-                description: string;
-            };
-            fullPage: {
-                type: string;
-                description: string;
-            };
-            output: {
-                type: string;
-                description: string;
-            };
-            tabId: {
-                type: string;
-                description: string;
-            };
-            timeout: {
-                type: string;
-                description: string;
-            };
-            frame: {
-                oneOf: {
-                    type: string;
-                }[];
-                description: string;
-            };
-        };
-        required: string[];
-    };
-};
-/**
- * extract 工具处理器
- */
-export declare function handleExtract(params: unknown): Promise<{
-    content: Array<{
-        type: 'text' | 'image';
-        text?: string;
-        data?: string;
-        mimeType?: string;
-    }>;
-    isError?: boolean;
-}>;
+export declare function registerExtractTool(server: McpServer): void;
 //# sourceMappingURL=extract.d.ts.map

package/dist/tools/extract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/tools/extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH;;GAEG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0CjC,CAAA;AAkBD;;GAEG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC;IAC1D,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5F,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC,CAgOD"}
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/tools/extract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAA;AA6ZtE;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAK3D"}

package/dist/tools/extract.js

@@ -10,73 +10,32 @@
  */
 import { writeFile } from 'fs/promises';
 import { z } from 'zod';
-import { formatErrorResponse, getSession, getUnifiedSession } from '../core/index.js';
-import { targetJsonSchema, targetToFindParams, targetZodSchema } from './schema.js';
-/**
- * extract 工具定义
- */
-export const extractToolDefinition = {
-    name: 'extract',
-    description: '提取页面内容：文本、HTML、属性、截图、状态',
-    inputSchema: {
-        type: 'object',
-        properties: {
-            type: {
-                type: 'string',
-                enum: ['text', 'html', 'attribute', 'screenshot', 'state'],
-                description: '提取类型',
-            },
-            target: {
-                ...targetJsonSchema,
-                description: '目标元素（attribute 必填；text/html 可选，省略则提取整个页面；screenshot/state 不需要）',
-            },
-            attribute: {
-                type: 'string',
-                description: '属性名（attribute）',
-            },
-            fullPage: {
-                type: 'boolean',
-                description: '是否全页面截图（screenshot）',
-            },
-            output: {
-                type: 'string',
-                description: '输出文件路径（可选）。若指定，结果写入文件；否则返回内容',
-            },
-            tabId: {
-                type: 'string',
-                description: '目标 Tab ID（可选，仅 Extension 模式）。不指定则使用当前 attach 的 tab。可操作非当前 attach 的 tab。CDP 模式下忽略此参数',
-            },
-            timeout: {
-                type: 'number',
-                description: '等待目标元素超时',
-            },
-            frame: {
-                oneOf: [{ type: 'string' }, { type: 'number' }],
-                description: 'iframe 定位（可选，仅 Extension 模式）。CSS 选择器（如 "iframe#main"）或索引（如 0）。不指定则在主框架操作',
-            },
-        },
-        required: ['type'],
-    },
-};
+import { formatErrorResponse, formatResponse, getSession, getUnifiedSession } from '../core/index.js';
+import { targetToFindParams, targetZodSchema } from './schema.js';
 /**
  * extract 参数 schema
  */
 const extractSchema = z.object({
-    type: z.enum(['text', 'html', 'attribute', 'screenshot', 'state']),
-    target: targetZodSchema.optional(),
-    attribute: z.string().optional(),
-    fullPage: z.boolean().optional(),
-    output: z.string().optional(),
-    tabId: z.string().optional(),
-    timeout: z.number().optional(),
-    frame: z.union([z.string(), z.number()]).optional(),
+    type: z.enum(['text', 'html', 'attribute', 'screenshot', 'state'])
+        .describe('提取类型'),
+    target: targetZodSchema.optional().describe('目标元素（attribute 必填；text/html 可选，省略则提取整个页面；screenshot/state 不需要）'),
+    attribute: z.string().optional().describe('属性名（attribute）'),
+    fullPage: z.boolean().optional().describe('是否全页面截图（screenshot）'),
+    scale: z.number().optional().describe('截图缩放比例（screenshot fullPage）。默认 1，设为 0.5 可降低分辨率加速大页面截图'),
+    format: z.enum(['png', 'jpeg', 'webp']).optional().describe('截图格式（screenshot）。默认 png，jpeg/webp 体积更小，复杂页面推荐 jpeg 减少超时'),
+    quality: z.number().min(0).max(100).optional().describe('截图质量（screenshot，仅 jpeg/webp 有效）。0-100，推荐 80'),
+    output: z.string()
+        .optional()
+        .describe('输出文件路径（可选）。若指定，结果写入文件；否则返回内容'),
+    tabId: z.string().optional().describe('目标 Tab ID（可选，仅 Extension 模式）。不指定则使用当前 attach 的 tab。可操作非当前 attach 的 tab。CDP 模式下忽略此参数'),
+    timeout: z.number().optional().describe('等待目标元素超时'),
+    frame: z.union([z.string(), z.number()]).optional().describe('iframe 定位（可选，仅 Extension 模式）。CSS 选择器（如 "iframe#main"）或索引（如 0）。不指定则在主框架操作'),
 });
 /**
  * extract 工具处理器
  */
-export async function handleExtract(params) {
+async function handleExtract(args) {
     try {
-        const args = extractSchema.parse(params);
         const unifiedSession = getUnifiedSession();
         const useExtension = unifiedSession.isExtensionConnected();
         const session = getSession();
@@ -94,32 +53,18 @@ export async function handleExtract(params) {
                             : await extractText(session, args.target, args.timeout);
                         if (args.output) {
                             await writeFile(args.output, text, 'utf-8');
-                            return {
-                                content: [
-                                    {
-                                        type: 'text',
-                                        text: JSON.stringify({
-                                            success: true,
-                                            type: 'text',
-                                            output: args.output,
-                                            size: text.length,
-                                        }),
-                                    },
-                                ],
-                            };
+                            return formatResponse({
+                                success: true,
+                                type: 'text',
+                                output: args.output,
+                                size: text.length,
+                            });
                         }
-                        return {
-                            content: [
-                                {
-                                    type: 'text',
-                                    text: JSON.stringify({
-                                        success: true,
-                                        type: 'text',
-                                        content: text,
-                                    }),
-                                },
-                            ],
-                        };
+                        return formatResponse({
+                            success: true,
+                            type: 'text',
+                            content: text,
+                        });
                     }
                     case 'html': {
                         const html = useExtension
@@ -127,32 +72,18 @@ export async function handleExtract(params) {
                             : await extractHTML(session, args.target, args.timeout);
                         if (args.output) {
                             await writeFile(args.output, html, 'utf-8');
-                            return {
-                                content: [
-                                    {
-                                        type: 'text',
-                                        text: JSON.stringify({
-                                            success: true,
-                                            type: 'html',
-                                            output: args.output,
-                                            size: html.length,
-                                        }),
-                                    },
-                                ],
-                            };
+                            return formatResponse({
+                                success: true,
+                                type: 'html',
+                                output: args.output,
+                                size: html.length,
+                            });
                         }
-                        return {
-                            content: [
-                                {
-                                    type: 'text',
-                                    text: JSON.stringify({
-                                        success: true,
-                                        type: 'html',
-                                        content: html,
-                                    }),
-                                },
-                            ],
-                        };
+                        return formatResponse({
+                            success: true,
+                            type: 'html',
+                            content: html,
+                        });
                     }
                     case 'attribute': {
                         if (!args.target) {
@@ -194,37 +125,28 @@ export async function handleExtract(params) {
                         else {
                             value = await extractAttribute(session, args.target, args.attribute, args.timeout);
                         }
-                        return {
-                            content: [
-                                {
-                                    type: 'text',
-                                    text: JSON.stringify({
-                                        success: true,
-                                        type: 'attribute',
-                                        attribute: args.attribute,
-                                        value,
-                                    }),
-                                },
-                            ],
-                        };
+                        return formatResponse({
+                            success: true,
+                            type: 'attribute',
+                            attribute: args.attribute,
+                            value,
+                        });
                     }
                     case 'screenshot': {
-                        const base64 = await unifiedSession.screenshot({ fullPage: args.fullPage ?? false });
+                        const base64 = await unifiedSession.screenshot({
+                            fullPage: args.fullPage ?? false,
+                            scale: args.scale,
+                            format: args.format,
+                            quality: args.quality,
+                        });
                         if (args.output) {
                             // 写入文件
                             await writeFile(args.output, Buffer.from(base64, 'base64'));
-                            return {
-                                content: [
-                                    {
-                                        type: 'text',
-                                        text: JSON.stringify({
-                                            success: true,
-                                            type: 'screenshot',
-                                            output: args.output,
-                                        }),
-                                    },
-                                ],
-                            };
+                            return formatResponse({
+                                success: true,
+                                type: 'screenshot',
+                                output: args.output,
+                            });
                         }
                         // 返回 base64 图片
                         return {
@@ -232,7 +154,7 @@ export async function handleExtract(params) {
                                 {
                                     type: 'image',
                                     data: base64,
-                                    mimeType: 'image/png',
+                                    mimeType: `image/${args.format === 'jpeg' ? 'jpeg' : args.format ?? 'png'}`,
                                 },
                             ],
                         };
@@ -241,31 +163,17 @@ export async function handleExtract(params) {
                         const state = await unifiedSession.readPage();
                         if (args.output) {
                             await writeFile(args.output, JSON.stringify(state, null, 2), 'utf-8');
-                            return {
-                                content: [
-                                    {
-                                        type: 'text',
-                                        text: JSON.stringify({
-                                            success: true,
-                                            type: 'state',
-                                            output: args.output,
-                                        }),
-                                    },
-                                ],
-                            };
+                            return formatResponse({
+                                success: true,
+                                type: 'state',
+                                output: args.output,
+                            });
                         }
-                        return {
-                            content: [
-                                {
-                                    type: 'text',
-                                    text: JSON.stringify({
-                                        success: true,
-                                        type: 'state',
-                                        state,
-                                    }, null, 2),
-                                },
-                            ],
-                        };
+                        return formatResponse({
+                            success: true,
+                            type: 'state',
+                            state,
+                        });
                     }
                     default:
                         return {
@@ -309,10 +217,9 @@ async function extractText(session, target, timeout) {
 async function extractHTML(session, target, timeout) {
     if (target) {
         const locator = session.createLocator(target, timeout !== undefined ? { timeout } : undefined);
-        const html = await locator.evaluateOn(`function() {
+        return await locator.evaluateOn(`function() {
       return this.outerHTML;
     }`);
-        return html;
     }
     return session.evaluate('document.documentElement.outerHTML');
 }
@@ -331,11 +238,13 @@ async function extractAttribute(session, target, attribute, timeout) {
  * 支持所有 Target 形式（css/xpath/text/role/label 等）
  */
 async function extractTextExtension(unifiedSession, target) {
-    if (!target)
+    if (!target) {
         return unifiedSession.getText();
+    }
     const { selector, text, xpath } = targetToFindParams(target);
-    if (selector)
+    if (selector) {
         return unifiedSession.getText(selector);
+    }
     // xpath/text 定位：通过 evaluate 在页面上下文中查找
     if (xpath) {
         return unifiedSession.evaluate(`(function(xp) { var r = document.evaluate(xp, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null); return r.singleNodeValue ? r.singleNodeValue.textContent || '' : '' })`, undefined, undefined, [xpath]);
@@ -350,11 +259,13 @@ async function extractTextExtension(unifiedSession, target) {
  * 支持所有 Target 形式（css/xpath/text/role/label 等）
  */
 async function extractHtmlExtension(unifiedSession, target, outer = true) {
-    if (!target)
+    if (!target) {
         return unifiedSession.getHtml(undefined, outer);
+    }
     const { selector, text, xpath } = targetToFindParams(target);
-    if (selector)
+    if (selector) {
         return unifiedSession.getHtml(selector, outer);
+    }
     const prop = outer ? 'outerHTML' : 'innerHTML';
     if (xpath) {
         return unifiedSession.evaluate(`(function(xp, p) { var r = document.evaluate(xp, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null); return r.singleNodeValue ? r.singleNodeValue[p] || '' : '' })`, undefined, undefined, [xpath, prop]);
@@ -368,12 +279,16 @@ async function extractHtmlExtension(unifiedSession, target, outer = true) {
  * Extension 模式：提取属性
  */
 async function extractAttributeExtension(unifiedSession, target, attribute) {
-    const { selector, text, xpath } = targetToFindParams(target);
+    const { selector, text, xpath, nth: nthParam } = targetToFindParams(target);
     // xpath/text 定位需要先 find 得到 refId，再获取属性
     if (xpath || text) {
         const elements = await unifiedSession.find(selector, text, xpath);
         if (elements.length > 0) {
-            return unifiedSession.getAttribute(undefined, elements[0].refId, attribute);
+            const nth = nthParam ?? 0;
+            if (nth >= elements.length) {
+                throw new Error(`第 ${nth} 个匹配元素不存在（共 ${elements.length} 个）`);
+            }
+            return unifiedSession.getAttribute(undefined, elements[nth].refId, attribute);
         }
         return null;
     }
@@ -391,7 +306,8 @@ async function extractAttributeExtension(unifiedSession, target, attribute) {
 async function waitForTargetExtension(unifiedSession, target, timeout) {
     const startTime = Date.now();
     const retryDelay = 100;
-    const { selector, text, xpath } = targetToFindParams(target);
+    const { selector, text, xpath, nth: nthParam } = targetToFindParams(target);
+    const nth = nthParam ?? 0;
     let lastError = null;
     while (true) {
         const elapsed = Date.now() - startTime;
@@ -407,12 +323,15 @@ async function waitForTargetExtension(unifiedSession, target, timeout) {
         try {
             const remaining = timeout - elapsed;
             const elements = await unifiedSession.find(selector, text, xpath, remaining);
-            if (elements.length > 0)
+            if (elements.length > nth) {
                 return;
+            }
         }
         catch (err) {
             // 暂时性错误（RPC 超时、发送失败、连接断开）可重试，其他确定性错误立即抛出
-            if (err instanceof Error && /Request timeout|Failed to send|disconnect|未连接|stopped|replaced/i.test(err.message)) {
+            if (err instanceof
+                Error &&
+                /Request timeout|Failed to send|disconnect|未连接|stopped|replaced/i.test(err.message)) {
                 lastError = err;
                 await new Promise(r => setTimeout(r, retryDelay));
                 continue;
@@ -422,4 +341,13 @@ async function waitForTargetExtension(unifiedSession, target, timeout) {
         await new Promise(r => setTimeout(r, retryDelay));
     }
 }
+/**
+ * 注册 extract 工具
+ */
+export function registerExtractTool(server) {
+    server.registerTool('extract', {
+        description: '提取页面内容：文本、HTML、属性、截图、状态',
+        inputSchema: extractSchema,
+    }, (args) => handleExtract(args));
+}
 //# sourceMappingURL=extract.js.map