内容
# 安娜档案MCP
一款用于通过安娜档案（Anna's Archive）搜索书籍并安全下载到本地的Rust MCP服务器，支持RapidAPI。
## 使用方法
本节是关于如何运行安娜档案MCP并从MCP客户端使用它的实用手册。
### 1. 构建服务器
克隆仓库并编译二进制文件：
```sh
git clone <你的仓库网址>
cd AnnasArchiveMCP
cargo build --release
```
编译后的二进制文件将位于：
```sh
target/release/annas-archive-mcp
```
### 2. 获取RapidAPI密钥
安娜档案MCP需要一个可以访问安娜档案API的RapidAPI密钥。
在启动服务器之前，请在环境变量中设置：
```sh
export RAPIDAPI_KEY=你的API密钥
```
您也可以将其放在本地的`.env`文件中，如果这更适合您的设置。
### 3. 配置可选默认值
您可以仅使用`RAPIDAPI_KEY`运行，但这些可选变量非常有用：
- `RAPIDAPI_HOST` — 默认值为 `annas-archive-api.p.rapidapi.com`
- `ANNAS_ARCHIVE_MCP_DOWNLOAD_DIR` — 下载文件的默认文件夹
- `ANNAS_ARCHIVE_MCP_OPEN_AFTER_DOWNLOAD` — `true` 或 `false`
- `ANNAS_ARCHIVE_MCP_CREATE_SUBDIRS` — `true` 或 `false`
- `ANNAS_ARCHIVE_MCP_OVERWRITE_DEFAULT` — `true` 或 `false`
- `ANNAS_ARCHIVE_MCP_DEFAULT_LIMIT` — 默认搜索结果数量
- `ANNAS_ARCHIVE_MCP_MAX_LIMIT` — 允许的最大搜索结果数量
- `RUST_LOG` — 日志级别，例如 `info` 或 `debug`
示例：
```env
RAPIDAPI_KEY=你的API密钥
ANNAS_ARCHIVE_MCP_DOWNLOAD_DIR=~/Downloads
ANNAS_ARCHIVE_MCP_OPEN_AFTER_DOWNLOAD=false
ANNAS_ARCHIVE_MCP_CREATE_SUBDIRS=true
ANNAS_ARCHIVE_MCP_OVERWRITE_DEFAULT=false
RUST_LOG=info
```
### 4. 运行服务器
在开发过程中，可以使用Cargo运行：
```sh
cargo run
```
或者直接运行编译后的二进制文件：
```sh
./target/release/annas-archive-mcp
```
服务器使用标准输入/输出，因此通常由MCP客户端启动，而不是作为独立的交互式命令行界面使用。
### 5. 添加到MCP客户端
将MCP客户端指向编译后的二进制文件，并提供所需的环境变量。
MCP客户端配置示例：
```json
{
"mcpServers": {
"annas-archive": {
"command": "/绝对路径/到/AnnasArchiveMCP/target/release/annas-archive-mcp",
"env": {
"RAPIDAPI_KEY": "你的API密钥",
"RUST_LOG": "info"
}
}
}
}
```
请将路径替换为机器上的实际绝对路径。
### 6. 搜索书籍
首先使用 `search_books` 工具。这是推荐的工作流程。
典型的搜索参数：
- `query` — 搜索文本，例如标题、作者或两者
- `formats` — 可选的优先格式，例如 `pdf` 或 `epub`
- `languages` — 可选的语言过滤器
- `yearFrom` / `yearTo` — 可选的年份范围
- `limit` — 返回的最大结果数量
- `sort` — `relevance`、`year` 或 `size`
典型的搜索请求在概念上类似于：
- 查询：`clean code`
- 格式：`["pdf", "epub"]`
- 限制：`5`
响应包括具有稳定 `result_id` 值的排名结果。为您要下载的结果保存 `result_id`。
### 7. 下载选定的书籍
搜索后，使用 `download_book` 并携带以下参数：
- `resultId` — 推荐，因为它直接来自 `search_books`
- `providerItemId` — 提供商本地标识符
可选的下载参数包括：
- `downloadDir`
- `filenameTemplate`
- `overwrite`
- `openAfterDownload`
- `createSubdirs`
典型工作流程：
1. 使用 `search_books` 进行搜索
2. 查看返回的结果
3. 复制期望的 `result_id`
4. 使用该 `resultId` 调用 `download_book`
响应包括最终保存的路径、文件名、写入的字节数以及文件是否自动打开。
### 8. 使用兼容性工作流程以实现单次调用行为
安娜档案MCP还提供 `search_and_download_book`。
此工作流程：
- 首先搜索
- 当需要手动选择时返回结果
- 或在选择设置允许时自动下载排名最高的匹配结果
有用的 `selectionMode` 值：
- `manual` — 始终返回供您检查的选择
- `auto_if_confident` — 仅当排名最高的匹配结果足够强时自动下载
- `force_top` — 始终选择排名最高的結果
此模式很方便，但通常单独的 `search_books` → `download_book` 流程更容易控制。
### 9. 推荐的日常使用
为了获得最安全和最可预测的体验，请使用以下常规：
1. 通过MCP客户端启动MCP服务器
2. 使用明确的查询调用 `search_books`
3. 检查标题、作者、年份、语言、格式和相关性
4. 选择最佳 `result_id`
5. 调用 `download_book`
6. 确认返回的 `destination_path`
### 10. 示例现实世界使用模式
如果您想要一本电子书的副本：
1. 搜索标题和作者
2. 传递 `formats: ["epub"]`
3. 将结果限制为少量，例如 `5`
4. 检查最佳匹配
5. 下载具有最准确元数据的结果
如果结果太少，请删除格式或语言过滤器，然后重试。
### 11. 响应中预期内容
`search_books` 返回结构化信息，例如：
- 摘要
- 规范化查询
- 结果数量
- 排名结果
- 相关时的警告
`download_book` 返回结构化信息，例如：
- 选定的结果标识符
- 标题和作者
- 文件格式和MIME类型
- 目标路径
- 最终文件名
- 写入的字节数
- 警告
### 12. 故障排除快速指南
如果服务器无法启动：
- 确认 `RAPIDAPI_KEY` 已设置
- 确认您的密钥具有安娜档案API访问权限
- 确认MCP客户端指向正确的二进制文件路径
如果搜索返回的结果没有用：
- 放宽查询
- 删除一些过滤器
- 验证上游API是否可用
如果下载失败：
- 检查目标目录权限
- 检查可用磁盘空间
- 验证选定的结果是否可下载
- 如果上游服务不可用或限速，请稍后重试
### 13. 安全提示
- 不要在源代码中硬编码API密钥
- 优先使用环境变量或MCP客户端秘密存储
- 不要提交包含真实机密的`.env`文件
## 功能
- 用Rust实现MCP标准输入/输出服务器
- 具有稳定的`result_id`值的规范化搜索结果
- 用于搜索和下载的独立工具
- 兼容性 `search_and_download_book` 工作流程
- 更安全的路径处理和文件名生成
- 具有手动和自动选择模式的排名结果选择
- 可选的下载后自动打开行为
- 为MCP客户端提供结构化的JSON响应
## 要求
- 推荐Rust 1.78+
- Cargo
- 具有安娜档案API访问权限的RapidAPI密钥
## 安装
克隆仓库并构建：
```sh
git clone <你的仓库网址>
cd AnnasArchiveMCP
cargo build --release
```
服务器二进制文件将位于：
```sh
target/release/annas-archive-mcp
```
## 配置
安娜档案MCP从环境变量和可选的本地`.env`文件读取配置。
### 必需
- `RAPIDAPI_KEY` — 您的RapidAPI API密钥
### 可选
- `RAPIDAPI_HOST` — 默认值为 `annas-archive-api.p.rapidapi.com`
- `ANNAS_ARCHIVE_MCP_DEFAULT_PROVIDER` — 默认值为 `annas_archive`
- `ANNAS_ARCHIVE_MCP_DOWNLOAD_DIR` — 默认下载目录
- `ANNAS_ARCHIVE_MCP_OPEN_AFTER_DOWNLOAD` — `true` 或 `false`
- `ANNAS_ARCHIVE_MCP_CREATE_SUBDIRS` — `true` 或 `false`
- `ANNAS_ARCHIVE_MCP_OVERWRITE_DEFAULT` — `true` 或 `false`
- `ANNAS_ARCHIVE_MCP_FILENAME_TEMPLATE` — 文件名模板字符串
- `ANNAS_ARCHIVE_MCP_MAX_FILENAME_LENGTH` — 最大生成文件名长度
- `ANNAS_ARCHIVE_MCP_DEFAULT_LIMIT` — 默认搜索结果限制
- `ANNAS_ARCHIVE_MCP_MAX_LIMIT` — 允许的最大搜索结果限制
- `ANNAS_ARCHIVE_MCP_ENABLE_DEBUG_FIELDS` — 默认包含提供商调试字段
- `ANNAS_ARCHIVE_MCP_TIMEOUT_SECS` — HTTP超时
- `ANNAS_ARCHIVE_MCP_MAX_RETRIES` — 提供商重试次数
- `ANNAS_ARCHIVE_MCP_USER_AGENT` — 自定义HTTP用户代理
- `RUST_LOG` — 日志级别，例如 `info` 或 `debug`
### 示例 `.env`
```env
RAPIDAPI_KEY=你的API密钥
RAPIDAPI_HOST=annas-archive-api.p.rapidapi.com
ANNAS_ARCHIVE_MCP_DOWNLOAD_DIR=~/Downloads
ANNAS_ARCHIVE_MCP_OPEN_AFTER_DOWNLOAD=false
ANNAS_ARCHIVE_MCP_CREATE_SUBDIRS=true
ANNAS_ARCHIVE_MCP_OVERWRITE_DEFAULT=false
ANNAS_ARCHIVE_MCP_DEFAULT_LIMIT=10
ANNAS_ARCHIVE_MCP_MAX_LIMIT=50
RUST_LOG=info
```
## 运行服务器
直接使用Cargo运行：
```sh
cargo run
```
或运行发布二进制文件：
```sh
./target/release/annas-archive-mcp
```
服务器通过标准输入/输出进行通信，旨在由MCP客户端启动。
## MCP客户端配置
基于命令的MCP配置示例：
```json
{
"mcpServers": {
"annas-archive": {
"command": "/绝对路径/到/AnnasArchiveMCP/target/release/annas-archive-mcp",
"env": {
"RAPIDAPI_KEY": "你的API密钥",
"RUST_LOG": "info"
}
}
}
}
```
请根据您的机器和MCP客户端调整路径。
## 可用工具
### `search_books`
搜索书籍并返回排名规范的结果。
#### 参数
- `query` （必填）：自由文本搜索查询
- `formats`：首选格式数组，如 `pdf`、`epub`、`mobi`
- `categories`：数组，如 `fiction`、`nonfiction`
- `languages`：语言代码或标签数组
- `yearFrom`：年份下限
- `yearTo`：年份上限
- `limit`：返回的最大结果数
- `provider`：提供商提示，目前为 `annas_archive`
- `sort`：`relevance`、`year` 或 `size`
- `debug`：包含排名/调试元数据
#### 返回值
包括以下结构化内容：
- `summary`
- `query`
- `count`
- `results`
- `warnings`
每个结果都包含以下字段：
- `result_id`
- `provider`
- `provider_item_id`
- `title`
- `subtitle`
- `authors`
- `publisher`
- `year`
- `language`
- `format`
- `file_size_bytes`
- `cover_url`
- `checksum_md5`
- `checksum_sha1`
- `downloadable`
- `relevance_score`
### `download_book`
使用 `resultId` 或 `providerItemId` 下载特定结果。
#### 参数
- `resultId`：`search_books` 返回的稳定结果ID
- `providerItemId`：提供商本地标识符
- `downloadDir`：覆盖目标目录
- `filenameTemplate`：覆盖文件名模板
- `overwrite`：覆盖现有文件
- `openAfterDownload`：下载后打开文件
- `createSubdirs`：创建目标目录（如果需要）
您必须提供 `resultId` 或 `providerItemId`。
#### 返回值
包括以下结构化内容：
- `summary`
- `result_id`
- `provider`
- `provider_item_id`
- `title`
- `authors`
- `format`
- `mime_type`
- `destination_path`
- `final_file_name`
- `bytes_written`
- `opened`
- `warnings`
### `search_and_download_book`
兼容性工作流程，首先搜索，然后：
- 如果需要手动选择，则返回匹配结果
- 或自动选择结果并下载
#### 参数
包括所有主要搜索和下载字段以及：
- `selectionMode`：以下之一
- `manual`
- `auto_if_confident`
- `force_top`
## 典型工作流程
### 推荐流程
1. 调用 `search_books`
2. 检查结果
3. 选择 `result_id`
4. 调用 `download_book`
### 兼容性流程
1. 调用 `search_and_download_book`
2. 如果 `selection_required` 为 `true`，则使用选择的 `resultId` 调用 `download_book`
3. 否则，使用返回的下载结果
## 行为说明
- 自动打开文件是可选的
- 下载使用更安全的 filename/path 处理
- 结果排名尝试优先选择更好的标题/作者/格式匹配
- 目前支持的提供商是通过RapidAPI的安娜档案
- 如果缺少API密钥，启动将失败，出现配置错误
## 开发
构建：
```sh
cargo build
```
运行测试：
```sh
cargo test
```
使用调试日志运行：
```sh
RUST_LOG=debug cargo run
```
格式化和检查：
```sh
cargo fmt
cargo clippy --all-targets --all-features
```
## 故障排除
### 服务器无法启动
检查：
- `RAPIDAPI_KEY` 是否已设置
- 您的密钥是否具有安娜档案 API 访问权限
- 您的 MCP 客户端配置中的二进制文件路径是否正确
### 没有返回结果
尝试：
- 更广泛的查询
- 删除限制性过滤器
- 验证上游 API 是否可达
### 下载失败
检查：
- 目标目录权限
- 可用磁盘空间
- 提供商结果是否实际上可下载
- 上游 API 是否限速或不可用
## 安全说明
- 不要在源文件中硬编码 API 密钥
- 优先使用环境变量或 MCP 客户端管理的机密
- 检查您的 MCP 客户端配置，以确保机密不会提交到版本控制中
## 项目状态
该项目是用 Rust 重写的，专注于更干净的 MCP 架构、更安全的下载和更好的可维护性，而不是旧的实现。
