内容
# LibGen 下载器 + MCP 服务器
一个强大的 Node.js/TypeScript 工具，用于从 LibGen 镜像站点搜索和下载电子书，具备模型上下文协议（MCP）服务器，实现与 LLM 的无缝集成。
## 🚀 功能特点
- **MCP 服务器集成**：使 LLMs（如 Claude）能够通过工具调用搜索和下载书籍
- **程序化 API**：完整的 Node.js API，用于自动化工作流程
- **批量下载**：通过 MD5 同时下载多本书籍
- **智能镜像发现**：LibGen+ 镜像的自动检测和故障转移
- **弹性操作**：内置重试和网络请求的错误处理
- **TypeScript 支持**：包含完整的类型定义
## 📦 安装
### 用于 MCP 服务器（LLM 集成）
```bash
npm install -g book-downloader-mcp
```
### 用于程序化使用
```bash
npm install book-downloader-mcp
```
**系统要求**：推荐 Node.js 16+
## 🤖 MCP 服务器设置
### Claude 桌面端集成
1. 全局安装：
```bash
npm install -g book-downloader-mcp
```
2. 添加到您的 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"libgen": {
"command": "libgen-mcp"
}
}
}
```
3. 重启 Claude 桌面端
助手现在可以访问 LibGen 搜索和下载功能！
### 其他 MCP 客户端
直接运行 MCP 服务器：
```bash
libgen-mcp
```
或从源代码运行：
```bash
npm run start:mcp
```
## 💻 程序化使用
### 基本示例
```javascript
const libgen = require('@rovodev/libgen-mcp-server');
async function searchAndDownload() {
// 初始化镜像连接
await libgen.ensureMirrorReady();
// 搜索书籍
const results = await libgen.searchBooks('The Art of War');
console.log(`Found ${results.length} results`);
if (results.length > 0) {
const book = results[0];
console.log(`Downloading: ${book.title} by ${book.authors}`);
// 获取直接下载 URL
const url = await libgen.getDirectDownloadUrlByMd5(book.md5);
console.log(`Download URL: ${url}`);
// 下载文件
const outcome = await libgen.downloadByMd5(book.md5);
if (outcome.status === 'ok') {
console.log(`Downloaded to: ${outcome.path}`);
}
}
}
searchAndDownload();
```
### TypeScript 示例
```typescript
import * as libgen from '@rovodev/libgen-mcp-server';
async function bulkDownload(searchQuery: string) {
await libgen.ensureMirrorReady();
const results = await libgen.searchBooks(searchQuery, 1, 10);
const md5List = results
.filter(book => book.md5)
.map(book => book.md5!)
.slice(0, 3); // 下载前 3 本书
const outcomes = await libgen.downloadByMd5List(md5List);
outcomes.forEach(outcome => {
if (outcome.status === 'ok') {
console.log(`✓ Downloaded: ${outcome.filename}`);
} else {
console.log(`✗ Failed: ${outcome.error}`);
}
});
}
```
### API 参考
- `ensureMirrorReady()`：初始化镜像配置
- `searchBooks(query, page?, pageSize?)`：搜索书籍
- `getDirectDownloadUrlByMd5(md5)`：获取书籍的下载 URL
- `downloadByMd5(md5)`：下载单个书籍
- `downloadByMd5List(md5Array)`：批量下载多个书籍
## 🛠 MCP 工具参考
通过 MCP 连接时，以下工具可用于 LLMs：
### 核心操作
| 工具 | 描述 | 输入 | 输出 |
|------|-------------|-------|--------|
| `libgen.ensureMirror` | 初始化并选择工作镜像 | `{}` | `{ mirror, config }` |
| `libgen.getActiveMirror` | 获取当前选定的镜像 | `{}` | `{ mirror }` |
| `libgen.setActiveMirror` | 手动设置活动镜像 | `{ mirrorSrc: string }` | `{ mirror }` |
### 搜索与发现
| 工具 | 描述 | 输入 | 输出 |
|------|-------------|-------|--------|
| `libgen.search` | 在 LibGen+ 上搜索书籍 | `{ query: string, page?: number, pageSize?: number }` | 带有元数据的书籍条目数组 |
**搜索结果字段**：`id`、`authors`、`title`、`publisher`、`year`、`pages`、`language`、`size`、`extension`、`mirror`、`md5`、`resolvedMirrorUrl`
### 下载操作
| 工具 | 描述 | 输入 | 输出 |
|------|-------------|-------|--------|
| `libgen.getDownloadUrl` | 获取直接下载 URL | `{ md5: string }` | `{ md5, url }` |
| `libgen.download` | 下载单个文件 | `{ md5: string }` | `{ md5, status, path?, filename?, total?, error? }` |
| `libgen.bulkDownload` | 下载多个文件 | `{ md5List: string[] }` | 下载结果数组 |
### 示例 MCP 工作流程
```javascript
// 1. 初始化
await mcp.call("libgen.ensureMirror", {});
// 2. 搜索
const results = await mcp.call("libgen.search", {
query: "machine learning",
page: 1
});
// 3. 下载第一个结果
if (results.length > 0) {
const outcome = await mcp.call("libgen.download", {
md5: results[0].md5
});
}
```
## ⚠️ 重要注意事项
- **镜像状态**：LibGen 镜像可能不稳定。该工具自动从配置中发现工作镜像
- **文件位置**：下载内容保存在当前工作目录中，文件名保持原样
- **网络弹性**：内置重试机制处理临时网络问题
- **LibGen+ 兼容性**：针对 LibGen+ 镜像结构和解析进行了优化
## 🔧 开发
### 构建项目
```bash
npm run build # 编译 TypeScript
npm run build:mcp # 构建并运行 MCP 服务器
npm run watch # 开发模式监听
```
### 本地运行
```bash
npm run start:mcp # 在开发环境中启动 MCP 服务器
npm run lint # 运行 ESLint
npm run format # 使用 Prettier 格式化代码
```
### 测试
```bash
npm test # 运行所有测试
npm run test:ci # 在 CI 模式下运行测试
```
**可选集成测试**：为 Groq API 测试设置环境变量：
- `GROQ_API_KEY`：您的 Groq API 密钥
- `RUN_GROQ_TESTS=1`：启用集成测试
在 `.env` 文件（gitignore）中或使用 `.env.test` 进行测试。参考 `.env.example` 获取示例。
## 🏗 架构
- **核心层**：HTML 解析（jsdom）、HTTP 请求、镜像发现、重试逻辑
- **MCP 服务器**：基于标准输入/输出的服务器，暴露 LibGen 操作为 MCP 工具
- **程序化 API**：Node.js 集成的直接函数导出
- **镜像管理**：动态配置获取和自动故障转移
## 📋 更新日志
### v3.0.2（当前）
- ✅ 完整的测试覆盖率和适当的模拟
- ✅ 更新的 MCP SDK 兼容性
- ✅ 增强的错误处理和重试机制
- ✅ 改进的文档和示例
### v3.0.0
- 🔄 LibGen+ 镜像作为主要来源
- ➖ 为适应 LibGen+ 兼容性，移除搜索筛选
- ➖ 暂时移除替代下载
### v2.x
- ➕ 替代下载、进度指示器
- ➕ CLI 搜索功能和快捷方式
- ➕ 缓存系统
### v1.x
- 🔄 完整的 UI 重写，使用 React/Ink/Zustand
- ➕ 批量下载功能
- ✅ 增强的错误处理和重试逻辑
## 📄 许可证
**WTFPL** - Do What The F*ck You Want To Public License
## ⚖️ 法律免责声明
此工具访问第三方 LibGen 镜像，可能：
- 在某些地区被屏蔽或不稳定
- 受当地法律法规约束
**请负责任地使用，并确保在您的司法管辖区内遵守适用的法律法规。**
---
## 🤝 贡献
1. Fork 仓库
2. 创建功能分支
3. 为新功能添加测试
4. 确保所有测试通过：`npm test`
5. 提交拉取请求
**仓库**：https://github.com/obsfx/libgen-downloader
