ncloud-gov-mcp-server

# Ncloud 공공존(Gov) MCP Server

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

[![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