건설알림이 MCP

서울시 건설공사(공사장) 알림 정보를 조회하는 MCP 서버.

상태

✅ fly.dev 배포 완료 — <앱이름>.fly.dev/mcp (2026-08-24부터 ?key= 인증 필수. 아래 "커넥터 연결 방법" 참고)

진행 순서

저장소 & 개발일지 세팅
데이터소스 확정 & 인증키 발급
로컬 스캐폴딩
도구(tool) 설계 및 실제 API 호출 테스트
테스트 & 배포 (fly.dev)
PlayMCP 등록 & Claude 연동 테스트
개발일지 마무리

사용하는 데이터

서울시 건설알림이 사업개요 (data.seoul.go.kr, OA-15585)
서울시 건설알림이 공사사진 (data.seoul.go.kr, OA-15586)
서울시 건설 알림이 정보 (ListConstructionWorkService) (data.seoul.go.kr, OA-1222)
서울시 건설공사 추진 현황 (ListOnePMISBizInfo) (data.seoul.go.kr, OA-2540)

도구(tool) 목록

search_construction_projects — 서울시 건설알림이(One-PMIS) 공사장 목록을 자치구명/키워드로 검색 (사업명, 위치, 발주처/시공사, 착공일, 준공예정일, 도급액, 위경도, 발주처/건설사업관리단/시공사 연락처 등 반환)
get_construction_project_photos — 사업코드(PJT_CD)로 공사현장 사진 목록 조회
search_construction_work_by_district — 서울시 건설 알림이 정보(ListConstructionWorkService)를 자치구명/프로젝트명 키워드로 검색 (자치구명이 있으면 서버가 직접 해당 구만 필터링해 반환. 프로젝트코드, 프로젝트명, 착수일, 사업기간, 진행상태, 사무실/현장주소, 위경도, 사업금액 등 반환)
get_construction_progress — 서울시 건설공사 추진 현황(ListOnePMISBizInfo)을 사업명/발주처기관명 키워드로 검색 (계획/실적 공정률, 대비율, D-Day, 도급액/사업비, 시공사/감리사/발주처 담당자, 공사위치 등 반환. 자치구명·최소 도급액(min_amount)은 클라이언트에서 필터링. 공정률/대비율이 0이면 "미입력"으로 표시)

출처 표기 필수: 모든 도구가 결과 JSON에 출처 필드(서울 열린데이터광장 데이터셋명)를 포함하며, 이 MCP를 사용해 답변할 때는 반드시 그 출처를 답변에 명시해야 한다. 출처 생략은 금지된다.

실행 방법

로컬 실행

npm install
npm start

서버는 http://localhost:8080/mcp (Streamable HTTP transport)에서 요청을 받는다.

커넥터 연결 방법

이 서버는 ?key= 쿼리 파라미터로 접근을 제한한다. 올바른 키 없이는 401로 거부된다.

https://<앱이름>.fly.dev/mcp?key=본인의_MCP_ACCESS_KEY

MCP_ACCESS_KEY는 이 서버 자체에 접근하기 위한 전용 비밀키로, 서버가 fly secrets로 보유한 값과 요청의 ?key= 값이 일치해야 통과한다. 서울 열린데이터광장 호출용 키(SEOUL_OPENAPI_KEY)와는 별개다 — 그 키는 서버가 업스트림 API를 호출할 때만 쓰이며 사용자가 URL에 붙일 필요가 없다.

인증을 통과한 요청에 대해서는 같은 IP 기준으로 아래 3단계 제한을 추가로 적용한다. 초과 시 429(Too Many Requests) 응답을 반환한다. (2026-08-25부터 개인 전용 사용 기준으로 완화 — ?key= 인증이 이미 걸려 있어, rate limit은 실수로 반복 호출해도 안 막히는 수준으로 낮췄다.)

분당 30회 초과 호출 제한
IP당 일일 총 호출 1000회 제한
1시간 내 429 응답을 20회 이상 받은 IP는 24시간 동안 차단

모든 기록은 메모리(서버 프로세스 내) 저장이며, 서버가 재시작되면 초기화된다.

fly.dev 배포

deploy.ps1 스크립트가 아래 순서를 한 번에 처리한다: node --check로 문법 확인 → (변경사항이 있으면) 커밋 → 원격에 새 커밋이 있으면 git pull --rebase로 동기화 → git push → flyctl deploy → 배포된 엔드포인트에 실제 initialize 요청을 보내 정상 동작 확인.

# 커밋할 변경사항이 있는 경우
.\deploy.ps1 -CommitMessage "feat: add xyz tool"

# 이미 커밋까지 끝난 상태라면 메시지 없이 실행
.\deploy.ps1

옵션:

-SkipSyntaxCheck — node --check 단계 생략
-SkipSmokeTest — 배포 후 라이브 엔드포인트 검증 단계 생략

커밋되지 않은 변경사항이 있는데 -CommitMessage를 지정하지 않으면, 의도치 않은 커밋을 막기 위해 스크립트가 변경 내역을 보여주고 중단한다.

수동으로 배포만 하려면:

flyctl deploy

건설알림이 MCP