SemanticScholar_MCP

Детерминированные интерфейсы Model Context Protocol для трёх семейств API Semantic Scholar:

• S2AG — поиск по академическому графу, метаданные, авторы, цитирования и ссылки.

• Recommendations — сервис рекомендаций статей Semantic Scholar.

• Datasets — обнаружение релизов, манифесты наборов данных и инкрементальные обновления наборов данных.

Проект намеренно предоставляет тонкие обёртки над API, а не агентную систему литературного поиска.

Дизайн

Центральное правило:

Один вызов инструмента MCP соответствует одной документированной операции Semantic Scholar.

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

Они не решают, какая литература научно значима.

Например:

Agent
  │
  ├── "Search for paired-pulse TMS papers"
  │         │
  │         ▼
  │       S2AG MCP
  │         │
  │         ▼
  │    Semantic Scholar
  │
  ├── "Recommend papers from these three seed papers"
  │         │
  │         ▼
  │  Recommendations MCP
  │         │
  │         ▼
  │    Semantic Scholar
  │
  └── "Describe the latest S2ORC dataset release"
            │
            ▼
       Datasets MCP
            │
            ▼
       Semantic Scholar

Расширение поиска, научная интерпретация, суммаризация, стратегия обхода графа цитирований и синтез исследования остаются обязанностью агента-потребителя.

Related MCP server: Semantic Scholar MCP Server

Структура репозитория

SemanticScholar_MCP/
├── src/
│   └── semantic_scholar_mcp/
│       ├── common/
│       │   ├── client.py
│       │   ├── errors.py
│       │   ├── models.py
│       │   ├── rate_limit.py
│       │   └── __init__.py
│       ├── datasets/
│       │   ├── server.py
│       │   └── __init__.py
│       ├── recommendations/
│       │   ├── server.py
│       │   └── __init__.py
│       ├── s2ag/
│       │   ├── server.py
│       │   └── __init__.py
│       └── __init__.py
├── tests/
├── AGENTS.md
├── CLAUDE.md
├── pyproject.toml
└── README.md

Требования

• Python 3.11 или новее

• Доступ к интернету для Semantic Scholar

• Необязательный API-ключ Semantic Scholar

В реализации используется текущая линия v2 официального MCP SDK для Python.

Установка

Создайте виртуальное окружение:

py -3.14 -m venv .venv
.\.venv\Scripts\Activate.ps1

Установите пакет в редактируемом режиме с зависимостями для разработки:

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Либо с помощью uv:

uv venv --python 3.14
uv pip install -e ".[dev]"

Python 3.14 не требуется; проект поддерживает Python 3.11 и более новые версии.

После настройки окружения Python-пакета можно дополнительно запустить тесты:

pytest
ruff check .
ruff format --check .

Если вы уже задали SEMANTIC_SCHOLAR_API_KEY как системную переменную окружения (см. следующий раздел, Authentication), вы также можете проверить живую интеграцию:

pytest --run-integration

Примечание: Если вы задали системную переменную окружения со своим API-ключом после запуска любого окна VSCode, вам нужно закрыть все окна VSCode, чтобы полностью перезапустить VSCode, прежде чем системное окружение будет перехвачено инструментами, запускаемыми через расширения VSCode!

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

Semantic Scholar поддерживает доступ без аутентификации ко многим операциям API.

Если API-ключ доступен, передайте его процессам MCP через:

$env:SEMANTIC_SCHOLAR_API_KEY = "..."

Не помещайте ключ в:

• .mcp.json;

• .codex/config.toml;

• исходный код;

• фиксируемые в репозитории файлы .env;

• тестовые фикстуры.

Серверы MCP автоматически используют ключ, когда он присутствует.

Операции, требующие аутентификации, должны возвращать явную ошибку, если ключ не настроен.

Примечание (ещё раз): Если вы задали системную переменную окружения со своим API-ключом после запуска любого окна VSCode, вам нужно закрыть все окна VSCode, чтобы полностью перезапустить VSCode, прежде чем системное окружение будет перехвачено инструментами, запускаемыми через расширения VSCode!

Обновления сборки

Скрипты .\rebuild.ps1 и .\version.ps1 предоставляются как утилиты для упрощения обновления версий при пересборке:

rebuild.ps1

Чтобы пересобрать без автоматического увеличения номера patch, явно укажите переключатель:

