smart-image-scraper-mcp 2.5.2 → 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 | 请求队列管理系统、自动资源释放 |
@@ -289,8 +304,11 @@ A: 检查网络连接，或尝试更换搜索源（bing → google）
 ### Q: 下载速度慢？
 A: 可以设置 `HTTP_PROXY` 环境变量使用代理
 
-### Q: 如何查看队列状态？
-A: 日志中会显示 `[Queue]` 相关信息
+### Q: Windsurf 中连续调用多次后卡住？
+A: 这是 Windsurf MCP 客户端的已知限制。建议：
+1. **使用批量查询**：`"skiing,ice skating,snowmobile"` 一次获取多个关键词
+2. **开新会话**：每3次调用后开一个新的聊天会话
+3. 等待 Windsurf 官方修复
 
 ## License
 

package/package.json

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

package/src/config/index.js

@@ -51,10 +51,10 @@ export const config = {
   USER_AGENT: process.env.USER_AGENT || 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
   REQUEST_TIMEOUT: parseEnvInt(process.env.REQUEST_TIMEOUT, 10000), // 10秒超时
   
-  // 并发控制
-  MAX_KEYWORD_CONCURRENCY: parseEnvInt(process.env.MAX_KEYWORD_CONCURRENCY, 2),
-  MAX_VALIDATE_CONCURRENCY: parseEnvInt(process.env.MAX_VALIDATE_CONCURRENCY, 10),
-  MAX_DOWNLOAD_CONCURRENCY: parseEnvInt(process.env.MAX_DOWNLOAD_CONCURRENCY, 5),
+  // 并发控制 - 降低默认值避免资源耗尽
+  MAX_KEYWORD_CONCURRENCY: parseEnvInt(process.env.MAX_KEYWORD_CONCURRENCY, 1),
+  MAX_VALIDATE_CONCURRENCY: parseEnvInt(process.env.MAX_VALIDATE_CONCURRENCY, 8),
+  MAX_DOWNLOAD_CONCURRENCY: parseEnvInt(process.env.MAX_DOWNLOAD_CONCURRENCY, 3),
   
   // 存储配置
   SAVE_ROOT: validatedSaveRoot,

package/src/index.backup.js

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+
+/**
+ * 全网智能图片抓取 MCP 服务器
+ * 基于 Model Context Protocol 的图片搜索、验证、下载工具
+ * 
+ * 设计原则（模仿主流 MCP 实现）：
+ * - 简洁：最小化基础设施代码
+ * - 无状态：每个请求独立处理
+ * - 可靠：简单的错误处理，避免资源泄漏
+ */
+
+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 { Orchestrator } from './services/orchestrator.js';
+import config from './config/index.js';
+
+// 从 package.json 读取版本号
+const require = createRequire(import.meta.url);
+const packageJson = require('../package.json');
+
+// 创建 MCP 服务器
+const server = new Server(
+  {
+    name: 'smart-image-scraper',
+    version: packageJson.version, // 动态读取版本号
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// 创建编排器实例
+const orchestrator = new Orchestrator();
+
+// 定义 Tool Schema
+const SMART_SCRAPER_TOOL = {
+  name: 'smart_scraper',
+  description: `全网智能图片抓取工具 - 从 Bing/Google 搜索、验证、下载高质量图片。
+
+【核心功能】
+1. 搜索图片链接 (mode=link) - 返回验证过的图片URL列表
+2. 下载图片 (mode=download) - 下载到本地，自动按质量排序优先高清
+3. 尺寸统一 (targetSize) - 下载后自动裁剪/缩放到指定尺寸
+4. 宽高比过滤 (aspect) - 横向/竖向/正方形
+
+【参数选择指南】
+- 用户要"找/搜索/查找图片" → mode="link"
+- 用户要"下载/保存/获取图片" → mode="download"
+- 用户要"高清/大图/壁纸" → size="large" 或 "wallpaper"
+- 用户要"电脑壁纸/横屏/横向" → aspect="wide"
+- 用户要"手机壁纸/竖屏/竖向" → aspect="tall"
+- 用户要"统一尺寸/固定大小" → targetSize="1920x1080" 或预设名
+- 用户要"多种类型图片" → query="猫,狗,鸟"（英文逗号分隔）
+
+【预设尺寸名称】
+- 电脑壁纸: desktop_1080p(1920x1080), desktop_2k(2560x1440), desktop_4k(3840x2160)
+- 手机壁纸: mobile_hd(1080x1920), mobile_2k(1440x2560)
+- 正方形: square_1080(1080x1080), square_512(512x512)
+- 社交媒体: instagram(1080x1080), twitter(1200x675), facebook(1200x630)
+
+【调用示例】
+1. 搜索5张猫的图片: {"query":"可爱的猫","mode":"link","count":5}
+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}`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description: '搜索关键词。批量搜索用英文逗号分隔，如 "猫,狗,鸟"。建议使用具体描述性词语如"可爱的橘猫"而非"猫"',
+      },
+      mode: {
+        type: 'string',
+        enum: ['link', 'download'],
+        description: "运行模式。link=仅返回验证过的图片URL列表（用户只需要链接时使用）；download=下载图片到本地文件系统（用户说下载/保存时使用）",
+      },
+      count: {
+        type: 'number',
+        description: '每个关键词获取的图片数量。范围1-100，推荐1-20。用户说"几张"用5-10，说"很多"用20-30',
+        default: 10,
+      },
+      source: {
+        type: 'string',
+        enum: ['bing', 'google'],
+        description: '搜索引擎。bing更稳定推荐优先使用，google结果可能更丰富但可能被限制',
+        default: 'bing',
+      },
+      size: {
+        type: 'string',
+        enum: ['all', 'small', 'medium', 'large', 'wallpaper'],
+        description: '图片尺寸。all=不限；small=小图/图标；medium=中图；large=大图/高清；wallpaper=壁纸级别(1080p+)',
+        default: 'all',
+      },
+      aspect: {
+        type: 'string',
+        enum: ['all', 'wide', 'tall', 'square'],
+        description: '图片宽高比。all=不限；wide=横向/宽屏(电脑壁纸)；tall=纵向/竖屏(手机壁纸)；square=正方形',
+        default: 'all',
+      },
+      targetSize: {
+        type: 'string',
+        description: '目标尺寸，下载后统一裁剪/缩放到此尺寸。格式: "宽x高"(如"1920x1080")或预设名(desktop_1080p/desktop_2k/desktop_4k/mobile_hd/mobile_2k/square_1080/instagram/twitter/facebook)',
+      },
+      fit: {
+        type: 'string',
+        enum: ['cover', 'contain', 'fill'],
+        description: '尺寸处理时的适应模式。cover=裁剪填充(默认,不留白)；contain=包含留白；fill=拉伸填充',
+        default: 'cover',
+      },
+      safeSearch: {
+        type: 'string',
+        enum: ['off', 'moderate', 'strict'],
+        description: '安全搜索。off=关闭；moderate=中等过滤(默认)；strict=严格过滤(儿童/家庭内容)',
+        default: 'moderate',
+      },
+    },
+    required: ['query', 'mode'],
+  },
+};
+
+// 注册工具列表（主流做法：简单返回）
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [SMART_SCRAPER_TOOL],
+}));
+
+// 注册工具调用（主流做法：每个请求创建新实例，避免状态污染）
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  if (name !== 'smart_scraper') {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `未知工具: ${name}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  try {
+    // 参数校验
+    if (!args.query || typeof args.query !== 'string') {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: '错误: 请提供有效的搜索关键词 (query)',
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    if (!args.mode || !['link', 'download'].includes(args.mode)) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: "错误: 请指定有效的运行模式 (mode): 'link' 或 'download'",
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    // 验证 count 参数
+    let count = parseInt(args.count, 10) || 10;
+    if (count < 1) count = 1;
+    if (count > 100) count = 100; // 限制最大数量
+
+    // 验证 query 长度
+    const query = args.query.trim();
+    if (query.length === 0) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: '错误: 搜索关键词不能为空',
+          },
+        ],
+        isError: true,
+      };
+    }
+    if (query.length > 500) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: '错误: 搜索关键词过长（最大500字符）',
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    // 验证 source 参数
+    const source = args.source || 'bing';
+    if (!['bing', 'google'].includes(source)) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: "错误: 无效的搜索源，请使用 'bing' 或 'google'",
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    // 检查是否正在关闭
+    if (gracefulShutdown.isShuttingDownNow()) {
+      return {
+        content: [{ type: 'text', text: '服务器正在关闭，无法处理新请求' }],
+        isError: true,
+      };
+    }
+
+    // 开始操作追踪
+    const operation = gracefulShutdown.startOperation(`scraper:${query.substring(0, 20)}`);
+    const startTime = Date.now();
+
+    try {
+      // 执行任务（requestQueue 已有超时机制，这里不再重复设置）
+      logger.info('Executing smart_scraper', { args });
+      
+      const result = await orchestrator.execute({
+        query: query,
+        mode: args.mode,
+        count: count,
+        source: source,
+        size: args.size || 'all',
+        aspect: args.aspect || 'all',
+        targetSize: args.targetSize || null,
+        fit: args.fit || 'cover',
+        safeSearch: args.safeSearch || 'moderate',
+      });
+
+      // 记录成功指标
+      metrics.recordSearch(source, true, Date.now() - startTime, result.results?.length || 0);
+
+      // 格式化输出
+      const formattedResult = orchestrator.formatResult(result);
+      
+      const totalTime = Date.now() - requestStartTime;
+      logger.info(`[MCP] 请求完成: ${totalTime}ms, requestId=${result.requestId}`);
+
+      // 每2个请求清理一次缓存和资源，避免内存累积
+      requestCount++;
+      if (requestCount >= 2) {
+        searchCache.clear();
+        validationCache.clear();
+        // 强制垃圾回收（如果可用）
+        if (global.gc) {
+          try { global.gc(); } catch (e) { /* ignore */ }
+        }
+        requestCount = 0;
+        logger.info('[MCP] 缓存已清理');
+      }
+
+      const response = {
+        content: [
+          {
+            type: 'text',
+            text: formattedResult,
+          },
+        ],
+      };
+      
+      return response;
+    } catch (innerError) {
+      // 记录失败指标
+      metrics.recordSearch(source, false, Date.now() - startTime);
+      metrics.recordError(innerError);
+      logger.error(`[MCP] 内部错误: ${innerError.message}`);
+      throw innerError;
+    } finally {
+      // 结束操作追踪
+      operation.end();
+    }
+  } catch (error) {
+    const totalTime = Date.now() - requestStartTime;
+    logger.error(`[MCP] 请求失败: ${totalTime}ms, error=${error.message}`);
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `## ❌ 执行错误\n\n**错误信息**: ${error.message}\n\n请检查网络连接或稍后重试。`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// 注册关闭回调
+gracefulShutdown.onShutdown(async () => {
+  logger.info('Closing MCP server connection...');
+  try {
+    await server.close();
+  } catch (error) {
+    logger.warn('Error closing server', { error: error.message });
+  }
+});
+
+// 启动服务器
+async function main() {
+  logger.info('Starting Smart Image Scraper MCP Server...');
+  logger.info('Configuration', {
+    saveRoot: config.SAVE_ROOT,
+    maxKeywordConcurrency: config.MAX_KEYWORD_CONCURRENCY,
+    maxDownloadConcurrency: config.MAX_DOWNLOAD_CONCURRENCY,
+  });
+  
+  // 执行初始健康检查
+  const healthResult = await healthChecker.runAllChecks();
+  logger.info('Initial health check', { status: healthResult.status });
+  
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  
+  logger.info('MCP Server is running and ready to accept requests');
+}
+
+main().catch((error) => {
+  logger.error('Server startup error', { error: error.message });
+  process.exit(1);
+});