# RAG MCP Claude

MCP (Model Context Protocol) Server สำหรับ **Semantic Search** บน YouTube transcripts ใช้ OpenAI Embeddings + ChromaDB

ต่างจาก keyword search ทั่วไป (FTS5) ที่ค้นได้เฉพาะ "คำตรงกัน" RAG ค้นหาด้วย **ความหมาย** ได้ เช่น ค้นว่า "วิธีฝึกจิตให้เข้มแข็ง" จะเจอข้อความเกี่ยวกับ "สมาธิ" แม้ไม่มีคำว่า "ฝึกจิต" ในข้อความเลย

> ดูรายละเอียดเปรียบเทียบ RAG vs Keyword Search ที่ [docs/concept-comparison.md](docs/concept-comparison.md)

## Features

- **rag_search** - ค้นหาด้วย semantic similarity (ความหมายใกล้เคียง)
- **rag_ingest** - นำ transcript / text เข้า knowledge base
- **rag_list_collections** - แสดง collections พร้อมสถิติ
- **rag_delete** - ลบข้อมูลออกจาก knowledge base

## Architecture

```
                         rag-mcp-claude
                         Port: 3020
┌──────────────────────────────────────────────────┐
│                                                  │
│  ┌──────────┐    ┌─────────────┐                 │
│  │  Ingest   │───▶│ Text Splitter│                 │
│  │  Pipeline │    │ (chunk 500   │                 │
│  └──────────┘    │  overlap 50) │                 │
│                   └──────┬──────┘                 │
│                          ▼                        │
│                  ┌───────────────┐                │
│                  │ OpenAI API     │                │
│                  │ text-embedding │                │
│    ┌──────┐      │ -3-small       │                │
│    │Search│─────▶│ (1536 dims)   │                │
│    └──────┘      └───────┬───────┘                │
│                          ▼                        │
│                  ┌───────────────┐                │
│                  │  ChromaDB      │                │
│                  │  Vector Store  │                │
│                  │  (cosine sim)  │                │
│                  └───────────────┘                │
│                                                  │
└──────────────────────────────────────────────────┘
```

## Quick Start

### 1. สร้าง OpenAI API Key

ไปที่ https://platform.openai.com/api-keys แล้วสร้าง key

### 2. สร้าง .env

```bash
cp .env.example .env
# แก้ไข .env ใส่ API key
```

```env
OPENAI_API_KEY=sk-your-api-key-here
```

### 3. Deploy ด้วย Docker

```bash
docker compose up -d
```

จะ start 2 containers:
- `rag-chromadb` - Vector database (port 8100)
- `rag-mcp-claude` - MCP server (port 3020)

### 4. ตรวจสอบ

```bash
curl http://localhost:3020/health
```

### 5. Ingest transcript ตัวอย่าง

```bash
# Ingest ทุกไฟล์ใน data/sources/
node src/cli-ingest.js --dir ./data/sources

# Ingest ไฟล์เดียว
node src/cli-ingest.js data/sources/SF6Tskjx6Qw.md
```

> ดูคู่มือ ingest ละเอียดที่ [docs/guide-ingest.md](docs/guide-ingest.md)

## MCP Client Configuration

เพิ่มใน `.mcp.json` หรือ Claude Desktop config:

```json
{
  "mcpServers": {
    "rag": {
      "url": "http://localhost:3020/mcp"
    }
  }
}
```

## Project Structure

```
rag-mcp-claude/
├── src/
│   ├── server-sse.js    # Streamable HTTP transport server (port 3020)
│   ├── index.js         # Stdio transport server
│   ├── config.js        # Configuration
│   ├── embeddings.js    # OpenAI embedding API wrapper
│   ├── vectorstore.js   # ChromaDB operations (CRUD)
│   ├── ingest.js        # Chunk → Embed → Store pipeline
│   ├── search.js        # Semantic search
│   └── cli-ingest.js    # CLI batch ingest tool
├── data/
│   └── sources/         # Transcript files (.md)
├── docs/
│   ├── concept-comparison.md  # RAG vs FTS5 comparison
│   ├── guide-ingest.md        # คู่มือ ingest ข้อมูล
│   ├── guide-search.md        # คู่มือ search
│   └── guide-openai-key.md    # คู่มือสร้าง OpenAI API Key
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── package.json
```

## API Endpoints

| Endpoint     | Method | Description              |
|-------------|--------|--------------------------|
| `/mcp`      | POST   | MCP message endpoint (Streamable HTTP) |
| `/mcp`      | GET    | SSE stream endpoint      |
| `/mcp`      | DELETE | Session termination      |
| `/health`   | GET    | Health check + status    |

## MCP Tools Reference

### rag_search

ค้นหาจาก knowledge base ด้วย semantic search

| Parameter    | Type   | Required | Default                | Description                |
|-------------|--------|----------|------------------------|----------------------------|
| `query`     | string | Yes      | -                      | คำค้นหา (ภาษาธรรมชาติ)     |
| `collection`| string | No       | `youtube_transcripts`  | ชื่อ collection             |
| `top_k`     | number | No       | `5`                    | จำนวนผลลัพธ์ (max 20)      |

