# geo-figure-mcp — 지리 시험용 지도·그래프 만들기 (0.2)

만든 사람: 김한솔 (한백고등학교 지리 교사)

AI에게 "서울 자치구 주간 인구 지수 지도랑 산점도, 구 이름은 A~E로 숨겨서"처럼 말하면, **실제 통계**를 찾아 **흑백 시험지용** 지도·그래프를 만들어 줍니다.
결과는 **PPTX·HWPX** 파일이고, 지역 한 칸·막대 하나·글자 하나까지 **도형**으로 들어갑니다(그림 파일이 아닙니다). 묶음을 풀면 하나씩 고칠 수 있습니다.

## 무엇이 되나
- **지도**: 한국 시·도 / 시·군·구(2026년 판, 16개 시·도), 세계·대륙(위·경도선), 단계 구분도(빗금·회색), A~E 기호, 지점, 흐름 화살표, 축척 자동, 경계 단순화 3단계
- **지형**: 등고선 지형도·지형 단면(실제 표고), 교과서식 모식도 7종(암석 해안, 모래 해안·석호, 하안 단구, 카르스트, 화산, 빙하, 식생의 수직 분포)
- **그래프**: 막대·누적 막대, 산점도·버블, 기후 그래프, 편차, 인구 피라미드, 삼각 그래프
- **통계(실제 자료만, 숫자를 지어내지 않음)**
  - 세계은행 WDI, Our World in Data(에너지·CO2): 인증키 없음
  - 기후: WMO 1991~2020 평년값 관측소 4,697곳 내장 + **평가원 기후 기출 지점 66곳**(2022~2026학년도)
  - **내장 KOSIS 통계 17종(인증키 없이 사용)**: 인구 구조(부양비·노령화 지수·중위 연령), 성·5세 연령별 인구(피라미드), 인구주택총조사, 주간 인구 지수(2020), 외국인 주민 유형, 합계 출산율(10년), 시·도 간 인구 이동, 도시 지역 인구, GRDP, 제조업 업종별 출하액, 산업별 사업체, 최종 에너지 소비, 신재생 에너지, 농가 인구, 노지 채소·시설 작물·작물별 재배 면적 — `scripts/build-kosis.js` 로 다시 받을 수 있음
  - **시·도별 발전원별 발전량**(공공데이터포털, 이용 허락 '제한 없음')
    - 원자력: 2014~2025년, 호기별 발전량을 발전소 소재 시·도로 합침
    - 석탄·LNG·유류: 2018~2021년, 전력시장 거래량
    - 태양광: 2025년
  - **시·도별 발전원별 발전 설비 용량**(KOSIS, 한국전력거래소, 2021~2025년)
  - 에너지경제연구원 『지역에너지통계연보』는 이용약관상 무단 복제·제공이 금지라 넣지 않았습니다. 검산에만 썼습니다(원자력 2021년 값 일치).
  - KOSIS 직접 조회(위에 없는 통계): 각자 무료 인증키 필요
  - 서울 자치구 주간 인구(2020 인구주택총조사) 내장
- **출제 가공**: 최댓값=100 지수·비율·편차·반올림, 지역명 → A~E/(가)~(마)(무작위·북→남·서→동), 판별이 잘 되는 지역 추천
- **시험지 규칙**(교사 인터뷰 + 경기도교육청 「지리」 평가 문항 제작 자료)
  - 흑백 구분
  - 출처는 그림 오른쪽 아래
  - 확대 지도엔 축척
  - 정답표는 파일 마지막 장
- 만들기 전에 AI가 계획(지표·연도·지역·가공·기호 순서·출력)을 요약해 보여 주고 확인을 받습니다(확인 없이는 파일을 만들지 않음).

