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 서버)

설치 방법

가상 환경 생성 및 활성화:

cd mcp_server
python3.10 -m venv .venv

# macOS/Linux
source .venv/bin/activate

# Windows
.venv\Scripts\activate

의존성 설치:

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 서버에 연결할 수 없습니다

해결:

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

라이선스

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

라이선스

내부 사용 목적

External Data MCP Server

External Data MCP Server

개요

특징

요구 사항

설치 방법

실행 방법

간편 실행 (권장)

직접 실행

아키텍처

SSE 방식 (현재)

장점

클라이언트 설정

원격 서버 사용

레거시: Claude Desktop 설정 (stdio 방식)

제공 도구 (Tools)

1. get_server_capabilities

2. get_weather_info

3. get_report_history

4. get_infrastructure_status

5. fetch_all_data

테스트

서버 상태 확인

Agentic AI에서 테스트

프로젝트 구조

확장 가능성

문제 해결

포트 충돌

연결 실패

라이선스

아키텍처

통합 방법

Python 애플리케이션에서 사용

향후 개선 사항

라이선스

Reviews