PDF RAG MCP 서버

PDF 처리, 벡터 저장, 그리고 MCP(모델 컨텍스트 프로토콜)를 활용하여 PDF 문서에 대한 의미론적 검색 기능을 제공하는 강력한 문서 지식 기반 시스템입니다. 이 시스템을 사용하면 최신 웹 인터페이스 또는 MCP 프로토콜을 통해 PDF 문서를 업로드, 처리 및 쿼리할 수 있으며, Cursor와 같은 AI 도구와 통합할 수 있습니다.

특징

PDF 문서 업로드 및 처리 : PDF를 업로드하고 콘텐츠를 자동으로 추출, 청크화 및 벡터화합니다.
실시간 처리 상태 : 문서 처리 중 WebSocket 기반 실시간 상태 업데이트
의미 검색 : 처리된 모든 문서에 대한 벡터 기반 의미 검색
MCP 프로토콜 지원 : 모델 컨텍스트 프로토콜을 사용하여 Cursor와 같은 AI 도구와 통합
최신 웹 인터페이스 : 문서 관리 및 쿼리를 위한 React/Chakra UI 프런트엔드
빠른 종속성 관리 : 효율적인 Python 종속성 관리를 위해 uv를 사용합니다.

Related MCP server: FastGPT Knowledge Base MCP

시스템 아키텍처

이 시스템은 다음으로 구성됩니다.

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
편리한 스크립트로 애플리케이션을 시작하세요:
uv run run.py
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

개발 설정(별도 서비스)

개발을 위해 서비스를 별도로 실행하려는 경우:

백엔드

백엔드 디렉토리로 이동합니다.
cd backend
uv를 사용하여 종속성을 설치합니다.
uv pip install -r requirements.txt
백엔드 서버를 실행합니다.
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

프런트엔드

프런트엔드 디렉토리로 이동합니다.
cd frontend
종속성을 설치합니다.
npm install
개발 서버를 실행합니다.
npm run dev

용법

문서 업로드

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 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

PDF RAG MCP Server