RAG MCP Server with Streamable HTTP Transport

MCP server สำหรับค้นหาเอกสาร (RAG) แบบ Hybrid Search (BM25 + Semantic + RRF) รองรับภาษาไทย ผ่าน Streamable HTTP transport (มาตรฐาน MCP ปัจจุบัน ใช้ endpoint เดียว แทน HTTP+SSE แบบเก่า) รันเป็น container ด้วย Docker

ใช้ Qdrant เป็น vector database และ Ollama (หรือ OpenAI) สำหรับสร้าง embedding — ทั้งสองตัวรวมอยู่ใน docker-compose.yml แล้ว — รันครั้งเดียวขึ้นมาครบทุกตัว ไม่ต้องติดตั้งแยกเอง

Repository นี้คงโปรเจกต์เดิมจาก 2026-2025-Best-MCP/rag-mcp-server-streamablehttp และแก้เฉพาะ MCP SDK compatibility จาก mcp>=1.2.0 เป็น mcp>=1.28,<2 เพื่อให้โค้ดที่ใช้ FastMCP API ของ SDK v1 ทำงานได้หลัง MCP SDK 2.x ออก

Features

• Streamable HTTP Transport — ใช้ endpoint เดียว (/mcp) รับ POST/GET/DELETE ตามมาตรฐาน MCP ปัจจุบัน
• Stateless — ไม่บังคับ Mcp-Session-Id (คล้าย FastMCP stateless_http=True) ต่อ client ได้หลากหลาย
• Hybrid Search — รวม BM25 (keyword) + Semantic (vector) เข้าด้วยกันด้วย RRF (Reciprocal Rank Fusion)
• Thai Language Support — ตัดคำ/normalize ภาษาไทย (รองรับเลขไทย ๑๒๓) ด้วย PyThaiNLP
• FastAPI + Uvicorn backend — web framework ที่เร็วและทันสมัย
• Docker Support — รันเป็น container ได้ทั้งหมด

MCP Tools (4)

Tool	หน้าที่
search_documentation	ค้นหาเอกสารที่เก็บไว้ (รับ query, limit default 5, search_mode default hybrid) — เลือกได้ semantic / bm25 / hybrid
list_sources	ลิสต์ source ของเอกสารทั้งหมดที่เก็บอยู่
add_directory	เพิ่มไฟล์เอกสารทั้งโฟลเดอร์เข้าระบบ (รับ path)
add_context	เพิ่ม text content ตรงๆ เข้า RAG store เช่น context จาก agent (รับ content, title, source, metadata)

Installation

Prerequisites:

1. ติดตั้งและเปิด Docker Desktop ก่อน (Mac / Windows)
2. port 8000 (MCP server), 6333 (Qdrant) และ 11434 (Ollama) บนเครื่องว่าง

ไม่ต้องติดตั้ง Qdrant/Ollama เอง — docker-compose.yml รันให้ครบทั้ง Qdrant + Ollama + MCP server และ pull nomic-embed-text ให้อัตโนมัติตอนรันครั้งแรก

ขั้นตอน Windows กับ Mac ต่างกันเล็กน้อย ทำตามหัวข้อของ OS ตัวเอง

---

Windows (double-click)

1. ดาวน์โหลดโปรเจกต์จาก GitHub

เปิด Command Prompt (CMD) แล้วรัน:

git clone https://github.com/aekanun2020/fixed-2026-rag-mcp-server-streamablehttp.git
cd fixed-2026-rag-mcp-server-streamablehttp

(ไม่มี Git? กดปุ่มสีเขียว Code ▾ ที่ หน้า repo → Download ZIP → แตกไฟล์แล้วเปิดโฟลเดอร์โปรเจกต์)

2. เริ่มรัน server

เปิดโฟลเดอร์โปรเจกต์ใน File Explorer แล้ว double-click ไฟล์ start_docker.bat

