ARES MCP

Локальный сервер Model Context Protocol для поиска и написания академической литературы. Он работает с открытыми каталогами (OpenAlex, arXiv, Crossref), загружает открытые PDF-файлы (только PDF), извлекает разделы IMRaD по запросу и добавляет BibTeX — предназначен для работы рядом с Cursor.

Лицензия: MIT. Вклад: CONTRIBUTING.md.

ARES не обходит платные стены издателей. Если OA PDF не существует, инструменты возвращают no_open_pdf вместо парсинга HTML.

Этот репозиторий — помощник по литературе, а не инструмент для скрининга/аудита PRISMA.

Инструменты

Типичный поток агента: поиск (sort=cited_by для известных статей) → загрузка OA-результата → извлечение Abstract/Methods → get_bibtex.

Related MCP server: Scholar MCP Server

Требования

• Python 3.11+

• uv рекомендуется для uvx

Файл .env не требуется. ARES выбирает контактный email для вежливого пула OpenAlex / Unpaywall в следующем порядке:

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

2. ARES_MAILTO в окружении процесса (блок env в mcp.json Cursor)

3. Опциональный .env в текущей директории (ARES_MAILTO=...) — только для локальных копий

4. git config user.email

5. Заглушка ares-mcp@localhost (сервер всё равно запускается)

Установка из PyPI (Cursor)

После публикации:

{
  "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 на ваш клон. Email опционален; если не задан, используется user.email из git.

Рекомендуется — 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"]
    }
  }
}

Перезагрузите MCP-серверы в Cursor, затем спросите: «Найди статьи открытого доступа по графовым нейронным сетям с 2022 года».

Инспектор (вне Cursor):

uv run fastmcp dev src/ares_mcp/server.py

Окружение

Записи ограничены текущей рабочей директорией сервера (проект, открытый в Cursor). Обход пути отклоняется.

Примечания по API

• OpenAlex: GET /works с search + filter. Аннотации хранятся в виде инвертированных индексов и восстанавливаются локально. Загрузка использует все locations с pdf_url, а также arXiv/PMC id, если они есть.

• Unpaywall: GET /v2/{doi} для легальных OA-копий (препринты, принятые рукописи, репозитории). Так многие статьи IEEE/Elsevier становятся доступными для загрузки без обращения к HTML платных стен.

• arXiv: Atom API на export.arxiv.org. Все результаты — OA.

• Crossref: согласование содержимого DOI Accept: application/x-bibtex.

• Идентифицируйте свой процесс с помощью --mailto или ARES_MAILTO, когда это возможно. Не перегружайте API; каждый вызов инструмента — это несколько запросов с одной повторной попыткой при 429/5xx.

Если каждый OA-кандидат возвращает 403 или HTML, инструмент сообщает download_failed или no_open_pdf. Передайте arXiv id, если вы знаете, что существует препринт. ARES не будет парсить HTML издателя.

Альтернативная лицензия

MIT — лицензия проекта. Apache-2.0 может быть рассмотрена позже, если потребуется патентная грамота; обсудите это в issue перед сменой лицензии.

Статус

MVP 0.1.0. Публикация с помощью uv build и uv publish (или Trusted Publisher на GitHub Actions). После этого Cursor может запускать uvx ares-mcp без .env.