# Task-513 완료 보고서: MCP 서버 구현 (OpenRAG Phase 4)

## SCQA

**S**: OpenRAG Phase 1~2(pgvector 하이브리드 검색, Docling 문서 파싱)가 완료되어 아누 시스템의 지식 베이스가 API 레벨에서 검색 가능한 상태이다.

**C**: 현재 지식 베이스 검색은 Python 코드를 직접 호출해야만 가능하여, Claude Desktop이나 Cursor 같은 AI 도구에서 직접 활용할 수 없다.

**Q**: MCP 서버를 구현하여 Claude Desktop/Cursor에서 아누 지식 베이스를 네이티브 tool로 사용할 수 있는가?

**A**: FastMCP(v1.26.0) 기반 stdio MCP 서버를 구현하여 3개 tool(search_knowledge, get_document, list_sources)을 제공한다. pytest 9건 전체 통과, pyright 에러 0건, black/isort 준수. Claude Desktop 설정 예시 및 README 문서 포함.

---

## 작업 내용

### 구현 산출물

1. **MCP 서버** (`/home/jay/workspace/services/mcp_server.py`)
   - FastMCP("anu-knowledge") 인스턴스, stdio 기반 통신
   - Tool 1: `search_knowledge` — libs/search.py의 hybrid_search() 호출, source 필터/limit 지원
   - Tool 2: `get_document` — Supabase knowledge_documents 테이블 조회
   - Tool 3: `list_sources` — source별 문서 수 집계
   - Supabase 클라이언트 lazy init (환경변수 미설정 시에도 import 안전)
   - 로깅은 stderr 전용 (stdio 프로토콜 간섭 방지)

2. **설정 예시** (`/home/jay/workspace/services/claude_desktop_config_example.json`)
   - Claude Desktop MCP 연결 설정 템플릿

3. **테스트** (`/home/jay/workspace/services/tests/test_mcp_server.py`)
   - TDD RED→GREEN 방식으로 작성
   - 9개 테스트 케이스 (mock 기반, 외부 의존성 없음)

4. **문서** (`/home/jay/workspace/services/README.md`)
   - 설치, 환경변수, Claude Desktop 설정, Tool 설명, 아키텍처

---

## 생성/수정 파일 목록

| 파일 | 상태 | 설명 |
|------|------|------|
| services/mcp_server.py | 신규 | MCP 서버 본체 (161줄) |
| services/claude_desktop_config_example.json | 신규 | Claude Desktop 설정 예시 |
| services/tests/__init__.py | 신규 | 테스트 패키지 |
| services/tests/conftest.py | 신규 | pytest 설정 (sys.path, anyio) |
| services/tests/test_mcp_server.py | 신규 | 테스트 9건 |
| services/README.md | 신규 | 사용 문서 |

---

## 테스트 결과

```
9 passed in 1.28s
```

- test_search_knowledge_basic: PASS
- test_search_knowledge_with_source_filter: PASS
- test_search_knowledge_with_limit: PASS
- test_get_document_found: PASS
- test_get_document_not_found: PASS
- test_list_sources: PASS
- test_list_sources_empty: PASS
- test_search_knowledge_error_handling: PASS
- test_tool_registration: PASS

**pyright**: 에러 0건, 경고 0건 (mcp_server.py + test_mcp_server.py)
**black/isort**: 준수

---

## 발견 이슈 (3건)

1. **import 경로** (WARN): `from search import hybrid_search`는 런타임 sys.path 추가에 의존. pyright에서 `type: ignore[import-not-found]` 필요. 실행에는 문제 없음.
2. **list_sources 성능** (WARN): `select("source")` 후 Python Counter 집계 방식. 문서 10만건 이상 시 DB 레벨 RPC 함수(GROUP BY)로 전환 권장.
3. **lazy init race condition** (INFO): MCP stdio는 단일 프로세스이므로 실제 위험 없음. HTTP 전환 시 고려 필요.

---

## QC 자동 검증

```json
{
  "task_id": "task-513",
  "verified_at": "2026-03-13T08:30:23",
  "overall": "PASS",
  "checks": {
    "api_health": {"status": "SKIP"},
    "file_check": {"status": "PASS", "details": ["mcp_server.py 5519 bytes OK", "test_mcp_server.py 11678 bytes OK", "report 3418 bytes OK"]},
    "data_integrity": {"status": "SKIP", "note": "timer가 task-513.1로 기록되어 task-513 매칭 불가 (시스템 이슈)"},
    "test_runner": {"status": "PASS", "details": ["9 passed in 1.24s"]},
    "tdd_check": {"status": "PASS", "details": ["테스트+구현 파일 모두 존재"]},
    "schema_contract": {"status": "SKIP"},
    "pyright_check": {"status": "PASS", "details": ["0 errors, 0 warnings"]},
    "style_check": {"status": "PASS", "details": ["black: OK, isort: OK"]},
    "scope_check": {"status": "SKIP"}
  },
  "summary": "5 PASS, 4 SKIP"
}
```