Scopus MCP Server

Ein MCP-Server, der die Elsevier-Scopus-API kapselt, sodass ein MCP-Client (Claude Desktop, Claude Code oder ein anderer MCP-Host) veröffentlichte akademische Artiel suchen und abrufen kann – nützlich für die Zitationsprüfung und die Analyse des Schreibstils auf der Grundlage echter, peer-reviewter Quellen.

Tools

Alle Antworten sind strukturiertes JSON (siehe Antwortformat unten). Jedes Tool gibt einen verständlichen, strukturierten Fehler zurück, anstatt eine Ausnahme auszulösen, wenn die Scopus-API nicht erreichbar ist, die Rate begrenzt ist oder eine ungültige ID übergeben wurde – siehe Fehlerbehandlung.

Im Hintergrund ruft der Server zwei Elsevier-APIs auf:

• Scopus Search API (GET /content/search/scopus) – wird von search_scopus verwendt.

• Abstract Retrieval API (GET /content/abstract/scopus_id/{id}) – wird von get_article_details und get_article_abstract verwendet, da die Search-API vollständige Abstracts, Zitationszahlen oder Schlüsselwörter nicht zuverlässig zurückgibt.

Related MCP server: MCP-scopus

Projektstruktur

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

Voraussetzungen

• Node.js 18 oder höher (verwendet das eingebaute globale fetch). Prüfen Sie mit node -v.

• Ein Scopus-API-Schlüssel. Registrieren Sie einen kostenlosen Schlüssel im Elsevier Developer Portal. Beachen Sie, dass Elsevier den Zugriff auf Voltexte/Abstracts über IP-Bereiche (institutionelles Abonnement) oder In stitutionstoken beshränkt – ein Schlüssel allein reicht aus, um die Konnektivität und die grundlegende Suche zu testen, aber einige Felder können je nach Ihren Berechtigungen eingschränkt sein.

Einrichtung

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

Bearbeiten Sie .env und setzen Sie Ihren Schlüssel:

SCOPUS_API_KEY=your_real_key_here

SCOPUS_API_KEY wird beim Start aus der Umgebung gelesen (src/scopusClient.ts); er ist niemals festkodiert und .env wird von Git ignoriert, sodass die Datei nicht versehentlich committet werden kann.

Umgebungsvariablen

Zuerst die Konnektivität testen

Bevor Sie den Server in einen MCP-Client einbinden, vergewissern Sie sich, dass der Scopus-API-Schlüssel und der Netzwerkpfad funktioniert:

npm run test:connection

Dies führt test/test-connection.ts aus, das dieselben Client-Funktionen aufruft, die auch die Tools verwenden – aber direkt, ohne das MCP-Protokoll zu sprechen – mit der Beispielabfrage "farmland abandonment Nepal". Sie können stattdessen eine eigene Abfrage übergeben:

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

Es durchläuft alle drei Tools nacheinander (Suche → Details → Abstract für das erste Ergebnis) und gibt pro Schritt ✅/❌ aus, zusätzlich zu einem vollständigen Anfrage-/Antwortprotokoll unter logs/scopus-mcp.log (siehe Protokollierung). Der Exit-Code ist nur dann 0, wenn jeder Schritt erfolgreich war.

Lokales Ausführen (stdio, für einen lokalen MCP-Client)

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

Der Server kommuniziert über stdio. Wenn Sie ihn direkt in einem Terminal ausführen, wartet er lediglich auf JSON-RPC auf stdin – das ist zu erwarten. Er ist dafür gedacht, von einem MCP-Client gestartet zu werden.

Verbindung mit Claude Code herstellen

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

(führen Sie zuerst npm run build aus, damit dist/index.js existiert), oder fügen Sie ihn zur .mcp.json eines Projekts hinzu:

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

Verbindung mit Claude Desktop herstellen

Fügen Sie denselben Block zu claude_desktop_config.json hinzu (%APPDATA%\Claude\claude_desktop_config.json unter Windows, ~/Library/Application Support/Claude/claude_desktop_config.json unter macOS), und starten Sie Claude Desktop neu:

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

Antwortformat

Beispiel für search_scopus (gekürzt):

