<p align="center">
  <h1 align="center">lecture-assistant-mcp</h1>
  <p align="center">
    <strong>YouTube 자막 + Wikipedia + arXiv. API 키 0개. 바로 사용.</strong>
  </p>
</p>

<p align="center">
  <a href="#"><img src="https://img.shields.io/badge/Python-3.10%2B-blue?logo=python&logoColor=white" alt="Python 3.10+"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green" alt="MIT License"></a>
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Compatible-purple?logo=anthropic&logoColor=white" alt="MCP"></a>
  <a href="https://github.com/wjddusrb03/lecture-assistant-mcp"><img src="https://img.shields.io/github/stars/wjddusrb03/lecture-assistant-mcp?style=social" alt="GitHub Stars"></a>
</p>

---

**YouTube 자막 추출 + Wikipedia 개념 설명 + arXiv 논문 검색**을 하나의 학습 파이프라인으로 결합한 MCP 서버입니다. **API 키가 전혀 필요 없습니다.** 유튜브 강의 URL 하나만 주면 자막 정리, 핵심 개념 위키 설명, 관련 논문까지 종합 학습 노트를 생성합니다.

## 왜 만들었나

유튜브 강의를 볼 때 매번 반복하는 작업이 있습니다:

1. 영상 자막 확인하며 내용 정리
2. 모르는 개념 위키피디아에서 검색
3. 더 깊이 공부하고 싶을 때 논문 찾기
4. 영어 개념을 한국어로 확인

탭 3개, 사이트 3개, 반복되는 복붙. **lecture-assistant-mcp**는 이 모든 걸 한 번의 도구 호출로 끝냅니다. 설치하면 **바로 사용 가능** — API 키 설정이 전혀 없습니다.

## 데모: `study_video` 실행 결과

> **나:** "이 강의 영상 학습 노트 만들어줘" (URL 첨부)

> **Claude**가 `study_video(url="https://www.youtube.com/watch?v=aircAruvnKk")`을 호출하면:

```
# Lecture Study Note

Generated: 2026-03-21 15:30

---

## 1. Video Info

  Title: But what is a neural network? | Chapter 1, Deep learning
  Channel: 3Blue1Brown
  URL: https://www.youtube.com/watch?v=aircAruvnKk

---

## 2. Transcript Summary

  Language: en (auto-generated)
  Total segments: 245

  [00:00] What is a neural network? Let's start with handwritten digit
  recognition. You have the digits 0 through 9, and the goal is to build
  a system that can learn to classify them...

  [05:00] Each neuron holds a number called its activation. The network
  has layers - an input layer, hidden layers, and an output layer...

  [10:00] The weights determine how one layer influences the next.
  Each connection has a weight, and each neuron has a bias...

  [15:00] The sigmoid function squishes values into a range between
  0 and 1, giving us a smooth activation function...

---

## 3. Key Concepts (Wikipedia)

  1. **Neural network**
     A neural network is a group of interconnected units called neurons
     that send signals to each other...
     Link: https://en.wikipedia.org/wiki/Neural_network

  2. **Deep learning**
     Deep learning is a subset of machine learning that uses neural
     networks with many layers...
     Link: https://en.wikipedia.org/wiki/Deep_learning

  3. **Backpropagation**
     In machine learning, backpropagation is a gradient estimation
     method used to train neural networks...
     Link: https://en.wikipedia.org/wiki/Backpropagation

---

## 4. Related Papers (arXiv)

  1. **Deep Learning**
     Yann LeCun, Yoshua Bengio et al. (2015-05-27)
     PDF: http://arxiv.org/pdf/1521.00561v1

  2. **A Survey of Deep Learning Techniques**
     Pouyanfar et al. (2019-01-15)
     PDF: http://arxiv.org/pdf/1901.05639v1

---

*Study note generated by lecture-assistant-mcp*
```

유튜브 URL 하나로 자막, 개념 설명, 관련 논문까지 전부 완료.

## 핵심 특징

- **API 키 0개** — 설치하면 바로 사용. 키 발급, .env 설정 전혀 없음
- **YouTube 자막 추출** — 수동 자막 + 자동 생성 자막 모두 지원
- **Wikipedia 개념 연결** — 강의 내용에서 핵심 개념 자동 검색 + 요약
- **arXiv 논문 연결** — 관련 학술 논문 자동 검색
- **다국어 지원** — 한국어/영어 자막, 한국어/영어 위키피디아

## 기능 목록

| 도구 | 설명 |
|------|------|
| `study_video` | **핵심 기능.** YouTube URL → 자막 + 개념 + 논문을 종합 학습 노트로 생성 |
| `get_transcript` | YouTube 영상 자막 추출 (언어 선택 가능) |
| `search_wikipedia` | Wikipedia 문서 검색 (한국어/영어 등) |
| `get_wiki_summary` | 특정 Wikipedia 문서의 요약 가져오기 |
| `search_lectures` | arXiv에서 관련 학술 논문 검색 |
| `translate_text` | Wikipedia 다국어 연결로 용어 번역 (영어 ↔ 한국어) |
| `api_status` | API 상태 확인 |

## 설치 방법

### 자동 설치 (권장)

```bash
git clone https://github.com/wjddusrb03/lecture-assistant-mcp.git
cd lecture-assistant-mcp
pip install -r requirements.txt
python setup_wizard.py
```

설치 마법사가 자동으로:
1. Claude Desktop 설정 파일을 찾고
2. MCP 서버를 등록하고
3. 기존 설정을 백업합니다

