# Plan: BigKinds MCP 리포트 기반 개선

> 작성일: 2025-12-15
> 참조: `tests/MCP_FINAL_REPORT.md`

## 1. Hypothesis (가설)

### 문제 정의
테스트 리포트에 따르면 3가지 Critical 이슈 존재:
1. **필터 기능 미작동** (E001, E002): providers/categories 필터 적용 시 0건 반환
2. **total_pages 계산 오류** (E003): sort_by="both" 병합 후 페이지 수 부정확
3. **news_id 조회 제한**: URL 없이 news_id만으로 기사 전문 조회 불가

### 가설
**H1**: 필터가 0건 반환하는 원인은 BigKinds API가 필터 파라미터를 무시하거나, 요청 형식이 잘못됨
**H2**: total_pages 계산이 sort_by="both" 병합 후 재계산되지 않음
**H3**: BigKinds에 news_id 기반 API 엔드포인트가 없어 URL 스크래핑만 가능

## 2. Expected Outcomes (예상 결과)

### Phase 0: 근본 원인 조사 (Root Cause Analysis)
- [ ] BigKinds API 실제 요청/응답 로깅으로 필터 전송 형식 확인
- [ ] 공식 문서 또는 커뮤니티에서 필터 사용법 조사 (context7, WebSearch)
- [ ] total_pages 계산 로직 코드 리뷰

**예상 시간**: 1-2시간
**성공 기준**: 각 이슈의 근본 원인이 명확히 파악됨

### Phase 1: Critical 이슈 수정
**목표**: E001, E002, E003 해결

#### 1.1 필터 기능 복구
- 원인 파악 후 수정 또는 fallback 로직 추가
- 필터 실패 시 경고 메시지 + 전체 결과 반환

#### 1.2 total_pages 계산 수정
- sort_by="both" 병합 후 `math.ceil(total_count / page_size)` 재계산
- 단위 테스트 추가

#### 1.3 news_id 조회 개선
- BigKinds API에 news_id 기반 엔드포인트 확인
- 없다면: 캐시 영구화 (SQLite) 또는 명확한 에러 메시지

**예상 시간**: 3-4시간
**성공 기준**: 테스트 리포트 E001-E003 모두 해결

### Phase 2: 유틸리티 툴 추가
**목표**: 리포트 권장사항 기반 새 기능 구현

#### 2.1 배치 분석 툴
```python
compare_keywords(keywords: list[str], ...) -> ComparisonResult
# 여러 키워드 동시 비교 분석
```

#### 2.2 스마트 샘플링
```python
smart_sample(keyword: str, start_date: str, end_date: str, sample_size: int = 100) -> SampleResult
# 대용량 결과에서 대표 샘플 추출 (기간별 균등 분포)
```

#### 2.3 캐시 관리
```python
cache_stats() -> dict
# 캐시 히트율, 크기 통계 조회
```

**예상 시간**: 4-5시간
**성공 기준**: 3개 툴 모두 작동, 문서화 완료

### Phase 3: 테스트 및 문서화
- [ ] 통합 테스트 (필터, total_pages, 새 툴)
- [ ] PRD AC 재검증
- [ ] MCP_GUIDE.md 업데이트

**예상 시간**: 2-3시간
**성공 기준**: 테스트 성공률 95% 이상

### Phase 4: 오픈소스 문서 업데이트
- [ ] README.md: 새 툴 추가, 예시 업데이트
- [ ] CHANGELOG.md: v1.2.0 릴리스 노트 작성
- [ ] PyPI 배포 준비

**예상 시간**: 1-2시간

## 3. Total Estimated Time
- Phase 0: 1-2시간
- Phase 1: 3-4시간
- Phase 2: 4-5시간
- Phase 3: 2-3시간
- Phase 4: 1-2시간

**Total**: 11-16시간 (1.5-2 작업일)

## 4. Risks & Mitigation

| Risk | Impact | Mitigation |
|------|--------|------------|
| 필터 API가 실제로 작동 안 함 | High | Fallback: 클라이언트 측 필터링 구현 |
| news_id 엔드포인트 없음 | Medium | 캐시 영구화 (SQLite) 또는 명확한 가이드 |
| 새 툴 구현 복잡도 과소평가 | Low | 우선순위 조정 (Phase 2 선택사항) |

## 5. Architecture Decisions

### AD1: 필터 처리 전략
**선택지**:
- A: API 요청 형식 수정 시도
- B: 클라이언트 측 필터링 (API 결과 후처리)
- C: 두 방법 hybrid (API 실패 시 B로 fallback)

**결정**: C (Hybrid)
**이유**: 유연성과 사용자 경험 모두 확보

### AD2: 캐시 영구화 방법
**선택지**:
- A: SQLite (파일 기반)
- B: Redis (외부 의존성)
- C: 인메모리 유지 + 명확한 에러 메시지

**결정**: 일단 C, 필요 시 A로 확장
**이유**: 의존성 최소화, 점진적 개선

### AD3: 새 툴 우선순위
**순서**:
1. `compare_keywords` (리포트에서 명시적 권장)
2. `smart_sample` (대용량 데이터 처리 전략)
3. `cache_stats` (운영/디버깅 유틸리티)

## 6. Next Actions

1. **즉시**: Phase 0 시작 - 필터 API 디버깅 로깅 추가
2. **Phase 0 완료 후**: Phase 1 착수 (근본 원인 기반 수정)
3. **Phase 1 검증 후**: Phase 2 설계 (새 툴 스펙)

---

**Generated by**: PM Agent
**References**:
- `tests/MCP_FINAL_REPORT.md` (테스트 리포트)
- `docs/PRD.md` (요구사항)
- `docs/IMPLEMENTATION_WORKFLOW_V2.md` (기존 워크플로)
