README.md•3.49 kB
# Sample MCP Server
이 프로젝트는 **Model Context Protocol (MCP)** 을 활용하여 ChatGPT와 연동되는 **검색(Search)** 및 **문서 조회(Fetch)** 기능을 제공하는 샘플 서버입니다.
OpenAI Vector Store를 사용하여 문서 검색 및 전체 내용을 조회할 수 있으며, ChatGPT의 Deep Research 및 Chat Connectors 기능과 함께 사용할 수 있습니다.
---
## ✨ Features
- **Semantic Search**
OpenAI Vector Store를 사용한 벡터 기반 문서 검색
자연어 쿼리를 지원하며 연관 문서를 스니펫 형태로 반환합니다.
- **Document Fetch**
검색된 문서의 ID로 전체 내용을 조회
파일명, 본문 텍스트, URL, 메타데이터 포함
- **FastMCP 기반 MCP 서버**
ChatGPT MCP 표준에 맞춰 작성된 경량 서버
SSE(Server-Sent Events)를 사용하여 ChatGPT와 통신
- **환경 변수 기반 설정**
`.env` 파일로 API Key, Vector Store ID 관리
---
## 📁 Project Structure
```
.
├── server.py
├── requirements.txt
└── .env (사용자가 직접 생성)
```
---
## 🔧 Requirements
Python 3.9+
설치 패키지는 `requirements.txt` 에 정의되어 있습니다.
예시:
```
fastmcp
openai
python-dotenv
```
---
## ⚙️ Setup
### 1. Repository 설치
```bash
git clone <your-repo-url>
cd <project-folder>
```
### 2. 가상환경 생성(선택)
```bash
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
```
### 3. Dependencies 설치
```bash
pip install -r requirements.txt
```
### 4. .env 파일 생성
프로젝트 루트에 `.env` 파일을 만들고 아래 내용을 추가합니다:
```env
OPENAI_API_KEY=your_openai_api_key
VECTOR_STORE_ID=your_vector_store_id
```
---
## 🚀 Running the Server
아래 명령어로 MCP 서버를 실행합니다.
```bash
python server.py
```
서버는 기본적으로 다음 주소에서 SSE 기반 MCP 서버로 동작합니다:
```
http://0.0.0.0:8000
```
ChatGPT(또는 Deep Research mode)에서 MCP 서버를 등록하면 Search 및 Fetch 도구를 사용할 수 있습니다.
---
## 🛠️ Tools
### 🔍 search(query: str)
벡터 스토어에서 쿼리와 관련된 문서를 검색합니다.
**Response 예시:**
```json
{
"results": [
{
"id": "file-xxxxx",
"title": "example.pdf",
"text": "문서의 앞부분 200자...",
"url": "https://platform.openai.com/storage/files/file-xxxxx"
}
]
}
```
---
### 📄 fetch(id: str)
문서의 ID를 받아 전체 내용을 반환합니다.
**Response 예시:**
```json
{
"id": "file-xxxxx",
"title": "example.pdf",
"text": "문서 전체 내용...",
"url": "https://platform.openai.com/storage/files/file-xxxxx",
"metadata": {}
}
```
---
## 📚 How It Works
1. **Search**
- `openai.vector_stores.search()` 호출
- 연관 문서 목록 반환
2. **Fetch**
- `vector_stores.files.content()` 로 전체 텍스트 조각 가져오기
- `vector_stores.files.retrieve()` 로 메타데이터 조회
- 하나의 문서로 병합해 반환
3. **Server**
- FastMCP로 MCP-compliant 서버 생성
- ChatGPT MCP 연결 모드에서 사용 가능
---
## 📝 Logging
기본 로그 레벨은 INFO로 설정되어 있으며, 검색/조회 요청과 서버 시작 정보를 출력합니다.
---
## 📄 License
이 프로젝트는 자유롭게 수정 및 확장하여 사용할 수 있는 샘플 코드입니다.