# power-plan-db

한국 정부의 **전력·에너지 법정 기본계획**(전력수급기본계획·국가 탄소중립 녹색성장 기본계획·분산에너지 활성화·지능형전력망·집단에너지·신재생에너지·국가기간 전력망 확충·장기 송변전설비계획 등)을 공표 채널에서 **자동 수집·파싱**하고, **MCP 서버**로 AI 에이전트(Claude 등)에 제공하는 도구.

> Collectors + parser + a thin MCP server for Korean government power/energy statutory plans. No API key required (public sources). Small corpus → plain full-text search, no vector DB. Bring-your-own-data: run the collectors to build your own local corpus.

## 무엇을 하나

- **수집(`collect_power_plans.py`)** — no-agent, stdlib only, 무키.
  - korea.kr 정책브리핑 보도자료 검색(부처 발표분) + KEPCO 게시판(장기 송변전설비계획).
  - 계획별 키워드 + 제목 AND-필터, 신규분만 dedup, 첨부 PDF/HWP를 `raw/<계획>/`에 저장.
- **파싱(`parse_plans.py`)** — `raw/`의 PDF → `parsed/<계획>/*.md` (markitdown, 멱등).
- **서빙(`power_plans_mcp.py`)** — thin MCP 서버. 도구 3개: `list_plans` / `search_plans` / `get_plan`.
  검색·문서제공만; 종합·분석은 호출하는 에이전트가.

## 설치와 사용 환경

이 저장소는 두 가지 방식으로 쓴다.

1. **로컬 수집·검색 도구** — 터미널에서 직접 수집·파싱하고 결과 파일을 읽는다.
2. **로컬 MCP 서버** — Claude Code·Claude Desktop·Codex 등, 로컬 `stdio` MCP를 실행할 수 있는 에이전트에 현재 코퍼스를 제공한다.

저장소 자체에는 호스팅된 MCP 주소가 없고, 기본 `stdio` 서버는 브라우저의 Claude.ai·ChatGPT에서 직접 접속할 수 없다. 웹 채팅은 사용자의 컴퓨터 안의 폴더나 프로세스를 볼 수 없기 때문이다.

### 로컬 설치

```bash
git clone https://github.com/dillettante/power-plan-db.git
cd power-plan-db
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
```

### 수집·파싱·로컬 검색

```bash
# 1) 수집 (최근 N일, 무키). --dry-run으로 먼저 확인, --selftest로 필터 점검
.venv/bin/python scripts/collect_power_plans.py --days 400
.venv/bin/python scripts/collect_power_plans.py --dry-run

# 2) 파싱 (PDF → markdown, 멱등)
.venv/bin/python scripts/parse_plans.py

# 3) MCP 서버 — 기본 stdio (아래 클라이언트 등록 참조)
.venv/bin/python scripts/power_plans_mcp.py
```

데이터 위치는 기본이 repo 루트(`raw/`·`parsed/`). 다른 곳에 두려면 `POWER_PLAN_DB_DIR` 지정(`.env.example` 참조).

## 로컬 MCP 클라이언트 등록

수집·파싱을 적어도 한 번 실행한 뒤 등록한다. 이 서버는 `raw/`·`parsed/`가 있는 **현재 컴퓨터의 코퍼스**만 검색한다. `list_plans`에서 수집 현황을 먼저 확인하고, 수치·근거법령은 반환된 원문과 대조한다.

**Claude Code:**
```bash
claude mcp add power-plans -s user -e POWER_PLANS_MCP_TRANSPORT=stdio \
  -- /abs/path/.venv/bin/python /abs/path/scripts/power_plans_mcp.py
```

**Claude Desktop** (`claude_desktop_config.json`의 `mcpServers`):
```json
"power-plans": {
  "command": "/abs/path/.venv/bin/python",
  "args": ["/abs/path/scripts/power_plans_mcp.py"],
  "env": { "POWER_PLANS_MCP_TRANSPORT": "stdio" }
}
```

**Codex·기타 로컬 MCP 클라이언트:** 제품의 MCP 설정 화면 또는 설정 파일에 위와 같은 명령·인수·환경변수를 등록한다. 핵심 값은 다음과 같다.

