Papers by Ouroboros Apps

Ouroboros 论文

Papers by Ouroboros 是面向学生、研究人员、写作者和临床工作者的远程 MCP 服务，帮助他们使用助手搜索并引用真实论文。它是 Consensus、SciSpace 和 Elicit 的轻量级独立替代方案。

助手可以搜索 OpenAlex、Semantic Scholar、PubMed、Crossref 和 arXiv；通过 DOI、PMID 或 arXiv id 打开论文；查看引用某篇论文的文献或该论文引用的文献；并生成 APA、MLA、Chicago 或 BibTeX 格式。每条结果都包含来源链接，以及由上述某个 API 返回的标识符。如果 API 没有返回结果，Papers 也不会返回任何内容。它不会用杜撰的引文来填补缺失信息。

• 适用于 ChatGPT、Claude、Gemini、Grok、Cursor，以及任何支持 Streamable HTTP 和 OAuth 2.1（动态客户端注册和 PKCE）的客户端

托管服务

• MCP 服务 URL：https://papers-mcp.vercel.app/mcp（在线，Streamable HTTP，OAuth 登录）
• 健康检查：https://papers-mcp.vercel.app/health
• 受保护资源元数据：https://papers-mcp.vercel.app/.well-known/oauth-protected-resource
• 连接指南：https://papers-mcp.vercel.app/connect
• 文档：https://ouroborosapps.com/docs/papers
• 注册表名称：io.github.LAHutchins91/papers（server.json 中的 remotes[0].url 指向上方的托管 URL）

如果你选择自托管，MCP 端点为 https://<your-host>/mcp。将 APP_BASE_URL 设置为该源地址，并修改你所用 server.json 副本中的 remotes[0].url。

连接

将客户端 ID 和密钥留空，以便客户端自行注册。

Cursor，配置文件位于 ~/.cursor/mcp.json 或项目中的 .cursor/mcp.json：

{
  "mcpServers": {
    "papers": {
      "url": "https://papers-mcp.vercel.app/mcp"
    }
  }
}

Claude Code：

claude mcp add --transport http papers https://papers-mcp.vercel.app/mcp

其他客户端：添加相同的 URL，并选择 OAuth。授权页面会显示助手名称和 papers 范围。工具发现（initialize、tools/list、ping）不需要令牌，但调用工具需要令牌。

工具

• search_papers — 按问题或关键词搜索，可选年份范围、领域、开放获取标记和来源（openalex、semantic_scholar、pubmed、crossref、arxiv 或 all）
• get_paper — 按 DOI、PMID、arXiv id 或 OpenAlex work id 获取一条记录及其摘要
• find_related_papers — 根据该标识符查找 cited_by 或 references
• format_citation — 根据获取的元数据生成 apa、mla、chicago 或 bibtex 格式的引文

标题会保留来源中的原始写法。作者姓名会从显示名称中拆分出来，因此像 “van” 这样的词可能会被放到错误的部分，发布引文前最好检查一下。

权限、数据与限制

OAuth scope。 一个 scope：papers。授权屏幕会显示助手名称和该 scope。它仅授予对此服务的工具调用权限，不会授予对任何其他账户、文件或服务的访问权限。

操作。 所有四种工具都只会查询公开的学术 API（readOnlyHint: true，destructiveHint: false）。没有写入或删除操作。Papers 不会代表你在服务之外或学术来源中创建、更改或删除任何内容。

确认。 由于不会写入或删除任何内容，因此没有工具会要求确认。只有连接时的 OAuth 授权屏幕，以及开始试用时的 Stripe Checkout 需要确认。

存储、保留与隐私。 Papers 不会保留查询日志或历史记录。搜索词或标识符会发送到负责提供结果的学术来源，并且在响应后不会保留。Papers 会存储一个随机账户 ID（cookie 保留 90 天，访问令牌保留 1 小时，刷新令牌保留 30 天）、未过期的单次授权码 ID（5 分钟），以及你开始试用后的一份订阅快照（账户 ID、Stripe 客户 ID、订阅 ID、状态、周期结束时间、套餐周期）。速率限制计数器会在内存中保留约 1 到 10 分钟。连接时不会要求你提供姓名或电子邮件地址。导出或删除请求请发送至 [email protected]。完整政策：https://papers-mcp.vercel.app/privacy

免费限制。 工具发现（initialize、tools/list、ping）开放使用。调用工具需要通过 Stripe Checkout 开始 14 天试用，之后需要 Pro 订阅。金额会显示在 Stripe Checkout 中；此仓库未列出金额。每个客户端 IP 每分钟最多可发送 300 个 MCP 请求。上游 API 也会施加自己的速率限制（见下文“速率限制”）。

