# 공유누리 (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종).

## 실행

```bash
# 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      # 인증키 승인 후 체크리스트
```

## 데이터 출처

행정안전부 공유누리(eShare) OPEN API — https://www.eshare.go.kr (가이드 v2.2).
인증키는 환경변수 `ESHARE_API_KEY`로만 주입 (코드·저장소에 미포함).