smart-image-scraper-mcp 2.6.0 → 2.7.0

package/README.md

@@ -7,7 +7,7 @@
 
 ## ✨ 核心特性
 
-### 🚀 高性能架构 (v2.4.0)
+### 🚀 高性能架构 (v2.7.0)
 - **多请求并行**：同时处理 5 个 MCP 请求
 - **并行翻页搜索**：同时获取多页结果，速度提升 5x
 - **HTTP 连接池**：Keep-Alive 复用 TCP 连接
@@ -23,7 +23,8 @@
 - **尺寸过滤**：small/medium/large/wallpaper
 - **宽高比过滤**：wide（横屏）/tall（竖屏）/square（正方形）
 - **尺寸统一**：下载后自动裁剪/缩放到指定尺寸
-- **质量优先**：自动按图片质量排序，高清优先
+- **质量控制**：三种质量模式（fast/balanced/high）
+- **文件大小过滤**：按最小文件大小筛选高质量图片
 
 ## 安装
 
@@ -100,6 +101,9 @@ npm install
 | `count` | number | ❌ | 每个关键词获取的图片数量，默认 10 |
 | `source` | string | ❌ | 搜索源，支持 `bing` 和 `google`，默认 `bing` |
 | `size` | string | ❌ | 图片尺寸：`all`, `small`, `medium`, `large`, `wallpaper`，默认 `all` |
+| `aspect` | string | ❌ | 宽高比：`all`, `wide`, `tall`, `square`，默认 `all` |
+| `quality` | string | ❌ | 质量模式：`fast`, `balanced`, `high`，默认 `balanced` |
+| `minFileSize` | string | ❌ | 最小文件大小：`any`, `50kb`, `100kb`, `200kb`, `500kb`, `1mb`，默认 `any` |
 | `safeSearch` | string | ❌ | 安全搜索：`off`, `moderate`, `strict`，默认 `moderate` |
 
 **使用示例**：
@@ -128,6 +132,16 @@ npm install
   "size": "wallpaper",
   "safeSearch": "strict"
 }
