MCP 服务器

eshare-mcp

MCP server for searching and recommending Korean public resources (rooms, facilities, parking, etc.) using a static snapshot of the eShare OPEN API, with read-only tools for filtered search, detail, recommendation, and filter options.

README

공유누리 (eShare) 공공자원 검색·추천 MCP 서버

전국 공공 개방자원(회의실·강의실·체육시설·주차장·물품·연구장비·강좌)을 검색·추천하는 MCP 서버. 행정안전부 공유누리(eShare) OPEN API의 빌드타임 스냅샷을 SQLite로 적재해, 런타임 외부 호출 0으로 응답한다.

카카오 AGENTIC PLAYER 10 출품용 · PlayMCP 규격 (Streamable HTTP · stateless · Tools-only · 응답 24KB 이하)

아키텍처 (ADR-001)

[빌드타임]  eShare OPEN API ──(POST+JSON, 분류별 목록→상세 100건 배치)──▶ data/eshare.db
[런타임 ]  MCP client ──(streamable-http, stateless)──▶ server.py ──▶ SQLite 읽기 전용

라이브 프록시 기각: 평균 100ms/p99 3s 성능 예산, 일 1,000콜 쿼터, 외부 장애 격리.
실시간 미단언: 전 응답에 스냅샷 타임스탬프 + "실시간 예약 가능 여부와 다를 수 있음" 디스클레이머 자동 부착. 예약은 공유누리/기관 채널로 안내.
결정론 커널: 교차기관 집계·분포 통계(get_filter_options), 고정 가중합 랭킹(recommend_resources, 동일입력→동일출력, 근거 분해 노출).

MCP Tools (4종, 전부 read-only)

Tool	기능
`search_resources`	keyword·region·resource_type(분류코드/명칭)·free_only 다기준 검색
`get_resource_detail`	자원 상세 + 예약채널(기관 예약 URL·공유누리 상세 링크) 필수 노출
`recommend_resources`	purpose 기반 결정론 가중 랭킹 (유형일치 50·키워드 20·요금 15·예약간편 5·규모 5 / 95점)
`get_filter_options`	분류·지역·기관 교차 집계 통계 + 유효 필터값 안내

annotations: readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=false + title (5종).

실행

# 1) 목업 DB (인증키 승인 전 개발용 — data_mode=mock, 응답에 목업 표시)
python3 scripts/build_mock_db.py

# 2) 실 스냅샷 (인증키 승인 후)
ESHARE_API_KEY=... python3 scripts/build_db.py --probe-only   # 승인 여부 확인 (1콜)
ESHARE_API_KEY=... python3 scripts/build_db.py                # 씬슬라이스 적재
ESHARE_API_KEY=... python3 scripts/build_db.py --full         # 전량

# 3) 서버 — 목업 DB로는 ALLOW_MOCK_DB=1 필요 (mock이 심사에 배포되는 사고 방지 가드)
ALLOW_MOCK_DB=1 python3 server.py   # streamable-http :8000 (PORT 환경변수로 변경)
python3 server.py                    # live 스냅샷일 때 (mock이면 기동 거부)

# 4) 수용 기준 테스트 (계획 C′ §6 — 24KB·디스클레이머·결정론·예약채널·annotations·성능)
python3 tests/test_acceptance.py

# 5) Docker (KC 배포) — 이미지 빌드 시 live 스냅샷 검증 (mock이면 빌드 실패)
docker build -t eshare-mcp . && docker run -p 8000:8000 eshare-mcp
docker build --build-arg ALLOW_MOCK=1 -t eshare-mcp-dev .   # 개발용 우회

프로젝트 구조

server.py                  # MCP 서버 (런타임 — SQLite RO 조회만)
adapters/eshare_api.py     # eShare OPEN API 클라이언트 (빌드타임 전용)
scripts/db_common.py       # 스키마·필드맵 (단일 원천: 가이드 v2.2)
scripts/build_mock_db.py   # 목업 스냅샷 (결정론 70건)
scripts/build_db.py        # 실 스냅샷 파이프라인 (프로브→목록→상세→적재→리포트)
tests/test_acceptance.py   # 수용 기준 8종
docs/승인후_잔여작업.md      # 인증키 승인 후 체크리스트