Quote MCP Server

# 📝 Sample MCP Server **company-info-mcp 구조를 기반으로 한 샘플 MCP 서버**입니다. 이 프로젝트는 다른 MCP 프로젝트를 만들 때 참고할 수 있는 템플릿입니다. ## ✨ 주요 기능 - **랜덤 명언 조회**: 무료 Quote API를 사용하여 랜덤 명언 가져오기 - **명언 검색**: 키워드로 명언 검색 - **ID로 조회**: 특정 ID의 명언 조회 ## 🛠️ 기술 스택 - **MCP Framework**: FastMCP - **HTTP Server**: FastAPI - **Data Validation**: Pydantic - **HTTP Client**: Requests - **Caching**: cachetools (TTL 캐시) - **Environment**: Python-dotenv ## 📦 설치 및 설정 ### 1) 의존성 설치 ```bash pip install -r requirements.txt ``` ### 2) 환경 변수 설정 (선택) 프로젝트 루트에 `.env` 파일을 생성: ```bash cp env.example .env ``` `.env` 파일 내용: ```env LOG_LEVEL=INFO PORT=8098 ``` > 💡 이 예제는 무료 API를 사용하므로 API 키가 필요 없습니다. ### 3) 서버 실행 #### MCP 서버 모드 (stdio) ```bash python -m src.main ``` #### HTTP 서버 모드 ```bash HTTP_MODE=1 python -m src.main ``` HTTP 서버는 기본적으로 `http://localhost:8098`에서 실행됩니다. ## 🔌 MCP 클라이언트 설정 ### Claude Desktop `claude_desktop_config.json` 파일에 다음을 추가: **설정 파일 위치:** - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - **Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json` **설정 예시:** ```json { "mcpServers": { "sample-quote": { "command": "python", "args": ["-m", "src.main"], "cwd": "/path/to/sample-mcp-server", "env": { "LOG_LEVEL": "INFO" } } } } ``` ## 🧰 사용 가능한 MCP 도구 ### `health` 서비스 상태 확인 ### `get_random_quote_tool` 랜덤 명언을 조회합니다. ### `search_quotes_tool` 키워드로 명언을 검색합니다. **파라미터:** - `keyword` (필수): 검색할 키워드 - `limit` (선택): 결과 개수 (기본값: 10, 최대: 50) ### `get_quote_by_id_tool` ID로 특정 명언을 조회합니다. **파라미터:** - `quote_id` (필수): 인용구 ID ## 📡 HTTP API 엔드포인트 HTTP 모드로 실행 시 다음 엔드포인트를 사용할 수 있습니다: ### Health Check ```bash GET /health POST /health ``` ### 도구 목록 조회 ```bash GET /tools ``` ### 도구 실행 ```bash POST /tools/{tool_name} Content-Type: application/json { "keyword": "success", "limit": 5, "env": { "QUOTE_API_KEY": "your_api_key" } } ``` ## 🏗️ 프로젝트 구조 ``` sample-mcp-server/ ├── src/ │ ├── __init__.py │ ├── main.py # FastMCP 서버 + FastAPI HTTP 엔드포인트 │ └── tools.py # 실제 API 호출 로직 ├── requirements.txt ├── pyproject.toml ├── env.example └── README.md ``` ## 📚 이 프로젝트를 참고하여 새 MCP 만들기 1. 이 프로젝트를 복사하여 새 프로젝트 생성 2. `src/main.py`에서 도구 정의 수정 3. `src/tools.py`에서 실제 API 호출 로직 구현 4. `pyproject.toml`에서 프로젝트명 변경 5. `requirements.txt`에 필요한 의존성 추가 6. `env.example`에 필요한 환경 변수 추가 ## 🔑 API 키 우선순위 MCP 서버는 다음 순서로 API 키를 찾습니다: 1. **우선순위 1**: `arguments.env.QUOTE_API_KEY` (메인 서버에서 받은 키) 2. **우선순위 2**: `.env` 파일의 `QUOTE_API_KEY` (로컬 개발용) ## 📄 라이선스 MIT License --- **이 프로젝트는 MCP 서버 개발 템플릿입니다.**