# KCI MCP 서버

[![MCP Compatible](https://img.shields.io/badge/MCP-1.10+-blue)](https://modelcontextprotocol.io)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

**KCI(한국학술지인용색인) Open API 기반 학술 논문 검색·분석 MCP 서버**

한국연구재단의 KCI Open API를 활용하여 국내 학술 논문 검색, 상세 조회, 참고문헌 분석, 인용지수 조회를 Claude AI와 통합합니다.

---

## ✨ 주요 특징

- **7개 도구**: 논문 검색·상세·참고문헌·인용지수·저자검색·키워드검색 완전 지원
- **공식 API 준수**: `open.kci.go.kr` 공식 엔드포인트 및 MetaData XML 구조 사용
- **KCI 5종 API**: articleSearch / articleDetail / referenceSearch / citation / citationDetail
- **STDIO + HTTP**: 로컬(Claude Desktop) 및 원격 배포 모두 지원
- **TypeScript**: 완전한 타입 안전성 및 구조화된 응답

---

## 🚀 설치 및 사용 방법

### 방법 1: Claude.ai 웹에서 바로 사용 (설치 없음, 가장 쉬움)

아무것도 설치하지 않고, 주소 하나만 입력하면 됩니다.  
> ⚠️ **Claude Pro / Max / Team / Enterprise** 요금제 필요 (Free는 커넥터 1개만 가능)

**커넥터 추가 방법:**

1. [claude.ai](https://claude.ai)에 로그인합니다.
2. 왼쪽 사이드바 하단의 **본인 이름**을 클릭합니다.
3. **"설정"** (또는 Settings)을 선택합니다.
4. **"커넥터"** (또는 Connectors) 메뉴로 들어갑니다.
5. **"커스텀 커넥터 추가"** 버튼을 클릭합니다.
6. 아래 내용을 입력합니다:
   - **이름**: `kci-mcp` (원하는 이름 아무거나 OK)
   - **URL**: 아래 주소에서 `YOUR_KCI_API_KEY` 부분을 **본인의 KCI API 인증키**로 바꿔서 입력하세요:

```
https://kci-mcp.fly.dev/mcp?key=YOUR_KCI_API_KEY
```

   > 💡 **KCI API 키 발급**: [KCI 포털](https://www.kci.go.kr/kciportal/main.kci) → 로그인 → Open API 신청  
   > 예시 형식: `https://kci-mcp.fly.dev/mcp?key=<발급받은_KCI_API_키>`

7. **저장** 후 Claude 채팅창으로 돌아가면 즉시 사용 가능합니다.

**사용 예시:**
```
AI 교육 관련 KCI 논문 최근 10건 검색해줘
2024년 KCI 인용지수 상위 20개 학술지 알려줘
```

---

### 방법 2: Claude Desktop에 로컬 설치

#### 사전 준비
- Node.js 18+

#### 설치

```bash
git clone https://github.com/auraweon7-ship-it/kci-mcp.git
cd kci-mcp
npm install
```

#### Claude Desktop 설정

아래 경로의 설정 파일을 엽니다:

| OS | 경로 |
|----|------|
| **Windows** | `%APPDATA%\\Claude\\claude_desktop_config.json` |
| **Mac** | `~/Library/Application Support/Claude/claude_desktop_config.json` |

> 💡 **단축 방법**: Claude Desktop → Settings → Developer → **Edit Config** 클릭

설정 파일에 아래 내용을 추가합니다 (**본인의 KCI API 키**로 교체):

```json
{
  "mcpServers": {
    "kci-mcp": {
      "command": "node",
      "args": ["/절대경로/kci-mcp/dist/index.js"],
      "env": {
        "KCI_API_KEY": "<발급받은_KCI_API_키>"
      }
    }
  }
}
```

> ⚠️ Windows 경로는 역슬래시를 **두 번** 써야 합니다: `C:\\Users\\사용자명\\kci-mcp\\dist\\index.js`

> 💡 **KCI API 키 발급**: [KCI 포털](https://www.kci.go.kr/kciportal/main.kci) → 로그인 → Open API 신청 (무료)

Claude Desktop을 **완전히 재시작**하면 채팅창 하단에 🔨 아이콘이 나타납니다.

---

### 방법 3: Claude Code (터미널, 개발자용)

```bash
# 전역 등록 (모든 프로젝트에서 사용, API 키를 본인 키로 교체)
claude mcp add-json kci-mcp \
  '{"type":"stdio","command":"node","args":["/절대경로/kci-mcp/dist/index.js"],"env":{"KCI_API_KEY":"<발급받은_KCI_API_키>"}}' \
  --scope user
```

또는 프로젝트 루트에 `.mcp.json` 파일 생성:

```json
{
  "mcpServers": {
    "kci-mcp": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "KCI_API_KEY": "<발급받은_KCI_API_키>"
      }
    }
  }
}
```

---

## ✅ 설치 확인

| 클라이언트 | 확인 방법 |
|---|---|
| **claude.ai 웹** | 채팅창 하단 `+` → Connectors에서 kci-mcp 활성 상태 확인 |
| **Claude Desktop** | 입력창 하단 🔨 아이콘 클릭 → 도구 목록에 `kci_search_articles` 등 7개 표시 |
| **Claude Code** | 터미널에서 `claude mcp list` 실행 |

---

## 🛠️ 도구 목록 (7개)

| 도구 | 설명 | 주요 파라미터 |
|------|------|--------------|
| `kci_search_articles` | 논문 기본 검색 | title, author, journal, keyword, dateFrom, dateTo |
| `kci_article_detail` | 논문 상세 조회 | id (ART번호) |
| `kci_search_references` | 참고문헌 검색 | title, author, pubiYr |
| `kci_get_citations` | 인용지수 목록 | year, years (2-5) |
| `kci_citation_detail` | 학술지 IF 상세 | id (SER번호) |
| `kci_search_by_author` | 저자별 논문 검색 | author, affiliation, dateFrom, dateTo |
| `kci_search_by_keyword` | 키워드 논문 검색 | keyword, journal, dateFrom, dateTo |

---

## 💬 사용 예시 프롬프트

```
# 논문 검색
AI 교육 관련 논문 최근 10건 검색해줘

# 저자 검색
홍길동 교수 논문 목록 찾아줘

# 키워드 검색
딥러닝 키워드 논문 2022년 이후로 검색해줘

# 인용지수 조회
2024년 KCI 인용지수 상위 20개 학술지 알려줘

# 논문 상세 조회 (검색 결과의 articleId 사용)
ART002358582 논문 상세 정보 보여줘
```

---

## 🔧 직접 실행 (HTTP 서버 모드)

```bash
# HTTP 모드로 실행 (원격 배포용)
KCI_API_KEY=<발급받은_KCI_API_키> node dist/index.js --http
# → http://localhost:3001/mcp
# → http://localhost:3001/health
```

---

## 📋 환경변수

| 변수 | 필수 | 기본값 | 설명 |
|------|------|--------|------|
| `KCI_API_KEY` | **O** | *(직접 입력 필수)* | KCI Open API 인증키 — [발급](https://www.kci.go.kr/kciportal/main.kci) |
| `PORT` | X | `3001` | HTTP 서버 포트 |
| `CORS_ORIGIN` | X | `*` | CORS 허용 오리진 |
| `TRANSPORT` | X | `stdio` | `http` 또는 `stdio` |

---

## 📚 KCI Open API 정보

| 항목 | 값 |
|------|-----|
| 공식 엔드포인트 | `https://open.kci.go.kr/po/openapi/openApiSearch.kci` |
| 응답 형식 | XML (UTF-8, MetaData 루트) |
| API 종류 | articleSearch / articleDetail / referenceSearch / citation / citationDetail |
| KCI 포털 | https://www.kci.go.kr/kciportal/main.kci |

---

## 🐳 Docker 배포

```bash
docker build -t kci-mcp .
docker run -e KCI_API_KEY=<발급받은_KCI_API_키> -p 3001:3001 kci-mcp
```

---

## 📄 라이선스

MIT

---

## 👤 만든 사람

<table>
  <tr>
    <td>

**박정원 | 朴正元 | Park Jeong Weon**

🏫 한국외국어대학교 중국학대학 중국언어문화학부  
&nbsp;&nbsp;&nbsp;&nbsp;Division of Chinese Language, Literature and Culture  
&nbsp;&nbsp;&nbsp;&nbsp;Hankuk University of Foreign Studies

🏛️ 국가교육위원회 AI특별위원회 위원  
📋 교육부 AI인재양성추진단

🌐 K-AI 교육네트워크: [https://k-ai.it.kr/](https://k-ai.it.kr/)  
📧 auraweon7@gmail.com  
📱 APP: [kletter.kr](https://kletter.kr) / [kteacher.kr](https://kteacher.kr)

  </td>
  </tr>
</table>