# 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

이 프로젝트는 자유롭게 수정 및 확장하여 사용할 수 있는 샘플 코드입니다.