# korea-academic-mcp

국내 학술 데이터베이스 **KCI · DBpia · RISS**를 각 기관의 **공식 Open API**로 검색하는 MCP 서버입니다.
Smithery 툴박스에 얹으면 게이트웨이 URL(`mcp.smithery.run/<계정>`)을 통해 Claude에서
Google Scholar처럼 국내 논문이 자동 검색됩니다.

제공 도구:

| 도구 | 대상 | 상태 |
|---|---|---|
| `dbpia_search` | DBpia | 정식 스펙 반영 — 키만 넣으면 동작 |
| `kci_search` | KCI (한국학술지인용색인) | 표준 구조 구현 — 엔드포인트/파라미터 설정 가능 |
| `riss_search` | RISS (학술연구정보서비스) | 승인 엔드포인트 설정 필요 |

> ⚠️ **스크래핑 없음.** 세 도구 모두 공식 REST API만 호출합니다. 원문 다운로드·상업적
> 재배포는 각 기관 약관/구독 범위를 따르세요. 이 서버는 검색·서지 메타데이터 용도입니다.

---

## 0. 사전 준비 — API 키 발급 (본인이 직접)

| 소스 | 발급처 | 비고 |
|---|---|---|
| DBpia | https://api.dbpia.co.kr | 가입 → 검색 API 신청 → 약관 동의 |
| KCI | https://open.kci.go.kr 또는 공공데이터포털(한국연구재단 KCI 논문정보서비스) | 활용신청 → 인증키 |
| RISS | https://www.riss.kr/openAPI | KERIS 승인 필요(기관 단위인 경우 많음) |

키 발급은 계정 인증이 걸린 작업이라 **반드시 본인이** 하셔야 합니다.

---

## 1. 로컬 테스트 (선택)

```bash
npm install
cp .env.example .env      # 키 입력
npm run dev               # smithery dev — 로컬에서 도구 호출 테스트
```

빌드 없이 타입만 확인하려면:

```bash
npm run typecheck
```

---

## 2. Smithery 배포 (GitHub 연결형)

`runtime: typescript` 서버는 GitHub 저장소를 Smithery가 빌드·호스팅합니다.

1. 이 폴더를 **GitHub 저장소로 push** (예: `qvism9/korea-academic-mcp`)
2. https://smithery.ai/new 접속 → **Deploy / Continue with GitHub**
3. 저장소 선택 → Smithery가 `smithery.yaml`(`runtime: typescript`)을 읽어 자동 빌드
4. 배포 완료 시 `@qvism9/korea-academic` 형태의 서버가 생성됨

배포 시 요구되는 파일은 이미 다 들어 있습니다:
- `smithery.yaml` → `runtime: typescript`
- `package.json` → `"module": "./src/index.ts"`, `"type": "module"`
- `src/index.ts` → `export const configSchema` + `export default createServer({ config })`

---

## 3. 설정값(config) 입력

Smithery 서버 페이지의 **Config** 화면(또는 툴박스 연결 시)에서 키를 넣습니다.
Claude가 세션마다 이 config를 서버로 주입합니다.

| config 키 | 필수 | 설명 |
|---|---|---|
| `dbpiaKey` | DBpia 사용 시 | DBpia API 키 |
| `kciKey` | KCI 사용 시 | KCI 인증키 |
| `rissKey` | RISS 사용 시 | RISS 키 |
| `kciEndpoint` | 선택 | 기본 `https://open.kci.go.kr/po/openapi/openApiSearch.kci` |
| `kciApiCode` | 선택 | 기본 `articleSearch` |
| `kciQueryParam` | 선택 | 기본 `title` (명세가 `keyword` 등이면 교체) |
| `rissEndpoint` | RISS 사용 시 | 승인받은 RISS 검색 URL |
| `rissQueryParam` | 선택 | 기본 `query` |

> **KCI/RISS 튜닝 포인트:** 키 발급 후 받는 **명세서(Open API 규격)**에 적힌
> 엔드포인트·파라미터명이 위 기본값과 다르면, 코드 수정 없이 config 값만 맞추면 됩니다.
> `kci_search` 결과가 0건이면 대개 `kciQueryParam`/`kciApiCode` 불일치가 원인입니다.

---

## 4. 툴박스에 추가 → Claude에서 사용

1. Smithery 대시보드에서 배포된 `korea-academic` 서버를 **본인 툴박스(qvism9)에 Add**
2. 게이트웨이 URL(`mcp.smithery.run/qvism9`)이 자동 반영
3. Claude 세션에서 커넥터를 새로고침(또는 토글 OFF→ON)하면
   `dbpia_search` · `kci_search` · `riss_search`가 나타남
4. 이제 "디지털 카르텔 국내 논문 찾아줘" → DBpia·KCI·RISS 자동 검색

---

## 파일 구조

```
korea-academic-mcp/
├── smithery.yaml       # runtime: typescript
├── package.json        # module 엔트리 + smithery 스크립트
├── tsconfig.json
├── .env.example        # 로컬 테스트용 키 템플릿
├── .gitignore
├── README.md
└── src/
    └── index.ts        # configSchema + 3개 도구(dbpia/kci/riss)
```