# BigKinds MCP Server

한국 뉴스 데이터베이스 [BigKinds](https://www.bigkinds.or.kr)를 위한 MCP(Model Context Protocol) 서버.

Claude Desktop, Claude Code 등 MCP 클라이언트에서 한국 뉴스 검색 및 분석 기능을 사용할 수 있습니다.

## 주요 기능

- **뉴스 검색**: 키워드, 날짜, 언론사, 카테고리 기반 검색
- **기사 스크래핑**: URL에서 전문, 이미지, 메타데이터 추출
- **트렌드 분석**: 오늘의 인기 이슈, 키워드 트렌드
- **LLM 최적화**: 마크다운 변환, 이미지 필터링, 구조화된 컨텍스트

> **상세 가이드**: 모든 도구와 출력 형식에 대한 자세한 설명은 [MCP_GUIDE.md](docs/MCP_GUIDE.md)를 참조하세요.

## 설치

### 방법 1: uvx (권장)

```bash
# 별도 설치 없이 바로 실행
uvx bigkinds-mcp
```

### 방법 2: pip

```bash
pip install bigkinds-mcp
bigkinds-mcp
```

### 방법 3: 소스에서 설치

```bash
git clone https://github.com/seolcoding/bigkinds-mcp.git
cd bigkinds-mcp
uv sync
uv run bigkinds-mcp
```

## MCP 클라이언트 설정

### Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) 또는
`%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "bigkinds": {
      "command": "uvx",
      "args": ["bigkinds-mcp"],
      "env": {
        "BIGKINDS_USER_ID": "your_email@example.com",
        "BIGKINDS_USER_PASSWORD": "your_password"
      }
    }
  }
}
```

> **Note**: `env` 필드는 선택사항입니다. 키워드 트렌드, 연관어 분석 등 로그인 필요 기능 사용 시에만 설정하세요.

### Claude Code

```bash
# 기본 설정 (로그인 불필요 기능만)
claude mcp add bigkinds -- uvx bigkinds-mcp

# 환경변수 포함 (로그인 필요 기능)
claude mcp add bigkinds -- env BIGKINDS_USER_ID=your_email BIGKINDS_USER_PASSWORD=your_password uvx bigkinds-mcp
```

### Cursor / VS Code

`.cursor/mcp.json` 또는 `.vscode/mcp.json`:

```json
{
  "mcpServers": {
    "bigkinds": {
      "command": "uvx",
      "args": ["bigkinds-mcp"],
      "env": {
        "BIGKINDS_USER_ID": "your_email@example.com",
        "BIGKINDS_USER_PASSWORD": "your_password"
      }
    }
  }
}
```

## 사용 가능한 Tools

### search_news
뉴스 기사 검색

```
키워드: AI
기간: 2024-12-01 ~ 2024-12-15
정렬: date | relevance | both (기본값)
```

### get_article_count
기사 수 집계

```
키워드: 반도체
그룹: total | day | week | month
```

### get_article
기사 상세 조회 (news_id로)

### scrape_article_url
URL에서 기사 스크래핑
- 전문 추출
- 이미지 필터링 (광고/로고 제거)
- 마크다운 변환

### get_today_issues
오늘의 인기 이슈 키워드

### get_current_korean_time
현재 한국 시간 (KST)

### find_category
언론사/카테고리 코드 검색

### list_providers
전체 언론사 목록

### list_categories
전체 카테고리 목록

## 사용 가능한 Resources

| URI | 설명 |
|-----|------|
| `stats://providers` | 언론사 코드 목록 |
| `stats://categories` | 카테고리 코드 목록 |
| `news://{keyword}/{date}` | 특정 날짜 뉴스 |
| `article://{news_id}` | 개별 기사 정보 |

## 사용 가능한 Prompts

| Prompt | 설명 |
|--------|------|
| `news_analysis` | 뉴스 분석 (요약/감성/트렌드/비교) |
| `trend_report` | 트렌드 리포트 생성 |
| `issue_briefing` | 일일 이슈 브리핑 |

## 사용 예시

### Claude Desktop에서

```
사용자: AI 관련 최근 뉴스 검색해줘

Claude: [search_news 도구 사용]
2024년 12월 AI 관련 뉴스 9,817건을 찾았습니다.

주요 기사:
1. "OpenAI, GPT-5 개발 착수" - 한국경제
2. "삼성전자 AI 반도체 투자 확대" - 매일경제
...
```

```
사용자: 이 기사 전문 보여줘

Claude: [scrape_article_url 도구 사용]
# OpenAI, GPT-5 개발 착수

**한국경제 | 2024-12-15**

OpenAI가 차세대 AI 모델 GPT-5 개발에...
```

### 코드에서 직접 사용

```python
from bigkinds_mcp.tools import search, article
from bigkinds_mcp.core.async_client import AsyncBigKindsClient
from bigkinds_mcp.core.async_scraper import AsyncArticleScraper
from bigkinds_mcp.core.cache import MCPCache

# 초기화
client = AsyncBigKindsClient()
scraper = AsyncArticleScraper()
cache = MCPCache()

search.init_search_tools(client, cache)
article.init_article_tools(client, scraper, cache)

# 검색
result = await search.search_news(
    keyword="AI",
    start_date="2024-12-01",
    end_date="2024-12-15",
)

# 스크래핑
scraped = await article.scrape_article_url(
    url="https://n.news.naver.com/article/015/0005079123",
    include_markdown=True,
)
```

## 프로젝트 구조

```
bigkinds/
├── src/bigkinds_mcp/           # MCP 서버
│   ├── server.py               # 엔트리포인트
│   ├── tools/                  # MCP Tools (9개)
│   │   ├── search.py           # 검색 도구
│   │   ├── article.py          # 기사 도구
│   │   └── metadata.py         # 메타데이터 도구
│   ├── resources/              # MCP Resources (4개)
│   ├── prompts/                # MCP Prompts (3개)
│   ├── core/                   # 비동기 클라이언트, 캐시
│   │   ├── async_client.py
│   │   ├── async_scraper.py
│   │   └── cache.py
│   ├── models/                 # Pydantic 스키마
│   └── utils/                  # 유틸리티
│       ├── errors.py           # 에러 처리
│       ├── image_filter.py     # 이미지 필터링
│       └── markdown.py         # 마크다운 변환
├── bigkinds/                   # 기존 클라이언트 (레거시)
├── tests/                      # 테스트
│   ├── unit/                   # 단위 테스트
│   └── e2e/                    # E2E 테스트
└── docs/                       # 문서
```

## 테스트

```bash
# 단위 테스트
uv run pytest tests/unit/ -v

# 통합 테스트 (실제 API 호출)
uv run pytest tests/test_tools.py -v

# E2E 테스트
uv run pytest tests/e2e/ -v -m e2e

# 전체 테스트
uv run pytest
```

## 개발

```bash
# 개발 모드로 서버 실행
uv run bigkinds-mcp

# 린트
uv run ruff check .

# 포맷
uv run ruff format .
```

## 관련 링크

- [PyPI Package](https://pypi.org/project/bigkinds-mcp/) - `uvx bigkinds-mcp`로 설치

## 라이선스

MIT License

## 주의사항

BigKinds의 비공식 API를 활용합니다.
