# 📝 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 서버 개발 템플릿입니다.**