arxiv-mcp-server

Публичный размещённый сервер: https://arxiv.caseyjhand.com/mcp

Инструменты

Четыре инструмента для поиска и чтения статей arXiv:

arxiv_search

Поиск статей по свободным текстовым запросам с префиксами полей и булевыми операторами.

• Префиксы полей: ti: (заголовок), au: (автор), abs: (аннотация), cat: (категория), all: (все поля)

• Булевы операторы: AND, OR, ANDNOT

• Опциональный фильтр по категории, сортировка (relevance, submitted, updated) и постраничная навигация

• Категория принимает код конечного узла (cs.CL) или целый архив (astro-ph, cs, math) — архив без указания подкласса охватывает его предметные классы, а также устаревшие плоские статьи, поданные до его разделения

• submitted_from / submitted_to ограничивают дату подачи (включительно, UTC YYYY-MM-DD). Последовательные окна покрывают совпадения без пропусков — статья, поданная ровно на стыке полуночи, попадает в оба окна, поэтому дедуплицируйте по ID — так можно получить результаты за пределами потолка пагинации в 10 000

• Возвращает запрос в том виде, в котором он реально выполнялся, со всеми включёнными фильтрами — повторный запуск воспроизводит тот же набор результатов

• Возвращает до 50 результатов на запрос с полными метаданными, включая аннотацию

arxiv_get_metadata

Получение полных метаданных одной или нескольких статей по известному arXiv ID.

• Пакетное получение до 10 статей за один запрос

• Принимает как версионированные (2401.12345v2), так и неверсионированные (2401.12345) ID

• Поддерживается устаревший формат ID (hep-th/9901001)

• Сообщает о ненайденных ID отдельно от найденных статей

arxiv_read_paper

Чтение полного текста статьи arXiv.

• Сначала пробует родной HTML arXiv, затем ar5iv, затем текст, извлечённый из PDF — поле source сообщает, какой источник ответил

• Удаляет HTML-шапку и служебную обвязку и сворачивает MathML в LaTeX, ограниченный знаками доллара ($…$ встроенный, $$…$$ блочный), чтобы лимит символов расходовался на содержимое статьи

• Возвращает сырой HTML — без разбора и извлечения; LLM интерпретирует содержимое напрямую. Текст, извлечённый из PDF, — это обычный текст: проза надёжна, но математика, таблицы и структура заголовков уплощаются

• max_characters по умолчанию равен 100 000; передайте null, чтобы получить всю статью за один вызов. Сырой HTML для статей с большим объёмом математики может составлять 500 КБ–3 МБ+, что больше, чем большинство клиентов принимает в одном результате инструмента — вместо этого листайте с помощью start

arxiv_list_categories

Вывод кодов и названий категорий arXiv для ознакомления.

• ~155 категорий в 8 группах верхнего уровня (cs, math, physics, q-bio, q-fin, stat, eess, econ)

• Опциональный фильтр по группе для сужения результатов

• Статические данные — всегда выполняется успешно

Related MCP server: arxiv-reader-mcp

Ресурсы

Возможности

Построен на @cyanheads/mcp-ts-core:

• Декларативные определения инструментов — один файл на инструмент, фреймворк обрабатывает регистрацию и валидацию

• Единая обработка ошибок во всех инструментах

• Подключаемая аутентификация (none, jwt, oauth)

• Структурированное логирование с опциональной трассировкой OpenTelemetry

• Запускается локально (stdio/HTTP) из той же кодовой базы

Специфика arXiv:

• Только чтение, аутентификация не требуется — API arXiv бесплатен, метаданные имеют лицензию CC0

• Очередь запросов с ограничением скорости, обеспечивающая 3-секундную задержку обхода arXiv

• Адаптивная пауза при ограничении скорости (5s → 10s → 20s → 30s), учитывает Retry-After

• Повторные попытки с экспоненциальной задержкой при временных сбоях

• Цепочка резервных источников контента: родной HTML arXiv → ar5iv → извлечение текста из PDF (оба HTML-рендера используют LaTeXML, поэтому они склонны отказывать одновременно; PDF — это артефакт, который есть у каждой статьи, и он также покрывает сбой ar5iv, не позволяя одному сбою сорвать чтение)

• Полная таксономия категорий arXiv, встроенная как статические данные

• Опциональное локальное зеркало метаданных OAI-PMH (SQLite + FTS5) — включается по желанию, устраняет подверженность ограничению скорости для arxiv_search и arxiv_get_metadata. См. Опционально: локальное зеркало.

Начало работы

Публичный размещённый экземпляр

Публичный экземпляр доступен по адресу https://arxiv.caseyjhand.com/mcp — установка не требуется. Подключите любой MCP-клиент к нему через Streamable HTTP:

{
  "mcpServers": {
    "arxiv-mcp-server": {
      "type": "streamable-http",
      "url": "https://arxiv.caseyjhand.com/mcp"
    }
  }
}

