Scopus MCP Server

Сервер MCP, который оборачивает Elsevier Scopus API, чтобы MCP-клиент (Claude Desktop, Claude Code или любой другой MCP-хост) мог искать и получать опубликованные научные статьи — полезно для проверки цитирования и анализа стиля на основе реальных рецензируемых источников.

Tools

Все ответы представляют собой структурированный JSON (см. Форма ответа ниже). Каждый инструмент возвращает понятную структурированную ошибку вместo исключения, когда Scopus API недоступен, превышен лимит запросов или передан неверный ID — см. Обработка ошибок.

Под капотом сервер вызыват два API Elsevier:

• Scopus Search API (GET /content/search/scopus) — использутся search_scopus.

• Abstract Retrieval API (GET /content/abstract/scopus_id/{id}) — использутся get_article_details и get_article_abstract, посколькю Search API не гарантирует надёжный возврат полных аннотаций, числа цитирований или ключевых слов.

Related MCP server: MCP-scopus

Project layout

mcp-server/
├── src/
│   ├── index.ts          # stdio entry point (for local MCP clients)
│   ├── httpServer.ts      # Streamable HTTP entry point (for remote deployment)
│   ├── registerTools.ts   # tool definitions, shared by both entry points
│   ├── scopusClient.ts    # Elsevier API client: requests, normalization, error mapping
│   ├── types.ts           # TypeScript types for raw Scopus responses + normalized output
│   └── logger.ts          # structured logger → stderr + logs/scopus-mcp.log
├── test/
│   └── test-connection.ts # standalone connectivity test (bypasses the MCP protocol)
├── logs/                  # log file written here at runtime (gitignored)
├── .env.example
├── package.json
└── tsconfig.json

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

• Node.js 18 или новее (использует встроенный глобальный fetch). Проверьте с помощью node -v.

• Ключ Scopus API. Зарегистрируйте бесплатный ключ на Elsevier Developer Portal. Обратите вниманиe: Elsevier ограничивает доступ к полным текстам/аннотациям по диапазону IP (институционалная подписка) или Institutional Token — одного ключа достасточно для проверки подключения и базового поиска, но некоторые поля могут быть ограничены в зависимости от ваших прав.

Setup

cd mcp-server
npm install
cp .env.example .env

Отредактируйте .env и укажите свой ключ:

SCOPUS_API_KEY=your_real_key_here

SCOPUS_API_KEY считывается из окружения при запуске (src/scopusClient.ts); он никогда не зашит в коде, а .env находится в .gitignore, чтобы его нельзя было случайно закоммитить.

Переменные окружения

Сначала проверьте подключение

Прежде чем подключать сервер к какому-либо MCP-клиенту, проверьте, что ключ Scopus API и сетевой путь работают:

npm run test:connection

Эта команда запускает test/test-connection.ts, который вызывает те же клиентские функции, что и инструменты, — но напрямую, без протокола MCP, — с примерным запросом "farmland abandonment Nepal". Вы можете передать свой запрос вмест:

npm run test:connection -- "AUTH(Smith J) AND TITLE(remote sensing)"

Он последовательно проходит все три инструмента (поиск → детали → аннотация для первого результата) и печатает ✅/❌ на каждом шаге, плюс полный журнал запросов/ответов в logs/scopus-mcp.log (см. Журналирование). Код возврата равен 0, только если все шаги выполнены успешно.

Запуск локально (stdio, для локального MCP-клиента)

npm run dev     # runs src/index.ts directly via tsx, no build step
# or
npm run build && npm start   # compiles to dist/ then runs the compiled server

Сервер общается через stdio, поэтому при прямом запуске в терминале он просто будет ждать JSON-RPC на stdin — это нормально. Его запускает MCP-клиент.

Подключение к Claude Code

claude mcp add scopus --env SCOPUS_API_KEY=your_real_key_here -- node /absolute/path/to/mcp-server/dist/index.js

(сначала выполните npm run build, чтобы появился dist/index.js), или добавьте его в .mcp.json проекта:

{
  "mcpServers": {
    "scopus": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": { "SCOPUS_API_KEY": "your_real_key_here" }
    }
  }
}

Подключение к Claude Desktop

Добавьте тот же блок в claude_desktop_config.json (%APPDATA%\Claude\claude_desktop_config.json в Windows, ~/Library/Application Support/Claude/claude_desktop_config.json в macOS), затем перезапустите Claude Desktop:

{
  "mcpServers": {
    "scopus": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": { "SCOPUS_API_KEY": "your_real_key_here" }
    }
  }
}

Форма ответа

search_scopus пример (сокращён):

{
  "query": "farmland abandonment Nepal",
  "totalResults": 42,
  "returnedResults": 10,
  "articles": [
    {
      "scopusId": "85123456789",
      "eid": "2-s2.0-85123456789",
      "title": "Drivers of farmland abandonment in the mid-hills of Nepal",
      "authors": ["Sharma B.", "Poudel K."],
      "publicationYear": 2021,
      "sourceTitle": "Land Use Policy",
      "doi": "10.1016/j.landusepol.2021.105123",
      "doiUrl": "https://doi.org/10.1016/j.landusepol.2021.105123",
      "scopusUrl": "https://www.scopus.com/inward/record.uri?...",
      "citedByCount": 17,
      "abstract": null,
      "documentType": "Article"
    }
  ]
}