```text
command: /abs/path/.venv/bin/python
args:    ["/abs/path/scripts/power_plans_mcp.py"]
env:     POWER_PLANS_MCP_TRANSPORT=stdio
```

제품마다 설정 파일 형식과 지원 transport가 다르므로, 클라이언트의 최신 MCP 설정 문서를 따른다. 이 저장소는 서버 명령과 데이터 경로만 제공하며, 각 제품의 설정 파일을 자동으로 수정하지 않는다.

### Claude.ai·ChatGPT 등 웹 채팅

브라우저 기반 채팅에 로컬 `stdio` 서버를 붙일 수는 없다. 안전하고 단순한 선택지는 다음 둘이다.

1. **로컬 에이전트 경유**: Claude Code·Claude Desktop·Codex 같은 로컬 MCP 클라이언트로 검색한 뒤, 필요한 발췌와 원문 경로를 웹 채팅에 제공한다.
2. **문서 업로드**: 특정 계획의 `parsed/<계획>/*.md`와 원본 PDF의 관련 쪽만 업로드해 분석을 요청한다. 이 방법은 실시간 코퍼스 검색은 아니므로, 자료의 차수·작성일·공표 채널을 함께 제공하고 최신성 확인을 별도로 요청한다.

ChatGPT의 custom MCP app은 원격 MCP 서버에 연결하며 로컬 서버에는 직접 연결하지 않는다. 원격 연결을 도입하려면 인증된 중계·터널, 접근 통제, 보안 검토가 별도로 필요하다. 이 프로젝트의 현행 SSE 서버는 인증 기능이 없으므로, ChatGPT나 Claude.ai에 연결하려고 공인 인터넷에 공개해서는 안 된다. OpenAI의 기능·요금제·관리자 요건은 수시로 바뀌므로 [Developer mode 및 MCP apps 안내](https://help.openai.com/en/articles/12584461-developer-mode-and-full-mcp-connectors-in-chatgpt)를 확인한다.

### LAN 자체호스팅(SSE)

한 대에서 서버를 띄우고 **신뢰할 수 있는 동일 LAN의 MCP 클라이언트**가 붙는 경우에만 쓴다.

```bash
POWER_PLANS_MCP_TRANSPORT=sse POWER_PLANS_MCP_PORT=8766 .venv/bin/python scripts/power_plans_mcp.py
# 클라이언트는 http://<서버-LAN-IP>:8766/sse 로 커스텀 커넥터 추가
# ⚠️ 인증 없음 — 포트 포워딩·공인 IP 공개 금지. 로컬 한정: POWER_PLANS_MCP_HOST=127.0.0.1
```

이 명령은 LAN 배포용이지 인터넷 공개용이 아니다. 외부 접속·조직 배포가 필요하면 인증·TLS·접근제어를 갖춘 별도 서버 배포를 설계하고 보안 검토를 거친다.

## 데이터는 포함하지 않습니다

계획 원문(PDF)·파싱본은 repo에 넣지 않습니다(`.gitignore`). 수집기를 돌려 **각자 최신 코퍼스를 직접 생성**하세요. 대상은 한국 정부가 공표한 공개 자료입니다(대체로 공공누리). 스크레이핑은 각 사이트 이용약관·robots를 확인하고, 스크립트의 요청 간격(sleep)을 유지해 정중하게 사용하세요.

## 한계

- RSS가 사문화(2026)돼 검색 페이지 HTML을 스크랩 → **사이트 구조 변경 시 셀렉터 조정** 필요.
- 국가 탄소중립·지능형전력망 기본계획은 위원회(탄녹위) 발표라 korea.kr 보도자료에 없음 → 별도 확보.
- 표 레이아웃(공백 정렬 PDF)은 파싱 시 다소 깨질 수 있음(본문·수치는 정상).
- 근거법령·차수·수치를 실제 인용할 때는 원본과 교차확인하세요(이 도구는 검색·제공 도구입니다).

## 라이선스

MIT — `LICENSE` 참조.