paperboy

# paperboy [](https://github.com/michaelellis003/paperboy/actions/workflows/ci.yml) [](LICENSE) [](https://glama.ai/mcp/servers/michaelellis003/paperboy)  一款将研究论文和书籍交付到您的电子阅读器的MCP服务器，以Zotero作为事实来源。向Claude请求一个阅读列表，然后说“将它们排队并发送到我的Kindle。”（MCP是Claude使用的插件协议：该程序在您的机器或云项目上运行，Claude在对话过程中调用其工具。）在Claude Code和Claude Desktop上本地运行；Cloud Run部署添加了claude.ai和Claude移动应用程序，以便可以从手机发送论文（[docs/deploy.md](docs/deploy.md)）。 两件事情是分开的：**交付**论文到您的设备和**编目**作品到Zotero。您可以两者都做。您可以跟踪您拥有的书籍、付费参考资料或您已经拥有的PDF，而无需将其发送到电子阅读器。 Zotero本身是可选的：没有它，您仍然可以搜索和发送论文。阅读队列、收藏和跨会话的重复保护需要它。 ## 工作原理 您向Claude请求论文；它使用paperboy的工具查找、排队和交付它们。实际操作如下： - 您排队的论文会放入Zotero中的**阅读队列**收藏中，按需创建。 - 一旦论文到达您的设备，paperboy就会在Zotero中标记它为`sent-to-ereader`，这样即使在后续对话中，它也会跳过已经发送到您的电子阅读器的论文。（没有Zotero，不同发送之间没有记忆，因此此保护功能需要它。） - Claude还可以将论文归档到您的主题收藏中。它会从论文的主题和您现有的收藏名称中提出一个收藏，并在不确定的情况下向您询问。论文可以同时存在于多个收藏中，因此归档不会干扰队列。 - 论文通过arXiv ID、DOI或标题查找（足够接近的标题匹配，因此Claude编写的阅读列表可以原样发送）。当标题仅松散匹配时，paperboy会提供最接近的候选者进行确认，而不是猜测或无声失败。 - 书籍也可以：`add_book`将ISBN、图书DOI或标题解析为正确的Zotero **book**项目（出版商、版本、ISBN、页数）。书籍被编目，而不是交付。 - 已经有PDF（工作论文、讲义、开放获取教科书）？`attach_pdf`会将PDF文件到Zotero中，并附上您提供的元数据，并且可以将其发送到电子阅读器。 Zotero保存了所有这些，因此服务器本身不保留任何状态：无需运行数据库，随时安全部署。 ### 交付后端 | 后端 | 设备 | 方式 | |---|---|---| | `email`（默认） | Kindle、PocketBook、任何具有电子邮件接收功能的设备 | 通过SMTP到设备地址。Kindle限制强制执行：每封邮件25个附件/50MB；发送者必须在批准的个人文档电子邮件列表中 | | `dropbox` | Kobo（设备上的本地Dropbox同步） | 通过Dropbox API上传。Kobo仅同步`Apps/Rakuten Kobo/`，因此使用具有`DROPBOX_FOLDER="/Apps/Rakuten Kobo"`的**完整Dropbox**范围的应用；应用文件夹范围的应用无法访问它 | ## 工具 | 工具 | 功能 | |---|---| | `search_papers` | 搜索OpenAlex（常规）或arXiv（`source="arxiv"`）；结果带有`ref`和`open_access_pdf`标志 | | `recommend_papers` | 发现相关或新的论文：引用图推荐（Semantic Scholar）从您的Zotero库中播种，加上从Claude提炼的兴趣关键词发现。排除您已经拥有的论文 | | `send_papers` | 通过arXiv ID、DOI、URL或标题一次性发送论文（如果配置了Zotero，也会记录在Zotero中） | | `queue_papers` | 将论文添加到Zotero阅读队列中，而不发送（可选地归档到主题收藏中） | | `add_to_library` | 在Zotero中跟踪论文**而不**排队或发送它们（拥有、付费或稍后阅读）；缺少开放访问PDF不会被视为失败 | | `add_book` | 通过ISBN、图书DOI或标题将图书编目为Zotero `book`项目（Crossref、Open Library、Google Books）；永远不会交付 | | `attach_pdf` | 摄入您已经拥有的PDF（灰色文献、开放获取教科书）并附上PDF和您提供的元数据；可选地发送 | | `list_collections` | 列出Zotero收藏，以便Claude可以提出将论文归档到哪里，或询问您 | | `file_papers` | 将排队的论文归档到主题收藏中（按需创建；队列成员资格不受影响） | | `unfile_papers` | 从一个收藏中删除论文（对于错误归档的项目）；论文本身及其队列/发送状态不受影响 | | `list_queue` | 显示队列及其每个项目的状态（未发送/已发送/无开放访问PDF） | | `remove_from_queue` | 通过确切的参考或标题删除队列项目 | | `send_queue` | 发送所有未发送的队列项目（在电子邮件限制下自动拆分），然后标记为已发送 | | `setup_status` | 报告已配置的内容和缺少的内容（无机密）以便Claude可以指导设置 | ## 设置 运行交互式向导。它会询问您拥有的电子阅读器，遍历设备所需的凭证，并验证您输入的每个凭证：SMTP登录测试，Zotero密钥检查，自动库ID查找，完整的Dropbox OAuth交换。 ```bash uv sync && uv run paperboy setup ``` [docs/setup.md](docs/setup.md)是分步版本：查找Zotero、Amazon、Gmail和Dropbox中的每个凭证，并附有链接到每个步骤的官方页面。 根据设备的不同，您需要设置的凭证数量也会有所不同： | 您拥有 | 需要的凭证 | |---|---| | Kindle | 2 — 发送到Kindle的地址 + SMTP应用密码 | | PocketBook | 2 — 发送到PocketBook的地址 + SMTP应用密码 | | Kobo | 一个Dropbox应用（密钥/秘密 + 一个OAuth批准）+ 联系邮箱 | | + Zotero队列（可选） | 1 — 一个Zotero API密钥（自动检测库ID） | 如果您想手动设置，请复制`.env.example`并填写`.env`。每个变量都有文档说明。然后使用Claude Code注册： ```bash claude mcp add paperboy -- uv run --directory /path/to/paperboy paperboy ``` `--directory`很重要：服务器从其工作目录加载`.env`（设置`PAPERBOY_ENV=/path/to/.env`以指向其他位置）。 如果添加了paperboy但配置不完整，请让Claude“检查我的paperboy设置”。`setup_status`工具报告缺少的内容和下一步骤，无需通过聊天传递机密。 ## 远程使用 ### 您获得了URL和令牌 如果有人与您共享了他们的部署，这是您的完整设置： ```bash claude mcp add --transport http paperboy <URL>/mcp \ --header "Authorization: Bearer <token>" ``` URL需要`/mcp`路径后缀。请像密码一样对待令牌：它允许您完全作为所有者操作：从他们的地址发送电子邮件，交付到他们的电子阅读器，并读取和编辑他们的Zotero库。没有降低权限的模式；如果这不是您想要的，请部署您自己的实例。 ### 部署您自己的 一个脚本创建一个锁定、单租户的Cloud Run服务。您需要gcloud CLI和具有启用账单的Google Cloud帐户，因此需要一张卡。您的费用取决于您的使用情况：个人部署发送论文通常在Cloud Run的免费层内，不会产生费用，但大量或共享使用可能会超过免费层。脚本设置了一个每月1美元的预算警报，以便您了解账单。 ```bash uv run paperboy setup && ./deploy/deploy.sh my-paperboy-project ``` 客户端连接到部署服务器的方式取决于客户端： - **Claude Code和API** 使用脚本生成的承载令牌。您将其粘贴到`Authorization`标头中，如上所述。 - **claude.ai和Claude移动应用** 通常无法从其连接器对话框发送承载令牌，因此它们改为使用Google登录。 这需要一次性Google OAuth客户端，您在自己的云项目中创建（带有重定向URI的Web应用程序客户端）。 登录仅限于您自己的电子邮件地址，并且由于paperboy仅向Google请求您的电子邮件，因此登录不会过期。 [docs/deploy.md](docs/deploy.md)包含两种方式的完整过程，包括OAuth控制台步骤、安全模型和成本边界。部署脚本还会打印确切的OAuth步骤，其中已填充您的项目URL。 ## 开发和贡献 使用uv进行打包，ruff（Google风格），ty，pytest，强制执行80％的覆盖率门控。`uv sync && uv run pre-commit install`，然后`uv run pytest`。测试套件完全离线运行；开发无需凭证。 欢迎贡献。[CONTRIBUTING.md](CONTRIBUTING.md)涵盖设置、测试约定以及使更改易于合并的内容；[SECURITY.md](SECURITY.md)涵盖如何私密报告漏洞。 ## 路线图 - [ ] reMarkable交付后端（真正的云API） - [ ] 通过pandoc将arXiv HTML转换为EPUB，以便可重流阅读（按纸张选择；转换对于密集数学来说是有损的，因此PDF仍是默认值） - [ ] Kindle高亮 → Zotero笔记往返（`My Clippings.txt`解析器与模糊标题匹配） ## 先前作品和致谢 paperboy建立的想法：使用标签驱动的Zotero→Kindle想法来自[stakats/zotero-to-kindle](https://github.com/stakats/zotero-to-kindle)（约2011年，由Zotero的原始董事之一）；[wahiggins3/send-to-kindle-mcp](https://github.com/wahiggins3/send-to-kindle-mcp)；[openags/paper-search-mcp](https://github.com/openags/paper-search-mcp)；以及[54yyyu/zotero-mcp](https://github.com/54yyyu/zotero-mcp)，我们的设置向导的模型；paperboy将库管理留给它。 感谢[arXiv](https://arxiv.org)允许使用其开放访问互操作性。论文元数据和开放访问链接来自[OpenAlex](https://openalex.org)、[Crossref](https://www.crossref.org)和[Unpaywall](https://unpaywall.org)，所有这些都作为开放的学术基础设施运行。[Semantic Scholar](https://www.semanticscholar.org)通过推荐API提供建议（Allen Institute for AI）。通过[Zotero](https://www.zotero.org) Web API进行库管理。在[FastMCP](https://github.com/jlowin/fastmcp)、[pyzotero](https://github.com/urschrei/pyzotero)和[httpx](https://github.com/encode/httpx)上构建。 paperboy由[Claude Code](https://claude.com/claude-code)构建。