Самостоятельное размещение / Локально

Добавьте в конфигурацию вашего MCP-клиента (например, claude_desktop_config.json):

{
  "mcpServers": {
    "arxiv-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/arxiv-mcp-server@latest"]
    }
  }
}

Предварительные требования

• Bun v1.3.0 или выше.

Установка

1. Клонируйте репозиторий:

git clone https://github.com/cyanheads/arxiv-mcp-server.git

2. Перейдите в каталог:

cd arxiv-mcp-server

3. Установите зависимости:

bun install

Конфигурация

Вся конфигурация опциональна — сервер работает из коробки с разумными значениями по умолчанию.

Запуск сервера

Локальная разработка

• Сборка и запуск:

  bun run build
  bun run start:http   # or start:stdio

• Запуск проверок и тестов:

  bun run devcheck     # Lint, format, typecheck, audit
  bun run test         # Vitest

Опционально: локальное зеркало

Для самостоятельных развёртываний за одним исходящим IP-адресом задержка обхода arXiv ~3 секунды на IP-адрес сериализует одновременных пользователей. Опциональное локальное зеркало устраняет подверженность ограничению скорости для arxiv_search и arxiv_get_metadata, обслуживая запросы из хранилища SQLite + FTS5, наполняемого через OAI-PMH. arxiv_read_paper продолжает использовать живой API — полный сбор контента запрещён политикой данных arXiv.

Отключено по умолчанию. Чтобы включить:

# 1. Cold-start harvest (~4.4h sequential, resumable from checkpoint). One-time per installation.
bun run mirror:init

# 2. Enable the mirror.
export ARXIV_MIRROR_ENABLED=true

# 3. Start the server — reads switch to the mirror once the harvest completes.
bun run start:http

Ежедневное инкрементальное обновление (небольшая дельта; длительность зависит от темпа выдачи страниц OAI-PMH arXiv) через:

bun run mirror:refresh   # wire to cron / systemd timer / launchd, OR
                         # set ARXIV_MIRROR_REFRESH_CRON to schedule it in HTTP mode (spawned as a child process)
bun run mirror:verify    # schema version + PRAGMA integrity_check / quick_check

Обновления схемы. Зеркало записывает версию схемы и выполняет миграцию на месте при первом открытии более новым сервером — никогда не повторный сбор и не отдельный шаг оператора. Обновление, добавившее comment и journal_ref в полнотекстовый индекс (#37), перестраивает этот индекс из уже сохранённых строк, поэтому поиски co: и jr: работают по зеркалу, собранному до этого обновления. Перестройка выполняется при запуске, до того как хранилище ответит на первый запрос чтения, и в процессе выводит строки прогресса mirror migration v2→v3 (fts rebuild) — на зеркале с полным корпусом первый запуск после обновления, как ожидается, займёт заметно больше времени, чем обычно. Прерванная перестройка повторяется при следующем открытии, а не остаётся наполовину применённой. bun run mirror:verify выводит версию схемы, которую содержит файл, и завершается с ненулевым кодом, если миграция так и не завершилась.

Замечания по поведению. Расхождение ранжирования: FTS5 BM25 отличается от внутреннего ранжирования arXiv, поэтому sortBy=relevance против зеркала возвращает другой top-K, чем живой API. Запросы, отсортированные по submitted по убыванию в пределах ARXIV_MIRROR_RECENT_DAYS_LIVE дней, направляются в живой API, чтобы покрыть промежуток между ночными обновлениями. Устойчивость обновления: после завершения первоначального холодного сбора выполняющееся или завершившееся сбоем ежедневное обновление продолжает обслуживать существующий набор данных из зеркала — arxiv_search и arxiv_get_metadata не переключаются на живой API во время окна обновления (#21). Плановое обновление в HTTP-режиме выполняется в дочернем процессе, поэтому синхронные записи SQLite при сборе никогда не блокируют цикл обработки событий запросов — поиск и метаданные остаются отзывчивыми на протяжении всего процесса (#22). Зеркало хранит только последнюю версию; чтение по отдельным версиям продолжает использовать живой API. Полное описание см. в #12.

Docker

docker build -t arxiv-mcp-server .
docker run -p 3010:3010 arxiv-mcp-server

Структура проекта

Руководство по разработке

См. CLAUDE.md с рекомендациями по разработке и архитектурными правилами. Краткая версия:

• Обработчики выбрасывают исключения, фреймворк ловит их — никаких try/catch в логике инструментов

• Используйте ctx.log для доменного логирования

• Ограничение частоты запросов управляется ArxivService — не добавляйте задержки для отдельных инструментов

• arXiv API возвращает HTTP 200 для всего — проверяйте content-type и тело ответа

Участие в разработке

Приветствуются issue и pull request. Перед отправкой запустите проверки:

bun run devcheck
bun test

Лицензия

Apache-2.0 — подробности см. в LICENSE.