npm package: @mcpcn/mcp-pansou-search
Description: MCP网盘资源搜索服务器 - 基于PanSou API提供网盘资源搜索功能
Latest version: 1.0.4

# PanSou 网盘资源搜索 MCP 服务器 (@mcpcn/mcp-pansou-search)

一个基于 Model Context Protocol (MCP) 的网盘资源搜索服务器，集成了 [PanSou](https://github.com/fish2018/pansou) API，为 AI 代理（如 Cline、Claude Desktop）提供强大的网盘资源搜索功能。

![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)
![Node.js](https://img.shields.io/badge/Node.js-43853D?style=flat&logo=node.js&logoColor=white)
![MCP](https://img.shields.io/badge/MCP-Compatible-blue)

## ✨ 功能特点

- 🔍 **多网盘支持** - 支持百度网盘、阿里云盘、夸克网盘、天翼云盘等主流网盘
- 📺 **多源搜索** - 集成Telegram频道和多个插件搜索源
- 🚀 **高性能并发** - 支持多频道多插件并发搜索
- 🎯 **智能分类** - 按网盘类型自动分类展示搜索结果
- 🔧 **灵活配置** - 可自定义搜索频道、插件、网盘类型等
- 📊 **健康监控** - 提供API服务状态和可用性检查
- 🌐 **多服务器支持** - 可配置不同的PanSou API服务器

## 🎯 支持的网盘类型

- 📁 百度网盘 (baidu)
- ☁️ 阿里云盘 (aliyun)
- 🌟 夸克网盘 (quark)
- 📱 天翼云盘 (tianyi)
- 🔥 UC网盘 (uc)
- 📲 移动云盘 (mobile)
- 💾 115网盘 (115)
- 🎯 PikPak (pikpak)
- ⚡ 迅雷云盘 (xunlei)
- 🎨 123网盘 (123)
- 🧲 磁力链接 (magnet)
- 🔗 电驴链接 (ed2k)

## 🚀 快速开始

### 安装依赖

```bash
cd typescript/网盘资源搜索
npm install
npm run build
```

### MCP 配置

#### Claude Desktop 配置 (macOS)

编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "pansou-search": {
      "command": "node",
      "args": [
        "/path/to/your/skills/typescript/网盘资源搜索/dist/index.js"
      ]
    }
  }
}
```

#### Cline/Cursor 配置

在 Cursor 设置中的 MCP 服务器配置中添加：

```json
{
  "mcpServers": {
    "pansou-search": {
      "command": "node",
      "args": [
        "path/to/your/skills/typescript/网盘资源搜索/dist/index.js"
      ],
      "autoApprove": ["search_pansou", "health_check_pansou"]
    }
  }
}
```

## 🔧 使用说明

### search_pansou 工具

**功能：** 搜索网盘资源，支持多种网盘类型和搜索源

**参数：**

- `kw` (必需): 搜索关键词
- `api_url` (可选): PanSou API服务地址，默认 `https://so.252035.xyz`
- `channels` (可选): 搜索的频道列表
- `conc` (可选): 并发搜索数量
- `refresh` (可选): 强制刷新，不使用缓存
- `res` (可选): 结果类型 (`all`/`results`/`merge`)，默认 `merge`
- `src` (可选): 数据来源 (`all`/`tg`/`plugin`)，默认 `all`
- `plugins` (可选): 指定搜索的插件列表
- `cloud_types` (可选): 指定返回的网盘类型列表
- `ext` (可选): 扩展参数对象

### health_check_pansou 工具

**功能：** 检查PanSou API服务状态，获取可用频道和插件信息

**参数：**

- `api_url` (可选): PanSou API服务地址，默认 `https://so.252035.xyz`

## 📖 使用示例

### 1. 基础搜索

```json
{
  "tool_name": "search_pansou",
  "arguments": {
    "kw": "速度与激情"
  }
}
```

### 2. 指定网盘类型搜索

```json
{
  "tool_name": "search_pansou",
  "arguments": {
    "kw": "Python教程",
    "cloud_types": ["baidu", "aliyun", "quark"],
    "res": "merge"
  }
}
```

### 3. 高级搜索配置

```json
{
  "tool_name": "search_pansou",
  "arguments": {
    "kw": "机器学习",
    "channels": ["tgsearchers3"],
    "plugins": ["jikepan", "pansearch"],
    "src": "all",
    "conc": 5,
    "refresh": true,
    "ext": {
      "title_en": "Machine Learning",
      "is_all": true
    }
  }
}
```

### 4. 健康检查

```json
{
  "tool_name": "health_check_pansou",
  "arguments": {
    "api_url": "https://so.252035.xyz"
  }
}
```

### 5. 自定义API服务器

```json
{
  "tool_name": "search_pansou",
  "arguments": {
    "kw": "编程教程",
    "api_url": "http://your-custom-pansou-server:8888"
  }
}
```

## 📊 搜索结果格式

搜索成功后，系统会返回格式化的结果，包括：

### 按类型分类的结果
- 📁 **网盘类型统计** - 每种网盘的资源数量
- 🔗 **资源链接** - 直接可用的网盘链接
- 🔑 **提取码** - 网盘资源的提取密码
- ⏰ **更新时间** - 资源发布或更新时间
- 📍 **来源标识** - 资源来源（TG频道或插件）

### 详细搜索结果
- 📝 **资源描述** - 详细的资源介绍
- 📺 **来源频道** - Telegram频道信息
- 🏷️ **标签分类** - 资源相关标签
- 🖼️ **预览图片** - 资源相关图片（如有）

## 💻 对话示例

```
用户：帮我搜索一下"人工智能入门教程"的网盘资源

助手：我来为您搜索人工智能入门教程的网盘资源...

🔍 网盘资源搜索结果 - "人工智能入门教程"

📊 总计: 23 个结果

📁 按网盘类型分类的结果:

### 百度网盘 (12 个)

1. **人工智能入门到精通全套视频教程**
   🔗 链接: https://pan.baidu.com/s/1abcdef
   🔑 提取码: ai2024
   ⏰ 时间: 2024-01-15T10:30:00Z
   📍 来源: tg:AI资源分享

2. **Python人工智能入门实战教程**
   🔗 链接: https://pan.baidu.com/s/1ghijk
   🔑 提取码: py123
   ⏰ 时间: 2024-01-10T14:20:00Z
   📍 来源: plugin:jikepan

### 夸克网盘 (8 个)

1. **深度学习与人工智能基础**
   🔗 链接: https://pan.quark.cn/s/abc123
   ⏰ 时间: 2024-01-12T09:15:00Z
   📍 来源: tg:学习资源库

...

用户：只要百度网盘的资源

助手：我来为您搜索仅限百度网盘的人工智能教程资源...

[执行搜索，指定cloud_types为["baidu"]]
```

## 🔒 安全特性

- 🛡️ **API限流保护** - 遵循PanSou API的访问限制
- 🔐 **请求验证** - 验证所有输入参数的合法性
- 🌐 **网络安全** - 仅支持HTTPS协议的API请求
- 📝 **错误处理** - 完善的错误捕获和友好的错误信息

## ⚠️ 注意事项

1. **API服务** - 需要PanSou API服务正常运行
2. **网络连接** - 需要稳定的网络连接访问API服务
3. **访问限制** - 请遵守PanSou API的访问频率限制
4. **资源时效** - 网盘链接可能存在时效性，建议及时下载
5. **合规使用** - 请遵守相关法律法规，仅用于合法用途

## 🔧 故障排除

### 常见问题

1. **API连接失败**
   ```
   错误：PanSou API请求失败 (500): Internal Server Error
   ```
   **解决方案**: 
   - 检查API服务器状态
   - 尝试使用health_check_pansou工具检查服务可用性
   - 更换API服务器地址

2. **搜索无结果**
   ```
   总计: 0 个结果
   ```
   **解决方案**: 
   - 调整搜索关键词
   - 尝试不同的搜索源(src参数)
   - 检查网盘类型限制

3. **网络超时**
   ```
   错误：fetch failed
   ```
   **解决方案**: 
   - 检查网络连接
   - 增加并发限制(降低conc参数)
   - 重试搜索请求

4. **参数错误**
   ```
   错误：关键词不能为空
   ```
   **解决方案**: 
   - 检查必需参数是否提供
   - 验证参数格式是否正确

## 🎯 可用插件

当前PanSou支持的搜索插件包括：
- pansearch - 综合网盘搜索
- jikepan - 即刻搜盘
- qupansou - 去搜盘
- hunhepan - 混合搜盘
- pan666 - 666盘搜
- panyq - 盘友圈
- susu - 素搜
- 等等...

使用health_check_pansou工具可以获取完整的可用插件列表。

## 🌐 官方资源

- 📁 **PanSou GitHub**: https://github.com/fish2018/pansou
- 🌍 **官方搜索站**: https://so.252035.xyz/
- 📚 **API文档**: 详见PanSou项目文档

## 📄 许可证

本项目采用 MIT 许可证。

---

基于 [fish2018/pansou](https://github.com/fish2018/pansou) API 开发的 MCP 服务器。