Skip to main content
Glama
nguyenkhanhtoan-ai

mcp-rag

by nguyenkhanhtoan-ai
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Hybrid

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...).