MCP MAGMA Handbook Server

# 🚀 Enhanced MCP-MAGMA-Handbook v3.0 설정 가이드

**LangConnect 방법론 기반 차세대 MAGMA MCP 서버 완벽 설정법**

## 🎯 설정 개요

v3.0은 기존 v2.x와 완전히 다른 아키텍처를 사용합니다:
- **Multi-query 검색 엔진** (GPT-4o-mini 활용)
- **Hybrid 검색 시스템** (Vector + Keyword)
- **Collection 관리** (주제별 분류)
- **Conversation 저장** (대화 내용 축적)

## 📋 사전 준비사항

### 1. **시스템 요구사항**
- Node.js ≥ 18.0.0
- npm 또는 yarn
- Supabase 계정
- OpenAI API 키

### 2. **필수 계정 설정**

#### **Supabase 설정**
1. [supabase.com](https://supabase.com) 접속
2. 새 프로젝트 생성
3. **Project URL**과 **anon public key** 기록
4. SQL Editor에서 데이터베이스 스키마 설정 (아래 참조)

#### **OpenAI API 키**
1. [platform.openai.com](https://platform.openai.com) 접속
2. API Keys 섹션에서 새 키 생성
3. `sk-proj-...` 형태의 키 저장

## 🗄️ 데이터베이스 설정

### **Step 1: Supabase Extensions 활성화**
Supabase 대시보드 → SQL Editor → 새 쿼리:

```sql
-- 필수 확장 기능 활성화
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS pg_trgm;
```

### **Step 2: 스키마 생성**
프로젝트의 `database-schema.sql` 파일 내용을 Supabase SQL Editor에 복사하여 실행:

```bash
# 로컬에서 파일 확인
cat database-schema.sql
```

### **Step 3: 스키마 검증**
```sql
-- 테이블 생성 확인
SELECT table_name FROM information_schema.tables 
WHERE table_schema = 'public' 
AND table_name IN ('collections', 'documents');

-- 함수 생성 확인  
SELECT routine_name FROM information_schema.routines 
WHERE routine_schema = 'public' 
AND routine_name IN ('match_documents', 'hybrid_search');
```

## 📦 패키지 설치 및 설정

### **Method 1: Global 설치 (권장)**
```bash
# 전역 설치
npm install -g mcp-magma-handbook@3.0.0

# 설치 확인
mcp-magma-handbook --version
```

### **Method 2: 프로젝트 클론**
```bash
# 저장소 클론
git clone https://github.com/LeGenAI/mcp-magma-handbook.git
cd mcp-magma-handbook

# 의존성 설치
npm install

# 빌드
npm run build
```

## 🔧 환경 변수 설정

### **Option 1: .env 파일 생성**
```bash
# 프로젝트 루트에 .env 파일 생성
cat > .env << EOF
# Required
OPENAI_API_KEY=sk-proj-your-actual-key-here
SUPABASE_URL=https://your-project-id.supabase.co
SUPABASE_KEY=your-anon-public-key-here

# Optional (기본값 사용 권장)
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIMENSIONS=1536
CHAT_MODEL=gpt-4o-mini
EOF
```

### **Option 2: Claude Desktop 설정에서 직접**
환경 변수를 Claude Desktop 설정에서 직접 지정 (아래 참조)

## 🖥️ Claude Desktop 통합

### **Step 1: Claude Desktop MCP 설정**

**macOS 경로**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows 경로**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "enhanced-magma-handbook": {
      "command": "npx",
      "args": ["mcp-magma-handbook@3.0.0"],
      "env": {
        "OPENAI_API_KEY": "sk-proj-your-actual-key-here",
        "SUPABASE_URL": "https://your-project-id.supabase.co",
        "SUPABASE_KEY": "your-anon-public-key-here"
      }
    }
  }
}
```

### **Step 2: Claude Desktop 재시작**
- Claude Desktop 완전 종료
- 다시 실행
- 새 대화에서 MCP 도구 확인

## 📚 문서 인덱싱

### **MAGMA Handbook 준비**
1. MAGMA 공식 문서 PDF 다운로드
2. `data/pdfs/` 폴더에 저장
3. 파일명: `Handbook.pdf` (권장)

### **인덱싱 실행**
```bash
# 고급 인덱서 사용 (권장)
npm run index-advanced

# 기본 인덱서 사용
npm run index

# 인덱싱 진행 상황 모니터링
tail -f indexing.log
```

### **인덱싱 검증**
```sql
-- Supabase에서 문서 수 확인
SELECT 
  c.name,
  COUNT(d.id) as document_count,
  AVG(LENGTH(d.content)) as avg_content_length
FROM collections c 
LEFT JOIN documents d ON c.id = d.collection_id 
GROUP BY c.id, c.name;
```

## 🧪 설정 테스트

### **Step 1: 서버 단독 테스트**
```bash
# 개발 모드로 서버 실행
npm run dev

# 다른 터미널에서 테스트 실행
npx tsx test-enhanced-mcp-complete.ts
```

### **Step 2: Claude Desktop 테스트**
Claude Desktop에서 다음 명령어들을 테스트:

```
1. 도구 목록 확인
사용 가능한 MCP 도구를 보여주세요.

