# 아누 지식 베이스 MCP 서버

## 📋 프로젝트 개요

**아누(Anu) 지식 베이스 MCP 서버**는 Claude Desktop, Cursor 등 MCP를 지원하는 도구에서 아누 시스템의 지식 베이스를 직접 검색하고 조회할 수 있는 서버입니다.

Anthropic의 **MCP(Model Context Protocol)** 기반 표준에 따라 개발되었으며, stdio 통신을 통해 AI 도구와 연동됩니다.

## 🚀 설치 방법

### 필수 패키지 설치

```bash
pip install mcp supabase openai
```

### 필수 환경변수 설정

서버 실행 전 다음 환경변수를 설정해야 합니다.

| 변수명 | 설명 | 예시 |
|--------|------|------|
| `INSURO_NEW_SUPABASE_URL` | Supabase 프로젝트 URL | `https://xxx.supabase.co` |
| `INSURO_NEW_SERVICE_ROLE_KEY` | Supabase Service Role 키 | `eyJhbGc...` |
| `OPENAI_API_KEY` | OpenAI API 키 (텍스트 임베딩용) | `sk-...` |

```bash
export INSURO_NEW_SUPABASE_URL="https://xxx.supabase.co"
export INSURO_NEW_SERVICE_ROLE_KEY="eyJhbGc..."
export OPENAI_API_KEY="sk-..."
```

## ⚙️ Claude Desktop 설정

### 설정 파일 위치

운영체제에 따라 다음 위치의 `claude_desktop_config.json` 파일을 수정하세요.

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

### 설정 추가

아래 설정을 `claude_desktop_config.json`의 `mcpServers` 객체에 추가합니다.

```json
{
  "mcpServers": {
    "anu-knowledge": {
      "command": "python3",
      "args": ["/home/jay/workspace/services/mcp_server.py"],
      "env": {
        "INSURO_NEW_SUPABASE_URL": "https://xxx.supabase.co",
        "INSURO_NEW_SERVICE_ROLE_KEY": "eyJhbGc...",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}
```

## 🛠️ 제공 Tool 목록

### 1. `search_knowledge`

아누 지식 베이스에서 관련 문서를 **하이브리드 검색**(의미 기반 + 키워드 기반)으로 찾습니다.

**입력 파라미터:**
- `query` (str, 필수): 검색할 질의어
- `source` (str, 선택): 특정 소스에서만 검색 (예: "보험약관", "FAQ")
- `limit` (int, 기본값: 5): 반환할 최대 문서 수

**출력:**
```json
{
  "results": [
    {
      "id": "doc-123",
      "title": "자동차 보험 기본 약관",
      "content": "...",
      "source": "보험약관",
      "similarity": 0.95
    }
  ]
}
```

### 2. `get_document`

특정 문서의 전체 내용을 조회합니다.

**입력 파라미터:**
- `document_id` (str, 필수): 조회할 문서의 ID

**출력:**
```json
{
  "id": "doc-123",
  "title": "자동차 보험 기본 약관",
  "content": "...",
  "source": "보험약관",
  "metadata": {
    "created_at": "2024-01-15",
    "updated_at": "2024-03-10"
  }
}
```

### 3. `list_sources`

등록된 모든 소스와 각 소스의 문서 수를 조회합니다.

**입력 파라미터:**
- 없음

**출력:**
```json
{
  "sources": [
    {
      "source": "보험약관",
      "document_count": 45
    },
    {
      "source": "FAQ",
      "document_count": 120
    },
    {
      "source": "신청가이드",
      "document_count": 23
    }
  ]
}
```

## 💬 사용 예시

Claude Desktop에서 다음과 같이 사용할 수 있습니다.

### 문서 검색
```
사용자: "보험 약관에서 면책 조항을 검색해줘"
→ search_knowledge(query="면책 조항") 자동 호출
```

### 특정 소스에서 검색
```
사용자: "FAQ에서 청구 방법을 찾아줘"
→ search_knowledge(query="청구 방법", source="FAQ") 자동 호출
```

