ao3-mcp 是一个 MCP（Model Context Protocol）服务器，用于把 AI 智能体——Claude、Cursor 或任何 MCP 客户端——连接到 Archive of Our Own（AO3）。
用途
- 检索 AO3 同人小说，支持完整筛选条件。
- 将模糊的措辞解析为 AO3 的规范标签。
- 让 AI 在给出推荐之前先真正阅读作品，使推荐基于真实正文。
主要能力与工作方式
- 你的智能体本身从不阅读小说文本，而是把阅读任务委派给一个低成本的次级模型（Gemini）。该模型会消化整篇作品——即使是 15 万词的长篇——并返回结构化报告。这样你的智能体上下文保持干净，推荐基于真实文本而非简介宣传语。
- 相比基于简介的推荐：AO3 简介是作者写的广告。该服务器的工作流程是：广泛搜索（40–60 条结果），让阅读模型阅读候选名单——一次调用最多可读 20 篇完整作品——并只推荐实际被阅读过的内容，同时附带逐字原文样本，让质量判断来自文本本身。
- 写作与角色扮演灵感引擎：如果你用 AI 写作——同人、原创小说、角色扮演——它可以充当灵感引擎。在场景进行中，智能体可以调取真实同人作者如何处理你正写到的具体桥段；阅读器会返回结构、风格笔记和逐字原文样本，让模型了解该桥段实际是如何被书写的，而不是凭想象猜测同人是什么样的。角色扮演同理：可拉取能拿捏某角色口吻的作品报告，作为风格参考。
使用方式 依赖：需要 Python 3.10+ 和一个免费的 Gemini API key。获取方式：前往 aistudio.google.com/api-keys，用任意 Google 账号登录，点击“Create API key”。免费额度足够，无须设置计费。
添加到智能体：将命令指向 ao3-mcp，并通过 --api-key 传入密钥。若不想把密钥放在参数列表里，可去掉 --api-key，改用 env 块传入——服务器会从环境变量中读取 GEMINI_API_KEY 作为回退。
配置位置：
- Cursor：Settings → MCP → New MCP Server，粘贴 JSON 配置。
- .gemini/antigravity/mcp_config.json：添加上面的 JSON 配置。
缓存：作品下载会在本地缓存 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 托管各种分级的内容。服务器会透传你搜索范围内的任何内容——请使用分级筛选和 AO3 的警告标签来控制获取内容。
- 规模：这是一个小型、单一用途的服务器——几百行可读代码，没有框架魔法。你可以 fork 并修改任何内容：重写阅读器的提示词、换用其他模型、修改节流、添加工具。这是预期的使用方式。
从源码运行：支持从源码运行。
致谢与版权：AO3 访问方式基于 wendytg 的 ao3_api 构建。所有同人作品归其在 Archive of Our Own 的作者所有，AO3 是 Organization for Transformative Works 的项目。