2. 상태 확인  
get_health_status 도구를 사용해서 서버 상태를 확인해주세요.

3. 컬렉션 조회
list_collections 도구로 사용 가능한 컬렉션을 보여주세요.

4. 검색 테스트
search_magma 도구를 사용해서 "polynomial ring" 을 검색해주세요.
```

## 🔧 고급 설정

### **Multi-Query 설정 최적화**
```typescript
// enhanced-mcp-server.ts에서 수정 가능
const multiQueryConfig = {
  maxQueries: 5,        // 최대 쿼리 수
  temperature: 0,       // GPT 창의성 (0 = 정확도 우선)
  fallbackEnabled: true // multi-query 실패 시 단일 쿼리로 전환
};
```

### **Hybrid Search 가중치 조정**
```typescript
// 검색 방식별 가중치 (합계 = 1.0)
const searchWeights = {
  semantic: 0.7,    // 의미 검색 70%
  keyword: 0.3      // 키워드 검색 30%
};
```

### **Performance Tuning**
```sql
-- Supabase에서 인덱스 최적화
REINDEX INDEX idx_documents_embedding;
VACUUM ANALYZE documents;

-- 벡터 검색 최적화 (lists 값 조정)
DROP INDEX IF EXISTS idx_documents_embedding;
CREATE INDEX idx_documents_embedding ON documents 
USING ivfflat (embedding vector_cosine_ops) 
WITH (lists = 100);  -- 문서 수에 따라 조정
```

## 🚨 문제 해결

### **일반적인 문제들**

#### **1. OpenAI API 키 오류**
```
Error: The OPENAI_API_KEY environment variable is missing
```
**해결**: 
- API 키 형식 확인 (`sk-proj-` 시작)
- 환경 변수 설정 재확인
- Claude Desktop 재시작

#### **2. Supabase 연결 오류**
```
Error: Invalid Supabase URL or Key
```
**해결**:
- Project URL 형식: `https://project-id.supabase.co`
- anon public key 사용 (service_role 아님)
- Supabase 프로젝트 활성화 상태 확인

#### **3. Vector 검색 실패**
```
Error: relation "documents" does not exist
```
**해결**:
- `database-schema.sql` 재실행
- Extensions 설치 확인
- 테이블 권한 확인

#### **4. Multi-query 실패**
```
Error: Failed to generate queries
```
**해결**:
- OpenAI API 크레딧 확인
- 네트워크 연결 확인
- Fallback 모드로 자동 전환됨

### **디버깅 도구**

#### **로그 레벨 설정**
```bash
# 상세 로그 활성화
DEBUG=* npm run dev
```

#### **데이터베이스 상태 확인**
```sql
-- 컬렉션 통계
SELECT * FROM collection_stats;

-- 최근 검색 성능
EXPLAIN ANALYZE 
SELECT * FROM match_documents(
  array_to_vector(array_fill(0, array[1536])), 
  5
);
```

## 📊 성능 모니터링

### **검색 성능 벤치마크**
```bash
# 품질 벤치마크 실행
npm run test-quality

# 결과 예시:
# Average Relevance Score: 92.3%
# Multi-query Improvement: +7.8%
# Hybrid Search Accuracy: 94.1%
```

### **시스템 리소스 모니터링**
```bash
# 메모리 사용량
ps aux | grep node

# 네트워크 사용량  
netstat -i

# 디스크 I/O
iostat -x 1
```

## 🔄 업그레이드 가이드

### **v2.x → v3.0 마이그레이션**

#### **1. 백업 생성**
```sql
-- 기존 documents 테이블 백업
CREATE TABLE documents_backup AS SELECT * FROM documents;
```

#### **2. 스키마 업그레이드**
```bash
# 새 스키마 적용
psql -f database-schema.sql
```

#### **3. 설정 파일 업데이트**
```bash
# 기존 설정 백업
cp ~/.config/claude/claude_desktop_config.json claude_config_backup.json

# 새 설정 적용
# (위의 Claude Desktop 설정 참조)
```

#### **4. 호환성 확인**
```bash
# 테스트 실행으로 모든 기능 검증
npm run test-quality
```

## ✅ 설정 완료 체크리스트

- [ ] Node.js ≥ 18.0.0 설치됨
- [ ] Supabase 프로젝트 생성 및 설정됨
- [ ] OpenAI API 키 발급됨
- [ ] `database-schema.sql` 실행됨
- [ ] 패키지 설치됨 (`npm install -g mcp-magma-handbook@3.0.0`)
- [ ] 환경 변수 설정됨
- [ ] Claude Desktop 설정 업데이트됨
- [ ] MAGMA 문서 인덱싱 완료됨
- [ ] 테스트 통과됨
- [ ] 기본 검색 동작 확인됨

## 📞 추가 지원

설정 중 문제가 발생하면:

1. **GitHub Issues**: [문제 신고](https://github.com/LeGenAI/mcp-magma-handbook/issues)
2. **이메일**: baegjaehyeon@gmail.com  
3. **문서**: [상세 가이드](https://github.com/LeGenAI/mcp-magma-handbook/blob/main/README-v3.md)

---

**🎉 설정 완료! 이제 Enhanced MCP v3.0의 강력한 기능들을 마음껏 활용하세요!** 🚀