.\rebuild.ps1 -SkipVersionIncrement

В противном случае .\rebuild.ps1 автоматически увеличивает номер patch непосредственно в pyproject.toml.

version.ps1

Чтобы увеличить <major> | <minor> | <patch> без пересборки:

.\version.ps1 patch -NoRebuild

Чтобы увеличить версию minor, сбросив patch в 0, и пересобрать:

.\version.ps1 minor

Чтобы увеличить версию major, сбросив и minor, и patch в 0, и пересобрать:

.\version.ps1 major

Конфигурация MCP-клиента

Три сервера MCP Semantic Scholar можно настроить либо:

• в рамках проекта, чтобы они были доступны только в конкретном репозитории; либо

• глобально для пользователя, чтобы они были доступны во всех репозиториях.

Серверы:

• s2ag — академический граф Semantic Scholar

• s2_recommendations — API рекомендаций Semantic Scholar

• s2_datasets — API наборов данных Semantic Scholar

В примерах ниже предполагается, что этот репозиторий установлен по пути:

C:\MyRepos\Python\SemanticScholar_MCP

При необходимости скорректируйте путь.

В примерах намеренно вызывается интерпретатор Python из виртуального окружения через python -m ..., а не запускаются сгенерированные консольные лаунчеры semantic-scholar-*.exe напрямую. Это рекомендуется при локальной разработке в Windows, поскольку запуск консольных лаунчеров может помешать pip заменить их при переустановке в редактируемом режиме.

Codex

Codex поддерживает как глобальные для пользователя, так и локальные для проекта файлы config.toml.

Локальная для проекта конфигурация Codex

Создайте или отредактируйте:

<project>/.codex/config.toml

Например:

[mcp_servers.s2ag]
command = 'C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe'
args = ["-m", "semantic_scholar_mcp.s2ag.server"]
startup_timeout_sec = 15
tool_timeout_sec = 120
enabled = true

[mcp_servers.s2_recommendations]
command = 'C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe'
args = ["-m", "semantic_scholar_mcp.recommendations.server"]
startup_timeout_sec = 15
tool_timeout_sec = 120
enabled = true

[mcp_servers.s2_datasets]
command = 'C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe'
args = ["-m", "semantic_scholar_mcp.datasets.server"]
startup_timeout_sec = 15
tool_timeout_sec = 120
enabled = true

Конфигурация Codex в рамках проекта загружается только для проектов, которые Codex считает доверенными.

Глобальная для пользователя конфигурация Codex

Чтобы сделать серверы доступными для Codex во всех проектах, поместите ту же конфигурацию в:

~/.codex/config.toml

В Windows это обычно:

%USERPROFILE%\.codex\config.toml

Например:

C:\Users\<username>\.codex\config.toml

Сами блоки MCP-серверов идентичны примеру для локальной конфигурации проекта выше.

Проверка конфигурации Codex

Из терминала:

codex mcp list

Отдельные регистрации также можно просмотреть с помощью:

codex mcp get s2ag
codex mcp get s2_recommendations
codex mcp get s2_datasets

Claude Code

Claude Code различает MCP-серверы, общие для проекта, и MCP-серверы в области пользователя.

Локальная / общая для проекта конфигурация Claude

Создайте:

<project>/.mcp.json

с содержимым:

{
  "mcpServers": {
    "s2ag": {
      "command": "C:\\MyRepos\\Python\\SemanticScholar_MCP\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "semantic_scholar_mcp.s2ag.server"
      ]
    },
    "s2_recommendations": {
      "command": "C:\\MyRepos\\Python\\SemanticScholar_MCP\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "semantic_scholar_mcp.recommendations.server"
      ]
    },
    "s2_datasets": {
      "command": "C:\\MyRepos\\Python\\SemanticScholar_MCP\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "semantic_scholar_mcp.datasets.server"
      ]
    }
  }
}

Этот файл можно фиксировать в репозитории проекта-потребителя, если конфигурация MCP предназначена для совместного использования с другими пользователями этого репозитория.

Глобальная для пользователя конфигурация Claude

Для глобальной конфигурации Claude Code предпочтительный подход — позволить Claude Code самостоятельно управлять регистрациями MCP в области пользователя.

Выполните:

claude mcp add --scope user s2ag -- "C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe" -m semantic_scholar_mcp.s2ag.server

