MCP RAG Server cho PDF

MCP server (HTTP) cho phép Claude tìm kiếm ngữ nghĩa (semantic search) trên các file PDF của bạn thông qua RAG (Retrieval-Augmented Generation).

• Transport: HTTP (streamable-http) — kết nối qua Claude Connectors, dùng được trên Claude Desktop, claude.ai, và mobile
• Vector DB: ChromaDB (embedded, lưu trên đĩa)
• Embedding: OpenAI text-embedding-3-small
• PDF: chỉ hỗ trợ PDF dạng text (không OCR)
• Xác thực: không có (xem lưu ý bảo mật trong DEPLOY.md)

Cấu trúc project

mcp-rag-pdf/
├── documents/          # Bỏ file PDF cần index vào đây
├── chroma_db/           # Chroma tự tạo, lưu vector index (không sửa tay)
├── config.py             # Cấu hình chung
├── pdf_utils.py          # Đọc PDF + chia chunk
├── vector_store.py       # Wrapper Chroma + OpenAI embedding
├── ingest.py             # Script chạy thủ công để nạp/refresh dữ liệu
├── server.py              # MCP server (HTTP)
├── Dockerfile
├── requirements.txt
└── DEPLOY.md              # Hướng dẫn deploy lên cloud (Railway)

1. Cài đặt (chạy dev trên máy)

cd mcp-rag-pdf
python3 -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Cấu hình OpenAI API key

Tạo file .env (copy từ .env.example):

OPENAI_API_KEY=sk-...

3. Ingest PDF

Bỏ file .pdf vào documents/, sau đó chạy:

python ingest.py

Các lệnh hữu ích khác:

python ingest.py --reset          # xoá index cũ, ingest lại từ đầu
python ingest.py --force          # ingest lại tất cả kể cả file không đổi
python ingest.py --dir /path/khac # ingest từ thư mục khác

Chạy lại python ingest.py bất cứ khi nào thêm/sửa file PDF — script tự động bỏ qua file không đổi (dựa trên hash nội dung), chỉ re-index file mới hoặc đã thay đổi.

Lưu ý chi phí: mỗi lần ingest gọi OpenAI Embedding API. Với vài trăm file PDF, chi phí text-embedding-3-small thường dưới $1.

4. Chạy thử server local

python server.py

Mặc định lắng nghe tại http://0.0.0.0:8000/mcp, có endpoint kiểm tra sống tại http://localhost:8000/health.

Đổi port bằng biến môi trường: PORT=8080 python server.py

Test bằng MCP Inspector:

npx @modelcontextprotocol/inspector http://localhost:8000/mcp

5. Deploy lên cloud + kết nối vào Claude

Xem hướng dẫn chi tiết trong DEPLOY.md — deploy lên Railway, lấy public URL, rồi add qua Claude → Settings → Connectors → Add custom connector.

Quy trình cập nhật dữ liệu

Local: chạy lại python ingest.py sau khi thêm/sửa PDF trong documents/.

Cloud (Railway): ingest được thực hiện trong lúc build Docker image — push code/PDF mới rồi redeploy (chi tiết trong DEPLOY.md).

Giới hạn hiện tại

• Chỉ đọc PDF dạng text; PDF scan (ảnh) sẽ bị bỏ qua với cảnh báo.
• Xoá file khỏi documents/ không tự động xoá khỏi index — cần chạy python ingest.py --reset để làm sạch hoàn toàn.
• Không có xác thực — chỉ nên deploy cho môi trường nội bộ tin cậy, hoặc đặt sau 1 lớp bảo vệ khác (VPN, IP allowlist...).