内容
# ao3-mcp
<!-- mcp-name: io.github.ArturLys/ao3-mcp -->
一个遵循模型上下文协议（MCP）的服务器，它连接AI代理（如Claude、Cursor或任何MCP客户端）到[Archive of Our Own（AO3）](https://archiveofourown.org/)。该服务器允许搜索AO3上的同人小说，支持完整的筛选条件，解决模糊的关键词以匹配规范的标签，并获取小说的实际内容，以便在推荐之前进行评估。
其诀窍在于：您的代理永远不会直接读取小说文本。它将阅读任务委托给一个廉价的次要模型（Gemini），该模型可以消化整个小说——甚至是15万字的小说——并返回结构化的报告。您的代理的上下文保持干净；推荐基于实际文本，而不是小说的简介。
```
代理 ──MCP──> server.py
├─ ao3.py AO3 爬虫（无公开API）—— 节流且礼貌
└─ reader.py Gemini 读取小说，返回报告：情节、风格、
文本样本、内容备注、排名
```
## 为什么这种方式优于基于简介的推荐
AO3的小说简介是由作者撰写的。本服务器的工作流程是：广泛搜索（40–60个结果），让阅读模型阅读短名单——每次调用最多20部小说——并仅推荐实际阅读过的小说，并附有逐字文本样本，以便从文本本身判断质量。
## 安装
需要 **Python 3.10+** 和一个免费的 **Gemini API密钥**：
> 前往 [aistudio.google.com/api-keys](https://aistudio.google.com/api-keys)，使用任何Google账户登录，然后点击 **"创建API密钥"**。免费层足够使用——无需设置计费。
```bash
pip install ao3-mcp
```
## 添加到您的代理
将 `command` 指向 `ao3-mcp` 并使用 `--api-key` 传递您的密钥：
```json
{
"mcpServers": {
"ao3": {
"command": "ao3-mcp",
"args": ["--api-key", "您的GEMINI密钥"]
}
}
}
```
更喜欢将密钥保留在参数列表之外？删除 `--api-key` 并在 `env` 块中传递它——服务器从环境中读取 `GEMINI_API_KEY` 作为备用：
```json
"env": { "GEMINI_API_KEY": "您的GEMINI密钥" }
```
<details>
<summary>Claude 代码</summary>
```bash
claude mcp add ao3 -- ao3-mcp --api-key 您的GEMINI密钥
```
</details>
<details>
<summary>Cursor</summary>
`Cursor 设置` → `MCP` → `新建 MCP 服务器`，粘贴上面的 JSON 配置。
</details>
<details>
<summary>Google Antigravity</summary>
将上面的 JSON 配置添加到 `.gemini/antigravity/mcp_config.json`。
</details>
<details>
<summary>VS Code / Copilot</summary>
```bash
code --add-mcp '{"name":"ao3","command":"ao3-mcp","args":["--api-key","您的GEMINI密钥"]}'
```
</details>
然后直接提问：
```
给我找一篇已完成的 <fandom> 里的敌对转恋爱长篇小说，阅读最佳候选作品，并告诉我哪一篇写得最好。
```
### 启动参数
| 参数 | 环境变量 | 默认值 | 功能 |
| ----------------- | --------------------- | -------------------- | --------------------------------------------- |
| `--api-key` | `GEMINI_API_KEY` | — | Gemini API密钥（必填）。 |
| `--model` | `GEMINI_MODEL` | `gemini-flash-latest`| 阅读模型使用的模型。 |
| `--backup-model` | `GEMINI_MODEL_BACKUP` | `gemini-flash-lite-latest` | 主模型被限流时的备用模型。 |
| `--min-interval` | `AO3_MIN_INTERVAL` | `0.6` | AO3请求的最小间隔（秒）。 |
## 工具
| 工具 | 功能 |
| -------------- | ---------------------------------------------------------------------------- |
| `search_works` | 搜索AO3：题材、配对、角色、标签、评级、字数、完成度、排序。每页20个结果，最多5页/次调用。`query`字段支持AO3的完整搜索运算符语法（`words>10000`、`kudos>500`、`sort:kudos`等）。 |
| `find_tags` | 实时自动补全——模糊关键词 → 规范的AO3标签、题材、配对或角色名称。 |
| `get_work` | 单部作品的完整元数据卡：标签、统计数据、摘要、系列信息。 |
| `read_works` | 使用次要模型读取1–20部小说，并返回每部小说的结构化报告——情节、角色、风格、逐字文本样本、内容备注——以及根据您的问题对它们进行比较排名。 |
小说下载会在本地缓存24小时，因此用新问题重新阅读小说不会产生额外的AO3请求。
## 需要注意的事项
- **AO3没有API** —— 本项目通过爬取其（干净的）HTML，一次一个请求，默认每0.6秒限流（可使用 `--min-interval` 调整），并遵守 `Retry-After`。AO3由志愿者维护；礼貌是故意的。
- **Cloudflare:** AO3阻止纯HTTP客户端。本项目使用 `curl_cffi` 带有移动Safari的TLS指纹，目前可以通过。如果请求开始失败，返回403并附有 `cf-mitigated: challenge`，请更改 `ao3.py` 中的 `IMPERSONATE`。
- **隐私：** 小说文本会发送到Google的Gemini API进行阅读；除此之外，您的设备上不会发送任何其他数据，无需遥测。
- **成人内容：** AO3托管各类评级的作品。本服务器会传递您搜索范围内的内容——请使用 `rating` 过滤器和AO3的警告标签来控制获取的内容。
## 自定义
这是一个小型、单一用途的服务器——几百行可读代码，无需框架魔术。您可以 fork 它并编辑任何内容：重写阅读器的提示、换用不同的模型、更改限流、添加工具。这就是使用它的预期方式。
从源码运行：
```bash
git clone https://github.com/ArturLys/ao3-mcp.git
cd ao3-mcp
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python smoke_test.py 您的GEMINI密钥 # 端到端检查：搜索 → 下载 → 消化
python server.py --api-key 您的GEMINI密钥 # 或将客户端的命令指向此处
```
## 致谢
- AO3访问方法基于 [ao3_api](https://github.com/wendytg/ao3_api) 由wendytg开发。
- 所有同人作品均归属于其作者，Archive of Our Own是[Organization for Transformative Works](https://www.transformativeworks.org/)的项目。
## 许可证
MIT
