Parking Information MCP Server

# 주차장 정보 조회 MCP 서버 fastMCP를 사용하여 전국 주차장 정보를 조회하는 MCP (Model Context Protocol) 서버입니다. ## 주요 특징 - **전국 주차장 검색**: 카카오 로컬 API를 통한 전국 주차장 검색 - **지역별 정보 제공**: 서울/경기 지역은 실시간 정보 및 상세 정보 제공 - **실시간 주차 정보**: 서울 지역 실시간 주차 가능 대수 제공 - **운영 시간 및 요금 정보**: 서울/경기 지역 운영 시간 및 요금 정보 제공 - **사용자 친화적 에러 메시지**: 기술적 용어 없이 명확한 안내 메시지 ## 개발 환경 설정 (Windows) ### 1. Python 가상환경 생성 PowerShell에서 다음 명령어를 실행하세요: ```powershell # Python 3.8 이상이 설치되어 있어야 합니다 python --version # 가상환경 생성 python -m venv venv # 가상환경 활성화 .\venv\Scripts\Activate.ps1 ``` **참고**: PowerShell 실행 정책 오류가 발생하는 경우: ```powershell Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser ``` 또는 Command Prompt(cmd)를 사용하는 경우: ```cmd venv\Scripts\activate.bat ``` ### 2. 필요한 라이브러리 설치 가상환경이 활성화된 상태에서: ```powershell pip install --upgrade pip pip install -r requirements.txt ``` ### 3. 환경 변수 설정 `.env.example` 파일을 참고하여 `.env` 파일을 생성하세요: ```powershell copy .env.example .env ``` 그리고 `.env` 파일을 열어서 실제 API 키를 입력하세요. **참고**: `.env.example` 파일이 없는 경우 `env.example` 파일을 참고하세요. ## 프로젝트 구조 ``` parking-mcp2/ ├── venv/ # 가상환경 (gitignore됨) ├── .env # 환경 변수 (gitignore됨) ├── env.example # 환경 변수 예시 ├── .gitignore ├── requirements.txt # Python 의존성 ├── README.md ├── test_api.py # API 클라이언트 테스트 ├── test_api_call.py # 실제 API 호출 테스트 ├── test_server.py # 서버 구조 테스트 └── src/ # 소스 코드 ├── __init__.py ├── server.py # MCP 서버 메인 파일 └── api_clients/ # API 클라이언트 모듈 ├── __init__.py ├── kakao_local.py # 카카오 로컬 API (주요 검색 API) ├── seoul_data.py # 서울 열린데이터 (서울 실시간 정보) └── gyeonggi_data.py # 경기데이터드림 (경기 실시간 정보) ``` ## API 키 발급 방법 ### 1. 카카오 로컬 API 키 1. [카카오 개발자 콘솔](https://developers.kakao.com/) 접속 2. 애플리케이션 생성 3. **앱 설정 > 앱 키**에서 **REST API 키** 복사 4. **제품 설정 > 카카오 로그인** 활성화 (필수) 5. **제품 설정 > 로컬** 활성화 (필수) 6. `.env` 파일에 `KAKAO_REST_API_KEY`에 입력 **주의**: "OPEN_MAP_AND_LOCAL" 서비스가 활성화되어 있어야 합니다. ### 2. 서울 열린데이터 API 키 1. [서울 열린데이터 광장](https://data.seoul.go.kr/) 접속 2. 회원가입 및 로그인 3. **마이페이지 > 인증키 관리**에서 인증키 발급 4. `.env` 파일에 `SEOUL_DATA_API_KEY`에 입력 **사용 API**: - `GetParkingInfo`: 서울시 공영주차장 실시간 정보 ### 3. 경기데이터드림 API 키 1. [경기데이터드림](https://data.gg.go.kr/) 접속 2. 회원가입 및 로그인 3. **마이페이지 > 인증키 관리**에서 인증키 발급 4. `.env` 파일에 `GYEONGGI_DATA_API_KEY`에 입력 **사용 API**: - `ParkingPlace`: 경기도 공영주차장 정보 ## 사용 방법 ### 서버 실행 ```powershell # 가상환경 활성화 .\venv\Scripts\Activate.ps1 # 서버 실행 (모듈로 실행) $env:PYTHONPATH="src"; python -m src.server ``` ### MCP 서버 연결 MCP 클라이언트에서 다음과 같이 연결하세요: ```json { "mcpServers": { "parking-mcp": { "command": "python", "args": ["-m", "src.server"], "env": { "PYTHONPATH": "src" } } } } ``` ### 테스트 ```powershell # API 클라이언트 초기화 테스트 python test_api.py # 실제 API 호출 테스트 (카카오 API) python test_api_call.py # 서버 구조 테스트 python test_server.py ``` ## 주요 기능 ### 제공하는 Tool 함수 1. **search_nearby_parking** - 주변 주차장 검색 (카카오 로컬 API 사용) - 좌표 기반 검색 (위도, 경도, 반경) - 지역별 정보 자동 추가 (서울/경기/기타) **파라미터:** - `latitude`: 위도 (필수) - `longitude`: 경도 (필수) - `radius`: 검색 반경 미터 (기본값: 1000) 2. **get_parking_info** - 특정 주차장 상세 정보 조회 - 주차장 이름 또는 주소로 검색 - 지역별 실시간 정보 자동 추가 **파라미터:** - `parking_id`: 주차장 이름 또는 주소 (필수) ### 지역별 제공 정보 | 정보 | 서울 | 경기 | 기타 | |------|------|------|------| | 기본 정보 (이름, 주소) | ✅ | ✅ | ✅ | | 총 주차 대수 | ✅ | ✅ | ❌ | | 실시간 주차 가능 대수 | ✅ | ❌ | ❌ | | 운영 시간 | ✅ | ✅ | ❌ | | 요금 정보 | ✅ | ✅ | ❌ | | 업데이트 시간 | ✅ | ❌ | ❌ | **서울 지역:** - 실시간 주차 가능 대수 제공 - 상세 운영 시간 (평일/주말/공휴일) - 상세 요금 정보 (기본 요금, 추가 요금, 일일 최대 요금 등) - 실시간 정보 업데이트 시간 **경기 지역:** - 총 주차 대수 제공 - 운영 시간 (평일/토요일/공휴일) - 요금 정보 (기본 요금, 추가 요금, 결제 방법) **기타 지역:** - 기본 주차장 정보만 제공 (이름, 주소, 카테고리) - 안내 메시지 표시 ### 지원하는 API - **카카오 로컬 API**: 전국 주차장 검색 및 주소 변환 (주요 검색 API) - **서울 열린데이터**: 서울시 실시간 주차 정보 (서울 지역 실시간 정보 추가) - **경기데이터드림**: 경기도 실시간 주차 정보 (경기 지역 실시간 정보 추가) ## 사용 예시 ### 예시 1: 서울 지역 주차장 검색 ```python # search_nearby_parking 호출 { "latitude": 37.5665, "longitude": 126.9780, "radius": 1000 } # 응답 예시 { "parkings": [ { "name": "서울시청 주차장", "address": "서울 중구 세종대로 110", "total_spots": 1260, "available_spots": 507, "fee": "교통,지하철 > 지하철역 > 주차장", "distance": 62, "operating_info": { "operating_type": "시간제 운영", "weekday_start": "0000", "weekday_end": "2400", ... }, "fee_info": { "is_paid": "유료", "basic_fee": 430.0, "basic_hours": 5.0, ... }, "update_time": "2025-12-10 10:24:30" } ], "count": 1 } ``` ### 예시 2: 경기 지역 주차장 검색 ```python # search_nearby_parking 호출 { "latitude": 37.2892, "longitude": 127.0086, "radius": 1000 } # 응답 예시 { "parkings": [ { "name": "화성행궁", "address": "경기도 수원시 팔달구 화성행궁 159", "total_spots": 62, "available_spots": null, "fee": "교통,지하철 > 지하철역 > 주차장", "distance": 0, "operating_info": { "weekday_start": "00:00", "weekday_end": "23:59", ... }, "fee_info": { "is_paid": "유료", "basic_time": 90, "basic_fee": 400, ... } } ], "count": 1 } ``` ### 예시 3: 기타 지역 주차장 검색 ```python # search_nearby_parking 호출 { "latitude": 35.1631, "longitude": 129.1636, "radius": 1000 } # 응답 예시 { "notice": "해당 지역은 기본 주차장 정보만 제공됩니다. 실시간 정보는 서울 지역에서, 요금 및 운영시간 정보는 서울/경기 지역에서 이용 가능합니다.", "parkings": [ { "name": "해운대역 주차장", "address": "부산 해운대구 우동 1378-95", "total_spots": null, "available_spots": null, "fee": "교통,지하철 > 지하철역 > 주차장", "distance": 0 } ], "count": 1 } ``` ### 에러 응답 예시 ```json { "error": "주차장 정보를 불러오는 중 오류가 발생했습니다. 잠시 후 다시 시도해주세요.", "parkings": [] } ``` 상세한 응답 형식은 [MCP_RESPONSE_FORMAT.md](MCP_RESPONSE_FORMAT.md)를 참고하세요. ## 의존성 - fastmcp: MCP 서버 프레임워크 - requests: HTTP API 호출 - python-dotenv: 환경 변수 관리