arXiv Research MCP

A read-only, deployable MCP server for scientific literature research.

ChatGPT
   ↓  Streamable HTTP
arXiv Research MCP
   ↓  official Atom API
arXiv scientific papers

The server retrieves and normalizes metadata. ChatGPT remains responsible for explaining physics, comparing papers, and working through equations.

Инструменты

Каждый инструмент помечен как доступный только для чтения и возвращает типизированные структурированные данные, содержащие arXiv ID, нормализованные заголовок и аннотацию, авторов, категории, даты, DOI, ссылку на журнал, URL аннотации и URL PDF, когда они доступны.

Локальная настройка

Требуется Python 3.11 или новее.

py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
Copy-Item .env.example .env

Отредактируйте ARXIV_USER_AGENT в файле .env и замените пример контакта на вашу электронную почту или URL проекта. arXiv не требует API-ключа.

Запуск локально через stdio:

arxiv-mcp

Запуск совместимого с удалённым доступом транспорта локально:

arxiv-mcp --transport streamable-http --host 127.0.0.1 --port 8000

Конечные точки:

http://127.0.0.1:8000/mcp
http://127.0.0.1:8000/health

Для ручной проверки инструмента запустите HTTP-сервер, запустите официальный MCP Inspector и подключите его к http://127.0.0.1:8000/mcp:

npx @modelcontextprotocol/inspector@latest

Запуск тестов

pytest
ruff check .

Тесты используют имитированные HTTP-ответы и не обращаются к arXiv API. GitHub Actions запускает те же проверки при каждом push и pull request.

Надёжность и безопасность

• Фиксированный разрешённый вышестоящий сервер: https://export.arxiv.org/api/query

• Трёхсекундный глобальный интервал между запросами по умолчанию

• Ограниченные повторные попытки при тайм-аутах, сетевых сбоях, HTTP 429 и временных ответах 5xx

• Строгая проверка результатов, смещения, категории, сортировки и arXiv ID

• Безопасный разбор XML с отключёнными внешними сущностями

• Нет выполнения команд оболочки, произвольной загрузки URL, секретов, операций записи или хранения пользовательских данных

• Развёртывание без сохранения состояния через Streamable HTTP

Развёртывание на Render

Репозиторий включает Dockerfile без прав root и Blueprint render.yaml.

1. Отправьте этот репозиторий на GitHub.

2. Войдите в Render и выберите New → Blueprint.

3. Подключите репозиторий GitHub и примените render.yaml.

4. В среде сервиса Render измените ARXIV_USER_AGENT, чтобы включить ваш реальный контактный email или URL репозитория.

5. Дождитесь успешного прохождения /health, затем скопируйте URL сервиса.

Итоговый MCP URL:

https://<your-render-service>.onrender.com/mcp

Blueprint использует бесплатный экземпляр Render, поэтому развёртывание не создаёт незаметно обязательств по оплате. Render документирует, что бесплатные сервисы переходят в спящий режим после 15 минут бездействия и могут перезапускаться около минуты. Такой холодный запуск может превысить тайм-аут MCP-клиента; обновите сервис до starter или другого платного экземпляра, прежде чем полагаться на него как на постоянно доступный производственный коннектор. См. ограничения бесплатного тарифа Render и справочник Blueprint.

Подключение к ChatGPT

Эти шаги соответствуют текущей официальной документации OpenAI:

1. Разверните сервер и убедитесь, что публичный HTTPS /mcp URL работает в MCP Inspector.

2. В ChatGPT откройте Settings → Security and login и включите Developer mode.

3. Откройте ChatGPT Plugins и нажмите кнопку plus.

4. Введите:

   • Имя: arXiv Research

   • Описание: Read-only search and metadata retrieval from the official arXiv API.

   • Подключение: публичная MCP-конечная точка

   • URL сервера: https://<your-render-service>.onrender.com/mcp

   • Аутентификация: нет

5. Создайте подключение и убедитесь, что обнаружены ровно пять инструментов.

6. Начните новый чат и добавьте arXiv Research из меню инструментов.

OpenAI в настоящее время требует публичную HTTPS-конечную точку (или свой Secure MCP Tunnel) и Streamable HTTP, обычно по адресу /mcp. Доступность режима разработчика зависит от учётной записи и политики рабочего пространства. Текущая страница OpenAI не обещает его для каждого именованного тарифа ChatGPT, поэтому наличие переключателя Developer mode в вашей учётной записи является авторитетной проверкой. Если в учётной записи Plus он не отображается, сервер остаётся пригодным для использования через MCP Inspector, другой MCP-клиент или OpenAI API Playground. См. текущее руководство по подключению OpenAI и руководство по MCP-серверу.

Примеры запросов к ChatGPT

• Search arXiv for recent quantum gravity papers.

• Find papers about the Bondi-Sachs formalism.

• Search hep-th for path integral approaches to gravity.

• Find papers by Roger Penrose related to general relativity.

• Get the metadata and PDF link for arXiv:2401.12345.

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

.
├── src/arxiv_mcp/
│   ├── arxiv_client.py
│   ├── config.py
│   ├── models.py
│   └── server.py
├── tests/
├── .github/workflows/ci.yml
├── .env.example
├── Dockerfile
├── render.yaml
├── pyproject.toml
└── README.md

Лицензия MIT.