# Global Papers MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![FastMCP](https://img.shields.io/badge/FastMCP-0.3.0+-green.svg)](https://github.com/jlowin/fastmcp)
[![Fly.io](https://img.shields.io/badge/Deploy-Fly.io-blueviolet.svg)](https://fly.io)

통합 해외 학술 논문 검색 MCP 서버 - OpenAlex, Semantic Scholar, CrossRef, arXiv API 통합

---

## ⚡ 빠른 시작 (5분)

### 🎯 2가지 배포 방법

#### 방법 1: Railway (가장 쉬움 - 추천!)

**GitHub 푸시만으로 자동 배포!**

1. **GitHub에 푸시**
   ```bash
   cd global-papers-mcp
   git init && git add . && git commit -m "Initial commit"
   git remote add origin https://github.com/YOUR_USERNAME/global-papers-mcp.git
   git push -u origin main
   ```

2. **Railway 연결**
   - https://railway.app 접속
   - **Sign in with GitHub**
   - **New Project** → **Deploy from GitHub repo**
   - `global-papers-mcp` 선택 → **Deploy Now**

3. **도메인 확인**
   - Settings → Networking → **Generate Domain**
   - URL 복사: `https://xxx.up.railway.app/mcp`

4. **Claude.ai 연결**
   - Settings → Connectors → Add Connector
   - URL 입력 → 저장

**완료!** 🎉

상세 가이드: **[RAILWAY_DEPLOY.md](RAILWAY_DEPLOY.md)**

---

#### 방법 2: Fly.io (고급 사용자)

**자동 배포 스크립트:**

```bash
# Mac/Linux
./deploy.sh

# Windows
deploy.bat
```

상세 가이드: **[ONE_CLICK_DEPLOY.md](ONE_CLICK_DEPLOY.md)**

---

## 📋 목차

- [빠른 개요](#-빠른-개요)
- [개요](#개요)
- [주요 기능](#주요-기능)
- [설치 및 실행](#설치-및-실행)
  - [로컬 실행](#로컬-실행)
  - [Fly.io 배포](#flyio-배포)
- [Claude MCP 커넥터 등록](#claude-mcp-커넥터-등록)
  - [방법 1: Claude.ai 웹/모바일 (추천)](#-방법-1-claudeai-웹모바일-추천)
  - [방법 2: Claude Desktop 앱](#-방법-2-claude-desktop-앱)
  - [연결 확인 및 테스트](#-연결-확인-및-테스트)
  - [문제 해결](#-문제-해결)
- [API 키 설정](#api-키-설정)
- [사용 예시](#사용-예시)
- [기술 스택](#기술-스택)
- [Rate Limits](#rate-limits)
- [참고 프로젝트](#참고-프로젝트)
- [라이선스](#라이선스)
- [기여](#기여)
- [문의](#문의)

---

## 🎯 빠른 개요

Claude.ai에서 **전 세계 5억+ 학술 논문**을 통합 검색하는 MCP 서버

- 🔍 **4개 API 통합** - OpenAlex, Semantic Scholar, CrossRef, arXiv
- 🛠 **13개 도구** - 검색, 상세 조회, 인용 추적, 저자/기관 정보
- 🚀 **5분 배포** - Fly.io Tokyo 리전으로 빠른 응답
- 📚 **완벽한 문서화** - 11개 가이드 문서 제공
- ✅ **API 키 대부분 불필요** - OpenAlex, CrossRef, arXiv는 즉시 사용

## 개요

Claude.ai에서 해외 학술 논문을 검색하고 분석할 수 있는 MCP (Model Context Protocol) 서버입니다.
4개의 주요 학술 API를 통합하여 포괄적인 논문 검색 기능을 제공합니다.

### 지원 API

1. **OpenAlex** - 전 분야 2억 5천만+ 논문
2. **Semantic Scholar** - AI/ML 특화 2억+ 논문
3. **CrossRef** - DOI 기반 1억 5천만+ 메타데이터
4. **arXiv** - 물리/수학/CS 프리프린트 240만+

## 주요 기능

### OpenAlex Tools (4개)
- `openalex_search_papers` - 논문 검색
- `openalex_get_paper_detail` - 논문 상세 정보
- `openalex_get_author` - 저자 정보 조회
- `openalex_search_institutions` - 기관 검색

### Semantic Scholar Tools (4개)
- `semantic_search_papers` - 논문 검색
- `semantic_get_paper_detail` - 논문 상세 정보
- `semantic_get_citations` - 인용 논문 조회
- `semantic_get_references` - 참고문헌 조회

### CrossRef Tools (3개)
- `crossref_search_works` - 논문 검색
- `crossref_get_work_by_doi` - DOI로 논문 조회
- `crossref_search_journals` - 저널 검색

### arXiv Tools (2개)
- `arxiv_search_papers` - 논문 검색
- `arxiv_get_paper_detail` - 논문 상세 정보

## 설치 및 실행

### 로컬 실행

```bash
# 1. 저장소 클론
git clone https://github.com/YOUR_USERNAME/global-papers-mcp.git
cd global-papers-mcp

# 2. 의존성 설치
pip install -r requirements.txt

# 3. 환경 변수 설정 (선택)
cp .env.example .env
# .env 파일에서 SEMANTIC_SCHOLAR_API_KEY 설정 (선택사항)

# 4. 로컬 테스트 실행
python server.py
```

### Fly.io 배포

```bash
# 1. Fly.io CLI 설치
curl -L https://fly.io/install.sh | sh

# 2. Fly.io 로그인
flyctl auth login

# 3. 앱 생성 (도쿄 리전 사용으로 latency 최소화)
flyctl launch --no-deploy

# 4. 리전을 Tokyo(nrt)로 변경
flyctl regions set nrt

# 5. 배포
flyctl deploy

# 6. API 키 설정 (Semantic Scholar 사용 시)
flyctl secrets set SEMANTIC_SCHOLAR_API_KEY=your_api_key_here

# 7. MCP URL 확인
flyctl info
# URL 예시: https://global-papers-mcp.fly.dev/mcp
```

## Claude MCP 커넥터 등록

### 🌐 방법 1: Claude.ai 웹/모바일 (추천)

**가장 간단하고 빠른 방법입니다!**

#### 1단계: MCP 서버 배포 및 URL 확인

먼저 Fly.io에 배포를 완료하세요 (위 [Fly.io 배포](#flyio-배포) 참고)

```bash
# 배포 후 MCP URL 확인
flyctl info
```

출력 예시:
```
Hostname = global-papers-mcp.fly.dev
```

**MCP URL**: `https://global-papers-mcp.fly.dev/mcp` (끝에 `/mcp` 필수!)

#### 2단계: Claude.ai 접속

웹 브라우저에서 https://claude.ai 접속 (또는 모바일 앱 실행)

#### 3단계: 설정 메뉴 열기

**웹 (데스크톱):**
- 좌측 하단 프로필 아이콘 (또는 본인 이름) 클릭
- `Settings` (설정) 선택

**모바일 (iOS/Android):**
- 우측 상단 메뉴 버튼 (≡) 탭
- `Settings` (설정) 선택

#### 4단계: 커넥터 메뉴 이동

- `Connectors` 또는 `Integrations` 메뉴 클릭
- 또는 `Features` → `Model Context Protocol` 선택

#### 5단계: 새 커넥터 추가

`Add Connector` 또는 `+ Add` 버튼 클릭

#### 6단계: MCP 정보 입력

다음 정보를 정확히 입력:

| 필드 | 입력 내용 |
|------|-----------|
| **Name** | `Global Papers` (원하는 이름) |
| **URL** | `https://your-app-name.fly.dev/mcp` |

**⚠️ 중요: URL 끝에 반드시 `/mcp` 포함!**

예시:
- ✅ 올바른 URL: `https://global-papers-mcp.fly.dev/mcp`
- ❌ 잘못된 URL: `https://global-papers-mcp.fly.dev`

#### 7단계: 저장 및 연결

- `Connect` 또는 `Save` 버튼 클릭
- 연결 테스트 자동 실행
- "Connected" 또는 "Active" 상태 확인

#### 8단계: 연결 확인 및 테스트

**Connectors 목록에서 확인:**
- Global Papers MCP가 목록에 표시
- 상태: 🟢 Connected

**실제 사용 테스트:**

새 대화를 시작하고 다음 명령어 입력:

```
"OpenAlex에서 machine learning 관련 논문 5개 검색해줘"
```

Claude가 논문 검색 결과를 반환하면 성공! 🎉

---

### 💻 방법 2: Claude Desktop 앱

**로컬 PC에서 Claude Desktop 앱을 사용하는 경우**

### 💻 방법 2: Claude Desktop 앱

**로컬 PC에서 Claude Desktop 앱을 사용하는 경우**

#### Option A: Fly.io 배포 URL 사용 (권장)

1. **설정 파일 위치 찾기**

   운영체제별 경로:
   - **Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
   - **Linux**: `~/.config/claude/claude_desktop_config.json`

2. **설정 파일 열기**

   **Mac/Linux:**
   ```bash
   # 파일이 없으면 생성
   mkdir -p ~/Library/Application\ Support/Claude/
   nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
   ```

   **Windows:**
   ```cmd
   notepad %APPDATA%\Claude\claude_desktop_config.json
   ```

3. **MCP 서버 추가**

   다음 내용을 입력하거나 기존 파일에 추가:

   ```json
   {
     "mcpServers": {
       "global-papers": {
         "url": "https://global-papers-mcp.fly.dev/mcp"
       }
     }
   }
   ```

   **여러 MCP 서버를 사용하는 경우:**
   ```json
   {
     "mcpServers": {
       "global-papers": {
         "url": "https://global-papers-mcp.fly.dev/mcp"
       },
       "kci-papers": {
         "url": "https://kci-mcp-korea.fly.dev/mcp"
       }
     }
   }
   ```

4. **파일 저장 및 Claude Desktop 재시작**

   - 설정 파일 저장 (Ctrl+S 또는 Cmd+S)
   - Claude Desktop 앱 완전히 종료
   - Claude Desktop 다시 실행

5. **연결 확인**

   Claude Desktop에서 새 대화 시작 후:
   ```
   "사용 가능한 도구를 보여줘"
   ```

   Global Papers MCP 도구들이 표시되면 성공!

---

#### Option B: 로컬 서버 실행

**Fly.io 없이 로컬에서만 실행하는 경우**

1. **로컬 서버 실행 준비**

   ```bash
   cd /path/to/global-papers-mcp
   pip install -r requirements.txt
   ```

2. **설정 파일 수정**

   `claude_desktop_config.json`:
   ```json
   {
     "mcpServers": {
       "global-papers": {
         "command": "python",
         "args": ["/absolute/path/to/global-papers-mcp/server.py"]
       }
     }
   }
   ```

   **⚠️ 주의:**
   - 경로는 반드시 **절대 경로**로 입력
   - Windows: `C:\\Users\\YourName\\global-papers-mcp\\server.py`
   - Mac/Linux: `/Users/YourName/global-papers-mcp/server.py`

3. **Claude Desktop 재시작**

   설정 파일 저장 후 앱 재시작

4. **서버 자동 실행**

   Claude Desktop이 실행될 때 자동으로 로컬 서버가 시작됩니다.

---

### 🔍 연결 확인 및 테스트

#### 연결 상태 확인

**Claude.ai (웹/모바일):**
1. Settings → Connectors
2. Global Papers 상태 확인
   - 🟢 Connected = 정상
   - 🔴 Disconnected = 오류

**Claude Desktop:**
1. 새 대화 시작
2. 다음 명령어 입력:
   ```
   "연결된 MCP 서버를 보여줘"
   ```

#### 기능 테스트

**기본 검색:**
```
"OpenAlex에서 transformer architecture 관련 논문 5개 검색해줘"
```

**DOI 조회:**
```
"CrossRef에서 이 DOI의 논문을 조회해줘: 10.1038/s41586-021-03819-2"
```

**arXiv 검색:**
```
"arXiv에서 cs.AI 카테고리의 최신 논문 10개 보여줘"
```

**인용 관계 추적:**
```
"Semantic Scholar에서 'Attention is All You Need' 논문을 검색하고, 이 논문을 인용한 주요 논문들을 찾아줘"
```

---

### ⚠️ 문제 해결

#### "Connection failed" 오류

**원인 1: URL 오류**
- `/mcp` 엔드포인트 누락
- 해결: URL 끝에 `/mcp` 추가

**원인 2: 서버 미실행**
```bash
# Fly.io 서버 상태 확인
flyctl status

# 서버가 중지되어 있으면
flyctl apps restart
```

**원인 3: 방화벽 차단**
- 회사/학교 네트워크에서 Fly.io 차단 가능
- 해결: 다른 네트워크 시도 또는 IT 부서 문의

#### 도구가 표시되지 않음

**Claude.ai:**
1. 브라우저 새로고침
2. 로그아웃 후 재로그인
3. 다른 브라우저 시도

**Claude Desktop:**
1. 설정 파일 경로 확인
2. JSON 문법 오류 확인 ([JSONLint](https://jsonlint.com)에서 검증)
3. 앱 완전히 종료 후 재시작

#### 느린 응답 속도

**원인: 리전 문제**
```bash
# 현재 리전 확인
flyctl regions list

# Tokyo(nrt) 리전으로 변경
flyctl regions set nrt
flyctl deploy
```

---

### 📚 추가 도움말

- **상세 가이드**: [DEPLOYMENT.md](DEPLOYMENT.md)
- **문제 해결**: [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
- **사용 예시**: [EXAMPLES.md](EXAMPLES.md)
- **FAQ**: [FAQ.md](FAQ.md)

---## API 키 설정

대부분의 API는 키 없이 사용 가능하나, Semantic Scholar는 API 키 사용 시 rate limit이 완화됩니다.

### Semantic Scholar API 키 발급
1. https://www.semanticscholar.org/product/api 방문
2. "Get API Key" 클릭하여 무료 키 발급
3. `.env` 파일 또는 환경 변수에 설정

## 사용 예시

Claude.ai에서 다음과 같이 사용:

```
"transformer 아키텍처 관련 최신 논문을 OpenAlex에서 검색해줘"

"이 DOI의 논문을 CrossRef에서 조회해줘: 10.1038/nature12345"

"arXiv에서 quantum computing 관련 최신 프리프린트 찾아줘"

"Semantic Scholar에서 이 논문을 인용한 논문들을 찾아줘"
```

## 기술 스택

- **FastMCP** - MCP 서버 프레임워크
- **httpx** - 비동기 HTTP 클라이언트
- **Python 3.9+**
- **Fly.io** - 배포 플랫폼 (Tokyo 리전)

## Rate Limits

- **OpenAlex**: 100,000 requests/day (API 키 불필요)
- **Semantic Scholar**: API 키 없이 100 requests/5분, API 키 사용 시 완화
- **CrossRef**: polite pool 사용 시 더 빠른 응답
- **arXiv**: 1 request/3초 권장

## 참고 프로젝트

- [kci-mcp-korea](https://github.com/auraweon7-ship-it/kci-mcp) - 한국 학술지인용색인(KCI) MCP 서버

## 라이선스

MIT License

## 기여

이슈 및 PR 환영합니다!

## 문의

- GitHub Issues: https://github.com/YOUR_USERNAME/global-papers-mcp/issues