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
-
Search
openai.vector_stores.search()호출- 연관 문서 목록 반환
-
Fetch
vector_stores.files.content()로 전체 텍스트 조각 가져오기vector_stores.files.retrieve()로 메타데이터 조회- 하나의 문서로 병합해 반환
-
Server
- FastMCP로 MCP-compliant 서버 생성
- ChatGPT MCP 연결 모드에서 사용 가능
📝 Logging
기본 로그 레벨은 INFO로 설정되어 있으며, 검색/조회 요청과 서버 시작 정보를 출력합니다.
📄 License
이 프로젝트는 자유롭게 수정 및 확장하여 사용할 수 있는 샘플 코드입니다.