{
  "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 fügt zusätzlich zu denselben Feldern keywords, subjectAreas, openAccess und aggregationType hinzu. get_article_abstract gibt { scopusId, title, abstract, hasAbstract } zurück.

Felder, die Scopus für einen bestimmten Datensatz nicht hat, werden als null zurückgegeben (oder [] für Listenfelder, oder hasAbstract: false), anstatt ausgelassen zu werden – prüfen Sie auf null/false, bevor Sie annemen, dass ein Feld wegen eines Fehlers fehlt.

Fehlerbehandlung

Jedes Tool fängt Fehler intern ab und gibt isError: true mit einem strukturierten JSON-Body zurück, anstatt die MCP-Verbindung zum Absturz zu bringen:

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

kind ist einer der folgenden Werte: unauthorized (ungültiger/fehlender API-Schlüssel), rate_limited (HTTP 429), not_found (ungültige Scopus-ID / HTTP 404), bad_request (leere Abfrage, fehlerhafte Eingabe), network_error (DNS-/Verbindungsfehler), timeout (SCOPUS_REQUEST_TIMEOUT_MS überschritten) oder unknown. Eine Suche, die erfolgreich ist, aber nichts findet, ist kein Fehler – sie gibt totalResults: 0 und eine menschenlesbare message zurück, die Vorschläge macht, wie die Abfrage erweitert werden kann.

Protokollierung

Alle API-Aufrufe und -Antworten werden zu Debugzwecken protokolliert:

• Jede Anfrage protokolliert ihre URL (API-Schlüssel geschwärzt), bevor sie gesendet wird.

• Jede Antwort protokolliert Statuscode, vergangene Zeit und eine 500-Zeichen-Vorschau des Bodys.

• Protokolle gehen an stderr als einzeiliges JSON (niemals stdout – stdout ist für das MCP-Protokoll auf dem stdio-Transport reserviert) und werden zusätzlich an logs/scopus-mcp.log angehängt.

• Setzen Sie LOG_LEVEL=debug für mehr Details oder LOG_LEVEL=error, um es ruhiger zu machen.

Bereitstellung auf einer Remote-/Serverless-Plattform (Render, Railway usw.)

Der stdio-Transport (src/index.ts) funktioniert nur für MCP-Clienten, die einen lokalen Prozess starten können – er ist über das Netzwerk nicht erreichbar. Um diesen Server remote zu hosten, verwenden Sie stattdessen den Streamable HTTP-Einstiegspunkt: src/httpServer.ts. Er bedient dieselben drei Tools unter POST /mcp und fügt einen GET /healthz-Endpunkt für die Health-Checks der Plattform hinzu.

Weder Render noch Railway ist wirklich "serverless" (keine Scale-to-Zero-Kaltstarts mitten in einer Anfrage) – beide betreiben dies als normalen persistenten Node-Prozess, was ein zustandsbehaftetes Protokoll wie MCP benötigt. Behandeln Sie "serverless Plattform" hier als "verwaltetes Node-Hosting".

Render

1. Pushen Sie dieses Repo (oder nur den Ordner mcp-server/) zu GitHub.

2. Im Render-Dashboard: New → Web Service, verbinden Sie das Repo, setzen Sie root directory auf mcp-server, wenn es ein Unterordner eines größeren Repos ist.

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

4. Start command: npm run start:http

5. Unter Environment fügen Sie hinzu:

   • SCOPUS_API_KEY = Ihr Schlüssel (als Geheimnis markieren)

   • MCP_HTTP_AUTH_TOKEN = eine lange, zufällige Zeichenfolge, die Sie generieren (z. B. openssl rand -hex 32)

   • optional MCP_ALLOWED_HOSTS = Ihr Render-Hostname, z. B. scopus-mcp.onrender.com

6. Render setzt PORT automatisch — httpServer.ts liest ihn, keine Aktion erforderlich.

7. Bereitstellen. Health-Check-Pfad: /healthz.

Railway

1. New Project → Deploy from GitHub repo, setzen Sie den Service-Root auf mcp-server, falls erforderlich.

2. Railway erkennt Node automatisch; falls es nicht den richtigen Befehl ausführt, setzen Sie:

   • Build command: npm install && npm run build

   • Start command: npm run start:http

3. Unter Variables fügen Sie SCOPUS_API_KEY und MCP_HTTP_AUTH_TOKEN wie oben hinzu.

4. Railway injiziert PORT automatisch.

5. Nach der Bereitstellung ist Ihr MCP-Endpunkt https://<your-app>.up.railway.app/mcp.

Verbinden eines MCP-Clients mit dem gehosteten Server

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

Sicherheitshinweise für die HTTP-Bereitstellung

• Setzen Sie MCP_HTTP_AUTH_TOKEN immer. Ohne ihn kann jeder mit der URL Ihre Tools aufrufen und Ihr Scopus-API-Kontingent verbrauchen – der Server protokolliert eine Startwarnung, falls er nicht gesetzt ist.

• Der Server bindet DNS-Rebinding-Schutz automatisch für localhost/127.0.0.1; für eine echte 0.0.0.0- Bereitstellung setzen Sie MCP_ALLOWED_HOSTS auf den Hostnamen Ihrer Plattform.

• Rotieren Sie SCOPUS_API_KEY und MCP_HTTP_AUTH_TOKEN über den Secret-Manager Ihrer Plattform, niemals durch Committen in das Repo.

• Ziehen Sie in Erwägung, das eigene Rate-Limiting der Plattform / einen Reverse-Proxy für öffentliche Bereitstellungen vorzuschalten, zusätzlich zu den eigenen Pro-Schlüssel-Rate-Limits von Elsevier.

Fehlerbehebung

Lizenz

MIT