FastAPI + OpenAI + MCP 기반 RAG Assistant

이 프로젝트는 다음 기능을 하나의 PyCharm 프로젝트에서 단계적으로 확인하기 위한 교육용 예제입니다.

• OpenAI GPT 질의응답
• MCP Tool 호출
• MCP Resource 제공
• MCP Prompt 제공
• 안전한 파일 시스템 접근
• MySQL 데이터 저장 및 조회
• FAISS 또는 Qdrant Vector Search
• RAG 문서 검색과 근거 기반 답변
• FastAPI REST API

1. 프로젝트 구조

mcp_rag_project/
├── app/
│   ├── main.py
│   ├── routers/
│   ├── services/
│   ├── tools/
│   ├── vectordb/
│   ├── llm/
│   └── config/
├── mcp_server/
│   ├── server.py
│   ├── tools.py
│   └── resources.py
├── docs/
├── data/
├── requirements.txt
├── .env.example
└── README.md

2. 권장 실행 환경

• Windows 11
• Python 3.11
• PyCharm
• 선택 사항: MySQL 8.x
• 선택 사항: Qdrant Docker 서버
• 선택 사항: Node.js(MCP Inspector 실행 시)

3. 설치

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip setuptools wheel
pip install -r requirements.txt
Copy-Item .env.example .env

기본 설정은 다음과 같으므로 API 키나 외부 DB 없이도 인덱싱과 검색 구조를 확인할 수 있습니다.

EMBEDDING_BACKEND=local
VECTOR_BACKEND=faiss
MYSQL_ENABLED=false

실제 OpenAI GPT와 임베딩을 사용하려면 .env를 수정합니다.

OPENAI_API_KEY=발급받은_API_KEY
EMBEDDING_BACKEND=openai

4. FastAPI 실행

python -m app.main

또는 다음과 같이 실행합니다.

uvicorn app.main:app --reload

접속 주소:

• 안내 화면: http://127.0.0.1:8000
• Swagger: http://127.0.0.1:8000/docs
• 상태 확인: http://127.0.0.1:8000/api/health

5. RAG 실행 순서

Swagger에서 다음 순서로 실행합니다.

1. POST /api/rag/rebuild
2. POST /api/rag/search
3. POST /api/rag/ask

검색 예:

{
  "query": "MCP의 Tool과 Resource 차이는?",
  "top_k": 4
}

RAG 질문 예:

{
  "question": "MCP의 주요 구성 요소를 설명해줘.",
  "top_k": 4
}

6. MCP 서버 실행

FastAPI와 MCP 서버는 역할이 다르므로 별도 터미널에서 실행합니다.

python -m mcp_server.server

stdio 서버는 일반 웹 화면을 열지 않고 MCP Client의 연결을 기다립니다.

7. MCP Inspector 테스트

Node.js가 설치되어 있다면 다음 명령으로 MCP Tool, Resource, Prompt를 테스트합니다.

npx -y @modelcontextprotocol/inspector python -m mcp_server.server

Inspector에서 확인할 기능:

• Tools
  • add
  • list_document_files
  • read_document_file
  • vector_search
  • rebuild_rag_index
  • rag_question_answer
  • mysql_knowledge_list
• Resources
  • config://runtime
  • docs://catalog
• Prompts
  • grounded_rag_prompt

8. Qdrant local 모드

별도 Qdrant 서버 없이 프로젝트 폴더에 데이터를 저장합니다.

VECTOR_BACKEND=qdrant
QDRANT_MODE=local

설정 변경 후 FastAPI를 재시작하고 인덱스를 다시 구축합니다.

9. Qdrant server 모드

Docker에서 Qdrant를 실행합니다.

docker run -p 6333:6333 -p 6334:6334 -v qdrant_storage:/qdrant/storage qdrant/qdrant

.env 설정:

VECTOR_BACKEND=qdrant
QDRANT_MODE=server
QDRANT_URL=http://127.0.0.1:6333

10. MySQL 설정

root 계정으로 다음 SQL을 실행합니다.

CREATE DATABASE IF NOT EXISTS mcp_rag_db
CHARACTER SET utf8mb4
COLLATE utf8mb4_unicode_ci;

CREATE USER IF NOT EXISTS 'mcp_user'@'localhost'
IDENTIFIED BY '1234';

GRANT ALL PRIVILEGES ON mcp_rag_db.* TO 'mcp_user'@'localhost';

FLUSH PRIVILEGES;

.env를 수정합니다.

MYSQL_ENABLED=true
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_DATABASE=mcp_rag_db
MYSQL_USER=mcp_user
MYSQL_PASSWORD=1234

Swagger 실행 순서:

1. POST /api/mysql/init
2. POST /api/mysql/items
3. GET /api/mysql/items

11. 주의 사항

• local 임베딩은 API 키 없이 구조를 실습하기 위한 해시 기반 임베딩입니다.
• 의미 기반 검색 품질을 높이려면 OpenAI 임베딩을 사용합니다.
• stdio MCP 서버에서는 일반 print()를 stdout에 출력하지 않는 것이 안전합니다.
• 파일 Tool은 보안을 위해 docs 폴더 밖의 경로 접근을 차단합니다.
• MySQL API는 학습용 테이블만 사용하며 임의 SQL 실행 기능을 제공하지 않습니다.