# Ncloud 공공존(Gov) MCP Server

**한국어** | [English](README.en.md)

> [!WARNING]
> **이 패키지는 지원이 중단되었습니다.** 공공존 지원은 [**ncloud-mcp-server**](https://github.com/sjk4425/ncloud-mcp-server) 2.0+ 에 통합되었습니다. 이 패키지는 민간존·공공존·금융존을 하나로 지원합니다.
> `ncloud-gov-mcp-server` 0.2.x는 설치·실행이 계속 되지만, 앞으로 기능 추가와 API 변경 대응은 통합 패키지에서만 합니다.

## 통합 패키지로 이전하기

1. 패키지를 `ncloud-gov-mcp-server` 에서 `ncloud-mcp-server` 로 바꿉니다.
2. `NCLOUD_ZONE=gov` 를 추가합니다. **빠뜨리면 민간존 API로 호출되어 인증 오류가 납니다.**
3. 나머지 환경 변수는 그대로 둡니다. 공공존 키, `NCLOUD_REGION`(`KR`/`KRS`), `NCLOUD_TOOL_GROUPS`, `NCLOUD_ARCHIVE_PROJECT_ID`/`NCLOUD_ARCHIVE_DOMAIN_ID` 등은 이름과 의미가 같습니다.

```diff
 {
   "mcpServers": {
     "ncloud-gov": {
       "command": "npx",
-      "args": ["-y", "ncloud-gov-mcp-server"],
+      "args": ["-y", "ncloud-mcp-server"],
       "env": {
+        "NCLOUD_ZONE": "gov",
         "NCLOUD_ACCESS_KEY": "your-gov-access-key",
         "NCLOUD_SECRET_KEY": "your-gov-secret-key",
         "NCLOUD_REGION": "KR"
       }
     }
   }
 }
```

### 도구 차이 (0.2.0 → ncloud-mcp-server 2.0.1, `NCLOUD_ZONE=gov`)

통합 패키지는 공공존에서 도구 약 1,000개를 등록합니다(0.2.0은 약 900개). 0.2.0의 도구 대부분은 이름이 같고, 아래 30개만 다릅니다.

**이름이 바뀐 도구 (9개)**

| 0.2.0 | ncloud-mcp-server |
|------|------|
| `ncloud_nks_list_addon_configs` | `ncloud_nks_list_available_addons` |
| `ncloud_nks_get_addon_config` | `ncloud_nks_get_available_addon` |
| `ncloud_nks_get_addon_config_version` | `ncloud_nks_get_available_addon_version` |
| `ncloud_nks_install_cluster_addon` | `ncloud_nks_install_addons` |
| `ncloud_nks_update_cluster_addon` | `ncloud_nks_update_addon` |
| `ncloud_nks_delete_cluster_addon` | `ncloud_nks_delete_addon` |
| `ncloud_change_fabric_cluster_name` / `ncloud_change_fabric_cluster_description` | `ncloud_update_fabric_cluster` (하나로 통합) |
| `ncloud_cdss_restart_cmak` | `ncloud_cdss_restart_cmak_service` |

**제공하지 않는 도구 (21개)**

| 0.2.0 도구 | 이유 |
|------|------|
| CDN+ `ncloud_cdnplus_*` 5개, Global CDN `ncloud_globalcdn_*` 5개 | 2026-12-31 서비스 종료 예정(신규 생성 불가). 대신 **Global Edge**(`ncloud_edge_*`)를 제공 |
| SES `ncloud_ses_get_cluster_detail`, `get_server_generations`, `get_server_specs`, `get_cluster_server_images`, `get_subnet_list_g3`, `create_cluster_g3`, `change_disk_size` | 공공존 API 가이드에 없는 오퍼레이션(민간존 전용 G3/KVM 계열) |
| CDSS `ncloud_cdss_get_server_generations`, `get_server_spec_list`, `get_cluster_server_images` | 공공존 API 가이드에 없는 오퍼레이션(민간존 전용 G3 계열) |
| `ncloud_nks_reset_kubeconfig` | 공공존 API 가이드에 없는 오퍼레이션 |

**파라미터 변경**: Cache, Search Engine Service, Cloud Data Streaming Service, Cloud Insight, Container Registry, KMS 등의 도구 약 80개는 공식 API 가이드에 맞게 파라미터가 바뀌었습니다. AI 클라이언트는 도구 스키마를 자동으로 읽으므로 대개 신경 쓸 필요가 없습니다. 도구 이름과 파라미터를 직접 적어 둔 스크립트나 프롬프트만 확인하세요.

> 통합 패키지의 공공존 지원은 공공존 API 가이드와 단위 테스트로 검증되었습니다. 실제 공공존 계정으로는 아직 테스트하지 않았습니다. 문제가 있으면 [ncloud-mcp-server 이슈](https://github.com/sjk4425/ncloud-mcp-server/issues)로 알려 주세요.

---

> 아래는 0.2.x 기준 문서입니다(보관용).

[![CI](https://github.com/sjk4425/ncloud-gov-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/sjk4425/ncloud-gov-mcp-server/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/ncloud-gov-mcp-server?logo=npm&color=cb3837)](https://www.npmjs.com/package/ncloud-gov-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
![Node.js](https://img.shields.io/badge/Node.js-20%2B-brightgreen?logo=node.js&logoColor=white)
![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)

[Naver Cloud Platform 공공존(Government Cloud)](https://www.gov-ncloud.com) 인프라를 AI 클라이언트에서 자연어로 생성·조회·관리하는 MCP(Model Context Protocol) 서버입니다.

민간존용 [ncloud-mcp-server](https://github.com/sjk4425/ncloud-mcp-server) 를 기반으로 파생한 **공공존 전용** 프로젝트로, API Gateway 도메인이 `*.apigw.gov-ntruss.com` 을 사용하도록 구성되어 있습니다. 현재 **13개 그룹 · 약 877개 도구**를 제공합니다.

## 지원 서비스

| 그룹 (`key`) | 서비스 |
|------|--------|
| **common** | Region / Zone (always on) |
| **compute** | Server, Block Storage, Public IP, Login Key, Init Script, Placement Group, Auto Scaling, ACG, Network Interface, Cloud Functions |
| **network** | VPC, Network ACL, NAT Gateway, Route Table, VPC Peering, Load Balancer, Target Group, Global DNS, Global Traffic Manager |
| **database** | Cloud DB for MySQL / PostgreSQL / MSSQL / MongoDB / Redis(Cache) |
| **containers** | Container Registry (NCR), Kubernetes Service (NKS) |
| **storage** | NAS, Object Storage (S3 호환), Archive Storage (OpenStack Swift) |
| **devtools** | Source Commit, Source Build, Source Deploy, Source Pipeline |
| **security** | Certificate Manager, Private CA, Security Monitoring, KMS (v2.0) |
| **analytics** | Cloud Hadoop, Search Engine Service, Cloud Data Streaming Service, Cloud Log Analytics |
| **cdn** | CDN+, Global CDN |
| **media** | VOD Station, One-Click Multi DRM |
| **governance** | Sub Account, Activity Tracer, Cloud Insight, Resource Manager, WMS |
| **billing** | List Price, Cost and Usage, Discount (요금·비용·할인 조회) |

> 일부 서비스는 관리·모니터링 중심으로 핵심 엔드포인트만 우선 제공합니다(예: VOD Station, Sub Account IAM 전체 범위).

## 요구 사항

- Node.js 20 이상
- 공공존 콘솔([console.gov-ncloud.com](https://console.gov-ncloud.com))에서 발급한 **API 인증키**(Access Key / Secret Key)

## 설치 & 실행

### 방법 1: npx (권장 - 별도 설치 없이 실행)

npm에 배포된 패키지를 clone·빌드 없이 바로 실행합니다.

```bash
npx -y ncloud-gov-mcp-server
```

### 방법 2: 로컬 빌드 (소스에서 직접)

```bash
git clone https://github.com/sjk4425/ncloud-gov-mcp-server.git
cd ncloud-gov-mcp-server
npm install
npm run build   # dist/ 생성 (prepare 훅으로 install 시 자동 실행)
```

## MCP 클라이언트 설정 예시

### npx 방식

```json
{
  "mcpServers": {
    "ncloud-gov": {
      "command": "npx",
      "args": ["-y", "ncloud-gov-mcp-server"],
      "env": {
        "NCLOUD_ACCESS_KEY": "your-gov-access-key",
        "NCLOUD_SECRET_KEY": "your-gov-secret-key",
        "NCLOUD_REGION": "KR"
      }
    }
  }
}
```

### 로컬 빌드 방식

```json
{
  "mcpServers": {
    "ncloud-gov": {
      "command": "node",
      "args": ["/path/to/Ncloud-GOV/dist/index.js"],
      "env": {
        "NCLOUD_ACCESS_KEY": "your-gov-access-key",
        "NCLOUD_SECRET_KEY": "your-gov-secret-key",
        "NCLOUD_REGION": "KR"
      }
    }
  }
}
```

## 도구 그룹 선택 & 동적 로딩

`NCLOUD_TOOL_GROUPS` 환경 변수로 로딩할 그룹을 제어합니다. 모든 도구를 한꺼번에 올리면 컨텍스트가 커지므로, 필요한 그룹만 선택하거나 런타임에 확장할 수 있습니다.

| 설정값 | 동작 |
|--------|------|
| (미설정) | **전체 ON** — 13개 그룹 877개 도구 모두 등록 |
| `compute,network` | 지정한 그룹 + `common` 만 등록 (**잠금** — 런타임 변경 불가) |
| `all,-database` | 전체에서 특정 그룹 제외. 제외된 그룹은 런타임 활성화도 **차단** |
| `dynamic` | 코어 세트(`common` + `compute` + `network` + `database`)만 시작 + **런타임 확장 허용** |

### 동적 그룹 (`dynamic`)

`NCLOUD_TOOL_GROUPS=dynamic` 으로 켜면 두 개의 메타 도구가 노출됩니다:

- **`ncloud_list_tool_groups`** — 그룹 목록·서비스·도구 수·상태(enabled / available / blocked) 조회
- **`ncloud_enable_tool_group`** — 원하는 그룹을 세션 중 즉시 로딩 (예: 스토리지 작업 요청 시 `storage` 그룹 활성화)

시작 시에는 코어 그룹만 올려 도구 수를 줄이고, AI가 필요한 서비스를 만나면 해당 그룹만 켜서 컨텍스트를 절약합니다. 그룹 활성화 시 발생하는 다량의 `tools/list_changed` 통지는 1회로 합쳐 전송됩니다.

> 보안 경계: `-database` 처럼 운영자가 명시적으로 제외한 그룹은 `dynamic` 모드에서도 런타임 활성화가 거부됩니다.

## 환경 변수

| 변수 | 필수 | 기본값 | 설명 |
|------|:----:|--------|------|
| `NCLOUD_ACCESS_KEY` | ✅ | — | 공공존 API Access Key |
| `NCLOUD_SECRET_KEY` | ✅ | — | 공공존 API Secret Key |
| `NCLOUD_REGION` | | `KR` | 리전 코드 (`KR` 수도권 / `KRS` 남부권) |
| `NCLOUD_API_URL` | | `https://ncloud.apigw.gov-ntruss.com` | 기본 API Gateway 도메인 |
| `NCLOUD_TOOL_GROUPS` | | (전체 ON) | 로딩할 그룹. `dynamic` = 코어 세트 + 런타임 확장 (위 표 참고) |
| `NCLOUD_ARCHIVE_PROJECT_ID` | | — | Archive Storage 사용 시 필수 (Keystone project_id). 두 값이 모두 있어야 Archive 도구 등록 |
| `NCLOUD_ARCHIVE_DOMAIN_ID` | | — | Archive Storage 사용 시 필수 (Keystone domain_id) |
| `NCLOUD_LANG` | | `ko` | 에러 메시지 언어 (`en` 지정 시 영문) |
| `NCLOUD_TIMEOUT_MS` | | `30000` | API 요청 타임아웃(ms) |

전체 목록은 [.env.example](.env.example) 참고.

## 공공존과 민간존의 차이

- **도메인**: 대부분의 API Gateway 엔드포인트가 `*.apigw.gov-ntruss.com` 을 사용합니다 (민간존은 `*.apigw.ntruss.com`).
- **인증 방식**: HMAC-SHA256 서명(`x-ncp-apigw-signature-v2` 등)으로 민간존과 **동일**합니다.
- **도메인 예외(기계적 치환 불가)**: 일부 서비스는 gov에서 다른 도메인/경로를 씁니다. 반드시 [공공존 API 문서](https://api-gov.ncloud-docs.com/docs)로 확인:
  - Container Registry: `gov-ncr.apigw.gov-ntruss.com` (경로 `/ncr/{kr|krs}/v2/`)
  - Object Storage: `{kr|krs}.object.gov-ncloudstorage.com` (S3 호환 · AWS SigV4 · 서명 리전 `gov-standard`/`gov2-standard`)
  - Archive Storage: `kr.archive.gov-ncloudstorage.com` (OpenStack Swift · Keystone v3)
  - Private CA: `privateca.apigw.gov-ntruss.com` (민간존 `pca` 아님)
  - KMS v2.0: `ocapi.gov-ncloud.com` (apigw 게이트웨이 아님)
  - VOD Station: `vod-station.apigw.gov-ntruss.com` (하이픈)
  - NKS / Search Engine / Cloud Data Streaming: 남부권(KRS)은 경로 prefix가 다름 (`krs-v2` 등)
- **제공 서비스**: 공공존은 격리망 특성상 일부 서비스만 제공됩니다. 서비스 추가 전 공공존 API 문서에서 제공 여부를 확인하세요.

## 검증 상태

- **빌드 & 등록**: `tsc` 빌드 + 단위 테스트 통과. MCP 프로토콜 스모크 테스트로 13개 그룹 877개 도구 등록·중복 없음·동적 활성화 동작 확인.
- **실 API 호출**: 공공존 계정으로 각 서비스 엔드포인트를 실제 호출한 검증은 미완료 항목이 있습니다.

## 라이선스

MIT