## 설치 (Claude 데스크톱)
1. [Node.js](https://nodejs.org) 20 이상(LTS) 설치 — 이것만 있으면 됩니다. 프로그램은 처음 쓸 때 자동으로 내려받습니다(`npx`).
2. (소스로 고쳐 쓰고 싶을 때만) 이 폴더에서 `npm install` 후 `"command": "node", "args": ["C:/경로/geo-figure-mcp/src/server.js"]`
3. Claude 데스크톱 → 설정 → 개발자 → 구성 편집 → `claude_desktop_config.json` 에 추가:
```json
{
  "mcpServers": {
    "geo-figure": {
      "command": "npx",
      "args": ["-y", "geo-figure-mcp"],
      "env": { "GEO_FIGURE_OUT": "C:/Users/<이름>/Documents/지리시험자료" }
    }
  }
}
```
4. Claude 데스크톱을 다시 켜고 "지리 시험 자료 만들어 줘"라고 말합니다.
5. (선택) 내장 자료에 없는 KOSIS 통계를 직접 받고 싶을 때만:
   - [KOSIS 공유서비스](https://kosis.kr/openapi/)에서 인증키를 무료로 발급받습니다.
   - Claude에게 "KOSIS 키 저장해 줘: ○○○"라고 말하면 이 컴퓨터 사용자 폴더에만 저장됩니다.

## 설치 (Google Antigravity)
1. Node.js 설치는 위와 같습니다.
3. Antigravity → 에이전트 창의 `…` → MCP Servers → Manage MCP Servers → View raw config 를 열거나, 아래 파일을 직접 엽니다.
   - 전체 공통: `C:/Users/<이름>/.gemini/config/mcp_config.json` (예전 판: `.gemini/antigravity/mcp_config.json`)
4. 다음을 넣고 저장합니다(경로는 `/` 로).
```json
{
  "mcpServers": {
    "geo-figure": {
      "command": "npx",
      "args": ["-y", "geo-figure-mcp"],
      "env": { "GEO_FIGURE_OUT": "C:/Users/<이름>/Documents/지리시험자료" }
    }
  }
}
```
5. MCP 목록에서 새로 고침 → `geo-figure` 도구 14개가 보이면 됩니다. 에이전트에게 "geo-figure 로 경기도 주간 인구 지수 지도 만들어 줘"라고 말합니다.
- `npx` 를 못 찾는다고 나오면 `command` 에 `C:/Program Files/nodejs/npx.cmd` 처럼 전체 경로를 넣습니다.
- 원격 서버를 쓸 때는 `"serverUrl": "https://…/mcp?token=비밀번호"` 한 줄로 등록합니다(`url`·`httpUrl` 이 아님).

## 내장 통계와 지도 이름 맞추기
- 내장 자료의 각 행에는 `mapName`(예: '경기 화성시')이 붙어 있어 지도 기호·단계 구분에 그대로 씁니다.
- 일반구(수원시 장안구 등)는 지도에서 시로 합쳐 그리므로 `mapName` 이 없고, 시 합계 행을 씁니다.
- 지도 판은 자료 연도에 맞춥니다. 2026년 7월 이전 자료는 2025년 판(17개 시·도)을 씁니다. 결과의 `mapEdition` 을 지도 `edition` 에 넣으면 됩니다.
- 단계 구분에 지도에 없는 이름이 섞이면 조용히 빠지지 않고 오류로 알립니다.

## 선생님들은 어떻게 쓰나 — 두 가지 방법

| | ① 내 컴퓨터에 설치 (권장) | ② 원격 서버 주소 붙이기 |
|---|---|---|
| 쓰는 AI | Claude 데스크톱 (MCP를 지원하는 데스크톱 앱) | ChatGPT·Claude 웹·Gemini 등 |
| 준비 | Node.js 설치 + 설정 파일 한 줄 (위 '설치') | 주소와 비밀번호만 받으면 끝 |
| 그림 파일 | **내 컴퓨터에만** 저장 | 서버에서 한 번 내려받음(받으면 바로 지움) |
| 정답표 | 파일 마지막 장에 들어감 | **파일에 넣지 않음** — 대화창에만 보여 줌 |
| KOSIS 직접 조회 | 내 키로 가능 | 안 됨 (내장 통계만) |
| 알맞은 용도 | **내신 시험 문항** | 연수 체험, 수업·연습 자료 |

①은 선생님마다 각자 자기 컴퓨터에서 돌리는 방식이라 서버가 필요 없고, 남의 서버를 거치지 않습니다. 대화 내용은 쓰는 AI 회사로 가니, 학생 개인정보는 대화에 넣지 마세요.

## 원격 서버 (ChatGPT·Gemini·Claude 웹)
설치 없이 주소만 붙여 쓰게 하려면 서버 한 곳에 올립니다.
1. 이 폴더를 깃허브에 올리고, [Render](https://render.com) 같은 곳에서 'Docker 웹 서비스'로 연결합니다. `render.yaml`·`Dockerfile` 이 들어 있습니다.
2. 받은 주소를 환경 변수 `PUBLIC_URL` 에 넣습니다(예: `https://geo-figure-mcp.onrender.com`). `ACCESS_TOKEN`(접속 비밀번호)은 **필수**입니다 — Render는 무작위로 만들어 줍니다.
3. 각 AI에 MCP 주소 `https://…/mcp?token=비밀번호` 를 붙입니다.
   - ChatGPT: 설정 → 커넥터(개발자 모드) → 새 커넥터 → 주소 입력
   - Claude 웹: 설정 → 커넥터 → 사용자 지정 커넥터 추가
   - Gemini CLI: `settings.json` 의 `mcpServers` 에 `httpUrl` 로 추가

보안·사용량 규칙
- **정답표는 파일에 넣지 않습니다.** 내려받기 주소가 새도 정답은 새지 않게 하려는 것입니다.
- 만든 파일은 **한 번 받으면 바로 지우고**, 안 받아도 60분 뒤 지웁니다(`KEEP_MINUTES`).
- 서버에는 KOSIS 키가 없고, 원격에서는 KOSIS 직접 조회를 끕니다(키를 대화창에 붙여 넣지 않도록). 내장 통계만 씁니다.
- 학교 양식 글꼴은 저장하지 않으니 `make_figures` 의 `style` 로 매번 넘깁니다.
- 사용량 제한: IP마다 1분 60번·그림 1시간 30번, 서버 전체 그림 하루 300번(`DAILY_MAX`). 이름·학교 같은 개인정보는 받지 않고, IP는 사용량 계산에만 메모리에 잠깐 둡니다.
- 카드가 등록된 곳(Cloud Run 등)에 올리면 예산 알림과 최대 인스턴스 수를 꼭 정하세요.
- 내 컴퓨터에서 시험: `ACCESS_TOKEN=아무거나 npm run start:remote` → `node examples/remote-test.js http://localhost:8787/mcp 아무거나`

## 고치는 법
- **PowerPoint**: 그림 선택 → 마우스 오른쪽 → 그룹 → 그룹 해제. 범례·막대·기호 같은 작은 묶음도 한 번 더 풀 수 있습니다.
- **한글**: 그림 선택 → 마우스 오른쪽 → 개체 풀기. 풀어도 조각이 제자리에 남습니다.
  - 그림은 '글 앞으로' 놓이고, 그 자리는 고정 높이 문단으로 비워 둡니다.
  - 묶음은 최대 3단입니다.
- **글꼴**
  - 한글 파일은 함초롬돋움(한글 기본 글꼴), PowerPoint 파일은 맑은 고딕(한국어 윈도 기본)을 씁니다.
  - "그림 글꼴을 ○○로 바꿔 줘"라고 하면 다음부터 그 설정으로 만듭니다(set_style).

## 기후 자료 출처 (지점마다 결과에 표시)
기출 지점 66곳은 계산한 쾨펜 기후를 평가원 기호와 대조했습니다(`node scripts/check-koppen.js`).

| 지점 수 | 출처 | 기준 |
|---|---|---|
| 48곳 | WMO 1991~2020 평년값 | 관측소 50km 이내 |
| 7곳 | NOAA GHCN-Daily 일별 기록 | 그달 20일 이상 기록된 해 10년 이상으로 직접 평균 |
| 11곳 | Beck et al.(2023) 0.1° 격자 1991~2020 | 관측소 자료가 부족한 곳만. 격자 추정값이라고 표시함 |

- 대조 결과 60곳은 일치했습니다.
- 다른 6곳 가운데 5곳은 경계형이나 고산 기후입니다(밴쿠버, 튀니스, 산티아고, 아디스아바바, 보고타).
- 칭다오는 목록에 Cs로 적혀 있으나 값으로는 Cwa입니다 [확인 필요].
- 티베트고원은 특정 지점이 아니라 좌표를 비워 두었습니다.

## 예시와 검사
- `node examples/run.js` → `examples/out/` 에 예시 5개를 만듭니다.
  1. 시·도 발전
  2. 서울 주간 인구
  3. 세계 기후 기출 지점
  4. 울릉도 등고선·단면
  5. 지형 모식도
- `node examples/mcp-test.js` → MCP 서버를 실제로 띄워 주요 도구를 불러 봅니다.

## 자료와 라이선스
- 코드: MIT
- 한국 경계: 본 데이터는 통계청 통계지리정보서비스(SGIS, https://sgis.kostat.go.kr)에서 공공누리 제1유형으로 개방한 행정동 경계를 가공한 것이며(가공: vuski/admdongkor, https://github.com/vuski/admdongkor), CC BY 4.0으로 배포됩니다. 이 도구는 이를 시·군·구로 합치고 단순화했습니다. 지도를 넣으면 그림 출처에 자동으로 표시됩니다.
- 세계 경계: Natural Earth(퍼블릭 도메인), topojson/world-atlas 가공(ISC License, Copyright Mike Bostock)
- 기후
  - WMO Member Nations (2023). WMO Climatological Standard Normals for 1991-2020 (NCEI Accession 0253808). NOAA NCEI. https://doi.org/10.25921/800j-vn07 — 이용 제한 없음, 인용 표시
  - NOAA GHCN-Daily(미국 정부 자료, 이용 제한 없음)
  - Beck, H.E. et al. (2023) 쾨펜-가이거 기후 분류 1km 지도(CC BY 4.0, doi:10.6084/m9.figshare.21789074)
  - 평가원 기출 기후 지점 목록: 지명·기후 기호·출제 시험 날짜만 정리한 사실 목록(교사 정리, skyblue3925-svg/geo-lab). 문항 원문·그림은 들어 있지 않습니다.
- 표고: Terrain Tiles(AWS 공개 데이터, 원자료 SRTM·GMTED·ETOPO1 등) — 쓸 때 내려받아 출처를 자동 표시
- 통계
  - 내장 KOSIS 통계: 국가데이터처(통계청) 등 작성기관 자료, KOSIS(공공누리 제1유형, 출처 표시). 표마다 출처가 자료에 들어 있습니다.
  - 발전원별 발전량: 공공데이터포털 한국전력거래소·한국수력원자력 파일 데이터(이용 허락 범위 제한 없음)
  - 세계은행 WDI(CC BY 4.0), Our World in Data(CC BY 4.0) — 쓸 때 받아 옴
- 시험지 규칙: 교사 인터뷰와 경기도교육청 「지리」 평가 문항 제작 자료를 참고해 다시 쓴 규칙입니다(원문 수록 안 함).
- WorldClim 등 재배포가 금지된 자료와 교과서·시험 문항 원문은 넣지 않았습니다.
- 자료의 정확성은 원자료를 따릅니다. 시험에 쓰기 전에 수치와 경계를 한 번 더 확인하세요.