# External Data MCP Server
신고 접수 시스템의 외부 데이터 조회 기능을 Model Context Protocol (MCP)로 제공하는 **독립 실행 HTTP 서버**입니다.
## 개요
이 MCP 서버는 **SSE (Server-Sent Events)** 방식으로 동작하는 독립 HTTP 서버입니다:
- **기상 정보 조회**: 위치 기반 현재 기상 정보
- **신고 이력 조회**: 주변 지역의 과거 신고 이력
- **인프라 상태 조회**: 해당 지역의 인프라 상태 정보
- **통합 데이터 조회**: 위 모든 데이터를 한 번에 조회
- **서버 능력 조회**: MCP 서버가 제공하는 도구 목록
## 특징
- ✅ **독립 실행**: subprocess가 아닌 완전히 별도의 HTTP 서버
- ✅ **SSE 통신**: Server-Sent Events를 통한 표준 HTTP 통신
- ✅ **설정 기반**: 클라이언트는 config.json으로 서버 연결
- ✅ **다중 클라이언트**: 여러 클라이언트가 동시 연결 가능
- ✅ **원격 지원**: 네트워크를 통한 원격 서버 연결 가능
## 요구 사항
- Python 3.10 이상
- MCP SDK
- sse-starlette (SSE 지원)
- uvicorn (ASGI 서버)
## 설치 방법
1. 가상 환경 생성 및 활성화:
```bash
cd mcp_server
python3.10 -m venv .venv
# macOS/Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activate
```
2. 의존성 설치:
```bash
pip install -r requirements.txt
```
## 실행 방법
### 간편 실행 (권장)
```bash
./start_mcp_server.sh
```
서버가 `http://localhost:3000/sse`에서 시작됩니다.
### 직접 실행
```bash
# SSE 서버 (독립 실행 - 권장)
python server_sse.py
# 또는 stdio 서버 (레거시, subprocess 전용)
python server.py
```
## 아키텍처
### SSE 방식 (현재)
```
MCP Server (독립 프로세스)
↓ HTTP Server (localhost:3000)
↓ SSE Protocol
Agentic AI Client
↓ HTTP Request
Config: mcp_config.json
```
### 장점
- 서버가 24/7 독립 실행
- 여러 클라이언트 동시 연결
- 표준 HTTP 프로토콜
- 원격 서버 지원
- 설정 파일로 관리
## 클라이언트 설정
Agentic AI 클라이언트는 `config/mcp_config.json`으로 연결:
```json
{
"mcp_server": {
"url": "http://localhost:3000/sse",
"type": "sse",
"enabled": true,
"timeout": 30
}
}
```
### 원격 서버 사용
```json
{
"mcp_server": {
"url": "http://production-server.com:3000/sse",
...
}
}
```
## 레거시: Claude Desktop 설정 (stdio 방식)
기존 stdio 방식 `server.py`를 Claude Desktop에서 사용하는 경우:
`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
```json
{
"mcpServers": {
"external-data-connector": {
"command": "/Users/swkeum/work/mcp_server/.venv/bin/python",
"args": ["/Users/swkeum/work/mcp_server/server.py"]
}
}
}
```
> **Note**: Agentic AI는 SSE 방식(`server_sse.py`)을 사용하므로 Claude Desktop 설정이 필요 없습니다.
## 제공 도구 (Tools)
### 1. get_server_capabilities
MCP 서버의 능력을 조회합니다.
**입력:** 없음
**출력:**
```json
{
"server_name": "external-data-connector",
"version": "1.0.0",
"transport": "sse",
"capabilities": {
"tools": [...],
"data_sources": ["weather", "history", "infrastructure"]
}
}
```
### 2. get_weather_info
기상 정보를 조회합니다.
**입력:**
- `latitude` (number): 위도
- `longitude` (number): 경도
**출력:**
```json
{
"temperature": 15.5,
"humidity": 65,
"rainfall": 0.0,
"wind_speed": 3.2,
"conditions": "맑음",
"forecast_3h": {
"temperature": 14.0,
"rainfall_probability": 10
}
}
```
### 3. get_report_history
과거 신고 이력을 조회합니다.
**입력:**
- `latitude` (number): 위도
- `longitude` (number): 경도
- `keywords` (array): 검색 키워드 리스트
- `radius_km` (number, optional): 검색 반경 (기본값: 1.0)
**출력:**
```json
[
{
"report_id": "R001",
"date": "2024-01-15",
"keywords": ["빗물받이", "막힘"],
"risk_level": "보통",
"status": "처리완료",
"distance_km": 0.3
}
]
```
### 4. get_infrastructure_status
주변 인프라 상태를 조회합니다.
**입력:**
- `latitude` (number): 위도
- `longitude` (number): 경도
- `keywords` (array): 검색 키워드 리스트
**출력:**
```json
{
"drainage_system": {
"status": "정상",
"last_maintenance": "2024-01-01",
"capacity_usage": 45
},
"road_conditions": {
"status": "양호",
"recent_repairs": 2
},
"nearby_facilities": [...]
}
```
### 5. fetch_all_data
모든 외부 데이터를 한 번에 조회합니다.
**입력:**
- `latitude` (number): 위도
- `longitude` (number): 경도
- `keywords` (array): 검색 키워드 리스트
**출력:**
```json
{
"weather": {...},
"history": [...],
"infrastructure": {...}
}
```
## 테스트
### 서버 상태 확인
```bash
# 서버가 실행 중인지 확인
curl http://localhost:3000/sse
```
### Agentic AI에서 테스트
```bash
# Agentic AI API를 통해 MCP 능력 조회
curl http://localhost:8000/api/v1/mcp/capabilities
```
## 프로젝트 구조
```
mcp_server/
├── server.py # Stdio 방식 MCP 서버 (레거시)
├── server_sse.py # SSE 방식 MCP 서버 (현재)
├── start_mcp_server.sh # 서버 시작 스크립트
├── requirements.txt # 의존성
├── README.md # 이 파일
├── SSE_GUIDE.md # SSE 방식 상세 가이드
└── .venv/ # 가상 환경
```
## 확장 가능성
현재는 더미 데이터를 반환하지만, 실제 외부 API와 연동 가능:
- **기상 API**: 기상청 API, OpenWeatherMap 등
- **데이터베이스**: PostgreSQL, MongoDB 등에서 실제 신고 이력 조회
- **인프라 시스템**: IoT 센서, 관리 시스템 API 연동
## 문제 해결
### 포트 충돌
```bash
# 3000번 포트 사용 중인 프로세스 확인
lsof -i :3000
# 프로세스 종료
kill -9 <PID>
```
### 연결 실패
```
ConnectionError: MCP 서버에 연결할 수 없습니다
```
해결:
1. MCP 서버가 실행 중인지 확인
2. `mcp_config.json`의 URL 확인
3. 방화벽 설정 확인
## 라이선스
MIT License - 자유롭게 사용, 수정, 배포 가능
- `longitude` (number): 경도
- `keywords` (array): 검색 키워드 리스트
**출력:**
```json
{
"weather": { /* 기상 정보 */ },
"history": [ /* 신고 이력 */ ],
"infrastructure": { /* 인프라 상태 */ },
"query_timestamp": "2026-02-02T10:30:00"
}
```
## 아키텍처
```
┌─────────────────────┐
│ MCP Client │
│ (Claude Desktop 등) │
└──────────┬──────────┘
│ MCP Protocol
│ (stdio)
┌──────────▼──────────┐
│ MCP Server │
│ (server.py) │
├─────────────────────┤
│ - get_weather_info │
│ - get_report_history│
│ - get_infrastructure│
│ - fetch_all_data │
└──────────┬──────────┘
│
▼
[External APIs]
(향후 실제 API 연동)
```
## 통합 방법
### Python 애플리케이션에서 사용
agentic_ai 프로젝트의 `external_data_connector.py`를 MCP 클라이언트로 업데이트하여 이 서버를 호출하도록 수정할 수 있습니다.
```python
from mcp.client import Client
# MCP 클라이언트로 서버에 연결
client = Client(server_path="server.py")
# 기상 정보 조회
result = await client.call_tool("get_weather_info", {
"latitude": 37.5665,
"longitude": 126.9780
})
```
## 향후 개선 사항
- [ ] 실제 기상 API 연동 (예: 기상청 API)
- [ ] 실제 데이터베이스 연동 (PostgreSQL/MongoDB)
- [ ] 인증 및 권한 관리
- [ ] 캐싱 레이어 추가
- [ ] 에러 핸들링 강화
- [ ] 로깅 시스템 추가
- [ ] 성능 모니터링
- [ ] Rate limiting
## 라이선스
내부 사용 목적
