# mcp-service

MCP(Model Context Protocol) 도구를 WebSocket으로 서빙하는 3계층 릴레이 서비스입니다.

## 아키텍처

```
[소비자] ──WS /call/──▶ [서버] ──WS /mcp/──▶ [파이프] ──stdio──▶ [도구]
```

| 계층 | 역할 | 진입점 |
|------|------|--------|
| **서버** | FastAPI WebSocket 릴레이, JSON-RPC ID 변환 | `python main.py server` |
| **파이프** | stdio ↔ WebSocket 양방향 연결, 자동 재연결 | `python main.py pipe` |
| **도구** | FastMCP 앱 (calculator, scripture, what_to_do) | subprocess (파이프가 자동 실행) |

## 빠른 시작

### 1. 환경 설정

```bash
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

### 2. 환경변수 설정

`.env` 파일을 프로젝트 루트에 생성:

```env
# 필수
MCP_SERVER_KEY=<서버/파이프가 공유하는 AES 키>
MCP_ENDPOINT=ws://localhost:2080/mcp_endpoint/mcp/

# 도구 사용 시 필요
GEMINI_API_KEY=your_gemini_api_key
KAKAO_API_KEY=your_kakao_api_key
```

> 통합 설치에서는 루트 `.env`의 `MCP_SERVER_KEY`를 사용합니다. 단독 실행 시 `main.py`가 로컬 `.env`를 생성하고 누락 값을 안내합니다.

### 3. 서버 실행

```bash
# 기본 모드: 서버와 파이프 동시 실행
python main.py

# 개별 실행
python main.py server   # 서버만 실행
python main.py pipe     # 파이프만 실행
```

## 설정

`mcp-service.cfg`로 서버 동작을 제어합니다. 민감한 키는 `.env`/환경변수에서 관리합니다.

```ini
[server]
host = 0.0.0.0
port = 2080
log_level = INFO

[websocket]
max_connections = 1000
ping_interval = 30
ping_timeout = 10

[security]
allowed_origins = *
enable_cors = true
```

## API

상세 계약은 루트 문서 [../docs/mcp/interface-contract.md](../docs/mcp/interface-contract.md)를 기준으로 확인합니다.

| 엔드포인트 | 설명 |
|-----------|------|
| `GET /` | 루트 |
| `GET /mcp_endpoint/` | 서버 상태 |
| `GET /mcp_endpoint/health?key=<server_key>` | 헬스 체크 |
| `WS /mcp_endpoint/mcp/?token=<token>` | 파이프 연결 |
| `WS /mcp_endpoint/call/?token=<token>` | 소비자 연결 |

토큰은 `MCP_SERVER_KEY`로 AES 암호화된 JSON 페이로드입니다. 현재 코드 기준 페이로드는 `{"agentId": "<name>"}` 형식입니다.

## MCP 도구

`mcp_config.json`에 등록된 도구를 파이프가 자동으로 subprocess로 실행합니다.

| 도구 | 설명 |
|------|------|
| `calculator` | Python 수식 계산 (`math`, `random` 모듈 지원) |
| `list_scriptures` | 종교 구절 목록 조회 (`bible`/`christian`, `catholic`, `buddhism`) |
| `get_scripture` | `list_scriptures`에서 받은 id로 본문과 해설 조회 |
| `recommend_what_to_do` | 위치 기반 음식/활동/숙박/관광 추천 (Gemini + Kakao) |

새 도구 추가 절차는 [../docs/mcp/adding-tools.md](../docs/mcp/adding-tools.md)를 따른다.

## 환경변수

| 변수 | 필수 | 설명 |
|------|------|------|
| `MCP_SERVER_KEY` | 파이프 필수 | AES 암호화 키 (서버 최초 실행 시 자동 생성) |
| `MCP_ENDPOINT` | 파이프 필수 | 서버 WebSocket 주소 |
| `MCP_PUBLIC_HOST` | 선택 | 서버 공개 호스트 오버라이드 |
| `MCP_CONFIG` | 선택 | mcp_config.json 커스텀 경로 |
| `GEMINI_API_KEY` | 도구 필수 | Google Gemini API 키 |
| `GEMINI_MODEL` | 선택 | Gemini 모델명 (기본: `gemini-2.5-flash-lite`) |
| `KAKAO_API_KEY` | 선택 | Kakao 로컬 API 키 |

## 테스트

```bash
pytest tests/ -v
```

서버 / 도구 / 파이프 / 유틸 계층 테스트를 포함한다.