External Data 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. 가상 환경 생성 및 활성화:

cd mcp_server
python3.10 -m venv .venv

# macOS/Linux
source .venv/bin/activate

# Windows
.venv\Scripts\activate

2. 의존성 설치:

pip install -r requirements.txt

실행 방법

간편 실행 (권장)

./start_mcp_server.sh

서버가 http://localhost:3000/sse에서 시작됩니다.

직접 실행

# 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으로 연결:

{
  "mcp_server": {
    "url": "http://localhost:3000/sse",
    "type": "sse",
    "enabled": true,
    "timeout": 30
  }
}

원격 서버 사용

{
  "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):

{
  "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 서버의 능력을 조회합니다.

입력: 없음

출력:

{
  "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): 경도

출력:

{
  "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)

출력:

[
  {
    "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): 검색 키워드 리스트

출력:

{
  "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): 검색 키워드 리스트

출력:

{
  "weather": {...},
  "history": [...],
  "infrastructure": {...}
}

테스트

서버 상태 확인

# 서버가 실행 중인지 확인
curl http://localhost:3000/sse

Agentic AI에서 테스트

# 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 연동

문제 해결

포트 충돌

# 3000번 포트 사용 중인 프로세스 확인
lsof -i :3000

# 프로세스 종료
kill -9 <PID>

연결 실패

ConnectionError: MCP 서버에 연결할 수 없습니다

해결:

1. MCP 서버가 실행 중인지 확인
2. mcp_config.json의 URL 확인
3. 방화벽 설정 확인

라이선스

MIT License - 자유롭게 사용, 수정, 배포 가능

• longitude (number): 경도
• keywords (array): 검색 키워드 리스트

출력:

{
  "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 클라이언트로 업데이트하여 이 서버를 호출하도록 수정할 수 있습니다.

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

라이선스

내부 사용 목적