@isnow890/naver-search-mcp 1.0.48 → 1.0.49

package/README.md

@@ -7,6 +7,25 @@
 
 MCP server for Naver Search API and DataLab API integration, enabling comprehensive search across various Naver services and data trend analysis.
 
+## ⚠️ Naver is migrating these APIs — read this before you set up
+
+Naver is moving Search, Search Trend, and Shopping Insight from the Naver Developers Center to **NAVER API HUB** on NAVER Cloud Platform, and is shutting down three search APIs entirely.
+
+| Date | What happens |
+|---|---|
+| **2026-07-31** | Developers Center stops accepting **new** key applications.<br>Shopping / Book / Academic search APIs shut down completely. |
+| **2027-06-30** | Developers Center support ends — **existing keys stop working**. |
+
+Source: [Naver Developers Center official notice](https://developers.naver.com/notice/article/32530) (Korean) — "Search API, Search Trend, Shopping Insight 서비스 종료 및 NAVER API HUB 이관 안내".
+
+**Setting this up for the first time?** Get your keys from NAVER API HUB. The Developers Center path closes to new applicants on 2026-07-31, so it is no longer the place to start. Step-by-step instructions are in [Option A: NAVER API HUB](#option-a-naver-api-hub-recommended--the-forward-path) below.
+
+**Already running with Developers Center keys?** Nothing to change. They keep working until 2027-06-30, and this version supports both platforms from the same install. When you're ready, get a HUB key and swap the two environment variables — no other changes.
+
+**Support plan for this server:** both platforms stay supported side by side through Naver's 2027-06-30 cutoff. The Developers Center path will be dropped in a later major version only after that date, once it can no longer work for anyone — so upgrading in the meantime will never take your working setup away.
+
+**Three tools were removed in 1.0.49**: `search_shop`, `search_book`, `search_academic`. Naver shuts those search APIs down on 2026-07-31 with no replacement on any platform, so there is nothing this server can do to keep them. Shopping **Insight** (`datalab_shopping_*`) and `find_category` are a *different* API and are **not** affected.
+
 ## Available on ClawHub for OpenClaw
 
 You can install this MCP server as an OpenClaw skill from ClawHub:
@@ -15,7 +34,7 @@ You can install this MCP server as an OpenClaw skill from ClawHub:
 openclaw skills install naver-search-mcp
 ```
 
-The ClawHub skill uses the published npm package internally and requires `NAVER_CLIENT_ID` and `NAVER_CLIENT_SECRET` in your OpenClaw environment.
+The ClawHub skill uses the published npm package internally and needs **one** credential pair in your OpenClaw environment — either the NAVER API HUB pair (`NCP_APIGW_API_KEY_ID` / `NCP_APIGW_API_KEY`) or the Developers Center pair (`NAVER_CLIENT_ID` / `NAVER_CLIENT_SECRET`). OpenClaw's `apiKey` field maps to `NAVER_CLIENT_SECRET`; HUB users should set both HUB variables explicitly in the environment instead of using `apiKey`.
 
 ## Quick Start: Use Without API Key
 
@@ -35,14 +54,16 @@ You can use this server immediately without API keys through [Kakao PlayMCP](htt
 - **search_news**: Search Naver news
 - **search_blog**: Search Naver blogs
 - **search_cafearticle**: Search Naver cafe articles
-- **search_shop**: Search Naver shopping
 - **search_image**: Search Naver images
 - **search_kin**: Search Naver KnowledgeiN
-- **search_book**: Search Naver books
 - **search_encyc**: Search Naver encyclopedia
-- **search_academic**: Search Naver academic papers
 - **search_local**: Search Naver local places
 
+> **Removed in 1.0.49:** `search_shop`, `search_book`, `search_academic`.
+> Naver shuts down the Shopping / Book / Academic search APIs on 2026-07-31 with
+> no replacement on any platform. This is not a limitation of this server.
+> Shopping **Insight** (`datalab_shopping_*`) is a different API and is unaffected.
+
 #### DataLab Tools
 
 - **datalab_search**: Analyze search term trends
@@ -57,18 +78,67 @@ You can use this server immediately without API keys through [Kakao PlayMCP](htt
 
 ## Getting API Keys
 
+Two platforms issue keys for this server. Set **one** pair of environment variables — see
+[Configuration](#configuration) below for how the pair you set determines the platform used.
+
+### Option A: NAVER API HUB (recommended — the forward path)
+
+1. Go to the [NAVER Cloud Platform console](https://www.ncloud.com) and sign up or log in.
+2. Click the region & platform selector in the top right of the console, choose your region/platform, and click **Apply**.
+3. Open **Menu > All Services > Application Services > [NAVER API HUB](https://www.ncloud.com/product/applicationService/naverApiHub)**.
+4. Click **Application**, select (or create) your application, then under API management click **인증 정보 (Authentication Info)**.
+5. Copy the **Client ID** and **Client Secret** shown in the popup.
+6. Use these as `NCP_APIGW_API_KEY_ID` (Client ID) and `NCP_APIGW_API_KEY` (Client Secret) in the configuration below.
+
+### Option B: Naver Developers (legacy — existing keys only)
+
+> Naver Developers Center stops accepting new applications on **2026-07-31**. If you don't
+> already have a Client ID/Secret from this platform, use NAVER API HUB above instead.
+> Existing Developers Center keys keep working until 2027-06-30.
+
 1. Visit [Naver Developers](https://developers.naver.com/apps/#/register) and log in with your Naver account
 2. Click the "Application Registration" (애플리케이션 등록) button
 3. Fill in the application information:
    - **Application Name**: Enter any name (e.g., "Naver Search MCP")
    - **Usage**: Select "Search" (검색)
 4. In the API Settings section, check ALL of the following APIs:
-   - **Search** (검색) - Required for blog, news, book, cafe article, web, image, kin, encyclopedia, academic, and local search
+   - **Search** (검색) - Required for blog, news, cafe article, web, image, kin, encyclopedia, and local search
    - **DataLab - Search Trends** (데이터랩 - 검색어 트렌드) - Required for search term trend analysis
    - **DataLab - Shopping Insight** (데이터랩 - 쇼핑인사이트) - Required for shopping trend analysis
 5. Click "Register" to complete registration
 6. After registration, you'll see your **Client ID** and **Client Secret** on the application detail page
-7. Use these credentials in the configuration below
+7. Use these as `NAVER_CLIENT_ID` / `NAVER_CLIENT_SECRET` in the configuration below
+
+## Configuration
+
+### Credentials
+
+Two platforms are supported. Set **one** pair — the server picks the platform from
+which variables you set, since the key strings themselves are indistinguishable.
+
+| Variables | Platform | Endpoint |
+|---|---|---|
+| `NCP_APIGW_API_KEY_ID`, `NCP_APIGW_API_KEY` | NAVER API HUB (NCP) | `naverapihub.apigw.ntruss.com` |
+| `NAVER_CLIENT_ID`, `NAVER_CLIENT_SECRET` | Naver Developers (legacy) | `openapi.naver.com` |
+
+If both pairs are set, NAVER API HUB wins.
+
+The installation examples below use the legacy `NAVER_CLIENT_ID` / `NAVER_CLIENT_SECRET`
+pair; swap in the HUB pair from the table above if that's what you have.
+
+### Migration to NAVER API HUB
+
+Naver is moving these APIs from the Developers Center to NAVER API HUB on NAVER Cloud Platform.
+
+| Date | What happens |
+|---|---|
+| 2026-06-25 | NAVER API HUB launched |
+| 2026-07-31 | Developers Center stops accepting new applications |
+| 2027-06-30 | Developers Center support ends — existing keys stop working |
+
+Existing keys keep working until 2027-06-30. To migrate, get a key from the
+NAVER Cloud Platform console and set `NCP_APIGW_API_KEY_ID` / `NCP_APIGW_API_KEY`.
+Developers Center keys cannot be used against NAVER API HUB.
 
 ## Installation
 
@@ -128,7 +198,7 @@ The ClawHub skill uses the same published npm package internally:
 npx -y @isnow890/naver-search-mcp
 ```
 
-Make sure `NAVER_CLIENT_ID` and `NAVER_CLIENT_SECRET` are configured in your OpenClaw environment before using the skill.
+Make sure **one** credential pair is configured in your OpenClaw environment before using the skill — the NAVER API HUB pair (`NCP_APIGW_API_KEY_ID` / `NCP_APIGW_API_KEY`) or the Developers Center pair (`NAVER_CLIENT_ID` / `NAVER_CLIENT_SECRET`). OpenClaw's `apiKey` field maps to `NAVER_CLIENT_SECRET`; HUB users should set both HUB variables explicitly instead.
 
 ### Method 3: Local Installation
 
@@ -239,7 +309,7 @@ After completing the configuration, completely close and restart Claude Desktop
 
 ## Prerequisites
 
-- Naver Developers API Key (Client ID and Secret)
+- A credential pair for one platform — NAVER API HUB or Naver Developers (see [Getting API Keys](#getting-api-keys))
 - Node.js 18 or higher
 - NPM 8 or higher
 
@@ -251,6 +321,13 @@ MIT License
 
 ## Version History
 
+### 1.0.49 (2026-07-26)
+
+- NAVER API HUB support: set `NCP_APIGW_API_KEY_ID` / `NCP_APIGW_API_KEY` to call the new platform. Existing `NAVER_CLIENT_ID` / `NAVER_CLIENT_SECRET` keep working unchanged — the platform is chosen by which variable pair you set
+- **Removed** `search_shop`, `search_book`, `search_academic`. Naver shuts those search APIs down on 2026-07-31 with no replacement on any platform
+- API errors now throw a plain `Error` instead of the raw `AxiosError`. Code branching on `error.response?.status` sees `undefined`; the same detail is in `Error.message`
+- Error messages name the platform and HTTP status, and 401s suggest checking whether a key was set on the other platform's variables
+
 ### 1.0.48 (2026-05-12)
 
 - Fixed `find_category` data loading when the MCP server is launched by `npx` from a different working directory

package/dist/src/clients/naver-api-core.client.d.ts

@@ -1,15 +1,26 @@
 import { AxiosRequestConfig, AxiosInstance } from "axios";
 import { NaverSearchConfig } from "../schemas/search.schemas.js";
+import { NaverApiProvider } from "./naver-api-endpoints.js";
 export declare abstract class NaverApiCoreClient {
-    protected searchBaseUrl: string;
-    protected datalabBaseUrl: string;
     protected config: NaverSearchConfig | null;
     protected axiosInstance: AxiosInstance;
     constructor();
     initialize(config: NaverSearchConfig): void;
+    private requireConfig;
+    get provider(): NaverApiProvider;
+    /** 검색 API base. `${searchBaseUrl}/${type}` 형태로 사용한다. */
+    get searchBaseUrl(): string;
+    /** 검색어 트렌드 전체 URL. suffix를 붙이지 않는다. */
+    get trendUrl(): string;
+    /** 쇼핑인사이트 base. `${shoppingBaseUrl}/categories` 형태로 사용한다. */
+    get shoppingBaseUrl(): string;
     protected getHeaders(contentType?: string): AxiosRequestConfig;
     protected get<T>(url: string, params: any): Promise<T>;
     protected post<T>(url: string, data: any): Promise<T>;
+    /**
+     * 두 플랫폼의 오류 응답 형식이 다르므로 파싱하지 않고 그대로 감싼다.
+     */
+    private wrapError;
     /**
      * 리소스 정리 메서드 (메모리 누수 방지)
      */

package/dist/src/clients/naver-api-core.client.js

@@ -1,58 +1,88 @@
 import axios from "axios";
+import { getEndpoints, getAuthHeaderNames, } from "./naver-api-endpoints.js";
+import { formatApiError } from "./naver-api-error.js";
 export class NaverApiCoreClient {
     constructor() {
-        this.searchBaseUrl = "https://openapi.naver.com/v1/search";
-        this.datalabBaseUrl = "https://openapi.naver.com/v1/datalab";
         this.config = null;
         // HTTP/HTTPS 에이전트 설정으로 연결 풀링 및 메모리 누수 방지
         this.axiosInstance = axios.create({
             timeout: 30000, // 30초 타임아웃
             maxRedirects: 3,
-            // HTTP 연결 풀링 설정은 운영체제에서 처리하도록 단순화
         });
     }
     initialize(config) {
         this.config = config;
     }
-    getHeaders(contentType = "application/json") {
+    requireConfig() {
         if (!this.config)
             throw new Error("NaverApiCoreClient is not initialized.");
+        return this.config;
+    }
+    get provider() {
+        return this.requireConfig().provider;
+    }
+    /** 검색 API base. `${searchBaseUrl}/${type}` 형태로 사용한다. */
+    get searchBaseUrl() {
+        return getEndpoints(this.provider).search;
+    }
+    /** 검색어 트렌드 전체 URL. suffix를 붙이지 않는다. */
+    get trendUrl() {
+        return getEndpoints(this.provider).trend;
+    }
+    /** 쇼핑인사이트 base. `${shoppingBaseUrl}/categories` 형태로 사용한다. */
+    get shoppingBaseUrl() {
+        return getEndpoints(this.provider).shopping;
+    }
+    getHeaders(contentType = "application/json") {
+        const config = this.requireConfig();
+        const names = getAuthHeaderNames(config.provider);
         return {
             headers: {
-                "X-Naver-Client-Id": this.config.clientId,
-                "X-Naver-Client-Secret": this.config.clientSecret,
+                [names.id]: config.clientId,
+                [names.secret]: config.clientSecret,
                 "Content-Type": contentType,
             },
         };
     }
     async get(url, params) {
+        // provider를 요청 시점에 고정한다. 응답이 도착하기 전에 destroyInstance()가
+        // config를 비울 수 있고, 그때 this.provider를 읽으면 원래 에러가 사라진다.
+        const provider = this.provider;
         try {
             const response = await this.axiosInstance.get(url, {
                 params,
-                ...this.getHeaders()
+                ...this.getHeaders(),
             });
             return response.data;
         }
         catch (error) {
-            // 연결 정리는 axios가 자동으로 처리하지만 명시적으로 에러 처리
-            throw error;
+            throw this.wrapError(provider, url, error);
         }
     }
     async post(url, data) {
+        const provider = this.provider;
         try {
             const response = await this.axiosInstance.post(url, data, this.getHeaders());
             return response.data;
         }
         catch (error) {
-            // 연결 정리는 axios가 자동으로 처리하지만 명시적으로 에러 처리
-            throw error;
+            throw this.wrapError(provider, url, error);
         }
     }
+    /**
+     * 두 플랫폼의 오류 응답 형식이 다르므로 파싱하지 않고 그대로 감싼다.
+     */
+    wrapError(provider, url, error) {
+        const response = error?.response;
+        // 응답이 아예 없는 실패(타임아웃, DNS 실패, 연결 거부)는 axios 메시지가 유일한
+        // 단서다. 이걸 버리면 모든 네트워크 오류가 똑같은 문장으로 뭉개진다.
+        const body = response ? response.data : error?.message;
+        return new Error(formatApiError(provider, url, response?.status, body));
+    }
     /**
      * 리소스 정리 메서드 (메모리 누수 방지)
      */
     cleanup() {
-        // 연결 정리 - axios가 자동으로 처리
         this.config = null;
     }
 }

package/dist/src/clients/naver-api-endpoints.d.ts

@@ -0,0 +1,16 @@
+/** 네이버 API 제공 플랫폼 */
+export type NaverApiProvider = "legacy" | "hub";
+export interface NaverApiEndpoints {
+    /** 검색 API base. `${search}/${type}` 형태로 사용한다. */
+    search: string;
+    /** 검색어 트렌드 전체 URL. suffix를 붙이지 않는다. */
+    trend: string;
+    /** 쇼핑인사이트 base. `${shopping}/categories` 형태로 사용한다. */
+    shopping: string;
+}
+export interface NaverAuthHeaderNames {
+    id: string;
+    secret: string;
+}
+export declare function getEndpoints(provider: NaverApiProvider): NaverApiEndpoints;
+export declare function getAuthHeaderNames(provider: NaverApiProvider): NaverAuthHeaderNames;

package/dist/src/clients/naver-api-endpoints.js

@@ -0,0 +1,22 @@
+const ENDPOINTS = {
+    legacy: {
+        search: "https://openapi.naver.com/v1/search",
+        trend: "https://openapi.naver.com/v1/datalab/search",
+        shopping: "https://openapi.naver.com/v1/datalab/shopping",
+    },
+    hub: {
+        search: "https://naverapihub.apigw.ntruss.com/search/v1",
+        trend: "https://naverapihub.apigw.ntruss.com/search-trend/v1/search",
+        shopping: "https://naverapihub.apigw.ntruss.com/shopping/v1",
+    },
+};
+const AUTH_HEADER_NAMES = {
+    legacy: { id: "X-Naver-Client-Id", secret: "X-Naver-Client-Secret" },
+    hub: { id: "X-NCP-APIGW-API-KEY-ID", secret: "X-NCP-APIGW-API-KEY" },
+};
+export function getEndpoints(provider) {
+    return ENDPOINTS[provider];
+}
+export function getAuthHeaderNames(provider) {
+    return AUTH_HEADER_NAMES[provider];
+}

package/dist/src/clients/naver-api-error.d.ts

@@ -0,0 +1,5 @@
+import { NaverApiProvider } from "./naver-api-endpoints.js";
+/**
+ * 두 플랫폼의 오류 응답 형식이 다르므로 파싱하지 않고 그대로 실어 보낸다.
+ */
+export declare function formatApiError(provider: NaverApiProvider, url: string, status: number | undefined, body: unknown): string;

package/dist/src/clients/naver-api-error.js

@@ -0,0 +1,33 @@
+const PROVIDER_LABEL = {
+    legacy: "네이버 개발자센터",
+    hub: "NAVER API HUB",
+};
+const SWAPPED_KEY_HINT = {
+    legacy: "인증에 실패했습니다. NAVER API HUB 키를 NAVER_CLIENT_ID/NAVER_CLIENT_SECRET에 넣지 않았는지 확인하세요. HUB 키는 NCP_APIGW_API_KEY_ID/NCP_APIGW_API_KEY에 넣어야 합니다.",
+    hub: "인증에 실패했습니다. 개발자센터 키를 NCP_APIGW_API_KEY_ID/NCP_APIGW_API_KEY에 넣지 않았는지 확인하세요. 개발자센터 키는 NAVER_CLIENT_ID/NAVER_CLIENT_SECRET에 넣어야 합니다.",
+};
+function stringifyBody(body) {
+    if (body === undefined || body === null)
+        return "";
+    if (typeof body === "string")
+        return body;
+    try {
+        return JSON.stringify(body);
+    }
+    catch {
+        return String(body);
+    }
+}
+/**
+ * 두 플랫폼의 오류 응답 형식이 다르므로 파싱하지 않고 그대로 실어 보낸다.
+ */
+export function formatApiError(provider, url, status, body) {
+    const statusText = status === undefined ? "no response" : `HTTP ${status}`;
+    const lines = [`[${PROVIDER_LABEL[provider]}] ${statusText} — ${url}`];
+    const bodyText = stringifyBody(body);
+    if (bodyText)
+        lines.push(bodyText);
+    if (status === 401)
+        lines.push(SWAPPED_KEY_HINT[provider]);
+    return lines.join("\n");
+}

package/dist/src/clients/naver-search.client.d.ts

@@ -1,6 +1,6 @@
 import { NaverApiCoreClient } from "./naver-api-core.client.js";
-import { NaverSearchType, NaverSearchConfig, NaverLocalSearchParams, NaverDocumentSearchParams, SearchArgs } from "../schemas/search.schemas.js";
-import { NaverDocumentSearchResponse, NaverLocalSearchResponse } from "../types/search.types.js";
+import { NaverSearchType, NaverSearchConfig, NaverLocalSearchParams, SearchArgs } from "../schemas/search.schemas.js";
+import { NaverLocalSearchResponse } from "../types/search.types.js";
 import { DatalabSearchRequest, DatalabShoppingResponse, DatalabShoppingCategoryRequest, DatalabShoppingDeviceRequest, DatalabShoppingGenderRequest, DatalabShoppingAgeRequest, DatalabShoppingKeywordsRequest, DatalabShoppingKeywordRequest } from "../types/datalab.types.js";
 /**
  * NaverSearchClient - 네이버 API 서비스를 위한 싱글톤 클라이언트
@@ -31,10 +31,6 @@ export declare class NaverSearchClient extends NaverApiCoreClient {
      * @param params 검색 파라미터
      */
     search(type: NaverSearchType, params: SearchArgs): Promise<any>;
-    /**
-     * 전문자료 검색 메서드
-     */
-    searchAcademic(params: NaverDocumentSearchParams): Promise<NaverDocumentSearchResponse>;
     /**
      * 지역 검색 메서드
      */

package/dist/src/clients/naver-search.client.js

@@ -47,12 +47,6 @@ export class NaverSearchClient extends NaverApiCoreClient {
     async search(type, params) {
         return this.get(`${this.searchBaseUrl}/${type}`, params);
     }
-    /**
-     * 전문자료 검색 메서드
-     */
-    async searchAcademic(params) {
-        return this.get(`${this.searchBaseUrl}/doc`, params);
-    }
     /**
      * 지역 검색 메서드
      */
@@ -63,55 +57,55 @@ export class NaverSearchClient extends NaverApiCoreClient {
      * 검색어 트렌드 분석 메서드
      */
     async searchTrend(params) {
-        return this.post(`${this.datalabBaseUrl}/search`, params);
+        return this.post(this.trendUrl, params);
     }
     /**
      * 쇼핑 카테고리 트렌드 분석 메서드
      */
     async datalabShoppingCategory(params) {
-        return this.post(`${this.datalabBaseUrl}/shopping/categories`, params);
+        return this.post(`${this.shoppingBaseUrl}/categories`, params);
     }
     /**
      * 쇼핑 기기별 트렌드 분석 메서드
      */
     async datalabShoppingByDevice(params) {
-        return this.post(`${this.datalabBaseUrl}/shopping/category/device`, params);
+        return this.post(`${this.shoppingBaseUrl}/category/device`, params);
     }
     /**
      * 쇼핑 성별 트렌드 분석 메서드
      */
     async datalabShoppingByGender(params) {
-        return this.post(`${this.datalabBaseUrl}/shopping/category/gender`, params);
+        return this.post(`${this.shoppingBaseUrl}/category/gender`, params);
     }
     /**
      * 쇼핑 연령별 트렌드 분석 메서드
      */
     async datalabShoppingByAge(params) {
-        return this.post(`${this.datalabBaseUrl}/shopping/category/age`, params);
+        return this.post(`${this.shoppingBaseUrl}/category/age`, params);
     }
     /**
      * 쇼핑 키워드 트렌드 분석 메서드
      */
     async datalabShoppingKeywords(params) {
-        return this.post(`${this.datalabBaseUrl}/shopping/category/keywords`, params);
+        return this.post(`${this.shoppingBaseUrl}/category/keywords`, params);
     }
     /**
      * 쇼핑 키워드 기기별 트렌드 분석 메서드
      */
     async datalabShoppingKeywordByDevice(params) {
-        return this.post(`${this.datalabBaseUrl}/shopping/category/keyword/device`, params);
+        return this.post(`${this.shoppingBaseUrl}/category/keyword/device`, params);
     }
     /**
      * 쇼핑 키워드 성별 트렌드 분석 메서드
      */
     async datalabShoppingKeywordByGender(params) {
-        return this.post(`${this.datalabBaseUrl}/shopping/category/keyword/gender`, params);
+        return this.post(`${this.shoppingBaseUrl}/category/keyword/gender`, params);
     }
     /**
      * 쇼핑 키워드 연령별 트렌드 분석 메서드
      */
     async datalabShoppingKeywordByAge(params) {
-        return this.post(`${this.datalabBaseUrl}/shopping/category/keyword/age`, params);
+        return this.post(`${this.shoppingBaseUrl}/category/keyword/age`, params);
     }
 }
 NaverSearchClient.instance = null;

package/dist/src/config/credentials.d.ts

@@ -0,0 +1,20 @@
+import { NaverApiProvider } from "../clients/naver-api-endpoints.js";
+export interface CredentialEnv {
+    NAVER_CLIENT_ID?: string;
+    NAVER_CLIENT_SECRET?: string;
+    NCP_APIGW_API_KEY_ID?: string;
+    NCP_APIGW_API_KEY?: string;
+}
+export interface ResolvedCredentials {
+    provider: NaverApiProvider;
+    clientId: string;
+    clientSecret: string;
+    /** 해석은 성공했지만 사용자에게 알릴 것이 있을 때만 채운다. 없으면 키 자체를 넣지 않는다. */
+    warning?: string;
+}
+/**
+ * 환경변수에서 자격증명을 읽어 사용할 provider를 결정한다.
+ * 키 값 자체로는 두 플랫폼을 구분할 수 없으므로, 어느 변수에 들어있는지로 판단한다.
+ * HUB 쌍이 legacy 쌍보다 우선한다.
+ */
+export declare function resolveCredentials(env: CredentialEnv): ResolvedCredentials;

package/dist/src/config/credentials.js

@@ -0,0 +1,53 @@
+const SETUP_GUIDE = `
+NAVER API HUB(권장): NCP_APIGW_API_KEY_ID, NCP_APIGW_API_KEY
+  발급: NAVER Cloud Platform 콘솔 > NAVER API HUB
+네이버 개발자센터(2027-06-30 지원 종료): NAVER_CLIENT_ID, NAVER_CLIENT_SECRET
+
+두 자격증명은 서로 호환되지 않습니다. 발급받은 플랫폼에 맞는 환경변수에 넣어주세요.`;
+/**
+ * 환경변수에서 자격증명을 읽어 사용할 provider를 결정한다.
+ * 키 값 자체로는 두 플랫폼을 구분할 수 없으므로, 어느 변수에 들어있는지로 판단한다.
+ * HUB 쌍이 legacy 쌍보다 우선한다.
+ */
+export function resolveCredentials(env) {
+    const hubId = env.NCP_APIGW_API_KEY_ID?.trim();
+    const hubSecret = env.NCP_APIGW_API_KEY?.trim();
+    const legacyId = env.NAVER_CLIENT_ID?.trim();
+    const legacySecret = env.NAVER_CLIENT_SECRET?.trim();
+    if (hubId && hubSecret) {
+        return { provider: "hub", clientId: hubId, clientSecret: hubSecret };
+    }
+    if (hubId || hubSecret) {
+        const missing = hubId ? "NCP_APIGW_API_KEY" : "NCP_APIGW_API_KEY_ID";
+        // HUB 키가 반쪽이어도 개발자센터 키가 온전하면 서버를 죽이지 않는다.
+        // 이관 중에 HUB 키를 반만 넣어둔 기존 사용자를 막지 않되, 실수는 경고로 드러낸다.
+        if (legacyId && legacySecret) {
+            return {
+                provider: "legacy",
+                clientId: legacyId,
+                clientSecret: legacySecret,
+                warning: `NAVER API HUB 자격증명이 반쪽입니다. ${missing} 이(가) 설정되지 않아 개발자센터 키로 동작합니다.
+HUB로 이관하려면 ${missing} 을(를) 마저 설정하고, 이관할 생각이 없다면 남은 HUB 환경변수를 지우세요.`,
+            };
+        }
+        throw new Error(`NAVER API HUB 자격증명이 불완전합니다.
+  NCP_APIGW_API_KEY_ID: ${hubId ? "provided" : "missing"}
+  NCP_APIGW_API_KEY: ${hubSecret ? "provided" : "missing"}
+두 값을 함께 설정해야 합니다.`);
+    }
+    if (legacyId && legacySecret) {
+        return {
+            provider: "legacy",
+            clientId: legacyId,
+            clientSecret: legacySecret,
+        };
+    }
+    if (legacyId || legacySecret) {
+        throw new Error(`네이버 개발자센터 자격증명이 불완전합니다.
+  NAVER_CLIENT_ID: ${legacyId ? "provided" : "missing"}
+  NAVER_CLIENT_SECRET: ${legacySecret ? "provided" : "missing"}
+두 값을 함께 설정해야 합니다.`);
+    }
+    throw new Error(`자격증명이 설정되지 않았습니다.
+${SETUP_GUIDE}`);
+}

package/dist/src/handlers/search.handlers.d.ts

@@ -1,14 +1,6 @@
 import { NaverLocalSearchParams } from "../schemas/search.schemas.js";
 import { SearchArgs } from "../schemas/search.schemas.js";
 export declare const searchToolHandlers: Record<string, (args: any) => Promise<any>>;
-/**
- * 전문자료 검색 핸들러
- */
-export declare function handleAcademicSearch(params: SearchArgs): Promise<import("../types/search.types.js").NaverDocumentSearchResponse>;
-/**
- * 도서 검색 핸들러
- */
-export declare function handleBookSearch(params: SearchArgs): Promise<any>;
 /**
  * 지식백과 검색 핸들러
  */
@@ -33,10 +25,6 @@ export declare function handleNewsSearch(params: SearchArgs): Promise<any>;
  * 블로그 검색 핸들러
  */
 export declare function handleBlogSearch(params: SearchArgs): Promise<any>;
-/**
- * 쇼핑 검색 핸들러
- */
-export declare function handleShopSearch(params: SearchArgs): Promise<any>;
 /**
  * 카페글 검색 핸들러
  */

package/dist/src/handlers/search.handlers.js

@@ -15,10 +15,6 @@ export const searchToolHandlers = {
         console.error("search_blog called with args:", JSON.stringify(args, null, 2));
         return handleBlogSearch(SearchArgsSchema.parse(args));
     },
-    search_shop: (args) => {
-        console.error("search_shop called with args:", JSON.stringify(args, null, 2));
-        return handleShopSearch(SearchArgsSchema.parse(args));
-    },
     search_image: (args) => {
         console.error("search_image called with args:", JSON.stringify(args, null, 2));
         return handleImageSearch(SearchArgsSchema.parse(args));
@@ -27,18 +23,10 @@ export const searchToolHandlers = {
         console.error("search_kin called with args:", JSON.stringify(args, null, 2));
         return handleKinSearch(SearchArgsSchema.parse(args));
     },
-    search_book: (args) => {
-        console.error("search_book called with args:", JSON.stringify(args, null, 2));
-        return handleBookSearch(SearchArgsSchema.parse(args));
-    },
     search_encyc: (args) => {
         console.error("search_encyc called with args:", JSON.stringify(args, null, 2));
         return handleEncycSearch(SearchArgsSchema.parse(args));
     },
-    search_academic: (args) => {
-        console.error("search_academic called with args:", JSON.stringify(args, null, 2));
-        return handleAcademicSearch(SearchArgsSchema.parse(args));
-    },
     search_local: (args) => {
         console.error("search_local called with args:", JSON.stringify(args, null, 2));
         return handleLocalSearch(args);
@@ -48,18 +36,6 @@ export const searchToolHandlers = {
         return handleCafeArticleSearch(SearchArgsSchema.parse(args));
     },
 };
-/**
- * 전문자료 검색 핸들러
- */
-export async function handleAcademicSearch(params) {
-    return client.searchAcademic(params);
-}
-/**
- * 도서 검색 핸들러
- */
-export async function handleBookSearch(params) {
-    return client.search("book", params);
-}
 /**
  * 지식백과 검색 핸들러
  */
@@ -96,12 +72,6 @@ export async function handleNewsSearch(params) {
 export async function handleBlogSearch(params) {
     return client.search("blog", params);
 }
-/**
- * 쇼핑 검색 핸들러
- */
-export async function handleShopSearch(params) {
-    return client.search("shop", params);
-}
 /**
  * 카페글 검색 핸들러
  */

package/dist/src/index.d.ts

@@ -2,14 +2,20 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 export declare const configSchema: z.ZodObject<{
-    NAVER_CLIENT_ID: z.ZodString;
-    NAVER_CLIENT_SECRET: z.ZodString;
+    NAVER_CLIENT_ID: z.ZodOptional<z.ZodString>;
+    NAVER_CLIENT_SECRET: z.ZodOptional<z.ZodString>;
+    NCP_APIGW_API_KEY_ID: z.ZodOptional<z.ZodString>;
+    NCP_APIGW_API_KEY: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    NAVER_CLIENT_ID: string;
-    NAVER_CLIENT_SECRET: string;
+    NCP_APIGW_API_KEY?: string | undefined;
+    NCP_APIGW_API_KEY_ID?: string | undefined;
+    NAVER_CLIENT_ID?: string | undefined;
+    NAVER_CLIENT_SECRET?: string | undefined;
 }, {
-    NAVER_CLIENT_ID: string;
-    NAVER_CLIENT_SECRET: string;
+    NCP_APIGW_API_KEY?: string | undefined;
+    NCP_APIGW_API_KEY_ID?: string | undefined;
+    NAVER_CLIENT_ID?: string | undefined;
+    NAVER_CLIENT_SECRET?: string | undefined;
 }>;
 /**
  * 서버 인스턴스와 관련 리소스 정리 (메모리 누수 방지)

package/dist/src/index.js

@@ -9,10 +9,22 @@ import { SearchArgsSchema, NaverLocalSearchParamsSchema, } from "./schemas/searc
 import { DatalabSearchSchema, DatalabShoppingSchema, DatalabShoppingDeviceSchema, DatalabShoppingGenderSchema, DatalabShoppingAgeSchema, DatalabShoppingKeywordsSchema, DatalabShoppingKeywordDeviceSchema, DatalabShoppingKeywordGenderSchema, DatalabShoppingKeywordAgeSchema, } from "./schemas/datalab.schemas.js";
 import { FindCategorySchema } from "./schemas/category.schemas.js";
 import { findCategoryHandler, clearCategoriesCache } from "./handlers/category.handlers.js";
+import { resolveCredentials } from "./config/credentials.js";
 // Configuration schema for programmatic server creation and stdio startup
 export const configSchema = z.object({
-    NAVER_CLIENT_ID: z.string().describe("Naver API Client ID"),
-    NAVER_CLIENT_SECRET: z.string().describe("Naver API Client Secret"),
+    NAVER_CLIENT_ID: z.string().optional().describe("네이버 개발자센터 Client ID"),
+    NAVER_CLIENT_SECRET: z
+        .string()
+        .optional()
+        .describe("네이버 개발자센터 Client Secret"),
+    NCP_APIGW_API_KEY_ID: z
+        .string()
+        .optional()
+        .describe("NAVER API HUB Client ID"),
+    NCP_APIGW_API_KEY: z
+        .string()
+        .optional()
+        .describe("NAVER API HUB Client Secret"),
 });
 // Global server instance to prevent memory leaks
 let globalServerInstance = null;
@@ -38,7 +50,9 @@ function isConfigChanged(newConfig) {
     if (!currentConfig)
         return true;
     return (currentConfig.NAVER_CLIENT_ID !== newConfig.NAVER_CLIENT_ID ||
-        currentConfig.NAVER_CLIENT_SECRET !== newConfig.NAVER_CLIENT_SECRET);
+        currentConfig.NAVER_CLIENT_SECRET !== newConfig.NAVER_CLIENT_SECRET ||
+        currentConfig.NCP_APIGW_API_KEY_ID !== newConfig.NCP_APIGW_API_KEY_ID ||
+        currentConfig.NCP_APIGW_API_KEY !== newConfig.NCP_APIGW_API_KEY);
 }
 export function createNaverSearchServer({ config, }) {
     // 설정이 변경된 경우 기존 인스턴스 정리
@@ -53,14 +67,18 @@ export function createNaverSearchServer({ config, }) {
     // Create a new MCP server only once
     const server = new McpServer({
         name: "naver-search",
-        version: "1.0.44",
+        version: "1.0.49",
     });
     // Initialize Naver client with config
+    const credentials = resolveCredentials(config);
+    console.error(`Using ${credentials.provider === "hub"
+        ? "NAVER API HUB"
+        : "네이버 개발자센터 (2027-06-30 지원 종료 예정)"}`);
+    if (credentials.warning) {
+        console.error(`[경고] ${credentials.warning}`);
+    }
     const client = NaverSearchClient.getInstance();
-    client.initialize({
-        clientId: config.NAVER_CLIENT_ID,
-        clientSecret: config.NAVER_CLIENT_SECRET,
-    });
+    client.initialize(credentials);
     server.registerTool("search_webkr", {
         description: "🌐 Search Korean web documents and general content. Comprehensive search across Korean websites and online content. Find articles, information, and documents from various Korean sources. For recent content or 'today's results', use get_current_korean_time first. (네이버 웹문서 검색 - 한국 웹사이트 종합 검색, 최근 콘텐츠나 오늘 결과를 찾을 때는 먼저 get_current_korean_time으로 현재 시간을 확인하세요)",
         inputSchema: SearchArgsSchema.shape,
@@ -88,15 +106,6 @@ export function createNaverSearchServer({ config, }) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    server.registerTool("search_shop", {
-        description: "🛒 Search Naver Shopping for products, prices, and shopping deals. Compare prices across vendors, find product specifications, and discover shopping trends in Korea. For current deals or today's specials, use get_current_korean_time first. (네이버 쇼핑 검색 - 상품 정보와 가격 비교, 현재 할인이나 오늘 특가를 찾을 때는 먼저 get_current_korean_time으로 현재 시간을 확인하세요)",
-        inputSchema: SearchArgsSchema.shape,
-    }, async (args) => {
-        const result = await searchToolHandlers.search_shop(args);
-        return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-        };
-    });
     server.registerTool("search_image", {
         description: "🖼️ Search for images with Korean context and relevance. Find visual content, infographics, charts, and photos related to your search terms. Great for visual research and content discovery. For recent images or current visual content, use get_current_korean_time first. (네이버 이미지 검색 - 시각적 컨텐츠 발견, 최근 이미지나 현재 시각 자료를 찾을 때는 먼저 get_current_korean_time으로 현재 시간을 확인하세요)",
         inputSchema: SearchArgsSchema.shape,
@@ -115,15 +124,6 @@ export function createNaverSearchServer({ config, }) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    server.registerTool("search_book", {
-        description: "📚 Search for books, publications, and literary content. Find book reviews, author information, publication details, and reading recommendations in Korean literature and translated works. For new releases or current bestsellers, use get_current_korean_time first. (네이버 책 검색 - 도서 정보와 서평, 신간도서나 현재 베스트셀러를 찾을 때는 먼저 get_current_korean_time으로 현재 시간을 확인하세요)",
-        inputSchema: SearchArgsSchema.shape,
-    }, async (args) => {
-        const result = await searchToolHandlers.search_book(args);
-        return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-        };
-    });
     server.registerTool("search_encyc", {
         description: "📖 Search Naver Encyclopedia for authoritative knowledge and definitions. Best for academic research, getting reliable information, and understanding Korean concepts and terminology. For current definitions or recent updates, use get_current_korean_time for context. (네이버 지식백과 검색 - 신뢰할 수 있는 정보와 정의, 현재 정의나 최근 업데이트를 찾을 때는 get_current_korean_time으로 상황을 파악하세요)",
         inputSchema: SearchArgsSchema.shape,
@@ -133,15 +133,6 @@ export function createNaverSearchServer({ config, }) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     });
-    server.registerTool("search_academic", {
-        description: "🎓 Search academic papers, research documents, and scholarly content. Access Korean academic resources, research papers, theses, and professional publications. For recent publications or current research, use get_current_korean_time first. (네이버 전문자료 검색 - 학술 논문과 전문 자료, 최근 발표나 현재 연구를 찾을 때는 먼저 get_current_korean_time으로 현재 시간을 확인하세요)",
-        inputSchema: SearchArgsSchema.shape,
-    }, async (args) => {
-        const result = await searchToolHandlers.search_academic(args);
-        return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-        };
-    });
     server.registerTool("search_local", {
         description: "📍 Search for local businesses, restaurants, and places in Korea. Find location information, reviews, contact details, and business hours for Korean establishments. For current business hours or today's availability, use get_current_korean_time first. (네이버 지역 검색 - 지역 업체와 장소 정보, 현재 영업시간이나 오늘 이용 가능 여부를 확인할 때는 먼저 get_current_korean_time으로 현재 시간을 확인하세요)",
         inputSchema: NaverLocalSearchParamsSchema.shape,
@@ -314,29 +305,29 @@ function registerShutdownHandlers({ server, transport, }) {
 async function main() {
     try {
         console.error("Starting Naver Search MCP Server...");
-        // Get config from environment variables - check for empty strings too
-        const clientId = process.env.NAVER_CLIENT_ID?.trim();
-        const clientSecret = process.env.NAVER_CLIENT_SECRET?.trim();
+        // Get config from environment variables
+        const config = {
+            NAVER_CLIENT_ID: process.env.NAVER_CLIENT_ID,
+            NAVER_CLIENT_SECRET: process.env.NAVER_CLIENT_SECRET,
+            NCP_APIGW_API_KEY_ID: process.env.NCP_APIGW_API_KEY_ID,
+            NCP_APIGW_API_KEY: process.env.NCP_APIGW_API_KEY,
+        };
         console.error("Environment variables:", {
-            NAVER_CLIENT_ID: process.env.NAVER_CLIENT_ID
-                ? `[${process.env.NAVER_CLIENT_ID.length} chars]`
+            NAVER_CLIENT_ID: config.NAVER_CLIENT_ID
+                ? `[${config.NAVER_CLIENT_ID.length} chars]`
+                : "undefined",
+            NAVER_CLIENT_SECRET: config.NAVER_CLIENT_SECRET
+                ? `[${config.NAVER_CLIENT_SECRET.length} chars]`
+                : "undefined",
+            NCP_APIGW_API_KEY_ID: config.NCP_APIGW_API_KEY_ID
+                ? `[${config.NCP_APIGW_API_KEY_ID.length} chars]`
                 : "undefined",
-            NAVER_CLIENT_SECRET: process.env.NAVER_CLIENT_SECRET
-                ? `[${process.env.NAVER_CLIENT_SECRET.length} chars]`
+            NCP_APIGW_API_KEY: config.NCP_APIGW_API_KEY
+                ? `[${config.NCP_APIGW_API_KEY.length} chars]`
                 : "undefined",
         });
-        if (!clientId || !clientSecret) {
-            throw new Error(`Missing required environment variables:
-        NAVER_CLIENT_ID: ${clientId ? "provided" : "missing"}
-        NAVER_CLIENT_SECRET: ${clientSecret ? "provided" : "missing"}
-        
-        Please set these environment variables before running the server.`);
-        }
-        const config = {
-            NAVER_CLIENT_ID: clientId,
-            NAVER_CLIENT_SECRET: clientSecret,
-        };
-        console.error("Config loaded successfully");
+        // 자격증명 유효성은 여기서 먼저 확인한다 (실패 시 명확한 안내와 함께 종료)
+        resolveCredentials(config);
         // Validate config
         const validatedConfig = configSchema.parse(config);
         console.error("Config validated successfully");

package/dist/src/schemas/search.schemas.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-export declare const NaverSearchTypeSchema: z.ZodEnum<["news", "encyc", "blog", "shop", "webkr", "image", "doc", "kin", "book", "cafearticle", "local"]>;
+export declare const NaverSearchTypeSchema: z.ZodEnum<["news", "encyc", "blog", "webkr", "image", "kin", "cafearticle", "local"]>;
 export declare const NaverSearchParamsSchema: z.ZodObject<{
     query: z.ZodString;
     display: z.ZodOptional<z.ZodNumber>;
@@ -33,28 +33,18 @@ export declare const SearchArgsSchema: z.ZodObject<{
     sort?: "sim" | "date" | undefined;
 }>;
 export declare const NaverSearchConfigSchema: z.ZodObject<{
+    provider: z.ZodEnum<["legacy", "hub"]>;
     clientId: z.ZodString;
     clientSecret: z.ZodString;
 }, "strip", z.ZodTypeAny, {
+    provider: "legacy" | "hub";
     clientId: string;
     clientSecret: string;
 }, {
+    provider: "legacy" | "hub";
     clientId: string;
     clientSecret: string;
 }>;
-export declare const NaverDocumentSearchParamsSchema: z.ZodObject<{
-    query: z.ZodString;
-    display: z.ZodOptional<z.ZodNumber>;
-    start: z.ZodOptional<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    query: string;
-    display?: number | undefined;
-    start?: number | undefined;
-}, {
-    query: string;
-    display?: number | undefined;
-    start?: number | undefined;
-}>;
 export declare const NaverLocalSearchParamsSchema: z.ZodObject<{
     query: z.ZodString;
 } & {
@@ -77,4 +67,3 @@ export type NaverSearchParams = z.infer<typeof NaverSearchParamsSchema>;
 export type SearchArgs = z.infer<typeof SearchArgsSchema>;
 export type NaverSearchType = z.infer<typeof NaverSearchTypeSchema>;
 export type NaverSearchConfig = z.infer<typeof NaverSearchConfigSchema>;
-export type NaverDocumentSearchParams = z.infer<typeof NaverDocumentSearchParamsSchema>;

package/dist/src/schemas/search.schemas.js

@@ -4,12 +4,9 @@ export const NaverSearchTypeSchema = z.enum([
     "news",
     "encyc",
     "blog",
-    "shop",
     "webkr",
     "image",
-    "doc",
     "kin",
-    "book",
     "cafearticle",
     "local",
 ]);
@@ -40,16 +37,11 @@ export const SearchArgsSchema = z.object({
 });
 // 네이버 API 인증 정보
 export const NaverSearchConfigSchema = z.object({
-    clientId: z.string().describe("네이버 개발자센터에서 발급받은 Client ID"),
-    clientSecret: z
-        .string()
-        .describe("네이버 개발자센터에서 발급받은 Client Secret"),
-});
-// 전문자료(논문 등) 검색 파라미터
-export const NaverDocumentSearchParamsSchema = z.object({
-    query: z.string().describe("검색어"),
-    display: z.number().optional().describe("한 번에 가져올 결과 수 (최대 100)"),
-    start: z.number().optional().describe("검색 시작 위치 (최대 1000)"),
+    provider: z
+        .enum(["legacy", "hub"])
+        .describe("자격증명 발급 플랫폼 (legacy: 개발자센터, hub: NAVER API HUB)"),
+    clientId: z.string().describe("발급받은 Client ID"),
+    clientSecret: z.string().describe("발급받은 Client Secret"),
 });
 // 지역 검색 파라미터
 export const NaverLocalSearchParamsSchema = SearchArgsSchema.extend({

package/dist/src/types/search.types.d.ts

@@ -11,14 +11,6 @@ export interface NaverSearchItem {
     link: string;
     description: string;
 }
-export interface NaverDocumentSearchResponse extends NaverSearchResponse {
-    items: NaverDocumentItem[];
-}
-export interface NaverDocumentItem extends NaverSearchItem {
-    title: string;
-    link: string;
-    description: string;
-}
 export interface NaverEncyclopediaSearchResponse extends NaverSearchResponse {
     items: NaverEncyclopediaItem[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isnow890/naver-search-mcp",
-  "version": "1.0.48",
+  "version": "1.0.49",
   "description": "Naver Search MCP Server",
   "main": "dist/src/index.js",
   "module": "./src/index.ts",
@@ -13,7 +13,8 @@
     "build": "tsc && shx cp -r data dist/",
     "prepare": "npm run build",
     "watch": "tsc --watch",
-    "start": "node dist/src/index.js"
+    "start": "node dist/src/index.js",
+    "test": "npm run build && node --test"
   },
   "engines": {
     "node": ">=18"