@itapi-core/mcp-research

AI가 Google/Naver 웹검색을 수행하고, 카테고리별 정보를 수집·정리할 수 있도록 하는 MCP 서버입니다. 여행·IT·일반 카테고리에 따라 검색 전략과 응답 형식을 자동 분기하며, API 키 없이도 Google Maps 기반 위치 조회 및 동선 플래닝을 지원합니다.

Tools

분류 (Classification)

| Tool | Description | |------|-------------| | classify_query | 쿼리를 travel / IT / general 카테고리로 자동 분류 |

위치·지도 (Maps — API 키 없이 동작)

| Tool | Description | |------|-------------| | resolve_address | 주소·장소명 정규화 및 좌표 조회 (Google Geocoding → Nominatim 자동 fallback) | | get_place_links | 장소 하나에 대한 Google Maps 검색·길찾기·좌표 링크 세트 생성 | | plan_route | 출발지→경유지→목적지 동선 계획 + 각 장소별 Maps 링크 반환 |

검색 (Search — scaffold)

| Tool | Description | |------|-------------| | search_web | 카테고리별 Google/Naver 검색 전략 계획 (실 커넥터 연결 전 scaffold 단계) |

Geocoding 동작 방식

| 우선순위 | 수단 | API 키 필요 | 좌표 반환 | |---|---|---|---| | 1 | Google Geocoding API | ✅ GOOGLE_MAPS_API_KEY | ✅ | | 2 | OpenStreetMap Nominatim | ❌ 불필요 | ✅ | | 3 | 텍스트 링크 fallback | ❌ 불필요 | ❌ (검색 링크만) |

Setup

npm install @itapi-core/mcp-research

또는 npx로 바로 실행:

npx @itapi-core/mcp-research

소스에서 빌드

git clone https://gitlab.itapi.org/mcp/mcp_research.git -b dev
cd mcp_research
npm install
npm run build
npm start

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GOOGLE_MAPS_API_KEY | ❌ | Google Geocoding API 키. 없으면 Nominatim(OpenStreetMap)으로 자동 fallback |

Note: GOOGLE_MAPS_API_KEY 없이도 모든 Maps 도구가 동작합니다. API 키가 있으면 지오코딩 정확도와 신뢰도가 높아집니다.

Docker

docker-compose up -d

환경변수를 사용하려면 .env 파일을 생성합니다.

GOOGLE_MAPS_API_KEY=your_google_maps_api_key

MCP Client Configuration

stdio (기본)

{
  "mcpServers": {
    "mcp-research": {
      "command": "npx",
      "args": ["-y", "@itapi-core/mcp-research"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "your_key_here"
      }
    }
  }
}

GOOGLE_MAPS_API_KEY 없이도 동작합니다. 필요 없으면 env 블록을 생략하세요.

node 직접 실행

{
  "mcpServers": {
    "mcp-research": {
      "command": "node",
      "args": ["node_modules/@itapi-core/mcp-research/dist/index.js"]
    }
  }
}

Tool 상세

classify_query

쿼리 텍스트를 분석해 카테고리와 권장 응답 형식을 반환합니다.

// 입력
{ "query": "제주도 맛집 추천" }

// 출력
{
  "category": "travel",
  "confidence": 0.79,
  "signals": ["여행", "맛집"],
  "recommendedResponseStyle": "실용 정보 중심의 여행 일정/비용/동선/날씨/이벤트 요약"
}

resolve_address

주소나 장소명을 정규화하고 Google Maps 링크를 반환합니다. API 키 없으면 Nominatim으로 좌표를 조회합니다.

// 입력
{ "address": "경복궁", "locale": "ko" }

// 출력
{
  "normalizedAddress": "경복궁, 청운효자동, 종로구, 서울특별시, 03045, 대한민국",
  "candidates": [
    {
      "address": "경복궁, ...",
      "searchLink": "https://www.google.com/maps/search/?api=1&query=37.579754,126.9766818",
      "lat": 37.579754,
      "lng": 126.9766818
    }
  ],
  "googleMapsSearchLink": "https://www.google.com/maps/search/?api=1&query=37.579754,126.9766818",
  "confidence": 0.75,
  "source": "nominatim"
}

get_place_links

장소 하나에 대한 Google Maps 링크 세트를 반환합니다.

// 입력
{ "place": "남산타워" }

// 출력
{
  "normalizedPlace": "남산서울타워, 105, 남산공원길, ...",
  "searchLink": "https://www.google.com/maps/search/?api=1&query=37.5512692,126.9882959",
  "directionsLink": "https://www.google.com/maps/dir/?api=1&destination=...",
  "geocoded": {
    "lat": 37.5512692,
    "lng": 126.9882959,
    "formattedAddress": "남산서울타워, 105, 남산공원길, ...",
    "coordSearchLink": "https://www.google.com/maps/search/?api=1&query=37.5512692,126.9882959"
  },
  "source": "nominatim"
}

plan_route

출발지·경유지·목적지로 이동 동선을 계획하고 각 장소별 Maps 링크를 반환합니다.

// 입력
{
  "origin": "서울역",
  "destination": "경복궁",
  "waypoints": ["남산타워"],
  "travelMode": "transit"
}

// 출력
{
  "orderedStops": ["서울역", "남산타워", "경복궁"],
  "stopLinks": [
    {
      "stop": "서울역",
      "searchLink": "https://www.google.com/maps/search/?api=1&query=37.5554175,126.9723...",
      "directionsLink": "https://www.google.com/maps/dir/?api=1&destination=서울역",
      "lat": 37.5554175,
      "lng": 126.9723
    }
  ],
  "googleMapsDirectionsLink": "https://www.google.com/maps/dir/?api=1&origin=서울역&destination=경복궁&waypoints=남산타워&travelmode=transit"
}

search_web

카테고리에 따라 Google/Naver 검색 전략을 계획합니다. 현재 scaffold 단계로 소스 우선순위와 응답 형식 계획을 반환합니다.

// 입력
{
  "query": "부산 해운대 여행",
  "category": "travel",
  "engines": "both",
  "travelContext": {
    "destination": "부산",
    "travelDate": "2026-08-01",
    "partySize": "커플",
    "budget": "30만원"
  },
  "routeContext": {
    "origin": "서울",
    "destination": "부산",
    "travelMode": "driving"
  }
}

Security

• 모든 입력은 Zod schema로 검증합니다.
• API 키는 환경변수로만 주입하며 응답에 노출되지 않습니다.
• npm audit 기준 취약점 0을 유지합니다.
• 외부 서비스(Google API, Nominatim) 실패 시 graceful degradation합니다.

Repository

• GitLab: https://gitlab.itapi.org/mcp/mcp_research.git (branch: dev)
• npm: https://www.npmjs.com/package/@itapi-core/mcp-research