claude mcp add --scope user s2_recommendations -- "C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe" -m semantic_scholar_mcp.recommendations.server

claude mcp add --scope user s2_datasets -- "C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe" -m semantic_scholar_mcp.datasets.server

Claude Code в настоящее время хранит конфигурацию MCP в области пользователя в:

~/.claude.json

В Windows:

%USERPROFILE%\.claude.json

Использование claude mcp add --scope user предпочтительнее ручного редактирования этого файла, поскольку Claude Code владеет дополнительным состоянием в .claude.json.

Проверьте регистрации с помощью:

claude mcp list

Если конкретная версия Claude Code испытывает проблемы с загрузкой MCP-серверов в области пользователя, конфигурация проекта .mcp.json — самый простой запасной вариант.

API-ключ Semantic Scholar

Многие операции Semantic Scholar могут работать без аутентификации. Операции, требующие API-ключ, используют:

SEMANTIC_SCHOLAR_API_KEY

Не фиксируйте ключ в файле конфигурации MCP.

В Windows его можно сохранить как переменную окружения пользователя:

[Environment]::SetEnvironmentVariable(
    "SEMANTIC_SCHOLAR_API_KEY",
    "YOUR_API_KEY",
    "User"
)

Перезапустите VS Code, Codex, Claude Code или другие MCP-хосты после установки переменной, чтобы вновь запущенные процессы MCP унаследовали её.

Серверы MCP автоматически используют ключ, когда он присутствует, и в противном случае остаются без аутентификации там, где Semantic Scholar разрешает анонимный доступ.

Локально для проекта или глобально для пользователя

Полезное правило:

Для исследовательского репозитория, в котором от агентов явно ожидается выполнение поиска литературы, обычно предпочтительна локальная для проекта конфигурация, поскольку доступный набор исследовательских инструментов путешествует вместе с репозиторием.

Для общего личного доступа к Semantic Scholar из произвольных проектов более удобна глобальная для пользователя конфигурация.

Общее ограничение частоты запросов

Вводный лимит частоты запросов для аутентифицированного доступа Semantic Scholar применяется ко всем конечным точкам API в совокупности, а не независимо к каждому серверу MCP.

Поэтому в этом репозитории используется общий ограничитель:

S2AG MCP ────────────────┐
                         │
Recommendations MCP ─────┼── shared limiter ──> Semantic Scholar
                         │
Datasets MCP ────────────┘

Реализация по умолчанию должна допускать не более примерно одного восходящего запроса в секунду на всех трёх локальных серверах.

Это важно, когда одновременно работают несколько хостов, например:

VS Code / Codex
Claude Code
MCP Inspector
tests

Ограничитель должен координировать эти процессы, а не поддерживать независимые часы в каждом из них.

Поведение повторных попыток

Временные сбои восходящего сервиса могут повторяться с использованием ограниченной экспоненциальной задержки.

Примеры:

• HTTP 429;

• временные ответы 5xx;

• временные сетевые сбои.

Retry-After учитывается, когда он предоставлен.

Обычные клиентские ошибки, такие как недопустимые запросы, отклонённая аутентификация и отсутствующие ресурсы, не повторяются многократно.

Повторные попытки ограничены; MCP никогда не повторяет их бесконечно.

S2AG MCP

Запустите:

semantic-scholar-s2ag

или:

python -m semantic_scholar_mcp.s2ag.server

Первоначальная поверхность API должна включать:

Пагинация остаётся явной.

Запрос цитирований не обходит граф цитирований рекурсивно.

Поиск не выполняет автоматически дополнительные поисковые запросы.

Recommendations MCP

Запустите:

semantic-scholar-recommendations

или:

python -m semantic_scholar_mcp.recommendations.server

Первоначальная поверхность намеренно мала:

Сервер передаёт выбранные вызывающей стороной исходные статьи в Semantic Scholar.

Он не выбирает собственные исходные статьи и не применяет к результатам вторую ранжировку, выполненную LLM.

Пример концептуального рабочего процесса:

positive:
  paper A
  paper B
  paper C

negative:
  paper D

        │
        ▼

recommend_from_examples

        │
        ▼

Semantic Scholar recommendation ranking

Datasets MCP

Запустите:

semantic-scholar-datasets

или:

python -m semantic_scholar_mcp.datasets.server

