ncloud-mcp-server 1.0.0 → 1.0.2

package/README.md

@@ -2,6 +2,7 @@
 
 [English](./README_EN.md)
 
+[![npm version](https://img.shields.io/npm/v/ncloud-mcp-server.svg)](https://www.npmjs.com/package/ncloud-mcp-server)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/Node.js-20%2B-green.svg)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
@@ -29,18 +30,30 @@ Ncloud의 **60개 이상 서비스**, **1,000개 이상 API 도구**를 MCP 프
 | **Content Delivery** | Global Edge |
 | **Auto Scaling** | Launch Configuration, Auto Scaling Group, Scaling Policy |
 
+## 사전 요구사항
+
+- Node.js 20 이상
+- Ncloud API 인증키 ([포털에서 발급](https://www.ncloud.com/mypage/manage/authkey))
+
 ## 참고 사항
 
 - 이 MCP 서버는 **Ncloud 민간존(Public)** 기준으로 구현되었습니다. 금융존/공공존 환경에서는 API 엔드포인트가 다를 수 있습니다.
 - API 스펙은 [Ncloud API 공식 문서](https://api.ncloud-docs.com/docs/home)를 기반으로 작성되었습니다.
 - 한국(KR) 리전 위주로 테스트되었습니다. 다른 리전에서는 일부 API의 동작이 다를 수 있습니다.
 
-## 사전 요구사항
+## 설치
 
-- Node.js 20 이상
-- Ncloud API 인증키 ([포털에서 발급](https://www.ncloud.com/mypage/manage/authkey))
+### npx (권장 — 설치 불필요)
 
-## 설치
+별도 설치 없이 `npx`로 바로 실행할 수 있습니다:
+
+```bash
+npx -y ncloud-mcp-server
+```
+
+MCP 클라이언트 설정 방법은 아래 [MCP 클라이언트 설정](#mcp-클라이언트-설정) 섹션을 참고하세요.
+
+### 소스에서 빌드
 
 ```bash
 # 저장소 클론
@@ -65,10 +78,28 @@ npm run build
 
 ## MCP 클라이언트 설정
 
-### Kiro / Claude Desktop / Cursor
+### npx 사용 (권장)
 
 `mcp.json` (또는 해당 클라이언트의 MCP 설정 파일)에 추가:
 
+```json
+{
+  "mcpServers": {
+    "ncloud": {
+      "command": "npx",
+      "args": ["-y", "ncloud-mcp-server"],
+      "env": {
+        "NCLOUD_ACCESS_KEY": "your-access-key",
+        "NCLOUD_SECRET_KEY": "your-secret-key",
+        "NCLOUD_REGION": "KR"
+      }
+    }
+  }
+}
+```
+
+### 소스 빌드 사용
+
 ```json
 {
   "mcpServers": {
@@ -106,8 +137,20 @@ MCP 클라이언트에서 자연어로 Ncloud 인프라를 관리할 수 있습
 | 한국 | `KR` |
 | 일본 | `JPN` |
 | 싱가포르 | `SGN` |
-| 미국 서부 | `USWN` |
-| 독일 | `DEN` |
+
+> **참고:** 미국 서부(`USWN`), 독일(`DEN`) 리전은 Classic 환경만 지원되어 VPC 기반인 본 MCP 서버에서는 사용이 제한됩니다.
+
+## 문제 해결
+
+| 증상 | 원인 | 해결 방법 |
+|------|------|-----------|
+| 서버 시작 시 즉시 종료 | 환경 변수 미설정 | `NCLOUD_ACCESS_KEY`, `NCLOUD_SECRET_KEY` 환경 변수가 설정되어 있는지 확인 |
+| `인증 실패` (HTTP 401) | API 인증키 오류 | [포털](https://www.ncloud.com/mypage/manage/authkey)에서 키 상태가 **활성**인지 확인. 키 값에 공백이나 줄바꿈이 포함되지 않았는지 확인 |
+| `접근 거부` (HTTP 403) | 서비스 권한 부족 | 서비스 이용 신청 여부 확인. Sub Account 사용 시 해당 서비스에 대한 API 권한 부여 필요 |
+| `유효하지 않은 리전입니다` | 잘못된 리전 코드 | 지원 리전(KR, JPN, SGN) 확인. `ncloud_set_region` 도구로 변경 가능 |
+| `서비스 일시 불가` (HTTP 503) | API 엔드포인트 연결 불가 | 네트워크 상태 확인. 방화벽/프록시 환경에서는 `ncloud.apigw.ntruss.com` 아웃바운드 허용 필요 |
+| `요청 시간 초과` (HTTP 504) | API 응답 지연 | 잠시 후 재시도. 지속 시 Ncloud 상태 페이지 확인 |
+| `요청 제한 초과` (HTTP 429) | API Rate Limit 도달 | 요청 간격을 두고 재시도 |
 
 ## 프로젝트 구조
 

package/README_EN.md

@@ -2,6 +2,7 @@
 
 [한국어](./README.md)
 
+[![npm version](https://img.shields.io/npm/v/ncloud-mcp-server.svg)](https://www.npmjs.com/package/ncloud-mcp-server)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/Node.js-20%2B-green.svg)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
@@ -29,18 +30,30 @@ Provides **1,000+ API tools** across **60+ Ncloud services** via MCP protocol.
 | **Content Delivery** | Global Edge |
 | **Auto Scaling** | Launch Configuration, Auto Scaling Group, Scaling Policy |
 
+## Prerequisites
+
+- Node.js 20+
+- Ncloud API credentials ([Get from portal](https://www.ncloud.com/mypage/manage/authkey))
+
 ## Notes
 
 - This MCP server is built for the **Ncloud Public (민간존)** environment. API endpoints may differ for Financial or Government zones.
 - API specifications are based on the [Ncloud Official API Documentation](https://api.ncloud-docs.com/docs/home).
 - Primarily tested in the Korea (KR) region. Some APIs may behave differently in other regions.
 
-## Prerequisites
+## Installation
 
-- Node.js 20+
-- Ncloud API credentials ([Get from portal](https://www.ncloud.com/mypage/manage/authkey))
+### npx (Recommended — no install required)
 
-## Installation
+Use directly without installation:
+
+```bash
+npx -y ncloud-mcp-server
+```
+
+See the [MCP Client Configuration](#mcp-client-configuration) section below for setup details.
+
+### Build from source
 
 ```bash
 # Clone the repository
@@ -65,10 +78,28 @@ npm run build
 
 ## MCP Client Configuration
 
-### Kiro / Claude Desktop / Cursor
+### Using npx (Recommended)
 
 Add to your `mcp.json` (or equivalent MCP config file):
 
+```json
+{
+  "mcpServers": {
+    "ncloud": {
+      "command": "npx",
+      "args": ["-y", "ncloud-mcp-server"],
+      "env": {
+        "NCLOUD_ACCESS_KEY": "your-access-key",
+        "NCLOUD_SECRET_KEY": "your-secret-key",
+        "NCLOUD_REGION": "KR"
+      }
+    }
+  }
+}
+```
+
+### Using source build
+
 ```json
 {
   "mcpServers": {
@@ -106,8 +137,20 @@ Manage Ncloud infrastructure using natural language through your MCP client:
 | Korea | `KR` |
 | Japan | `JPN` |
 | Singapore | `SGN` |
-| US West | `USWN` |
-| Germany | `DEN` |
+
+> **Note:** US West (`USWN`) and Germany (`DEN`) regions only support the Classic environment and are not compatible with this VPC-based MCP server.
+
+## Troubleshooting
+
+| Symptom | Cause | Solution |
+|---------|-------|----------|
+| Server exits immediately on start | Environment variables not set | Ensure `NCLOUD_ACCESS_KEY` and `NCLOUD_SECRET_KEY` are configured |
+| `인증 실패` (HTTP 401) | Invalid API credentials | Verify key status is **active** on the [portal](https://www.ncloud.com/mypage/manage/authkey). Check for extra whitespace or newlines in key values |
+| `접근 거부` (HTTP 403) | Insufficient permissions | Confirm service subscription. For Sub Accounts, grant API permissions for the target service |
+| `유효하지 않은 리전입니다` | Invalid region code | Use supported regions (KR, JPN, SGN). Change via `ncloud_set_region` tool |
+| `서비스 일시 불가` (HTTP 503) | Cannot reach API endpoint | Check network connectivity. Allow outbound access to `ncloud.apigw.ntruss.com` in firewall/proxy environments |
+| `요청 시간 초과` (HTTP 504) | API response timeout | Retry after a moment. If persistent, check Ncloud status page |
+| `요청 제한 초과` (HTTP 429) | API rate limit reached | Wait and retry with intervals between requests |
 
 ## Project Structure
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ncloud-mcp-server",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
   "description": "MCP server for managing Naver Cloud Platform (Ncloud) infrastructure",
   "author": "sjk4425",