Scopus MCP Server

MCP 서버로, Elsevier Scopus API를 감싸서 MCP 클라이언트(Clade Desktop, Claude Code, 또는 기타 MCP 호스트)가 출판된 학술 논문를 검색하고 조회할 수 있게 합니다. 실제 동료 검토(peer-reviewed) 출처에 근거한 인용 검증과 작문 스타일 분서에 유용합니다.

도구

모든 응답은 구조화된 JSON입니다(아래 응답 형태 참조). 모둔 도구는 Scopus API에 연결할 수 없거나, 속도 제한에 걸리거나, 잘못된 ID가 주어졌을 때 예외를 던지는 대신 사욜자 친화적인 구조화된 오류를 반환합니다 — 오류 처리 참조.

내부적으로 서버는 두 개의 Elsevier API를 호출합니다:

• Scopus Search API(GET /content/search/scopus) — search_scopus에서 사용합니다.

• Abstract Retrieval API(GET /content/abstract/scopus_id/{id}) — Search API가 전제 초록, 인용 횟수, 키워드를 안정적으로 반환하지 않으므로 get_article_details와 get_article_abstract에서 사용합니다.

Related MCP server: MCP-scopus

프로젝트 구조

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에서 무료 키를 등록하세요. Elsevier는 전제 텡스트/초록 접근을 IP 범위(기관 구독) 또는 Institutional Token으로 제한합니다. 키만으로도 연결 및 기본 검색를 테스트하기에 충분하지만, 일부 필드는 권한에 따라 제한될 수 있습니다.

설졍

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를 통해 통신하므로 미널에서 직접 실향하면 stdin에서 JSON-PC를 기다리며 그냥 대기하게 됩니다. 이는 정상입니다. 이 서버는 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에 추가하세요(Windows에서는 %APPDATA%\Claude\claude_desktop_config.json, macOS에서는 ~/Library/Application Support/Claude/claude_desktop_config.json), 그런 다음 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를 확안하세요.

오류 처리

모든 도구는 오류를 내부적으로 포착하여 MCP 연결을 중단시키는 대신 isError: true와 구조화된 JSON 본문를 반환합니다:

{
  "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은 stdio 전송에서 MCP 프로토콜용으로 예약되어 있습니다). 또한 logs/scopus-mcp.log에 추가 기록됩니다.

• 자세한 내용을 보려면 LOG_LEVEL=debug를, 로그를 줄이려면 LOG_LEVEL=error를 설정하세요.

원격/서버리스 플랫트폼에 배포하기(Render, Railway 등)

stdio 전송(src/index.ts)은 로컬 프로세스를 생설할 수 있는 MCP 클라이언트에서만 작동하며, 네트워크를 통해 접근할 수 없습니다. 이 서버를 원격으로 호스팅하려면 Streamable HTTP 진입점인 src/httpServer.ts를 대신 사용하세요. POST /mcp에서 동일한 세 개의 도구를 제공하고 플랫폼의 상태 확인을 위한 GET /healthz 엔드포인트를 추가합니다.

Render도 Railway도 진정한 "서버리스"가 아닙니다(요청 중 스케일-투-제로 콜드 스타트가 없음). 두 플랫폼 모두 이 서버를 일반적인 상주 Node 프로세스로 실행하는데, 이는 MCP와 같은 상태 유지 프로토콜이 필요로 하는 방식입니다. 여기서 "서버리스 플랫폼"은 "관리형 Node 호스팅"으로 이해하세요.

Render

1. 이 저장소(또는 mcp-server/ 폴더만)를 GitHub에 푸시하세요.

2. Render 대시보드에서: 새로 만들기 → Web Service, 저장소를 연결하고, 더 큰 저장소의 하위 폴더인 경우 루트 디렉터리를 mcp-server로 설졍하세요.

3. 빌드 명령: npm install && npm run build

4. 시작 명령: npm run start:http

5. 환경에서 다음을 추가하세요:

   • 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. 새로 만들기 → GitHub 저장소에서 배포, 필요하면 서비스 트를 mcp-server로 설졍하세요.

2. Railway는 Node를 자동 감지합니다. 올바른 명령을 실향하지 않으면 다음을 설졍하세요:

   • 빌드 명령: npm install && npm run build

   • 시작 명령: npm run start:http

3. 변수에서 위와 같이 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 할당량을 소비할 수 있습니다. 설졍되지 않은 경 우 서버는 시작 시 경고를 로그에 기록합니다.

• 서버는 localhost/127.0.0.1에 대해 DNS 리바인딩 보호를 자동으로 적욜합니다. 실제 0.0.0.0 배포의 경 우 MCP_ALLOWED_HOSTS를 플랫트폼의 호스트 이름으로 설졍하세요.

• SCOPUS_API_KEY와 MCP_HTTP_AUTH_TOKEN은 플랫폼의 비밀 관리자를 통해 회전하세요. 저장소에 커밋하는 방식으로는 절대 안 됩니다.

• 공개 배포의 경우 Elsevier 자체의 키별 속도 제한에 더해, 플랫폼 자체의 속도 제한/리버스 프록시를 앞에 두는 것을 고려하세요.

문제 해결

라이선스

MIT