ARES MCP

本地 Model Context Protocol 服务器，用于 学术文献检索与写作。它对接开放目录 （OpenAlex、arXiv、Crossref），下载开放获取的 PDF（且只接受 PDF 文件）， 按需提取 IMRaD 章节，并追加 BibTeX——专为配合 Cursor 使用而设计。

许可证：MIT。贡献指南：CONTRIBUTING.md。

ARES 不会绕过出版商的付费墙。如果不存在开放获取的 PDF， 工具会返回 no_open_pdf，而不是去抓取 HTML。

本仓库是一个文献辅助工具，而不是 PRISMA 筛选/审计工作台。

工具

典型智能体流程：检索（知名论文用 sort=cited_by）→ 下载开放获取 命中文献 → 提取摘要/方法 → get_bibtex。

Related MCP server: Scholar MCP Server

环境要求

• Python 3.11+

• 推荐使用 uv 来运行 uvx

不需要 .env 文件。ARES 按以下顺序为 OpenAlex / Unpaywall 礼貌池选取联系邮箱：

1. ares-mcp --mailto you@university.edu

2. 进程环境中的 ARES_MAILTO（Cursor mcp.json 的 env 块）

3. 可选的当前目录 .env（ARES_MAILTO=...）——仅限本地检出

4. git config user.email

5. 占位符 ares-mcp@localhost（服务器仍会启动）

从 PyPI 安装

发布后：

{
  "mcpServers": {
    "ares": {
      "command": "uvx",
      "args": ["ares-mcp"]
    }
  }
}

可选身份（仍然无需 .env）：

{
  "mcpServers": {
    "ares": {
      "command": "uvx",
      "args": ["ares-mcp", "--mailto", "you@university.edu"]
    }
  }
}

安装（开发）

git clone <this-repo>
cd AREsMCP
uv sync

运行测试：

uv run pytest
uv run ruff check src tests

在线 API 检查（可选）：

uv run pytest -m integration

配置 Cursor（本地检出）

复制 .cursor/mcp.json，并把 --project 路径 替换为你的 clone 路径。邮箱可选；未设置时会使用 git config user.email。

推荐方式——uv run：

{
  "mcpServers": {
    "ares": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "C:/Users/vitor/Documents/Projetos/AREsMCP",
        "ares-mcp"
      ]
    }
  }
}

venv Python 方式：

{
  "mcpServers": {
    "ares": {
      "command": "C:/Users/vitor/Documents/Projetos/AREsMCP/.venv/Scripts/python.exe",
      "args": ["-m", "ares_mcp.server"]
    }
  }
}

从本地检出使用 uvx（无需发布到 PyPI）：

{
  "mcpServers": {
    "ares": {
      "command": "uvx",
      "args": ["--from", "C:/Users/vitor/Documents/Projetos/AREsMCP", "ares-mcp"]
    }
  }
}

在 Cursor 中重新加载 MCP 服务器，然后提问：“搜索 2024 年以来关于图神经网络的开放获取论文。”

Inspector（在 Cursor 之外使用）：

uv run fastmcp dev src/ares_mcp/server.py

环境

写入操作被限制在服务器当前工作目录（即 Cursor 打开的项目）内。 穿越路径会被拒绝。

API 说明

• OpenAlex： 使用 search + filter 调用 GET /works。摘要以 倒排索引存储并在本地重建。下载时使用所有包含 pdf_url 的 locations，兼用存在的 arXiv/PMC id。

• Unpaywall： 通过 GET /v2/{doi} 获取合法开放获取副本（预印本、 已录用手稿、机构知识库）。许多 IEEE/Elsevier 论文因此也可以在不触碰 付费墙 HTML 的情况下被下载。

• arXiv: Atom API 地址为 export.arxiv.org。所有命中的文献均为 OA。

• Crossref： DOI 内容协商 Accept: application/x-bibtex。

• 请尽可能用 --mailto 或 ARES_MAILTO 标明你的进程。不要 频繁请求这些 API；每次工具调用只发少量请求，并在 429/5xx 时重试一次。

如果所有开放获取候选都返回 403（或返回的是 HTML），工具会报告 download_failed 或 no_open_pdf。当你已知存在预印本时，可传入 arXiv id。ARES 不会抓取出版商的 HTML。

许可证备选方案

该项目使用 MIT 许可证。以后若有专利授权需求，可以考虑 Apache-2.0； 在重新许可之前，请先在 issue 中讨论。

状态

MVP 版本 0.1.0。发布时请使用 uv build 和 uv publish（或在 GitHub Actions 中使用 Trusted Publisher）。之后，Cursor 无需 .env 即可运行 uvx aares-mcp。