@inavi-maps/api-mcp-server 0.0.0-stage → 0.0.1

package/.env.example

@@ -0,0 +1,2 @@
+# iNavi Maps Open API 앱키 (필수)
+INAVI_APPKEY=

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 iNavi Maps MCP API Server contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -1,3 +1,173 @@
-# Temporary Holding Version
+# INAVI Maps API MCP Server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@inavi-maps/api-mcp-server)](https://www.npmjs.com/package/@inavi-maps/api-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+AI 어시스턴트가 INAVI Maps API를 **직접 호출**해 장소·주소·경로를 찾고, 결과를
+**대화 안의 동적 지도**로 보여 주는 MCP (Model Context Protocol) 서버입니다.
+
+- **장소·주소 검색** - 상호명·업종·주소로 찾기, 주변 분류 검색, 지오코딩·리버스 지오코딩을 지원합니다.
+- **경로** - 자동차(실시간·출발 시각 예측)·도보·킥보드 경로, 경유지 순서 최적화, 거리·시간 행렬을 지원합니다.
+- **지도 표시** - 결과를 [MCP Apps](https://github.com/modelcontextprotocol/ext-apps)로 대화 안에 표시하여, 다양한 인터랙션을 지원합니다.
+
+---
+
+## API Key 발급
+API Key 발급은 [이 곳](https://mapsapi.inavisys.com/mcp-intro#how-to-use)에서 확인해주세요.
+> **이 서버는 API Key 없이 시작되지 않습니다.** 아래 빠른 시작의 `INAVI_APPKEY`에 발급받은 키를 넣어 주세요.
+
+---
+
+## 빠른 시작
+
+> **사전 요구사항:** Node.js 22 이상이 설치되어 있어야 합니다 (`node -v`로 확인).
+
+아래 **서버 설정**을 사용 중인 도구의 **설정 경로**에 추가하고, `발급받은_API_Key`를 실제 API Key로 바꾼 뒤
+호스트를 재시작하세요.
+
+| 도구 | 설정 경로 | 서버 설정 |
+|---|---|---|
+| Claude Desktop | Windows `%APPDATA%\Claude\claude_desktop_config.json`<br>macOS `~/Library/Application Support/Claude/claude_desktop_config.json` | <pre>{<br>  "mcpServers": {<br>    "inavi-maps-api": {<br>      "command": "npx",<br>      "args": ["-y", "@inavi-maps/api-mcp-server"],<br>      "env": { "INAVI_APPKEY": "발급받은_API_Key" }<br>    }<br>  }<br>}</pre> |
+| Claude Code | `~/.claude.json` | <pre>{<br>  "mcpServers": {<br>    "inavi-maps-api": {<br>      "command": "npx",<br>      "args": ["-y", "@inavi-maps/api-mcp-server"],<br>      "env": { "INAVI_APPKEY": "발급받은_API_Key" }<br>    }<br>  }<br>}</pre> |
+| Cursor | `~/.cursor/mcp.json` | <pre>{<br>  "mcpServers": {<br>    "inavi-maps-api": {<br>      "command": "npx",<br>      "args": ["-y", "@inavi-maps/api-mcp-server"],<br>      "env": { "INAVI_APPKEY": "발급받은_API_Key" }<br>    }<br>  }<br>}</pre> |
+| VS Code | 사용자 프로필 | <pre>{<br>  "servers": {<br>    "inavi-maps-api": {<br>      "command": "npx",<br>      "args": ["-y", "@inavi-maps/api-mcp-server"],<br>      "env": { "INAVI_APPKEY": "발급받은_API_Key" }<br>    }<br>  }<br>}</pre> |
+
+<sub>Claude Code는 명령 한 줄로도 등록할 수 있습니다.</sub>
+
+```bash
+claude mcp add --transport stdio inavi-maps-api --env INAVI_APPKEY=발급받은_API_Key -- npx -y @inavi-maps/api-mcp-server
+```
+
+> **지도는 MCP Apps를 지원하는 호스트에서만 보입니다.** Claude Desktop에서 확인했습니다.
+> 지원하지 않는 호스트에서도 도구 호출과 응답은 그대로 동작하고, 지도만 그려지지 않습니다.
+
+---
+
+## 사용 예시
+
+결과에 대한 지도 시각화를 원한다면 `지도에 보여줘`를 함께 요청하세요.
+
+> Claude Desktop, ChatGPT App은 기본 내장 도구로 구글 지도를 지원합니다. 프롬프트 끝에 `INAVI MCP를 사용해줘`를 붙이는 것을 추천합니다.
+
+### 장소·주소
+
+```
+판교역 주변 스타벅스 찾아서 지도에 보여줘. INAVI MCP를 사용해줘
+```
+
+```
+판교역 반경 500m 안의 편의점 전부 지도에 보여줘. INAVI MCP를 사용해줘
+```
+
+```
+경기도 성남시 분당구 판교역로 240 좌표 알려줘. INAVI MCP를 사용해줘
+```
+
+```
+127.110750, 37.402159 여기 주소가 어디야? INAVI MCP를 사용해줘
+```
+
+### 경로
+
+```
+판교역에서 강남역까지 자동차 경로 알려줘. 지도에 보여줘. INAVI MCP를 사용해줘
+```
+
+```
+내일 아침 8시에 판교역에서 강남역으로 출발하면 얼마나 걸려? 8시 반이랑 비교해줘. INAVI MCP를 사용해줘
+```
+
+```
+판교역에서 판교테크노밸리까지 걸어가는 길 알려줘. 계단은 피하고 싶어. INAVI MCP를 사용해줘
+```
+
+```
+판교역에서 출발해서 서현역, 정자역, 미금역을 들르는 가장 짧은 순서 알려줘. INAVI MCP를 사용해줘
+```
+
+```
+판교역, 서현역, 정자역 사이 거리랑 시간 비교해줘. INAVI MCP를 사용해줘
+```
+
+---
+
+## 사용 가능한 도구
+
+INAVI Maps API를 호출하는 **11개의 도구**를 제공합니다. `lookup_category_code`를 뺀 10개의 도구에서
+지도를 그릴 수 있습니다.
+
+| 도구 | 설명 |
+|------|------|
+| `search_places` | 상호명·건물명·업종·주소·전화번호로 장소와 주소를 검색합니다. 한국어·영어·일본어·중국어를 지원합니다 |
+| `search_nearby_category` | 한 지점 주변(반경·사각 영역)에서 같은 분류의 장소를 모두 찾습니다 — 편의점·주차장·충전소처럼 이름이 제각각인 것 |
+| `geocode_address` | 주소를 좌표로 바꿉니다 |
+| `reverse_geocode` | 좌표를 주소·행정구역 코드·가장 가까운 건물 이름으로 바꿉니다 |
+| `find_entry_points` | 경로 탐색 전에 좌표를 차량 진입로·택시 승하차 지점으로 보정합니다 |
+| `get_admin_boundary` | 시도·시군구·읍면동·리의 행정구역 경계를 가져옵니다 |
+| `find_route` | 경유지 최대 5개의 자동차 경로. 실시간 또는 출발·도착 시각 기준 예측입니다 |
+| `find_walking_route` | 도보·킥보드(PM) 경로. 계단·엘리베이터 같은 시설 정보를 담습니다 |
+| `optimize_waypoint_order` | 경유지 최대 10곳의 최적 방문 순서를 구합니다 |
+| `get_distance_matrix` | 여러 지점 사이의 거리·시간 행렬을 구합니다 |
+| `lookup_category_code` | 분류 이름으로 분류 코드를 찾습니다 (API를 호출하지 않습니다) |
+
+### 지도에서 할 수 있는 일
+
+지도는 결과를 보여 주는 데서 끝나지 않습니다. 대화의 흐름이 끊기지 않도록 옵션 값을 변경하여 MCP Apps 내부에서 도구를 호출할 수 있습니다.
+
+| 결과 | 지도에서 하는 일 |
+|---|---|
+| 장소 검색 | 언어 바꾸기 · 페이지 넘기기 · 현재 지도에서 재검색 · 경로 만들기 프롬프트 생성 |
+| 주변 분류 검색 | 페이지 넘기기 · 경로 만들기 프롬프트 생성 |
+| 지오코딩 | 페이지 넘기기 |
+| 자동차 경로 | 탐색 기준 변경(추천·무료 도로·고속도로) · 차종 변경 |
+| 도보 경로 | 이동 수단 변경(도보·킥보드) · 탐색 기준 변경 |
+| 거리·시간 행렬 | 실시간 교통 반영 |
+
+**경로 만들기**는 목록이나 지도에서 출발·도착을 골라 경로 탐색 질문을 **대화 입력창에 채워** 줍니다.
+보내기 전에 문장을 확인할 수 있습니다. 목록의 **대화로** 버튼도 같은 방식으로 그 장소를 대화에 넘깁니다.
+
+모든 지도에서 지도 유형(일반·항공·하이브리드·지형)과 밝은·어두운 테마를 바꿀 수 있고,
+MCP 호스트가 지원하면 전체화면으로 볼 수 있습니다.
+
+---
+
+## 환경 변수
+
+| 변수 | 필수 | 설명 |
+|---|:---:|---|
+| `INAVI_APPKEY` | 필수 | INAVI Maps API Key |
+
+---
+
+## 문제 해결
+
+### MCP 서버가 연결되지 않을 때
+
+1. **API Key 확인**: 서버 설정의 `env`에 `INAVI_APPKEY`가 있는지 확인 — 없으면 서버가 시작되지 않습니다
+2. **Node.js 버전 확인**: Node.js 22 이상이 필요합니다 (`node -v`로 확인)
+3. **설정 파일 확인**: JSON 문법 오류가 없는지 확인
+4. **MCP Host 재시작**: 설정 변경 후 반드시 완전히 종료했다가 다시 실행
+
+### 그 밖의 증상
+
+| 증상 | 확인할 것 |
+|---|---|
+| 인증 실패(`300`) | `INAVI_APPKEY` 값이 맞는지 |
+| 지도 대신 "지도 표시 없이 조회한 결과입니다."만 뜬다 | 정상입니다. 요청에 "지도에 보여줘"를 붙이세요 |
+| 지도가 빈 화면 | `imaps.inavi.com`에 접근할 수 있는지(사내망 방화벽) |
+| MCP Inspector에서 지도 배경이 안 보인다 | Inspector는 지도 SDK가 쓰는 워커를 막습니다. 도구 호출 확인용으로 쓰고, 지도는 Claude Desktop에서 확인하세요 |
+
+---
+
+## 라이선스
+
+MIT License - 자유롭게 사용, 수정, 배포할 수 있습니다. 자세한 내용은 [LICENSE](./LICENSE) 파일을 참조하세요.
+
+---
+
+## 참고 자료
+
+- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP 공식 문서
+- [MCP Apps](https://github.com/modelcontextprotocol/ext-apps) - 대화 안에 화면을 그리는 MCP 확장
+- [Claude Desktop](https://claude.ai/download) - Claude Desktop 다운로드
+- [INAVI Maps API](https://mapsapi.inavisys.com/) - INAVI Maps API 공식 문서