+
+// 高质量模式 - 获取验证过的高清图片
+{
+  "query": "风景",
+  "mode": "link",
+  "count": 10,
+  "size": "large",
+  "quality": "high",
+  "minFileSize": "100kb"
+}
 ```
 
 ## 架构设计
@@ -267,6 +281,7 @@ npm test
 
 | 版本 | 日期 | 主要更新 |
 |------|------|----------|
+| 2.7.0 | 2026-02 | 新增质量控制：quality 参数（fast/balanced/high）、minFileSize 文件大小过滤 |
 | 2.4.0 | 2026-02 | 修复所有分析问题：超时策略统一、缓存键一致、版本号动态读取 |
 | 2.3.0 | 2026-02 | 性能优化：HTTP 连接池、并行翻页搜索、内存泄漏修复 |
 | 2.2.0 | 2026-02 | 请求队列管理系统、自动资源释放 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smart-image-scraper-mcp",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "全网智能图片抓取 MCP 服务器 - 支持 Bing/Google 图片搜索、验证和下载",
   "main": "src/index.js",
   "type": "module",

package/src/index.js

@@ -52,7 +52,8 @@ const SMART_SCRAPER_TOOL = {
 【参数选择指南】
 - 用户要"找/搜索/查找图片" → mode="link"
 - 用户要"下载/保存/获取图片" → mode="download"
-- 用户要"高清/大图/壁纸" → size="large" 或 "wallpaper"
+- 用户要"高清/大图/壁纸" → size="large" 或 "wallpaper"，quality="high"
+- 用户要"高质量/精选/优质" → quality="high"
 - 用户要"电脑壁纸/横屏/横向" → aspect="wide"
 - 用户要"手机壁纸/竖屏/竖向" → aspect="tall"
 - 用户要"统一尺寸/固定大小" → targetSize="1920x1080" 或预设名
@@ -69,7 +70,8 @@ const SMART_SCRAPER_TOOL = {
 2. 下载10张高清风景图: {"query":"风景","mode":"download","count":10,"size":"large"}
 3. 下载电脑壁纸并统一为1080p: {"query":"风景","mode":"download","count":10,"aspect":"wide","targetSize":"desktop_1080p"}
 4. 下载手机壁纸: {"query":"动漫","mode":"download","count":10,"aspect":"tall","targetSize":"mobile_hd"}
-5. 批量下载多类图片: {"query":"猫,狗,兔子","mode":"download","count":5}`,
+5. 批量下载多类图片: {"query":"猫,狗,兔子","mode":"download","count":5}
+6. 获取高质量图片: {"query":"风景","mode":"link","count":5,"size":"large","quality":"high"}`,
   inputSchema: {
     type: 'object',
     properties: {
@@ -121,6 +123,18 @@ const SMART_SCRAPER_TOOL = {
         description: '安全搜索。off=关闭；moderate=中等过滤(默认)；strict=严格过滤(儿童/家庭内容)',
         default: 'moderate',
       },
+      quality: {
+        type: 'string',
+        enum: ['fast', 'balanced', 'high'],
+        description: '质量模式。fast=快速返回(不验证,速度最快)；balanced=平衡模式(验证有效性,默认)；high=高质量优先(验证+按质量排序,速度较慢但质量最好)',
+        default: 'balanced',
+      },
+      minFileSize: {
+        type: 'string',
+        enum: ['any', '50kb', '100kb', '200kb', '500kb', '1mb'],
+        description: '最小文件大小过滤。文件越大通常质量越高。any=不限制；建议高清图片用100kb以上',
+        default: 'any',
+      },
     },
     required: ['query', 'mode'],
   },
@@ -172,6 +186,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       targetSize: args.targetSize || null,
       fit: args.fit || 'cover',
       safeSearch: args.safeSearch || 'moderate',
+      quality: ['fast', 'balanced', 'high'].includes(args.quality) ? args.quality : 'balanced',
+      minFileSize: ['any', '50kb', '100kb', '200kb', '500kb', '1mb'].includes(args.minFileSize) ? args.minFileSize : 'any',
     };
 
     // 执行任务

package/src/services/orchestrator.js

@@ -50,6 +50,25 @@ export class Orchestrator {
       .filter(k => k.length > 0);
   }
 
+  /**
+   * 解析最小文件大小参数
+   * @param {string} minFileSize - 最小文件大小字符串
+   * @returns {number} - 字节数
+   */
+  _parseMinFileSize(minFileSize) {
+    if (!minFileSize || minFileSize === 'any') return 0;
+    
+    const sizeMap = {
+      '50kb': 50 * 1024,
+      '100kb': 100 * 1024,
+      '200kb': 200 * 1024,
+      '500kb': 500 * 1024,
+      '1mb': 1024 * 1024,
+    };
+    
+    return sizeMap[minFileSize.toLowerCase()] || 0;
+  }
+
   /**
    * 处理单个关键词 - Link 模式
    * @param {string} keyword - 关键词
@@ -60,8 +79,11 @@ export class Orchestrator {
    */
   async processKeywordLink(keyword, count, source, options = {}) {
     const startTime = Date.now();
-    const fastMode = options.fastMode !== false;
-    const prioritizeQuality = options.prioritizeQuality === true;
+    // 根据 quality 参数决定模式
+    const qualityMode = options.quality || 'balanced';
+    const fastMode = qualityMode === 'fast';
+    const prioritizeQuality = qualityMode === 'high';
+    const minFileSize = this._parseMinFileSize(options.minFileSize);
     
     try {
       const scraper = getScraper(source);
@@ -94,21 +116,36 @@ export class Orchestrator {
         };
       }
 
-      // 快速模式：直接返回搜索结果（不验证）
+      // 根据 quality 模式处理
       let resultUrls;
-      if (fastMode && !prioritizeQuality) {
-        // 快速模式：直接使用搜索结果
+      let qualityModeLabel;
+      
+      if (fastMode) {
+        // fast 模式：直接使用搜索结果，不验证
         resultUrls = rawUrls.slice(0, count);
+        qualityModeLabel = '快速模式（跳过验证）';
         logger.info(`[FAST] "${keyword}" - ${resultUrls.length} URLs`);
       } else {
-        // 完整验证模式：验证不通过的继续搜索更多
+        // balanced 或 high 模式：验证链接
         const { valid } = await this.linkValidator.validateMany(rawUrls, {
           fetchQuality: prioritizeQuality,
           sortByQuality: prioritizeQuality,
+          minFileSize: minFileSize,
         });
-        resultUrls = valid.slice(0, count).map(v => v.url);
         
-        // 如果验证通过的不够，记录警告
+        // 过滤最小文件大小
+        let filteredValid = valid;
+        if (minFileSize > 0) {
+          filteredValid = valid.filter(v => {
+            const size = v.quality?.contentLength || 0;
+            return size >= minFileSize || size === 0; // size=0 表示未知，保留
+          });
+          logger.info(`[FILTER] minFileSize=${options.minFileSize}: ${valid.length} -> ${filteredValid.length}`);
+        }
+        
+        resultUrls = filteredValid.slice(0, count).map(v => v.url);
+        qualityModeLabel = prioritizeQuality ? '高质量模式（验证+排序）' : '平衡模式（验证）';
+        
         if (resultUrls.length < count) {
           logger.warn(`[VALIDATE] "${keyword}" - only ${resultUrls.length}/${count} valid`);
         }
@@ -121,7 +158,8 @@ export class Orchestrator {
         totalSearched: rawUrls.length,
         urls: resultUrls,
         count: resultUrls.length,
-        fastMode,
+        qualityMode,
+        qualityModeLabel,
         duration: Date.now() - startTime,
       };
     } catch (error) {
@@ -145,7 +183,10 @@ export class Orchestrator {
    */
   async processKeywordDownload(keyword, count, source, options = {}) {
     const startTime = Date.now();
-    const prioritizeQuality = options.prioritizeQuality !== false;
+    // 根据 quality 参数决定模式（download 模式默认高质量）
+    const qualityMode = options.quality || 'balanced';
+    const prioritizeQuality = qualityMode !== 'fast';
+    const minFileSize = this._parseMinFileSize(options.minFileSize);
     
     try {
       const scraper = getScraper(source);
@@ -178,17 +219,29 @@ export class Orchestrator {
         };
       }
 
-      // 先验证链接并按质量排序
+      // 根据 quality 模式处理
       let urlsToDownload = rawUrls.slice(0, searchCount);
       if (prioritizeQuality) {
-        logger.info(`Validating and sorting ${urlsToDownload.length} URLs by quality...`);
+        const sortByQuality = qualityMode === 'high';
+        logger.info(`Validating ${urlsToDownload.length} URLs (quality=${qualityMode})...`);
         const { valid } = await this.linkValidator.validateMany(urlsToDownload, {
-          fetchQuality: true,
-          sortByQuality: true,
+          fetchQuality: sortByQuality,
+          sortByQuality: sortByQuality,
+          minFileSize: minFileSize,
         });
-        // 使用排序后的URL列表
-        urlsToDownload = valid.map(v => v.url);
-        logger.info(`Quality sorted: ${urlsToDownload.length} valid URLs`);
+        
+        // 过滤最小文件大小
+        let filteredValid = valid;
+        if (minFileSize > 0) {
+          filteredValid = valid.filter(v => {
+            const size = v.quality?.contentLength || 0;
+            return size >= minFileSize || size === 0;
+          });
+          logger.info(`[FILTER] minFileSize: ${valid.length} -> ${filteredValid.length}`);
+        }
+        
+        urlsToDownload = filteredValid.map(v => v.url);
+        logger.info(`Quality filtered: ${urlsToDownload.length} valid URLs`);
       }
 
       // 下载图片（已按质量排序，高质量优先）
@@ -360,11 +413,7 @@ export class Orchestrator {
 
       if (r.mode === 'link') {
         lines.push(`- 搜索到: ${r.totalSearched || 0} 张`);
-        if (r.fastMode) {
-          lines.push(`- 模式: 快速模式（跳过验证）`);
-        } else {
-          lines.push(`- 验证通过: ${r.totalValidated || r.count || 0} 张`);
-        }
+        lines.push(`- 质量模式: ${r.qualityModeLabel || '快速模式'}`);
         lines.push(`- 返回: ${r.count || 0} 张`);
         lines.push(`- 耗时: ${(r.duration / 1000).toFixed(2)}秒`);
         lines.push('');