lh-mcp-server

LH(한국토지주택공사) **분양/임대 공고(분양임대공고문 조회 서비스)**를 검색할 수 있도록, Model Context Protocol(MCP) 툴(tool) 서버 형태로 감싼 프로젝트입니다.

이 서버는 LH_SERVICE_KEY(공공데이터포털에서 발급)로 LH OpenAPI를 호출하고, MCP 클라이언트(예: 에이전트/툴 런타임)에서 search_lh_notices 툴을 통해 공고 목록을 조회할 수 있게 합니다.

제공 기능

• MCP 엔드포인트
  • GET /mcp: MCP Streamable HTTP endpoint
  • GET /health: 헬스체크 (200 OK)
• 툴
  • search_lh_notices: 지역/상태/유형/키워드/기간/페이지로 LH 공고 검색

사전 준비

• Go: go.mod 기준 버전
• 필수 환경변수
  • LH_SERVICE_KEY: 공공데이터포털에서 발급받은 인증키(서비스키)
• 선택 환경변수
  • PORT: 서버 포트(숫자만). 미설정 시 8080

보안 주의: LH_SERVICE_KEY는 민감 정보입니다. 로그/레포지토리/이미지에 포함되지 않도록 주의하세요.

로컬 실행

export LH_SERVICE_KEY="YOUR_SERVICE_KEY"
go run .

• 기본 주소: http://localhost:8080
• 헬스체크:

curl -i http://localhost:8080/health

MCP로 연결하기

MCP 클라이언트에서 다음 엔드포인트로 연결합니다.

• MCP endpoint: http://localhost:8080/mcp

서버에 등록된 툴 이름은 search_lh_notices 입니다.

search_lh_notices 입력 스키마(요약)

docs/api-reference.md의 요청 파라미터를 기준으로, 아래 필드들로 검색 조건을 전달합니다.

• region (string, 옵션): 지역명 (예: 서울, 부산, 경기)
• status (string, 옵션): 공고상태 (예: 공고중, 접수중, 접수마감, 상담요청, 정정공고중)
• notice_type (string, 옵션): 공고유형 (예: 토지, 분양주택, 임대주택, 주거복지, 상가, 신혼희망타운)
• keyword (string, 옵션): 공고명 키워드
• start_date (string, 옵션): 공고게시일 시작 (YYYYMMDD)
• end_date (string, 옵션): 공고마감일 (YYYYMMDD)
• page (number, 옵션): 페이지 번호(기본 1)
• page_size (number, 옵션): 페이지당 결과 수(기본 10)

참고(SSOT): 실제 LH API 호출 파라미터는 internal/lh/client.go에서 구성합니다.
LH API는 PAN_NT_ST_DT와 CLSG_DT가 사실상 필수인데, 이 서버는 미입력 시 기본값(오늘 ~ 6개월 후) 으로 자동 설정합니다.

Docker

빌드:

docker build -t lh-mcp-server .

실행:

docker run --rm -p 8080:8080 -e LH_SERVICE_KEY="YOUR_SERVICE_KEY" lh-mcp-server

배포

ECS Fargate(ALB) 수동 배포 런북은 docs/deployment.md를 참고하세요.

검증(테스트)

go test ./...