ncloud-mcp-server 1.0.1 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +43 -23
  2. package/README_EN.md +42 -22
  3. package/package.json +5 -2
package/README.md CHANGED
@@ -30,39 +30,29 @@ Ncloud의 **60개 이상 서비스**, **1,000개 이상 API 도구**를 MCP 프
30
30
  | **Content Delivery** | Global Edge |
31
31
  | **Auto Scaling** | Launch Configuration, Auto Scaling Group, Scaling Policy |
32
32
 
33
+ ## 사전 요구사항
34
+
35
+ - Node.js 20 이상
36
+ - Ncloud API 인증키 ([포털에서 발급](https://www.ncloud.com/mypage/manage/authkey))
37
+
33
38
  ## 참고 사항
34
39
 
35
40
  - 이 MCP 서버는 **Ncloud 민간존(Public)** 기준으로 구현되었습니다. 금융존/공공존 환경에서는 API 엔드포인트가 다를 수 있습니다.
36
41
  - API 스펙은 [Ncloud API 공식 문서](https://api.ncloud-docs.com/docs/home)를 기반으로 작성되었습니다.
37
42
  - 한국(KR) 리전 위주로 테스트되었습니다. 다른 리전에서는 일부 API의 동작이 다를 수 있습니다.
38
43
 
39
- ## 사전 요구사항
40
-
41
- - Node.js 20 이상
42
- - Ncloud API 인증키 ([포털에서 발급](https://www.ncloud.com/mypage/manage/authkey))
43
-
44
44
  ## 설치
45
45
 
46
46
  ### npx (권장 — 설치 불필요)
47
47
 
48
- 별도 설치 없이 바로 사용할 수 있습니다:
48
+ 별도 설치 없이 `npx`로 바로 실행할 수 있습니다:
49
49
 
50
- ```json
51
- {
52
- "mcpServers": {
53
- "ncloud": {
54
- "command": "npx",
55
- "args": ["-y", "ncloud-mcp-server"],
56
- "env": {
57
- "NCLOUD_ACCESS_KEY": "your-access-key",
58
- "NCLOUD_SECRET_KEY": "your-secret-key",
59
- "NCLOUD_REGION": "KR"
60
- }
61
- }
62
- }
63
- }
50
+ ```bash
51
+ npx -y ncloud-mcp-server
64
52
  ```
65
53
 
54
+ MCP 클라이언트 설정 방법은 아래 [MCP 클라이언트 설정](#mcp-클라이언트-설정) 섹션을 참고하세요.
55
+
66
56
  ### 소스에서 빌드
67
57
 
68
58
  ```bash
@@ -88,10 +78,28 @@ npm run build
88
78
 
89
79
  ## MCP 클라이언트 설정
90
80
 
91
- ### Kiro / Claude Desktop / Cursor
81
+ ### npx 사용 (권장)
92
82
 
93
83
  `mcp.json` (또는 해당 클라이언트의 MCP 설정 파일)에 추가:
94
84
 
85
+ ```json
86
+ {
87
+ "mcpServers": {
88
+ "ncloud": {
89
+ "command": "npx",
90
+ "args": ["-y", "ncloud-mcp-server"],
91
+ "env": {
92
+ "NCLOUD_ACCESS_KEY": "your-access-key",
93
+ "NCLOUD_SECRET_KEY": "your-secret-key",
94
+ "NCLOUD_REGION": "KR"
95
+ }
96
+ }
97
+ }
98
+ }
99
+ ```
100
+
101
+ ### 소스 빌드 사용
102
+
95
103
  ```json
96
104
  {
97
105
  "mcpServers": {
@@ -129,8 +137,20 @@ MCP 클라이언트에서 자연어로 Ncloud 인프라를 관리할 수 있습
129
137
  | 한국 | `KR` |
130
138
  | 일본 | `JPN` |
131
139
  | 싱가포르 | `SGN` |
132
- | 미국 서부 | `USWN` |
133
- | 독일 | `DEN` |
140
+
141
+ > **참고:** 미국 서부(`USWN`), 독일(`DEN`) 리전은 Classic 환경만 지원되어 VPC 기반인 본 MCP 서버에서는 사용이 제한됩니다.
142
+
143
+ ## 문제 해결
144
+
145
+ | 증상 | 원인 | 해결 방법 |
146
+ |------|------|-----------|
147
+ | 서버 시작 시 즉시 종료 | 환경 변수 미설정 | `NCLOUD_ACCESS_KEY`, `NCLOUD_SECRET_KEY` 환경 변수가 설정되어 있는지 확인 |
148
+ | `인증 실패` (HTTP 401) | API 인증키 오류 | [포털](https://www.ncloud.com/mypage/manage/authkey)에서 키 상태가 **활성**인지 확인. 키 값에 공백이나 줄바꿈이 포함되지 않았는지 확인 |
149
+ | `접근 거부` (HTTP 403) | 서비스 권한 부족 | 서비스 이용 신청 여부 확인. Sub Account 사용 시 해당 서비스에 대한 API 권한 부여 필요 |
150
+ | `유효하지 않은 리전입니다` | 잘못된 리전 코드 | 지원 리전(KR, JPN, SGN) 확인. `ncloud_set_region` 도구로 변경 가능 |
151
+ | `서비스 일시 불가` (HTTP 503) | API 엔드포인트 연결 불가 | 네트워크 상태 확인. 방화벽/프록시 환경에서는 `ncloud.apigw.ntruss.com` 아웃바운드 허용 필요 |
152
+ | `요청 시간 초과` (HTTP 504) | API 응답 지연 | 잠시 후 재시도. 지속 시 Ncloud 상태 페이지 확인 |
153
+ | `요청 제한 초과` (HTTP 429) | API Rate Limit 도달 | 요청 간격을 두고 재시도 |
134
154
 
135
155
  ## 프로젝트 구조
136
156
 
package/README_EN.md CHANGED
@@ -30,39 +30,29 @@ Provides **1,000+ API tools** across **60+ Ncloud services** via MCP protocol.
30
30
  | **Content Delivery** | Global Edge |
31
31
  | **Auto Scaling** | Launch Configuration, Auto Scaling Group, Scaling Policy |
32
32
 
33
+ ## Prerequisites
34
+
35
+ - Node.js 20+
36
+ - Ncloud API credentials ([Get from portal](https://www.ncloud.com/mypage/manage/authkey))
37
+
33
38
  ## Notes
34
39
 
35
40
  - This MCP server is built for the **Ncloud Public (민간존)** environment. API endpoints may differ for Financial or Government zones.
36
41
  - API specifications are based on the [Ncloud Official API Documentation](https://api.ncloud-docs.com/docs/home).
37
42
  - Primarily tested in the Korea (KR) region. Some APIs may behave differently in other regions.
38
43
 
39
- ## Prerequisites
40
-
41
- - Node.js 20+
42
- - Ncloud API credentials ([Get from portal](https://www.ncloud.com/mypage/manage/authkey))
43
-
44
44
  ## Installation
45
45
 
46
46
  ### npx (Recommended — no install required)
47
47
 
48
48
  Use directly without installation:
49
49
 
50
- ```json
51
- {
52
- "mcpServers": {
53
- "ncloud": {
54
- "command": "npx",
55
- "args": ["-y", "ncloud-mcp-server"],
56
- "env": {
57
- "NCLOUD_ACCESS_KEY": "your-access-key",
58
- "NCLOUD_SECRET_KEY": "your-secret-key",
59
- "NCLOUD_REGION": "KR"
60
- }
61
- }
62
- }
63
- }
50
+ ```bash
51
+ npx -y ncloud-mcp-server
64
52
  ```
65
53
 
54
+ See the [MCP Client Configuration](#mcp-client-configuration) section below for setup details.
55
+
66
56
  ### Build from source
67
57
 
68
58
  ```bash
@@ -88,10 +78,28 @@ npm run build
88
78
 
89
79
  ## MCP Client Configuration
90
80
 
91
- ### Kiro / Claude Desktop / Cursor
81
+ ### Using npx (Recommended)
92
82
 
93
83
  Add to your `mcp.json` (or equivalent MCP config file):
94
84
 
85
+ ```json
86
+ {
87
+ "mcpServers": {
88
+ "ncloud": {
89
+ "command": "npx",
90
+ "args": ["-y", "ncloud-mcp-server"],
91
+ "env": {
92
+ "NCLOUD_ACCESS_KEY": "your-access-key",
93
+ "NCLOUD_SECRET_KEY": "your-secret-key",
94
+ "NCLOUD_REGION": "KR"
95
+ }
96
+ }
97
+ }
98
+ }
99
+ ```
100
+
101
+ ### Using source build
102
+
95
103
  ```json
96
104
  {
97
105
  "mcpServers": {
@@ -129,8 +137,20 @@ Manage Ncloud infrastructure using natural language through your MCP client:
129
137
  | Korea | `KR` |
130
138
  | Japan | `JPN` |
131
139
  | Singapore | `SGN` |
132
- | US West | `USWN` |
133
- | Germany | `DEN` |
140
+
141
+ > **Note:** US West (`USWN`) and Germany (`DEN`) regions only support the Classic environment and are not compatible with this VPC-based MCP server.
142
+
143
+ ## Troubleshooting
144
+
145
+ | Symptom | Cause | Solution |
146
+ |---------|-------|----------|
147
+ | Server exits immediately on start | Environment variables not set | Ensure `NCLOUD_ACCESS_KEY` and `NCLOUD_SECRET_KEY` are configured |
148
+ | `인증 실패` (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 |
149
+ | `접근 거부` (HTTP 403) | Insufficient permissions | Confirm service subscription. For Sub Accounts, grant API permissions for the target service |
150
+ | `유효하지 않은 리전입니다` | Invalid region code | Use supported regions (KR, JPN, SGN). Change via `ncloud_set_region` tool |
151
+ | `서비스 일시 불가` (HTTP 503) | Cannot reach API endpoint | Check network connectivity. Allow outbound access to `ncloud.apigw.ntruss.com` in firewall/proxy environments |
152
+ | `요청 시간 초과` (HTTP 504) | API response timeout | Retry after a moment. If persistent, check Ncloud status page |
153
+ | `요청 제한 초과` (HTTP 429) | API rate limit reached | Wait and retry with intervals between requests |
134
154
 
135
155
  ## Project Structure
136
156
 
package/package.json CHANGED
@@ -1,6 +1,7 @@
1
1
  {
2
2
  "name": "ncloud-mcp-server",
3
- "version": "1.0.1",
3
+ "version": "1.0.3",
4
+ "mcpName": "io.github.sjk4425/ncloud",
4
5
  "type": "module",
5
6
  "description": "MCP server for managing Naver Cloud Platform (Ncloud) infrastructure",
6
7
  "author": "sjk4425",
@@ -21,7 +22,9 @@
21
22
  "infrastructure",
22
23
  "cloud",
23
24
  "ai",
24
- "navercloudplatform"
25
+ "navercloudplatform",
26
+ "ncp",
27
+ "devops"
25
28
  ],
26
29
  "bin": {
27
30
  "ncloud-mcp-server": "dist/index.js"