API 키 설정 단계가 없습니다. 설치 후 Claude Desktop을 재시작하면 바로 사용할 수 있습니다.

### 수동 설치

**1. 의존성 설치**

```bash
git clone https://github.com/wjddusrb03/lecture-assistant-mcp.git
cd lecture-assistant-mcp
pip install -r requirements.txt
```

**2. Claude Desktop 설정에 추가**

Claude Desktop 설정 파일을 엽니다:

- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux:** `~/.config/claude/claude_desktop_config.json`

`mcpServers` 항목에 다음을 추가합니다:

```json
{
  "mcpServers": {
    "lecture-assistant": {
      "command": "python",
      "args": ["/전체/경로/lecture-assistant-mcp/server.py"]
    }
  }
}
```

Claude Desktop을 재시작합니다.

## API 구성

| API | 키 필요 | 제공 기능 |
|-----|---------|-----------|
| YouTube Transcript | 불필요 | 영상 자막 추출 (수동 + 자동생성) |
| Wikipedia | 불필요 | 개념 검색, 요약, 다국어 연결 |
| arXiv | 불필요 | 관련 학술 논문 검색 |

모든 API가 무료이며 키 발급이 필요 없습니다.

## 도구 상세 레퍼런스

### `study_video`

핵심 도구입니다. YouTube URL 하나로 종합 학습 노트를 생성합니다.

| 파라미터 | 타입 | 기본값 | 설명 |
|---------|------|--------|------|
| `url` | string | *(필수)* | YouTube 영상 URL 또는 영상 ID |
| `language` | string | `""` | 자막 언어 코드 (비어있으면 자동 감지) |

### `get_transcript`

| 파라미터 | 타입 | 기본값 | 설명 |
|---------|------|--------|------|
| `url` | string | *(필수)* | YouTube 영상 URL 또는 영상 ID |
| `language` | string | `""` | 자막 언어 코드 (비어있으면 ko, en 순서로 시도) |

### `search_wikipedia`

| 파라미터 | 타입 | 기본값 | 설명 |
|---------|------|--------|------|
| `query` | string | *(필수)* | 검색 키워드 |
| `lang` | string | `"en"` | 언어 코드 (`en`, `ko`, `ja` 등) |
| `count` | int | `5` | 결과 수 |

### `get_wiki_summary`

| 파라미터 | 타입 | 기본값 | 설명 |
|---------|------|--------|------|
| `title` | string | *(필수)* | Wikipedia 문서 제목 (예: `Neural network`) |
| `lang` | string | `"en"` | 언어 코드 |

### `search_lectures`

| 파라미터 | 타입 | 기본값 | 설명 |
|---------|------|--------|------|
| `query` | string | *(필수)* | 검색 키워드 |
| `count` | int | `5` | 결과 수 |

### `translate_text`

| 파라미터 | 타입 | 기본값 | 설명 |
|---------|------|--------|------|
| `term` | string | *(필수)* | 번역할 용어/문서 제목 (예: `Machine learning`) |
| `from_lang` | string | `"en"` | 원본 언어 코드 |
| `to_lang` | string | `"ko"` | 대상 언어 코드 |

## 사용 예시

설치 후 Claude에게 자연스럽게 말하면 됩니다:

**종합 학습 노트:**
> "이 유튜브 강의 학습 노트 만들어줘" (URL 첨부)

**자막 추출:**
> "이 영상 자막 뽑아줘"

**개념 검색:**
> "backpropagation 위키피디아에서 찾아줘"

**개념 요약:**
> "neural network 개념 설명해줘"

**논문 검색:**
> "attention mechanism 관련 논문 찾아줘"

**용어 번역:**
> "machine learning 한국어로 뭐야?"

## 요구사항

- Python 3.10+
- [Claude Desktop](https://claude.ai/download) (MCP 지원)
- API 키: **필요 없음**

### 의존성 패키지

| 패키지 | 버전 | 용도 |
|--------|------|------|
| `mcp` | >= 1.0.0 | MCP SDK (FastMCP 서버 프레임워크) |
| `httpx` | >= 0.27.0 | API 호출용 HTTP 클라이언트 |
| `youtube-transcript-api` | >= 1.0.0 | YouTube 자막 추출 |

## 프로젝트 구조

```
lecture-assistant-mcp/
    server.py           # 7개 도구가 정의된 MCP 서버
    setup_wizard.py     # 대화형 설치 스크립트
    core/
        youtube.py      # YouTube 자막 추출 모듈
        wikipedia.py    # Wikipedia API 클라이언트
        arxiv.py        # arXiv API 클라이언트
    requirements.txt    # Python 의존성
    pyproject.toml      # 패키지 메타데이터
    LICENSE             # MIT 라이선스
```

## 문제 보고 & 피드백

버그를 발견하셨거나 아이디어가 있으신가요? 이슈를 남겨주세요:

- [GitHub Issues](https://github.com/wjddusrb03/lecture-assistant-mcp/issues)

버그 보고 시 아래 내용을 포함해주시면 빠른 해결에 도움이 됩니다:
- 운영체제 (Windows / macOS / Linux)
- Python 버전 (`python --version`)
- 에러 메시지 또는 예상과 다른 동작
- 재현 방법 (가능하면 YouTube URL 포함)

PR(Pull Request)도 환영합니다!

## 라이선스

MIT License. 자세한 내용은 [LICENSE](LICENSE)를 참고하세요.

---

강의 볼 때마다 탭 3개 열지 말고, URL 하나만 주세요. API 키 없이 바로 써보세요.