# 百度图片搜索 MCP Server

基于百度图片搜索 API 的 MCP (Model Context Protocol) 服务器。支持图片搜索、下载和格式转换一体化。

## 功能特性

- 🔍 **图片搜索**：搜索百度图片，返回图片标题、URL、尺寸、格式等信息
- 📥 **一键下载**：搜索同时可直接下载图片到本地
- 🔄 **格式转换**：支持 JPEG、PNG、WebP 三种格式互转（基于 sharp）
- 🖼️ **双源选择**：可选择缩略图（thumburl，百度 CDN 稳定快速）或原图（objurl，可能有防盗链）
- 📄 **分页支持**：支持自定义每页数量和页码

## 安装

```bash
# 克隆仓库
git clone <repo-url>
cd mcp_image_bd_tools

# 安装依赖
npm install

# 构建
npm run build
```

## 配置 MCP

在 MCP 客户端配置中添加：

```json
{
  "mcpServers": {
    "image-baidu": {
      "command": "node",
      "args": ["path/to/mcp_image_bd_tools/dist/index.js"]
    }
  }
}
```

## 使用

### 工具：`search_images`

#### 参数说明

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `keyword` | string | ✅ | - | 搜索关键字 |
| `page` | number | ❌ | 1 | 页码，从 1 开始 |
| `perPage` | number | ❌ | 30 | 每页数量，最大 60 |
| `downloadPath` | string | ❌ | - | 下载目录路径。设置后自动下载图片 |
| `format` | string | ❌ | - | 输出格式：`jpeg` / `png` / `webp`（仅下载模式有效） |
| `urlType` | string | ❌ | `thumb` | 图片源：`thumb`（缩略图）/ `original`（原图） |

#### 使用示例

**仅搜索：**

```json
{
  "keyword": "维多利亚港",
  "page": 1,
  "perPage": 10
}
```

**搜索并下载缩略图：**

```json
{
  "keyword": "故宫",
  "downloadPath": "./downloads",
  "perPage": 5
}
```

**搜索并下载原图 + 转换为 JPEG：**

```json
{
  "keyword": "黄山",
  "downloadPath": "./downloads",
  "format": "jpeg",
  "urlType": "original",
  "perPage": 3
}
```

#### 返回结果结构

```json
{
  "keyword": "维多利亚港",
  "totalNum": 44880,
  "hasMore": true,
  "page": 1,
  "images": [
    {
      "index": 1,
      "thumbUrl": "https://img0.baidu.com/it/u=...",
      "originalUrl": "https://...",
      "sourceUrl": "http://...",
      "title": "图片标题",
      "width": 1920,
      "height": 1080,
      "format": "jpg",
      "isGif": false,
      "isCopyright": false,
      "detailUrl": "https://image.baidu.com/search/detail?...",
      "downloaded": true,
      "localPath": "downloads/1_图片标题_a1b2c3d4.jpg",
      "convertedFrom": "webp→jpeg"
    }
  ],
  "error": "有 1 张图片下载失败（如：...）"
}
```

## 技术架构

```
src/
├── index.ts          # MCP Server 入口，注册 search_images 工具
├── baidu-image.ts    # 百度图片搜索 API 封装（acjson 接口）
├── downloader.ts     # 图片下载 + sharp 格式转换模块
├── types.ts          # TypeScript 类型定义
└── utils.ts          # 工具函数（URL 构建、格式检测、随机 UA 等）
```

### 依赖

- **@modelcontextprotocol/sdk**: MCP 协议 SDK
- **axios**: HTTP 客户端
- **sharp**: 高性能图片格式转换（JPEG/PNG/WebP）

## 技术实现细节

### 搜索 API

使用百度图片搜索的 `acjson` 接口：

```
GET https://image.baidu.com/search/acjson
  ?tn=resultjson_com
  &word={关键字}
  &pn={偏移量}
  &rn={每页数量}
  &gsm={pn的十六进制}
  &newReq=1
```

- **已验证：无需 Cookie 即可调用**，直接请求即可返回完整结果
- 分页通过 `pn`（偏移量，步长为 `rn`）和 `gsm`（`pn` 的十六进制值）控制
- 响应中包含 `totalNum`（总结果数）和 `hasMore`（是否有更多）

### 图片格式检测

下载图片时自动检测格式，优先级：

1. 响应头 `Content-Type`
2. 文件魔数（Magic Bytes）

如果设置了 `format` 参数且与实际格式不一致，自动使用 sharp 转换。

### 反爬策略

- 随机 User-Agent（从多个真实浏览器 UA 中随机选择）
- 正确的 Referer 头
- 请求间添加 300-700ms 随机延迟
- 并发下载数限制为 3

## License

MIT