### 문서 전체 내용 조회
```
사용자: "doc-123 문서의 전체 내용을 보여줘"
→ get_document(document_id="doc-123") 자동 호출
```

### 등록된 소스 확인
```
사용자: "어떤 소스가 등록되어 있는지 알려줘"
→ list_sources() 자동 호출
```

## 🧪 테스트 실행

```bash
cd /home/jay/workspace/services
python3 -m pytest tests/ -v
```

테스트 결과 예시:
```
tests/test_search.py::test_search_knowledge PASSED
tests/test_search.py::test_get_document PASSED
tests/test_search.py::test_list_sources PASSED
===== 3 passed in 0.42s =====
```

## 🏗️ 아키텍처

```
┌─────────────────────────────────────┐
│  Claude Desktop / Cursor            │
│  (MCP 지원 AI 도구)                  │
└────────────┬────────────────────────┘
             │ MCP stdio 통신
             ↓
┌─────────────────────────────────────┐
│      mcp_server.py                  │
│  (MCP 서버 엔드포인트)                │
└────────────┬────────────────────────┘
             │
             ↓
┌─────────────────────────────────────┐
│      libs/search.py                 │
│  (hybrid_search 함수)                 │
│  - 의미 기반 검색 (벡터)              │
│  - 키워드 기반 검색 (전문 검색)        │
└────────────┬────────────────────────┘
             │
             ↓
┌─────────────────────────────────────┐
│      Supabase 데이터베이스           │
│  - pgvector (벡터 저장소)            │
│  - tsvector (전문 검색)              │
│  - documents 테이블                 │
│  - embeddings 저장소                │
└─────────────────────────────────────┘
```

## 📁 디렉토리 구조

```
/home/jay/workspace/services/
├── README.md                 # 이 문서
├── mcp_server.py            # MCP 서버 메인 코드
├── tests/                   # 테스트 디렉토리
│   ├── test_search.py
│   └── test_document.py
└── requirements.txt         # 의존성 패키지 목록
```

## 🔧 개발 가이드

### 새로운 Tool 추가하기

`mcp_server.py`에 새로운 tool을 추가하려면:

```python
@server.call_tool()
async def call_tool(name: str, arguments: dict) -> str:
    if name == "my_new_tool":
        result = my_function(arguments)
        return json.dumps(result)
```

### 로깅

서버 실행 로그는 Claude Desktop의 개발자 도구에서 확인할 수 있습니다.

## ⚠️ 주의사항

1. **API 키 관리**: Service Role 키와 OpenAI API 키는 절대 코드에 하드코딩하지 마세요.
2. **환경변수**: 모든 민감한 정보는 환경변수로 관리하세요.
3. **요청 제한**: OpenAI 임베딩 API의 사용량을 모니터링하세요.
4. **데이터베이스**: 대량의 문서 검색 시 Supabase 쿼리 성능을 고려하세요.

## 📞 문제 해결

### 서버가 시작되지 않음

```bash
# 환경변수 확인
echo $INSURO_NEW_SUPABASE_URL
echo $INSURO_NEW_SERVICE_ROLE_KEY
echo $OPENAI_API_KEY

# 직접 실행하여 에러 메시지 확인
python3 /home/jay/workspace/services/mcp_server.py
```

### 검색 결과가 없음

- Supabase 연결 상태 확인
- 데이터베이스에 문서가 등록되어 있는지 `list_sources` 호출
- 임베딩 벡터가 제대로 생성되었는지 확인

### Claude Desktop에서 Tool이 보이지 않음

- `claude_desktop_config.json` 파일 경로 확인
- 파일 문법 오류 확인 (JSON 유효성)
- Claude Desktop 재시작

## 📚 참고 자료

- [MCP 공식 문서](https://modelcontextprotocol.io)
- [Supabase pgvector](https://supabase.com/docs/guides/database/extensions/pgvector)
- [OpenAI Embeddings API](https://platform.openai.com/docs/guides/embeddings)