**Response:**
```json
{
  "query": "สมาธิเปลี่ยนสมองได้อย่างไร",
  "collection": "youtube_transcripts",
  "totalResults": 3,
  "sources": [
    {
      "source": "SF6Tskjx6Qw",
      "title": "Ep0 - Journey Within: สำรวจโลกในหัวคุณ",
      "url": "https://www.youtube.com/watch?v=SF6Tskjx6Qw",
      "channel": "The Mind Architect",
      "chunks": [
        {
          "text": "สมาธิทำให้สมองส่วน Prefrontal Cortex หนาขึ้น...",
          "score": 0.892,
          "chunk_index": 3
        }
      ]
    }
  ]
}
```

### rag_ingest

นำข้อมูลเข้า knowledge base

| Parameter    | Type   | Required | Description                              |
|-------------|--------|----------|------------------------------------------|
| `file_path` | string | No*      | Path ของ transcript markdown file (.md)  |
| `text`      | string | No*      | ข้อความที่จะ ingest โดยตรง                |
| `source`    | string | No       | ชื่อแหล่งข้อมูล (เช่น video ID)           |
| `title`     | string | No       | ชื่อเรื่อง                                |
| `collection`| string | No       | ชื่อ collection                           |

*ต้องระบุอย่างน้อย `file_path` หรือ `text`

### rag_list_collections

แสดง collections ทั้งหมดพร้อมจำนวน documents

**Response:**
```json
{
  "total": 1,
  "collections": [
    { "name": "youtube_transcripts", "count": 45 }
  ]
}
```

### rag_delete

ลบข้อมูลออกจาก knowledge base

| Parameter           | Type    | Required | Description                    |
|--------------------|---------|----------|--------------------------------|
| `collection`       | string  | Yes      | ชื่อ collection                 |
| `source`           | string  | No       | ลบ documents จาก source นี้     |
| `delete_collection`| boolean | No       | ลบทั้ง collection               |

## Environment Variables

| Variable            | Default                  | Description                     |
|--------------------|--------------------------|---------------------------------|
| `PORT`             | `3020`                   | Server port                     |
| `HOST`             | `0.0.0.0`                | Server host                     |
| `OPENAI_API_KEY`   | (required)               | OpenAI API key                  |
| `EMBEDDING_MODEL`  | `text-embedding-3-small` | OpenAI embedding model          |
| `CHROMA_URL`       | `http://localhost:8100`  | ChromaDB URL                    |
| `CHROMA_COLLECTION`| `youtube_transcripts`    | Default collection name         |
| `CHUNK_SIZE`       | `500`                    | Tokens per chunk                |
| `CHUNK_OVERLAP`    | `50`                     | Overlap tokens between chunks   |
| `DEFAULT_TOP_K`    | `5`                      | Default search results          |

## Docker Details

| Container        | Image                  | Port | Description      |
|-----------------|------------------------|------|------------------|
| `rag-mcp-claude`| node:22-slim (custom)  | 3020 | MCP server (Streamable HTTP) |
| `rag-chromadb`  | chromadb/chroma:latest | 8100 | Vector database  |

- ChromaDB data persisted in Docker volume `chroma-data`
- RAG server ใช้ `network_mode: host` เพื่อเข้าถึง ChromaDB
- OpenAI API Key ส่งผ่าน `.env` file

## Data Flow

```
YouTube Video
     │  (youtube-mcp-claude ดึง transcript)
     ▼
data/sources/*.md        ← Transcript files
     │
     ▼ (rag_ingest / cli-ingest.js)
┌────────────────┐
│ 1. Parse        │  แยก metadata + transcript text
│ 2. Chunk        │  ตัดเป็นท่อนๆ (500 tokens, overlap 50)
│ 3. Embed        │  OpenAI API → vector [1536 dims]
│ 4. Store        │  ChromaDB (cosine similarity index)
└────────────────┘
     │
     ▼ (rag_search)
┌────────────────┐
│ 1. Embed query  │  แปลงคำถามเป็น vector
│ 2. Search       │  หา vectors ที่ใกล้เคียงที่สุด
│ 3. Return       │  ส่งกลับ chunks + metadata + score
└────────────────┘
```

## Cost Estimation (OpenAI)

| Model                    | Price              | 1 transcript (~10K tokens) | 1 search query |
|--------------------------|--------------------|-----------------------------|----------------|
| `text-embedding-3-small` | $0.02 / 1M tokens | ~$0.0002 (< 1 สตางค์)      | ~$0.000002     |
| `text-embedding-3-large` | $0.13 / 1M tokens | ~$0.0013                    | ~$0.000013     |

ใช้ `text-embedding-3-small` ราคาถูกมาก ingest transcript 1,000 วิดีโอ ≈ $0.20 (7 บาท)

## Related Projects

| Server              | Port | Description                    |
|--------------------|------|--------------------------------|
| youtube-mcp-claude | 3010 | YouTube transcript extraction  |
| **rag-mcp-claude** | **3020** | **RAG semantic search**   |
| chat-mcp-claude    | 3001 | Chat history (FTS5)            |
| thudong-mcp-claude | 3002 | Survey analysis (FTS5)         |

## Documentation

- [Concept Comparison: RAG vs Keyword Search](docs/concept-comparison.md)
- [คู่มือสร้าง OpenAI API Key](docs/guide-openai-key.md)
- [คู่มือ Ingest ข้อมูล](docs/guide-ingest.md)
- [คู่มือ Search](docs/guide-search.md)