使用方式。 典型会话流程：用户提出研究问题，助手调用 search_papers，再用 get_paper 打开一到两条结果，接着调用 find_related_papers 查看引用这些论文的文献，最后用用户需要的格式调用 format_citation。答案中的每条记录都会链接回提供该记录的来源。

试用与账单

连接助手后，可在账户页面开始 14 天试用。金额只会显示在 Stripe Checkout 中。月付和年付套餐使用你配置的价格 ID。Papers 不会创建 Stripe 产品。

当 STRIPE_SECRET_KEY、STRIPE_PRICE_MONTHLY 和 STRIPE_PRICE_YEARLY 均已设置时，调用工具需要 Stripe 订阅处于 trialing 或 active 状态。未设置这些变量时，GET /health 会报告 billingConfigured: false，通过 OAuth 签名的调用者可以使用这些工具。向公众开放部署之前，请先设置 Stripe 变量。

存储

论文搜索是无状态的。订阅快照和已使用的授权码 ID 共用一个存储：

STORAGE_BACKEND	行为
memory（默认）	进程本地存储。适用于测试和单个 Node 进程。第二个进程仍可能接受本进程已使用过的授权码。
file	存储在 STORAGE_PATH 指定的一个 JSON 文档中（默认值为 data/accounts.json）。适用于单个 Docker 主机。
blob	存储在 STORAGE_BLOB_PATH 指定的一个私有 Vercel Blob 中（默认值为 papers/accounts.json）。在 Vercel 上使用此选项，以防授权码在多个实例间被重放。需要 BLOB_READ_WRITE_TOKEN。

文档结构为 { accounts, usedCodes }。每个账户的结构为 { userId, stripeCustomerId, subscriptionId, subscriptionStatus, currentPeriodEnd, plan, updatedAt }。usedCodes 将授权码 ID 映射到其过期时间（Unix 秒）。每次写入时都会移除已过期的 ID。仍可读取仅包含账户映射的旧文件。没有单独的数据库架构。配置计费后，Stripe 是事实来源：如果快照不存在，冷启动的进程会通过 metadata.papers_user_id 查找客户。

OAuth 访问令牌和客户端注册信息是签名令牌，而非数据行。请在生产环境中设置 AUTH_SIGNING_SECRET，以便令牌在重启后继续有效。在 Vercel 上，请在公开部署之前设置 STORAGE_BACKEND=blob。

环境变量

变量	是否必需	用途
APP_BASE_URL	生产环境	公开源站，不带尾部斜杠。OAuth 发行者和 MCP 受众。
AUTH_SIGNING_SECRET	生产环境	用于 OAuth 令牌和账户 Cookie 的 HMAC 密钥。
SCHOLARLY_CONTACT_EMAIL	生产环境	User-Agent 及 OpenAlex、Crossref 和 PubMed 礼貌使用池参数中的 mailto 地址。不会显示在公开页面上。
REVIEWER_LOGIN_EMAIL	商店审核时	在 Reviewer 登录时输入的邮箱。见下文。
REVIEWER_LOGIN_PASSWORD_HASH	商店审核时	审核人员密码的 scrypt 哈希。见下文。
COMP_ACCOUNT_EMAILS	商店审核时	以逗号分隔、拥有永久免费访问权限的邮箱。
COMP_ACCOUNT_IDS	否	以逗号分隔、拥有永久免费访问权限的账户 ID。
NCBI_API_KEY	否	提高 PubMed 速率限制。
SEMANTIC_SCHOLAR_API_KEY	否	提高 Semantic Scholar 速率限制。作为 x-api-key 发送。
STRIPE_SECRET_KEY	收费时	Stripe 密钥。
STRIPE_PRICE_MONTHLY	收费时	现有的月度价格 ID。
STRIPE_PRICE_YEARLY	收费时	现有的年度价格 ID。
STRIPE_WEBHOOK_SECRET	收费时	Webhook 签名密钥。将 Stripe 指向 POST /billing/webhook。
STORAGE_BACKEND	否	memory、file 或 blob。
STORAGE_PATH	否	后端为 file 时使用的 JSON 文件。
STORAGE_BLOB_PATH	否	后端为 blob 时使用的 Blob 路径名。默认为 papers/accounts.json。
BLOB_READ_WRITE_TOKEN	使用 blob 时	Vercel Blob 存储的读写令牌。SDK 会自行读取此令牌。
PORT	否	默认为 43127。

请勿提交密钥。将所需内容复制到主机的环境变量中，而不是仓库中。

本地运行

npm install
npm run dev

打开 http://127.0.0.1:43127。健康检查地址为 GET /health。

npm test
npm run typecheck

测试会调用不需要密钥的公开 API，不会调用 Stripe。Semantic Scholar 经常因共享 IP 地址空间返回 429；工具会报告该速率限制，不会编造论文来替代。