Первоначальные инструменты:

Datasets MCP намеренно не загружает автоматически целые наборы данных Semantic Scholar.

Некоторые наборы данных Semantic Scholar очень велики. Получение манифеста — подходящая операция MCP; запуск загрузки корпуса объёмом в несколько гигабайт требует явного управляемого пользователем инструментария.

В будущем выделенный CLI может предоставлять такие команды, как:

s2-dataset download ...
s2-dataset update ...
s2-dataset verify ...

не превращая эти операции в неявное поведение MCP.

Детерминизм

Для этого проекта детерминизм означает, что семантика инструментов явна и доступна для проверки.

Инструмент может:

validate input
    ↓
wait for rate limiter
    ↓
make one documented API request
    ↓
retry transient transport failures if necessary
    ↓
normalize response
    ↓
return structured data

Инструмент не должен молча превращаться в:

search
   ↓
search again with different terms
   ↓
fetch every page
   ↓
walk citations
   ↓
request recommendations
   ↓
rank with an LLM
   ↓
summarize papers

Оркестрация более высокого уровня находится за пределами этого репозитория.

Пагинация

Пагинация управляется вызывающей стороной.

Когда Semantic Scholar возвращает токен продолжения, смещение или эквивалентный курсор, MCP возвращает это значение.

Вызывающая сторона может явно запросить другую страницу.

MCP не извлекает автоматически все доступные страницы.

Это защищает и детерминизм, и использование API.

Поля

Там, где Semantic Scholar поддерживает явные поля ответа, инструменты должны запрашивать только те поля, которые нужны вызывающей стороне.

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

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

Ошибки

Состояния восходящего сервиса должны транслироваться в стабильные, понятные ошибки MCP.

Примеры:

authentication_required
rate_limited
not_found
invalid_request
upstream_error
transport_error

Где это полезно, структурированная ошибка может сохранять:

• HTTP-статус;

• возможность повтора;

• количество попыток;

• сообщение об ошибке Semantic Scholar.

Секреты никогда не должны включаться.

Разработка

Запустите модульные тесты:

pytest

Запустите линтер:

ruff check .

Проверьте форматирование:

ruff format --check .

Примените форматирование:

ruff format .

Живые тесты Semantic Scholar помечены отдельно:

pytest --run-integration

Обычные модульные тесты должны имитировать HTTP-взаимодействия и не должны расходовать квоту API Semantic Scholar.

Философия тестирования

Самые важные тесты проверяют точность API.

Для каждого MCP-инструмента тесты должны подтверждать:

input
  ↓
exact expected HTTP operation
  ↓
expected response normalization

Тесты также должны проверять отсутствие скрытого поведения.

Например, один запрос цитирования должен вызывать одну операцию API цитирования — а не автоматически запрашивать последующие страницы или ссылки.

Связь с исследовательскими инструментами

Этот репозиторий должен оставаться предметно-нейтральным.

Например, он может предоставлять:

paper A cites paper B

или:

Semantic Scholar recommends paper C from seeds A and B

но не должен делать вывод:

paper C is the strongest evidence for a particular neuroscience hypothesis

Отдельный исследовательский репозиторий, Research MCP или человек-исследователь может сделать эту интерпретацию.

Такое разделение позволяет слою Semantic Scholar оставаться:

• детерминированным;

• переиспользуемым;

• легко тестируемым;

• независимым от какой-либо конкретной научной области;

• пригодным для использования различными MCP-хостами и агентами.

Использование Semantic Scholar

Этот проект предназначен для законного исследовательского использования и должен соответствовать действующей лицензии и документации API Semantic Scholar.

Использование API должно:

• соблюдать действующие ограничения частоты запросов;

• использовать пакетные/массовые операции, где это уместно;

• запрашивать только нужные поля;

• использовать ограниченную экспоненциальную задержку;

• защищать учётные данные API;

• избегать неограниченного обхода API;

• предпочитать Datasets API, когда действительно требуется доступ в масштабе корпуса.

Публичные продукты или отображения, использующие данные ответов Semantic Scholar, могут требовать дополнительного указания авторства. Ознакомьтесь с текущей лицензией Semantic Scholar, прежде чем добавлять публичную презентацию данных.

О нормативных правилах разработки и использования API для этого репозитория см. в AGENTS.md.