greennode.vks-mcp-server 0.1.0__tar.gz

greennode_vks_mcp_server-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2026 Green Node
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

greennode_vks_mcp_server-0.1.0/NOTICE

@@ -0,0 +1,2 @@
+greennode.vks-mcp-server
+Copyright Green Node. All Rights Reserved.

greennode_vks_mcp_server-0.1.0/PKG-INFO

@@ -0,0 +1,597 @@
+Metadata-Version: 2.4
+Name: greennode.vks-mcp-server
+Version: 0.1.0
+Summary: A GreenNode MCP server for VKS (VNG Kubernetes Service)
+Author: Green Node
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/vngcloud/greennode-mcp
+Project-URL: Source, https://github.com/vngcloud/greennode-mcp
+Project-URL: Bug Tracker, https://github.com/vngcloud/greennode-mcp/issues
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: httpx<1.0,>=0.27.0
+Requires-Dist: kubernetes<36.0,>=28.0.0
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: cachetools<6.0,>=5.3.0
+Requires-Dist: pydantic<3.0,>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
+Requires-Dist: respx>=0.22.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Dynamic: license-file
+
+# GreenNode MCP Server
+
+MCP (Model Context Protocol) Server for VKS (VNG Kubernetes Service). Provides AI assistants with tools to manage Kubernetes clusters and resources on GreenNode.
+
+## Key Features
+
+- **Cluster Management** — Create, update, delete, and monitor VKS clusters
+- **Node Group Management** — Scale, update, and manage node groups
+- **Kubernetes Resources** — List pods/deployments/services, get logs, apply YAML manifests
+- **Auto-Upgrade** — Configure automatic cluster version upgrades
+- **Troubleshooting** — Get cluster events, pod logs, K8s events for debugging
+- **Safety Controls** — Read-only by default, write operations require explicit opt-in
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Quickstart](#quickstart)
+- [Configuration](#configuration)
+- [Tools](#tools)
+- [Security](#security)
+- [Getting Help](#getting-help)
+- [More Resources](#more-resources)
+
+## Prerequisites
+
+- Python 3.10 or later
+- [uv](https://docs.astral.sh/uv/) package manager (recommended) or pip
+- [GreenNode CLI](https://github.com/vngcloud/greennode-cli) (`grncli`) — **required** for credential setup
+- IAM Service Account from [VNG Cloud Console](https://hcm-3.console.vngcloud.vn/iam/)
+
+## Quickstart
+
+### 1. Install GreenNode CLI and configure credentials
+
+The MCP server reads credentials from `~/.greenode/credentials`, which is created by the GreenNode CLI:
+
+```bash
+pip install grncli
+grn configure
+```
+
+> **Note:** The MCP server cannot run without credentials. `grn configure` is the only way to set them up.
+
+### 2. Run the server
+
+```bash
+uvx vks-mcp-server
+```
+
+### 3. Configure your AI assistant
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "greennode.vks-mcp-server": {
+      "command": "uvx",
+      "args": [
+        "greennode.vks-mcp-server@latest",
+        "--allow-write"
+      ],
+      "autoApprove": [],
+      "disabled": false
+    }
+  }
+}
+```
+
+Config file location:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+</details>
+
+<details>
+<summary><strong>Claude Code</strong></summary>
+
+Add to `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "greennode.vks-mcp-server": {
+      "command": "uvx",
+      "args": [
+        "greennode.vks-mcp-server@latest",
+        "--allow-write"
+      ],
+      "autoApprove": [],
+      "disabled": false
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+Add to Cursor Settings → MCP Servers:
+
+```json
+{
+  "mcpServers": {
+    "greennode.vks-mcp-server": {
+      "command": "uvx",
+      "args": [
+        "greennode.vks-mcp-server@latest",
+        "--allow-write"
+      ],
+      "autoApprove": [],
+      "disabled": false
+    }
+  }
+}
+```
+
+</details>
+
+### Configuration options
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `command` | string | `"uvx"` to run from PyPI without installing |
+| `args` | array | Package name with `@latest` + server flags |
+| `autoApprove` | array | Tool names to auto-approve without user confirmation. Empty `[]` = ask every time |
+| `disabled` | boolean | Set `true` to disable the server without removing config |
+
+#### `autoApprove` example
+
+Auto-approve read-only tools so AI doesn't ask confirmation for every list/get:
+
+```json
+{
+  "mcpServers": {
+    "greennode.vks-mcp-server": {
+      "command": "uvx",
+      "args": [
+        "greennode.vks-mcp-server@latest",
+        "--allow-write"
+      ],
+      "autoApprove": [
+        "cluster_list",
+        "cluster_get",
+        "cluster_get_events",
+        "nodegroup_list",
+        "nodegroup_get",
+        "nodegroup_list_nodes",
+        "list_k8s_resources",
+        "get_pod_logs",
+        "get_k8s_events",
+        "list_api_versions"
+      ],
+      "disabled": false
+    }
+  }
+}
+```
+
+> **Tip:** Only auto-approve **read-only** tools. Keep write tools (create, update, delete) requiring manual approval for safety.
+
+## Configuration
+
+### Arguments
+
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `--allow-write` | `false` | Enable create, update, and delete operations. Without this flag, only read operations are available |
+| `--allow-sensitive-data-access` | `false` | Enable reading Kubernetes Secrets. Without this flag, Secret resources are hidden |
+
+> **Security Warning:** Enabling both `--allow-write` and `--allow-sensitive-data-access` gives the AI assistant full access to your cluster resources including secrets. Use with caution.
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `GRN_DEFAULT_REGION` | Default region (default: HCM-3) |
+| `GRN_PROFILE` | Profile name from config file (default: "default") |
+
+### Credential Files
+
+Created by `grn configure` (shared with [GreenNode CLI](https://github.com/vngcloud/greennode-cli)). Do not edit manually:
+
+```ini
+# ~/.greenode/credentials
+[default]
+client_id = your-client-id
+client_secret = your-client-secret
+```
+
+```ini
+# ~/.greenode/config
+[default]
+region = HCM-3
+```
+
+### Available Regions
+
+| Region | VKS Endpoint |
+|--------|-------------|
+| `HCM-3` | `https://vks.api.vngcloud.vn` |
+| `HAN` | `https://vks-han-1.api.vngcloud.vn` |
+
+## Tools
+
+The following tools are provided by the VKS MCP server for managing VKS clusters and Kubernetes resources. Each tool performs a specific action that can be invoked by AI assistants.
+
+### Cluster Management
+
+#### `cluster_list`
+
+Lists all VKS clusters in the configured region. Returns a markdown table with cluster name, ID, status, version, node count, and creation date.
+
+Features:
+
+* Supports pagination for large cluster lists.
+* Returns formatted markdown table for AI readability.
+
+Parameters:
+
+* page (optional), pageSize (optional, default: 50), region (optional)
+
+#### `cluster_get`
+
+Gets full detail of a specific VKS cluster by ID. Returns a markdown key-value table with all cluster properties.
+
+Features:
+
+* Returns comprehensive cluster details including name, status, version, network config, node count.
+* Input validation on cluster ID to prevent path traversal.
+
+Parameters:
+
+* cluster_id (required), region (optional)
+
+#### `cluster_get_events`
+
+Gets events for a VKS cluster. Returns a markdown table of events with type, reason, message, and timestamp.
+
+Features:
+
+* Supports pagination for event history.
+* Useful for troubleshooting cluster issues.
+
+Parameters:
+
+* cluster_id (required), page (optional), pageSize (optional, default: 20), region (optional)
+
+#### `cluster_delete_dryrun`
+
+Preview what will be deleted when deleting a cluster. Shows cluster info and all node groups that will be removed.
+
+Features:
+
+* Displays cluster details and all associated node groups.
+* Shows warning header and instructions to confirm deletion.
+* Safe to run — does not modify any resources.
+
+Parameters:
+
+* cluster_id (required), region (optional)
+
+#### `cluster_create_validate`
+
+Validates a cluster creation body without actually creating a cluster. Returns 'valid' or a list of validation errors.
+
+Features:
+
+* Validates cluster name format (regex: `^[a-z0-9][a-z0-9\-]{3,18}[a-z0-9]$`).
+* Checks required fields: vpcId, networkType, version, releaseChannel.
+* Validates network-type-specific fields (CIDR for CALICO/CILIUM_OVERLAY).
+* Validates node groups: name format, required fields, diskSize (20-5000), numNodes (0-10).
+
+Parameters:
+
+* body (required — CreateClusterComboDto JSON)
+
+#### `cluster_create`
+
+Creates a new VKS cluster. **Requires `--allow-write` flag.** Use `cluster_create_validate` first to check the body.
+
+Features:
+
+* Creates cluster with embedded node group configuration.
+* Supports poc and autoRenewal options.
+
+Parameters:
+
+* body (required — CreateClusterComboDto JSON), poc (optional, default: false), autoRenewal (optional, default: true), region (optional)
+
+#### `cluster_update`
+
+Updates an existing VKS cluster. **Requires `--allow-write` flag.**
+
+Features:
+
+* Supports partial updates (only send fields to change).
+
+Parameters:
+
+* cluster_id (required), body (required — update fields), region (optional)
+
+#### `cluster_delete`
+
+Deletes a VKS cluster. **IRREVERSIBLE. Requires `--allow-write` flag.** Use `cluster_delete_dryrun` first to preview.
+
+Features:
+
+* Permanently removes cluster and all associated resources.
+
+Parameters:
+
+* cluster_id (required), region (optional)
+
+### Auto-Upgrade
+
+#### `cluster_auto_upgrade_config`
+
+Configures auto-upgrade schedule for a VKS cluster. **Requires `--allow-write` flag.**
+
+Features:
+
+* Sets specific days and time for automatic Kubernetes version upgrades.
+
+Parameters:
+
+* cluster_id (required), weekdays (required — e.g. ['Mon', 'Wed', 'Fri']), time (required — HH:mm format, e.g. '03:00'), region (optional)
+
+#### `cluster_auto_upgrade_delete`
+
+Deletes auto-upgrade configuration for a VKS cluster. **Requires `--allow-write` flag.**
+
+Features:
+
+* Disables automatic cluster upgrades.
+
+Parameters:
+
+* cluster_id (required), region (optional)
+
+### Node Group Management
+
+#### `nodegroup_list`
+
+Lists all node groups in a VKS cluster. Returns a markdown table.
+
+Features:
+
+* Shows node group name, ID, status, node count, flavor, image.
+* Includes cluster name in context.
+
+Parameters:
+
+* cluster_id (required), region (optional)
+
+#### `nodegroup_get`
+
+Gets full detail of a specific node group. Returns a markdown key-value table.
+
+Features:
+
+* Shows flavor, image, disk size, scaling config, labels, taints, security groups.
+
+Parameters:
+
+* cluster_id (required), nodegroup_id (required), region (optional)
+
+#### `nodegroup_list_nodes`
+
+Lists individual nodes in a node group. Returns a markdown table with node name, ID, status, IP, and creation time.
+
+Features:
+
+* Supports pagination for large node groups.
+
+Parameters:
+
+* cluster_id (required), nodegroup_id (required), page (optional), pageSize (optional, default: 50), region (optional)
+
+#### `nodegroup_delete_dryrun`
+
+Preview what will be deleted when deleting a node group.
+
+Features:
+
+* Shows node group details and node count.
+* Safe to run — does not modify any resources.
+
+Parameters:
+
+* cluster_id (required), nodegroup_id (required), region (optional)
+
+#### `nodegroup_create`
+
+Creates a new node group in a VKS cluster. **Requires `--allow-write` flag.**
+
+Features:
+
+* Supports full node group configuration: flavor, image, disk, scaling, security groups, SSH key.
+
+Parameters:
+
+* cluster_id (required), body (required — CreateNodeGroupDto JSON with name, numNodes, imageId, flavorId, diskSize, diskType, enablePrivateNodes, securityGroups, sshKeyId, upgradeConfig), region (optional)
+
+#### `nodegroup_update`
+
+Updates a node group. **Requires `--allow-write` flag.** `imageId` is always required in body.
+
+Features:
+
+* Supports partial updates for numNodes, securityGroups, labels, taints, autoScaleConfig, upgradeConfig.
+
+Parameters:
+
+* cluster_id (required), nodegroup_id (required), body (required — must include imageId), region (optional)
+
+#### `nodegroup_delete`
+
+Deletes a node group. **IRREVERSIBLE. Requires `--allow-write` flag.** Use `nodegroup_delete_dryrun` first.
+
+Features:
+
+* Permanently removes node group and all its nodes.
+
+Parameters:
+
+* cluster_id (required), nodegroup_id (required), region (optional)
+
+### Kubernetes Resource Management
+
+#### `list_k8s_resources`
+
+Lists Kubernetes resources of a specific kind in a VKS cluster. Use this tool instead of `kubectl get` commands.
+
+Features:
+
+* Supports filtering by namespace, labels, and fields.
+* Returns resource summaries with name, namespace, creation time, and metadata.
+* Works with any resource kind (Pod, Service, Deployment, ConfigMap, etc.).
+
+Parameters:
+
+* cluster_id (required), kind (required — e.g. 'Pod', 'Service'), api_version (required — e.g. 'v1', 'apps/v1'), namespace (optional), label_selector (optional), field_selector (optional), region (optional)
+
+#### `get_pod_logs`
+
+Gets logs from a pod in a Kubernetes cluster. Use this tool instead of `kubectl logs`. **Requires `--allow-sensitive-data-access` flag.**
+
+Features:
+
+* Supports filtering by container, time range, and size.
+* Can retrieve previous terminated container logs for crash debugging.
+
+Parameters:
+
+* cluster_id (required), namespace (required), pod_name (required), container_name (optional), since_seconds (optional), tail_lines (optional, default: 100), limit_bytes (optional, default: 10240), previous (optional, default: false), region (optional)
+
+#### `get_k8s_events`
+
+Gets events related to a specific Kubernetes resource. Use this tool instead of `kubectl describe` or `kubectl get events`. **Requires `--allow-sensitive-data-access` flag.**
+
+Features:
+
+* Returns event timestamps, occurrence counts, messages, reasons, and reporting components.
+* Useful for troubleshooting pod startup failures, deployment issues, and scheduling problems.
+
+Parameters:
+
+* cluster_id (required), kind (required — e.g. 'Pod', 'Deployment'), name (required), namespace (optional), region (optional)
+
+#### `list_api_versions`
+
+Lists all available API versions in the Kubernetes cluster.
+
+Features:
+
+* Discovers core APIs (e.g. 'v1'), API groups (e.g. 'apps/v1'), and CRD APIs.
+* Helps determine the correct apiVersion for managing resources.
+
+Parameters:
+
+* cluster_id (required), region (optional)
+
+#### `manage_k8s_resource`
+
+Manages a single Kubernetes resource with CRUD operations. Use this tool instead of `kubectl create/edit/patch/delete/get`. **Requires `--allow-write` flag for mutating operations.** **Requires `--allow-sensitive-data-access` for Secret resources.**
+
+Features:
+
+* Supports create, replace, patch, delete, and read operations.
+* Handles both namespaced and cluster-scoped resources.
+
+Parameters:
+
+* operation (required — create/replace/patch/delete/read), cluster_id (required), kind (required), api_version (required), name (optional), namespace (optional), body (optional — required for create/replace/patch), region (optional)
+
+#### `apply_yaml`
+
+Applies Kubernetes YAML manifests from a local file. Use this tool instead of `kubectl apply -f`. **Requires `--allow-write` flag.**
+
+Features:
+
+* Supports multi-document YAML files.
+* Can create or update existing resources.
+* Path must be absolute (e.g. '/home/user/manifests/app.yaml').
+
+Parameters:
+
+* yaml_path (required — absolute path), cluster_id (required), namespace (required), force (optional, default: true), region (optional)
+
+## Security
+
+### Features
+
+- **Read-only by default** — Write operations (create/update/delete) require `--allow-write` flag
+- **Sensitive data protection** — Kubernetes Secrets hidden by default, require `--allow-sensitive-data-access`
+- **Credential security** — Credentials read from `~/.greenode/credentials` with `0600` file permissions
+- **Input validation** — All cluster and nodegroup IDs validated (alphanumeric + hyphens only) to prevent path traversal
+- **Token handling** — Access tokens stored in memory only, never written to disk or logged
+- **Request timeout** — All HTTP requests have 30s timeout to prevent hanging
+- **Retry with backoff** — Automatic retry with exponential backoff (1s → 2s → 4s) for transient errors (5xx, timeouts)
+
+### Permissions
+
+**Read-only mode** (default):
+
+All list, get, describe, and validation tools are available without any flags.
+
+**Write mode** (`--allow-write`):
+
+Enables mutating operations: `cluster_create`, `cluster_update`, `cluster_delete`, `nodegroup_create`, `nodegroup_update`, `nodegroup_delete`, `cluster_auto_upgrade_config`, `cluster_auto_upgrade_delete`, `manage_k8s_resource`, `apply_yaml`.
+
+**Sensitive data mode** (`--allow-sensitive-data-access`):
+
+Enables reading Kubernetes Secret resources via `list_k8s_resources` and `manage_k8s_resource`.
+
+### Best Practices
+
+- Start with **read-only mode** to explore clusters before enabling writes
+- Use `cluster_delete_dryrun` and `nodegroup_delete_dryrun` to preview deletions
+- Use `cluster_create_validate` to check parameters before creating clusters
+- Review AI-generated YAML carefully before using `apply_yaml`
+- Use separate IAM service accounts with minimal permissions per environment
+
+## Getting Help
+
+- [Open an issue](https://github.com/vngcloud/greennode-mcp/issues/new/choose) — Bug reports and feature requests
+- Search [existing issues](https://github.com/vngcloud/greennode-mcp/issues) before opening a new one
+
+## More Resources
+
+- [Development Guide](docs/DEVELOPMENT.md) — Contributing, CI/CD, release process
+- [GreenNode CLI](https://github.com/vngcloud/greennode-cli) — CLI companion tool
+- [MCP Protocol](https://modelcontextprotocol.io/) — Model Context Protocol specification
+- [VNG Cloud Console](https://hcm-3.console.vngcloud.vn/)
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE).