PDF RAG MCP 서버
PDF 처리, 벡터 저장, 그리고 MCP(모델 컨텍스트 프로토콜)를 활용하여 PDF 문서에 대한 의미론적 검색 기능을 제공하는 강력한 문서 지식 기반 시스템입니다. 이 시스템을 사용하면 최신 웹 인터페이스 또는 MCP 프로토콜을 통해 PDF 문서를 업로드, 처리 및 쿼리할 수 있으며, Cursor와 같은 AI 도구와 통합할 수 있습니다.
특징
- PDF 문서 업로드 및 처리 : PDF를 업로드하고 콘텐츠를 자동으로 추출, 청크화 및 벡터화합니다.
- 실시간 처리 상태 : 문서 처리 중 WebSocket 기반 실시간 상태 업데이트
- 의미 검색 : 처리된 모든 문서에 대한 벡터 기반 의미 검색
- MCP 프로토콜 지원 : 모델 컨텍스트 프로토콜을 사용하여 Cursor와 같은 AI 도구와 통합
- 최신 웹 인터페이스 : 문서 관리 및 쿼리를 위한 React/Chakra UI 프런트엔드
- 빠른 종속성 관리 : 효율적인 Python 종속성 관리를 위해 uv를 사용합니다.
시스템 아키텍처
이 시스템은 다음으로 구성됩니다.
- FastAPI 백엔드 : API 요청, PDF 처리 및 벡터 저장을 처리합니다.
- React Frontend : 문서 관리를 위한 사용자 친화적인 인터페이스를 제공합니다.
- 벡터 데이터베이스 : 의미 검색을 위한 임베딩을 저장합니다.
- WebSocket 서버 : 문서 처리에 대한 실시간 업데이트를 제공합니다.
- MCP 서버 : MCP 호환 클라이언트에 지식 기반을 공개합니다.
빠른 시작
필수 조건
- 파이썬 3.8 이상
- uv - 빠른 Python 패키지 설치 및 확인 프로그램
- 깃
- 커서(선택 사항, MCP 통합용)
uv와 run.py를 이용한 빠른 설치 및 시작
- 저장소를 복제합니다.지엑스피1
- 아직 uv가 없다면 설치하세요:
curl -sS https://astral.sh/uv/install.sh | bash
- uv를 사용하여 종속성을 설치합니다.
uv init .
uv venv
source .venv/bin/activate
uv pip install -r backend/requirements.txt
- 편리한 스크립트로 애플리케이션을 시작하세요:
- http://localhost:8000 에서 웹 인터페이스에 접속하세요
- 커서와 함께 사용
설정 -> 커서 설정 -> MCP -> 새 글로벌 MCP 서버 추가로 이동하여 아래 내용을 커서 ~/.cursor/mcp.json 파일에 붙여넣으세요. 자세한 내용은 커서 MCP 문서를 참조하세요.
{
"mcpServers": {
"pdf-rag": {
"url": "http://localhost:7800/mcp"
}
}
}
localhost를 서비스를 배포한 호스트 IP 주소로 변경할 수도 있습니다. 이 구성을 mcp json 파일에 추가하면 Cursor mcp 설정 페이지에 mcp 서버가 표시됩니다. 서버를 활성화하려면 해당 설정을 켜세요.
프런트엔드 구축(개발자용)
프런트엔드를 다시 빌드해야 하는 경우 두 가지 옵션이 있습니다.
옵션 1: 제공된 스크립트 사용(권장)
# Make the script executable if needed
chmod +x build_frontend.py
# Run the script
./build_frontend.py
이 스크립트는 자동으로 다음을 수행합니다.
- 프런트엔드 종속성 설치
- 프런트엔드를 구축하다
- 빌드 출력을 백엔드의 정적 디렉토리에 복사합니다.
옵션 2: 수동 빌드 프로세스
# Navigate to frontend directory
cd frontend
# Install dependencies
npm install
# Build the frontend
npm run build
# Create static directory if it doesn't exist
mkdir -p ../backend/static
# Copy build files
cp -r dist/* ../backend/static/
프런트엔드를 빌드한 후 run.py 스크립트를 사용하여 애플리케이션을 시작할 수 있습니다.
간단한 생산 설정
정적 파일이 이미 빌드된 프로덕션 환경의 경우:
- 미리 빌드된 프런트엔드를
backend/static 디렉토리에 넣으세요. - 서버를 시작합니다:
cd backend
uv pip install -r requirements.txt
python -m app.main
개발 설정(별도 서비스)
개발을 위해 서비스를 별도로 실행하려는 경우:
백엔드
- 백엔드 디렉토리로 이동합니다.
- uv를 사용하여 종속성을 설치합니다.
uv pip install -r requirements.txt
- 백엔드 서버를 실행합니다.
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
프런트엔드
- 프런트엔드 디렉토리로 이동합니다.
- 종속성을 설치합니다.
- 개발 서버를 실행합니다.
용법
문서 업로드
- http://localhost:8000 에서 웹 인터페이스에 접속하세요
- "새 PDF 업로드"를 클릭하고 PDF 파일을 선택하세요
- 시스템은 파일을 처리하고 실시간으로 진행 상황을 표시합니다.
- 처리가 완료되면 문서를 검색할 수 있습니다.
문서 검색
- 웹 인터페이스에서 검색 기능을 사용하세요
- 또는 MCP 프로토콜을 사용하여 Cursor와 통합합니다.
커서와 MCP 통합
- 커서 열기
- 설정 → AI 및 MCP로 이동하세요
- URL:
http://localhost:8000/mcp/v1 사용하여 사용자 정의 MCP 서버를 추가합니다. - 설정을 저장하세요
- 이제 Cursor에서 직접 PDF 지식 기반을 쿼리할 수 있습니다.
문제 해결
연결 문제
- 포트 8000이 다른 애플리케이션에서 사용되고 있지 않은지 확인하세요.
- WebSocket 연결이 제대로 작동하는지 확인하세요
- 브라우저가 WebSockets를 지원하는지 확인하세요.
처리 문제
- PDF에 추출 가능한 텍스트가 포함되어 있는지 확인하세요(일부 스캔한 PDF에는 포함되어 있지 않을 수 있음)
- 시스템에 충분한 리소스(메모리 및 CPU)가 있는지 확인하세요.
- 자세한 오류 메시지는 백엔드 로그에서 확인하세요.
프로젝트 구조
PdfRagMcpServer/
├── backend/ # FastAPI backend
│ ├── app/
│ │ ├── __init__.py
│ │ ├── main.py # Main FastAPI application
│ │ ├── database.py # Database models
│ │ ├── pdf_processor.py # PDF processing logic
│ │ ├── vector_store.py # Vector database interface
│ │ └── websocket.py # WebSocket handling
│ ├── static/ # Static files for the web interface
│ └── requirements.txt # Backend dependencies
├── frontend/ # React frontend
│ ├── public/
│ ├── src/
│ │ ├── components/ # UI components
│ │ ├── context/ # React context
│ │ ├── pages/ # Page components
│ │ └── App.jsx # Main application component
│ ├── package.json # Frontend dependencies
│ └── vite.config.js # Vite configuration
├── uploads/ # PDF file storage
└── README.md # This documentation
기여하다
기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.
특허
이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.