หน้าต่าง CMD จะเปิดขึ้นมาและทำให้ทั้งหมดให้อัตโนมัติ:

• สร้าง .env จาก .env.example (ถ้ายังไม่มี)
• build Docker image
• รัน container และแสดง log สด

3. เสร็จ

เมื่อเห็น log ขึ้น health แล้ว server จะรันที่ http://localhost:8000/mcp เปิดหน้าต่าง CMD ค้างไว้ — ปิดหน้าต่าง = server หยุด ถ้าจะหยุดให้ปิดหน้าต่างหรือกด Ctrl + C

---

Mac (Terminal)

1. ดาวน์โหลดโปรเจกต์จาก GitHub

เปิด Terminal แล้วรัน:

git clone https://github.com/aekanun2020/fixed-2026-rag-mcp-server-streamablehttp.git
cd fixed-2026-rag-mcp-server-streamablehttp

2. เริ่มรัน server

chmod +x start_docker.sh   # ทำแค่ครั้งแรกครั้งเดียว
./start_docker.sh

script จะสร้าง .env จาก .env.example (ถ้ายังไม่มี), build image, รัน container และแสดง log สด

3. เสร็จ

เมื่อเห็น log ขึ้น health แล้ว server จะรันที่ http://localhost:8000/mcp เปิด Terminal ค้างไว้ — ปิดหน้าต่าง (หรือกด Ctrl + C) = server หยุด

---

Configuration

ตัวติดตั้งจะ copy .env.example ไปเป็น .env ให้อัตโนมัติ โดยชี้ไปที่ service qdrant และ ollama ภายใน docker-compose.yml เดียวกัน:

QDRANT_URL=http://qdrant:6333
EMBEDDING_PROVIDER=ollama
EMBEDDING_MODEL=nomic-embed-text
OLLAMA_URL=http://ollama:11434
OPENAI_API_KEY=

qdrant / ollama คือชื่อ service ใน compose — container คุยกันผ่าน network ภายในได้เลย ไม่ต้องตั้ง Qdrant/Ollama แยกเอง

ถ้าจะใช้ OpenAI แทน Ollama ให้ตั้ง EMBEDDING_PROVIDER=openai และใส่ OPENAI_API_KEY

Managing the container

ชื่อ container คือ rag-mcp-streamable-http — รันคำสั่งเหล่านี้จาก root ของ repository

# เช็คสถานะ / health
docker ps

# ดู log สด
docker logs -f rag-mcp-streamable-http

# หยุด server (เก็บ container ไว้ start ใหม่ได้)
docker compose stop

# เปิดใช้งานใหม่ภายหลัง
docker compose start

Re-running with a new configuration

ถ้าแก้ .env (เช่น เปลี่ยน QDRANT_URL หรือ EMBEDDING_MODEL) ให้ apply config ใหม่ด้วยการ rebuild + recreate container ในที่เดิม:

docker compose up -d --build --force-recreate

ห้ามรัน docker compose down — down จะลบ container พร้อม network (และอาจกระทบ resource อื่น) ซึ่งไม่จำเป็น คำสั่ง up -d --build --force-recreate จะ recreate container ในที่พร้อม .env/config ใหม่ให้อยู่แล้ว — ใช้แค่คำสั่งนี้คำสั่งเดียว

ดูและล้างข้อมูลใน Qdrant

ข้อมูลเอกสาร (vector) เก็บอยู่ใน collection ชื่อ documentation บน Qdrant (port 6333) — สั่งคำสั่งได้ตรงด้วย curl

ดูจำนวนข้อมูล

# จำนวน points และโครงสร้าง collection
curl -s http://localhost:6333/collections/documentation | python3 -m json.tool
# ดู points_count — ถ้ามากกว่า 0 คือมีข้อมูลเก็บอยู่

# ดูรายการ collection ทั้งหมด
curl -s http://localhost:6333/collections | python3 -m json.tool