get_article_details добавляет keywords, subjectAreas, openAccess и aggregationType поверх тех же полей. get_article_abstract возвращат { scopusId, title, abstract, hasAbstract }.

Поля, которых нет в Scopus для данной записи, возвращатся как null (или [] для списковых полей, или hasAbstract: false), а не опускатся — проверяйте null/false, прежде чем считать, что поле отсутствует из-за ошибки.

Обработка ошибок

Каждый инструмент ловит ошибки внутренне и возвращат isError: true со структурированным JSON-телом вместо краша MCP-подключения:

{
  "error": true,
  "kind": "rate_limited",
  "message": "Scopus API rate limit exceeded (HTTP 429) for search_scopus(...). Retry after 30s.",
  "status": 429,
  "retryAfterSeconds": 30
}

kind принимает одно из значений: unauthorized (неверный/отсутствующий ключ API), rate_limited (HTTP 429), not_found (неверный Scopus ID / HTTP 404), bad_request (пустой запрос, некорректные входные данные), network_error (сбой DNS/подключения), timeout (превышен SCOPUS_REQUEST_TIMEOUT_MS) или unknown. Поиск, который выполняется успешно, но ничего не находит, не является ошибкой — он возвращает totalResults: 0 и понятное человеку message с подсказкой, как расширить запрос.

Журналирование

Все вызовы API и ответы журналируются для отладки:

• Каждый запрос журналирует свой URL (ключ API скрыт) перед отправкой.

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

• Журналы идут в stderr в виде однострочного JSON (никогда в stdout — stdout зарезервирован для протокола MCP на stdio-транспорте), а также дописываются в logs/scopus-mcp.log.

• Установите LOG_LEVEL=debug для большей детализации или LOG_LEVEL=error, чтобы уменьшить количество вывода.

Развёртывание на удалённой/серверless-платформе (Render, Railway и др.)

Транспорт stdio (src/index.ts) работает только с MCP-клиентами, которые могут запускать локальный процес — по сети к нему обратиться нельзя. Чтобы развернуть этот сервер удалённо, используйте вместo входную точку Streamable HTTP: src/httpServer.ts. Она обслуживает те же три инструмента на POST /mcp и добавляет GET /healthz эндпоинт для проверок здоровья платформы.

Ни Render, ни Railway не являются по-настоящему "serverless" (нет масштабирования до нуля и холодных стартов посреди запроса) — оба запускают это как обычный постоянный процес Node, что и нужно такому протоколу с состоянием, как MCP. Считайте "serverless-платформу" здесь "управляемым хостингом Node".

Render

1. Запуштите этот репозиторий (или только папку mcp-server/) на GitHub.

2. В панели Render: New → Web Service, подключите репозиторий, установите root directory в mcp-server, если это подпапка более крупного репозитория.

3. Build command: npm install && npm run build

4. Start command: npm run start:http

5. В разделе Environment добавьте:

   • SCOPUS_API_KEY = ваш ключ (пометь его как секрет)

   • MCP_HTTP_AUTH_TOKEN = длинная случайная строка, которую вы генерируете (например, openssl rand -hex 32)

   • по желанию MCP_ALLOWED_HOSTS = имя вашего хоста Render, например scopus-mcp.onrender.com

6. Render установит PORT авотомотически — httpServer.ts читает его, никаких действй не нужно.

7. Разверните. Путь для проверки здоровя: /healthz.

Railway

1. New Project → Deploy from GitHub repo, при необходимости укажите корневой католог сервиса mcp-server.

2. Railway авотомотически определяет Node; если он не запускает нужную команду, укажите:

   • Build command: npm install && npm run build

   • Start command: npm run start:http

3. В Variables добавьте SCOPUS_API_KEY и MCP_HTTP_AUTH_TOKEN, как выше.

4. Railway авотомотически внедряет PORT.

5. После развёртывания ваш MCP-эндпоинт: https://<your-app>.up.railway.app/mcp.

Подключение MCP-клиента к развернутом серверу

claude mcp add --transport http scopus https://<your-app>/mcp \
  --header "Authorization: Bearer <your MCP_HTTP_AUTH_TOKEN>"

Заметки по безопасности для HTTP-развёртывания

• Всегда устанавливайте MCP_HTTP_AUTH_TOKEN. Без него любой, у кого есть URL, сможет вызывать ваши инструменты и расходовать квоту Scopus API — сервер журналирует предупреждение при запуске, если он не установлен.

• Сервер авотомотически включатет защиту от DNS-rebinding для localhost/127.0.0.1; для настоящего 0.0.0.0 развёртывания укажите MCP_ALLOWED_HOSTS = имя хоста вашей платформы.

• Ротируйте SCOPUS_API_KEY и MCP_HTTP_AUTH_TOKEN через менеджер секретов платформы, никогда не коммитя их в репозиторий.

• Рассмотрите возможность разместить перед сервисом собственный лимит запросов платформы / обратный прокси для публичных развёртываний, в дополнение к собственным лимитам Elsevier на ключ.

Устранение неполадок

Лицензия

MIT