geup-ddong-seoul-mcp

서울시 공중화장실 데이터(스마트서울맵 테마 theme_id=100106)를 조회하는 MCP 서버입니다. 급할 때 내 위치에서 가까운, 지금 열려 있는 화장실을 찾는 것이 핵심 기능입니다.

• 전송 방식: Streamable HTTP (http://{HOST}:{PORT}/mcp)

• 데이터 출처: 스마트서울맵 갤러리 (공중화장실, 약 4,500개소)

• 다운로드는 로그인/인증 불필요 (공개 엔드포인트)

동작 개요

POST https://map.seoul.go.kr/smgis/webs/contents/contents.do
     ?mode=downloadGeomFormatXLSX&down_type=xlsx&lan_type=KOR&conts_type=A&theme_id=100106
  -> contents.zip  ->  contents.xlsx (데이터)  ->  파싱하여 메모리 적재

Related MCP server: dartpoint-mcp

원본 데이터 구조 (contents.xlsx)

contents.xlsx는 스마트서울맵 테마 업로드 공통 양식으로 77개 컬럼이며, 공중화장실은 약 4,538행입니다. 77컬럼 중 실제로 값이 들어있는 컬럼은 45개이고 나머지는 빈 스타일/예비 컬럼입니다. 헤더 1행은 콘텐츠 ID\n(필수 입력)처럼 안내문구가 붙어 있어 첫 줄만 컬럼명으로 사용합니다. (채움률은 실제 데이터 기준 근삿값)

고정 컬럼

상세 속성 (제목/내용 쌍 구조)

상세 정보는 상세 제목N / 상세 내용N 컬럼 쌍으로 저장됩니다. 예를 들어 상세 제목2칸에 개방시간, 상세 내용2칸에 정시(08:00~21:00)이 들어갑니다. 서버는 컬럼 위치(N)가 아니라 제목 텍스트로 매핑하므로 순서가 바뀌어도 안전합니다. 다중값은 |로 구분되며(남자|여자|) 끝의 |는 정리합니다.

원문 상세 전체(제목→내용)는 get_toilet 결과의 details에 그대로 담깁니다.

coord.xlsx

zip에 함께 들어오지만 공중화장실은 점(공간객체타입=1) 데이터라 좌표가 contents.xlsx에 모두 있어 사용하지 않습니다.

프로젝트 구조

geup-ddong-seoul-mcp/
├─ seoul_toilet/
│  ├─ __init__.py
│  ├─ data.py        # 다운로드/압축해제/파싱/질의 + ToiletStore(메모리·캐시)
│  └─ server.py      # FastMCP 서버(tool 4종) + /refresh, /health
├─ tests/
│  └─ test_logic.py  # 파싱·개방시간·거리·검색·다운로드(mock)·캐시 검증
├─ data_cache/       # 실행 시 생성: contents.zip, contents.xlsx 캐시
├─ requirements.txt
├─ pyproject.toml
└─ README.md

설치

pip install -r requirements.txt
# 또는 패키지로 설치
pip install -e .

요구사항: Python 3.10+, mcp, requests, openpyxl

실행

python -m seoul_toilet.server
# -> http://127.0.0.1:8000/mcp 에서 MCP 제공

환경변수로 설정합니다.

도메인(리버스 프록시) 뒤에서 /mcp를 서비스할 때 SEOUL_TOILET_PUBLIC_HOST를 지정하지 않으면 MCP의 DNS 리바인딩 보호가 외부 Host 헤더를 421 Invalid Host header로 막는다. /health·/refresh는 영향받지 않는다.

시작 시 캐시가 있으면 캐시를 읽고(네트워크 없음), 없으면 1회 다운로드합니다.

MCP 클라이언트 등록

Streamable HTTP를 지원하는 클라이언트에서 아래처럼 URL로 등록합니다.

{
  "mcpServers": {
    "geup-ddong-seoul": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

노출 Tool (LLM이 호출)

"지금 개방 중"은 별도 tool 대신 open_now 필터 + 결과의 open_now/open_hours 필드로 통합했습니다. LLM이 거리·개방·시설 조건을 조합해 판단하기 쉽도록, 각 결과에 개방시간(원문)·개방여부· 화장실구분·장애인화장실·편의시설·안전시설·관리기관·전화번호를 함께 담아 반환합니다.

결과 필드 예시

{
  "content_id": "rest2025_0448",
  "name": "강동구민회관",
  "district": "강동구",
  "road_address": "서울특별시 강동구 상암로 168",
  "latitude": 37.545731457, "longitude": 127.141222548,
  "phone": "02-2045-7617",
  "open_hours": "정시(08:00~21:00)", "open_now": true, "is_24h": false,
  "toilet_types": ["남자", "여자"],
  "disabled_toilet": ["남자", "여자"],
  "amenities": ["기저귀교환대(남)", "기저귀교환대(여)"],
  "safety": ["비상벨(여)"],
  "manager": "강동구도시관리공단",
  "distance_m": 12.3
}

반환 필드 레퍼런스

원본 필드(위 데이터 구조 표) 외에 서버가 계산해 넣는 파생 필드입니다.

빈 값은 단일 필드는 null, 리스트 필드는 []로 반환합니다.

데이터 갱신 (사용자가 직접 호출)

새로고침은 MCP tool로 노출하지 않고 운영용 HTTP 엔드포인트로만 제공합니다.

curl -X POST http://127.0.0.1:8000/refresh   # 원격에서 다시 받아 캐시 갱신
curl http://127.0.0.1:8000/health            # 상태 확인

월 1회 자동화 예시(cron):

0 6 1 * *  curl -fsS -X POST http://127.0.0.1:8000/refresh

공개 배포 등에서 /refresh 남용을 막으려면 SEOUL_TOILET_REFRESH_TOKEN을 설정하고 호출 시 토큰을 함께 보냅니다(미설정이면 공개 — cron이 없는 서버에서 그대로 호출 가능).

export SEOUL_TOILET_REFRESH_TOKEN=$(openssl rand -hex 24)
curl -fsS -X POST -H "X-Refresh-Token: $SEOUL_TOILET_REFRESH_TOKEN" http://127.0.0.1:8000/refresh
# 또는: -H "Authorization: Bearer $TOKEN"  /  "...?token=$TOKEN"

개방시간 해석 한계

개방시간 원문은 정시(08:00~21:00), 상시(00:00~24:00), 평일(09:00~18:00) 주말휴무 등 형식이 다양합니다. 서버는 시간 구간을 추출해 open_now(KST 기준)를 계산하되, 요일/공휴일별 차이는 완전히 반영하지 못할 수 있어 그런 경우 open_hours_note로 표시하고 원문(open_hours)을 함께 제공합니다. 최종 판단 시 원문을 함께 참고하세요.

왜 FastMCP인가

읽기 전용 조회 서버(다운로드→캐시→질의)라 저수준 SDK의 세밀한 제어가 불필요합니다. 공식 mcp SDK의 FastMCP는 @mcp.tool 데코레이터로 타입힌트 기반 입력 스키마를 자동 생성하고, @mcp.custom_route로 운영용 엔드포인트(/refresh)를 같은 앱에 손쉽게 붙일 수 있어 본 용도에 가장 적합합니다.

테스트

pip install pytest
python -m pytest tests/ -q

실제 스키마(77컬럼, 상세 제목/내용 쌍 구조)를 본뜬 합성 데이터로 파싱·개방시간·거리·검색· 다운로드(mock)·캐시까지 검증합니다.

라이선스/출처 표기

데이터: 서울특별시 스마트서울맵 (이용허락: 저작자표시 BY). 출처를 표기해 사용하세요.