ล้างข้อมูล — วิธีที่แนะนำ (ไม่ทำลายโครงสร้าง)

ลบเฉพาะ points ข้างใน — collection (vector size 768, Cosine, HNSW config) ยังอยู่ครบ ไม่ต้อง recreate container:

curl -X POST "http://localhost:6333/collections/documentation/points/delete?wait=true" \
  -H "Content-Type: application/json" \
  -d '{"filter": {}}'

✅ หลังลบ server ใช้งานต่อได้ทันที (add/search) — ไม่ต้องรีสตาร์ตอะไร นี่คือวิธีที่แนะนำสำหรับ reset ข้อมูล

หมายเหตุ (BM25 index): Qdrant (vector) จะว่างทันที แต่ BM25 index ในหน่วยความจำของ server จะยังจำของเก่าจนกว่าจะ add ข้อมูลชุดใหม่ หรือ restart container — ถ้าอยากล้าง BM25 ให้หมดจริงๆ ให้ docker compose restart mcp-server หลังลบ points

ลบทั้ง collection — รีเซ็ตสุด (ต้อง recreate container)

ถ้าอยากล้างแบบหมดจดรวมโครงสร้าง collection:

# 1. ลบทั้ง collection
curl -X DELETE http://localhost:6333/collections/documentation

# 2. ต้อง recreate container เพราะ server สร้าง collection แค่ตอน startup
docker compose up -d --force-recreate mcp-server

ระวัง: ถ้า DELETE ทั้ง collection แล้วไม่ recreate container — การเรียก add/search ครั้งถัดไปจะได้ error 404 Collection doesn't exist เพราะ server สร้าง collection เฉพาะตอน startup เท่านั้น ถ้าแค่ reset ข้อมูลธรรมดา — ใช้วิธี“ล้าง points”ด้านบนจะสะดวกกว่า (ไม่ต้อง recreate)

API Endpoints

/mcp เป็น endpoint เดียวของ Streamable HTTP รองรับ 3 method:

Method / Path	หน้าที่
POST /mcp	รับ JSON-RPC message ของ MCP (ตัวหลักที่ใช้สื่อสาร)
GET /mcp	เปิด SSE stream — ต้องส่ง Accept: text/event-stream ไม่งั้นคืน 405 ตาม spec
DELETE /mcp	ปิด session — คืน 204 ถ้ามี session, 404 ถ้าไม่มี
GET /health	Health check (ใช้โดย Docker healthcheck)
GET /	ข้อมูล service และรายการ endpoint

Session handling (stateless)

Server ทำงานแบบ stateless (คล้าย FastMCP stateless_http=True): ตอน initialize จะ mint Mcp-Session-Id ส่งกลับมาใน response header ไว้ให้ client ที่ต้องการใช้ (optional) แต่ request ถัดไป (tools/list, tools/call) จะคืน JSON response ตรงๆ โดยไม่บังคับ header นี้ ทำให้ client ที่ไม่ได้ส่ง session id กลับมา (เช่น Streamable HTTP path ของ PyClaw) ต่อได้โดยไม่ต้องแก้อะไร

Note: server รันที่ port 8000 ทั้งภายใน container และ expose ออกมาภายนอก (ตรงกับ rag-mcp-server-v3) — Qdrant อยู่ที่ 6333, Ollama อยู่ที่ 11434 (รันจาก compose เดียวกัน)

MCP Client Configuration

สำหรับ Claude Desktop หรือ MCP client อื่นๆ ให้ต่อผ่าน mcp-remote (มันทำหน้าที่ bridge จาก Streamable HTTP server ไปเป็น stdio ที่ client เหล่านี้ต้องการ):

{
  "mcpServers": {
    "rag-streamable-http": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8000/mcp",
        "--allow-http"
      ]
    }
  }
}