部署

Vercel：vercel.json 会构建 api/index.ts，并将所有路径路由到该函数，同时将 logo.jpg 打包进函数中。仓库文件（例如 /package.json 和 /src/*）不会作为静态文件提供。设置上述环境变量，将 APP_BASE_URL 设为部署来源地址，将 STORAGE_BACKEND=blob，并将 server.json 中的 remotes[0].url 更新为 https://<that-host>/mcp。在 Vercel 项目中创建 Blob 存储，并将其读写令牌保存在 BLOB_READ_WRITE_TOKEN 中。Stripe 的 webhook 端点为 POST /billing/webhook。

Docker：

docker build -t papers-mcp .
docker run --rm -p 43127:43127 -e APP_BASE_URL=http://127.0.0.1:43127 -e AUTH_SIGNING_SECRET=replace-me -e [email protected] papers-mcp

容器监听端口 43127。

速率限制

请求会按主机限速：OpenAlex 约为 10/s，Crossref 约为 4/s，没有 NCBI 密钥时 PubMed 约为 3/s，没有密钥时 Semantic Scholar 约为 1/s，arXiv 的调用间隔至少为 3 秒。始终会发送描述性 User-Agent。只有在设置了 SCHOLARLY_CONTACT_EMAIL 时，才会包含联系邮箱。

许可证

MIT。版权所有 Lawrence Hutchins。参见 LICENSE。

---

联系方式

公开支持、隐私、导出和删除事宜：[email protected]

• 隐私：/privacy
• 条款：/terms
• 支持：/support
• 网站：https://ouroborosapps.com

公开页面始终显示该邮箱。SCHOLARLY_CONTACT_EMAIL 仅会在学术 API 的礼貌使用请求头中发送，不会显示在网站上。不会读取 SUPPORT_EMAIL。

server.json、glama.json 和 .cursor-plugin/plugin.json 均没有联系邮箱字段。server.json 使用的注册表架构未定义此字段。

商店审核员登录

审核员在 OAuth 同意屏幕上使用 审核员登录 登录。无需单独注册，没有第二重验证，也无需银行卡。在托管平台（Vercel 项目 → Settings → Environment Variables）中设置以下变量，适用于 Production 以及审核员会打开的任何 Preview URL。不要提交这些值。

变量	格式
REVIEWER_LOGIN_EMAIL	一个电子邮箱地址，即审核员输入的值。比较时会转换为小写。
REVIEWER_LOGIN_PASSWORD_HASH	单行：scrypt$16384$8$1$<salt-base64url>$<hash-base64url>。Salt 为 16 字节。Hash 为 32 字节。scrypt 参数为 N=16384、r=8、p=1。
COMP_ACCOUNT_EMAILS	以逗号分隔的邮箱。包含 REVIEWER_LOGIN_EMAIL。每个邮箱都会为其派生出的稳定账户 ID 授予永久权益。
COMP_ACCOUNT_IDS	可选的、以逗号分隔的账户 ID。使用派生出的审核员 ID，或希望授予权益的匿名账户 ID。

登录时会检查邮箱和密码哈希。跳过试用和 Stripe 由允许列表决定。将 COMP_ACCOUNT_EMAILS 设为与 REVIEWER_LOGIN_EMAIL 相同的地址，或将派生出的 ID 放入 COMP_ACCOUNT_IDS。普通匿名账户不受影响，配置了计费时仍需要试用。

生成哈希（密码作为参数传入，不是仓库中的文件）：

node --input-type=module -e '
import crypto from "node:crypto";
const password = process.argv[1];
if (!password) { console.error("Pass the password as an argument."); process.exit(1); }
const salt = crypto.randomBytes(16);
const hash = crypto.scryptSync(password, salt, 32, { N: 16384, r: 8, p: 1 });
process.stdout.write(`scrypt$16384$8$1$${salt.toString("base64url")}$${hash.toString("base64url")}\n`);
' 'replace-with-the-reviewer-password'

打印用于 COMP_ACCOUNT_IDS 的账户 ID（对 papers-reviewer、一个 NUL 字节和小写邮箱计算 SHA-256，取前 32 个十六进制字符）：

node --input-type=module -e '
import crypto from "node:crypto";
const email = process.argv[1].trim().toLowerCase();
process.stdout.write(crypto.createHash("sha256").update(`papers-reviewer\0${email}`).digest("hex").slice(0, 32) + "\n");
' '[email protected]'

登录后，工具会返回实时记录。审核员可以使用简短查询调用 search_papers，然后使用 DOI 10.1038/nature14539 调用 get_paper、find_related_papers 和 format_citation。

Ouroboros 出品的论文。了解更多 Ouroboros 内容：https://ouroborosapps.com