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 설치

git clone <your-repo-url>
cd <project-folder>

2. 가상환경 생성(선택)

python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

3. Dependencies 설치

pip install -r requirements.txt

4. .env 파일 생성

프로젝트 루트에 .env 파일을 만들고 아래 내용을 추가합니다:

OPENAI_API_KEY=your_openai_api_key
VECTOR_STORE_ID=your_vector_store_id

🚀 Running the Server

아래 명령어로 MCP 서버를 실행합니다.

python server.py

서버는 기본적으로 다음 주소에서 SSE 기반 MCP 서버로 동작합니다:

http://0.0.0.0:8000

ChatGPT(또는 Deep Research mode)에서 MCP 서버를 등록하면 Search 및 Fetch 도구를 사용할 수 있습니다.

🛠️ Tools

🔍 search(query: str)

벡터 스토어에서 쿼리와 관련된 문서를 검색합니다.

Response 예시:

{
  "results": [
    {
      "id": "file-xxxxx",
      "title": "example.pdf",
      "text": "문서의 앞부분 200자...",
      "url": "https://platform.openai.com/storage/files/file-xxxxx"
    }
  ]
}

📄 fetch(id: str)

문서의 ID를 받아 전체 내용을 반환합니다.

Response 예시:

{
  "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

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