ถ้า client อยู่คนละเครื่องกับ server ให้เปลี่ยน localhost เป็น IP ของ server (เช่น LAN หรือ Tailscale address) ส่วน --allow-http จำเป็นเพราะ server เสิร์ฟผ่าน HTTP ธรรมดา ไม่ใช่ HTTPS

วิธีใช้งาน (Usage)

📘 อยากทดสอบทีละขั้นแบบ copy คำสั่งได้เลย? ดู TESTING_GUIDE.md — คู่มือทดสอบ 5 ขั้น (health → initialize → tools/list → add_directory → search ทั้ง 3 mode) พร้อม output จริงและคำอธิบาย score/log

หลัง server รันแล้ว ใช้งานได้ 2 ทาง: ผ่าน MCP client (เช่น Claude Desktop, PyClaw) หรือ เรียกตรงด้วย curl เพื่อทดสอบ

ขั้นตอนใช้งานพื้นฐาน

1. ใส่เอกสารเข้าระบบก่อน — ใช้ add_directory (ทั้งโฟลเดอร์) หรือ add_context (text ตรงๆ) เอกสารจะถูกแปลงเป็น vector เก็บใน Qdrant และ index ลง BM25 ไปพร้อมกัน
2. ค้นหาด้วย search_documentation — ใส่ query แล้วระบบจะค้นแบบ Hybrid (BM25 + Semantic + RRF) ให้อัตโนมัติ
3. ถ้าต้องการบังคับโหมด ให้ใส่ search_mode เป็น semantic, bm25 หรือ hybrid

ผ่าน MCP client: แค่พิมพ์สั่ง AI ว่า "ค้นหาเอกสารเรื่อง..." client จะเรียก search_documentation ให้เอง — ได้ Hybrid โดยอัตโนมัติ ไม่ต้องตั้งค่าอะไรเพิ่ม

ค้นหา (default = Hybrid)

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {
      "name": "search_documentation",
      "arguments": { "query": "Hybrid Search ภาษาไทย", "limit": 5 }
    }
  }'

เลือกโหมดค้นหา (semantic / bm25 / hybrid)

เพิ่ม search_mode ใน arguments:

# BM25 อย่างเดียว (keyword/exact match — เหมาะกับเลขข้อ เลขไทย ๒๑)
# เปลี่ยนเป็น "semantic" สำหรับ vector search ล้วน หรือ "hybrid" สำหรับรวมทั้งสอง (ค่าเริ่มต้น)
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {
      "name": "search_documentation",
      "arguments": { "query": "ข้อ ๘๖", "limit": 3, "search_mode": "bm25" }
    }
  }'

search_mode	ค้นแบบ	score ที่ได้
hybrid (default)	BM25 + Semantic รวมด้วย RRF	RRF score (เลขน้อย เช่น 0.0x — ปกติของ RRF)
semantic	Dense vector อย่างเดียว	cosine similarity (0–1)
bm25	Sparse keyword อย่างเดียว	BM25 score (keyword match)

เพิ่มเอกสาร

# add_directory — ทั้งโฟลเดอร์ (path ต้องเป็น path ภายใน container เช่น /home/mcpuser/documents)
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"add_directory","arguments":{"path":"/home/mcpuser/documents"}}}'

# add_context — ใส่ text ตรงๆ
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"add_context","arguments":{"content":"เนื้อหา...","title":"หัวข้อ","source":"agent"}}}'

ดู log ยืนยันว่า Hybrid ทำงานจริง

docker logs -f rag-mcp-streamable-http

ตอน startup จะเห็น BM25 index ถูกสร้าง และตอนค้นหาจะเห็นทั้ง BM25 และ Semantic ทำงาน:

SearchOrchestrator initialized with default_mode=hybrid
✅ BM25 index built successfully with N documents
Search request: query='...', mode=hybrid
BM25 search returned X results (max_score=...)
Hybrid search returned Y results (BM25: X, Semantic: X)

License

MIT