kubeview-mcp 1.0.0

package/.prettierrc.json

@@ -0,0 +1,11 @@
+{
+  "semi": true,
+  "trailingComma": "all",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "endOfLine": "lf"
+}

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2024-12-19
+
+### Added
+- **Initial stable release** 🎉
+- Complete **Kubernetes MCP Server** with read-only cluster introspection
+- **Comprehensive tool coverage**:
+  - Resource management (Pods, Services, Deployments, Ingresses, ConfigMaps, Secrets, Namespaces)
+  - Storage & persistence (PVs, PVCs with analysis)
+  - Monitoring & observability (Metrics, Events, Logs)
+  - Generic resource inspector
+- **Helm integration** with full lifecycle support:
+  - Release listing, status, history
+  - Values, manifests, notes, hooks inspection
+  - Kubernetes resource mapping
+- **Argo Workflows integration**:
+  - Workflow listing and inspection
+  - Log streaming
+  - Cron workflow support
+- **ArgoCD integration**:
+  - Application management
+  - History and resource tracking
+  - Log access
+- **Production-ready features**:
+  - Robust error handling with circuit breakers
+  - Connection pooling and retry strategies
+  - Comprehensive test suite (261 tests)
+  - TypeScript strict mode
+  - ESLint + Prettier formatting
+  - Husky git hooks with lint-staged
+- **Release automation**:
+  - Added `npm run release` script for streamlined releases
+  - Pre-release validation (git status, quality checks)
+  - Automatic version tagging
+
+### Technical Details
+- **Node.js ≥ 18** requirement
+- **ESNext modules** with TypeScript 5.8+
+- **Model Context Protocol SDK v1.17+**
+- **Kubernetes JavaScript client v1.3+**
+- Full **CI/CD pipeline** with automated quality gates
+
+### Documentation
+- Comprehensive README with usage examples
+- CLI reference for all 30+ tools
+- Integration guides for Cursor IDE
+- API documentation for developers
+
+[1.0.0]: https://github.com/mikhae1/kubeview-mcp/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 kubeview-mcp team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,251 @@
+# KubeView MCP – Kubernetes Model Context Protocol Server
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.8+-blue)](https://www.typescriptlang.org/)
+
+**KubeView MCP** is a **read-only Model Context Protocol (MCP) server** that exposes rich, AI-ready operations for Kubernetes clusters. Paired with tools like **Cursor IDE** or Chat-based assistants, it lets you inspect, analyse and debug your cluster through natural-language commands while guaranteeing zero write access.
+
+---
+
+## Table of Contents
+
+- [KubeView MCP – Kubernetes Model Context Protocol Server](#kubeview-mcp--kubernetes-model-context-protocol-server)
+  - [Table of Contents](#table-of-contents)
+  - [✨ Features](#-features)
+  - [🚀 Quick Start](#-quick-start)
+    - [Prerequisites](#prerequisites)
+    - [Installation](#installation)
+    - [Build & Run](#build--run)
+  - [📟 CLI Reference](#-cli-reference)
+    - [Resource Management](#resource-management)
+    - [Storage & Persistence](#storage--persistence)
+    - [Monitoring & Observability](#monitoring--observability)
+    - [Generic Resource Tool](#generic-resource-tool)
+  - [🪄 Helm Integration](#-helm-integration)
+    - [Core Operations](#core-operations)
+    - [Configuration & Values](#configuration--values)
+    - [Helm ↔ Kubernetes Bridge](#helm--kubernetes-bridge)
+      - [Example – list all Helm releases](#example--list-all-helm-releases)
+  - [Argo Integration](#argo-integration)
+  - [ArgoCD Integration](#argocd-integration)
+  - [💡 Usage Examples](#-usage-examples)
+  - [🤝 Contributing](#-contributing)
+  - [📄 License](#-license)
+  - [🙏 Acknowledgments](#-acknowledgments)
+
+---
+
+## ✨ Features
+
+- **Kubernetes Resources** – Read-only access to Pods, Services, Deployments, Namespaces, ConfigMaps, Secrets, PVCs and more.
+- **Helm Support** – Deep inspection of Helm releases including manifests, values, hooks and history.
+- **Argo & ArgoCD Integration** – Seamlessly interact with Argo Workflows and ArgoCD applications.
+- **Advanced Storage Analysis** – Diagnose PV/PVC issues with smart binding & reclaim-policy checks.
+- **Robust Monitoring** – CPU / memory metrics out-of-the-box, optionally enriched with Prometheus data.
+- **Log Streaming** – Tail or grep container logs directly from your AI assistant.
+- **Cluster Events** – Filter and analyse live Kubernetes events.
+
+---
+
+## 🚀 Quick Start
+
+### Zero-install via npx
+
+```bash
+npx https://github.com/mikhae1/kubeview-mcp
+```
+
+_For Cursor IDE or any other MCP-compatible client, add the following entry to your_ `mcp.json` _file (usually located in `~/.cursor/mcp.json`):_
+
+```json
+{
+  "mcpServers": {
+    "kubeview-mcp": {
+      "command": "npx",
+      "args": ["https://github.com/mikhae1/kubeview-mcp"],
+      "env": {
+        "KUBECONFIG": "$HOME/.kube/config"
+      }
+    }
+  }
+}
+```
+
+### Prerequisites
+
+- **Node.js ≥ 18**
+- **npm** (or **yarn/pnpm**) for dependency management
+- Access to a **Kubernetes cluster** with a valid *kubeconfig*
+- **Cursor IDE** (or another MCP-compatible client) for interactive use
+
+### Installation
+
+```bash
+# Clone the repository
+$ git clone https://github.com/mikhae1/kubeview-mcp.git
+$ cd kubeview-mcp
+
+# Install dependencies
+$ npm install
+
+# Generate local configuration for Cursor IDE & Claude
+$ npm run setup
+```
+
+### Build & Run
+
+```bash
+# Compile TypeScript → JavaScript
+$ npm run build
+
+# Start the MCP server
+$ npm start
+```
+
+The server will automatically locate your *kubeconfig* and use the current k8s context for all operations.
+
+---
+
+## 📟 CLI Reference
+
+All commands are invoked through the project-local helper:
+
+```bash
+npm run command -- <tool_name> [tool options]
+```
+
+### Resource Management
+
+| Tool             | Description                                               |
+| ---------------- | --------------------------------------------------------- |
+| `get_pods`       | List / filter pods with detailed phase & container state |
+| `get_services`   | Discover services and their exposed endpoints            |
+| `get_deployments`| Inspect deployment rollout status & spec                |
+| `get_ingresses`  | View ingresses and their routing rules                    |
+| `get_configmaps` | View ConfigMaps (with sensitive data automatically redacted) |
+| `get_secrets`    | Read-only secret inspector with built-in sanitisation    |
+| `get_namespaces` | Enumerate namespaces in the cluster                      |
+
+### Storage & Persistence
+
+| Tool                           | Description                                                  |
+| ------------------------------ | ------------------------------------------------------------ |
+| `get_persistent_volumes`       | Analyse PVs and detect reclaim / capacity issues            |
+| `get_persistent_volume_claims` | Inspect PVC binding, access modes & storage-class details   |
+
+### Monitoring & Observability
+
+| Tool            | Description                                                   |
+| --------------- | ------------------------------------------------------------- |
+| `get_metrics`   | Cluster-wide CPU & memory metrics (Prometheus optional)      |
+| `get_pod_metrics` | Fine-grained metrics for individual pods                     |
+| `get_events`    | Stream or filter recent cluster events                       |
+| `pod_logs`      | Tail container logs with regex / since-time filters          |
+
+### Generic Resource Tool
+
+| Tool           | Description                               |
+| -------------- | ----------------------------------------- |
+| `get_resource` | Inspect any Kubernetes resource by GVR    |
+
+---
+
+## 🪄 Helm Integration
+
+KubeView MCP ships with a dedicated **HelmToolsPlugin** bringing first-class Helm introspection.
+
+### Core Operations
+
+| Tool         | Description                                                |
+| ------------ | ---------------------------------------------------------- |
+| `helm_list`  | List releases across all namespaces with status & revision |
+| `helm_status`| Full release status (history, manifest, values)            |
+| `helm_history`| Complete upgrade / rollback history                        |
+
+### Configuration & Values
+
+| Tool               | Description                                   |
+| ------------------ | --------------------------------------------- |
+| `helm_get_values`  | Rendered values.yaml for a release            |
+| `helm_get_manifest`| Complete aggregated Kubernetes manifest       |
+| `helm_get_notes`   | Chart installation notes & post-deploy hints  |
+| `helm_get_hooks`   | Pre / post hooks configured by the chart      |
+
+### Helm ↔ Kubernetes Bridge
+
+| Tool                       | Description                                                         |
+| -------------------------- | ------------------------------------------------------------------- |
+| `helm_get_resources`       | Discover / categorise all resources created by a release            |
+| `helm_list_with_resources` | Enhanced `helm_list` that bundles the above analysis for each release |
+
+#### Example – list all Helm releases
+
+```bash
+npm run command -- helm_list
+```
+
+---
+##  Argo Integration
+
+The **ArgoToolsPlugin** provides tools for interacting with Argo Workflows.
+
+| Tool | Description |
+| --- | --- |
+| `argo_get`  | Get details about a workflow
+| `argo_list` | List all Argo Workflows |
+| `argo_logs` | Get logs from an Argo Workflow |
+| `argo_cron_list` | List all Argo Cron Workflows |
+
+## ArgoCD Integration
+
+The **ArgoCDToolsPlugin** provides tools for interacting with ArgoCD.
+
+| Tool | Description |
+| --- | --- |
+| `argocd_app_list` | List all ArgoCD applications |
+| `argocd_app_get` | Get a specific ArgoCD application |
+| `argocd_app_history` | Get the history of an ArgoCD application |
+| `argocd_app_logs` | Get the logs of an ArgoCD application |
+| `argocd_app_resources` | Get the resources of an ArgoCD application |
+
+---
+
+## 💡 Usage Examples
+
+Ask your assistant:
+
+> *“Show me the details of the **nginx** deployment in the **web** namespace.”*
+
+KubeView MCP will execute `get_resource` under the hood and return a structured JSON response that your assistant converts into a readable answer.
+
+> *“List all pods in the **default** namespace and show their CPU and memory usage.”*
+
+This will trigger the `get_pods` and `get_pod_metrics` tools, combining their output to provide a comprehensive view of your pods' resource consumption.
+
+---
+
+## 🤝 Contributing
+
+1. Fork the repo
+2. Create a feature branch: `git checkout -b feat/my-awesome-feature`
+3. Commit your changes: `git commit -m "feat: add my awesome feature"`
+4. Push to GitHub: `git push origin feat/my-awesome-feature`
+5. Open a Pull Request – thank you!
+
+> 💡 Run `npm run lint` and `npm run test` before opening a PR.
+
+---
+
+## 📄 License
+
+This project is released under the MIT License – see [LICENSE](LICENSE).
+
+---
+
+## 🙏 Acknowledgments
+
+- [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk)
+- [Kubernetes JavaScript Client](https://github.com/kubernetes-client/javascript)
+- [Winston](https://github.com/winstonjs/winston)
+- [TypeScript](https://www.typescriptlang.org/)

package/RELEASE.md

@@ -0,0 +1,154 @@
+# Release Process
+
+This document describes how to create releases for KubeView MCP.
+
+## Quick Release
+
+For a complete release with all quality checks and tagging:
+
+```bash
+npm run release
+```
+
+This single command will:
+1. ✅ **Check git status** - Ensure working directory is clean
+2. ✅ **Run quality assurance** - Lint, typecheck, and test the codebase
+3. ✅ **Build the project** - Compile TypeScript to JavaScript
+4. ✅ **Create git tag** - Tag the current version for release
+
+## Step-by-Step Release
+
+If you need more control, you can run individual release steps:
+
+### 1. Pre-release Validation
+```bash
+npm run release:check
+```
+Ensures your git working directory is clean (no uncommitted changes).
+
+### 2. Quality Assurance
+```bash
+npm run release:qa
+```
+Runs the complete QA pipeline:
+- `npm run lint` - ESLint validation
+- `npm run typecheck` - TypeScript compilation check
+- `npm run test` - Full test suite (261 tests)
+
+### 3. Build
+```bash
+npm run release:build
+```
+Compiles the project with `tsc` to the `dist/` directory.
+
+### 4. Create Git Tag
+```bash
+npm run release:tag
+```
+Creates a git tag with the current version from `package.json` (e.g., `v1.0.0`).
+
+## Version Management
+
+### Updating Version
+Before releasing, update the version in `package.json`:
+
+```json
+{
+  "version": "1.0.1"
+}
+```
+
+### Version Conventions
+We follow [Semantic Versioning](https://semver.org/):
+- **Major** (1.0.0 → 2.0.0): Breaking changes
+- **Minor** (1.0.0 → 1.1.0): New features, backwards compatible
+- **Patch** (1.0.0 → 1.0.1): Bug fixes, backwards compatible
+
+## Publishing to npm
+
+The release scripts prepare the project but do not automatically publish to npm.
+
+To publish manually after a successful release:
+
+```bash
+# Login to npm (if not already logged in)
+npm login
+
+# Publish the package
+npm publish
+```
+
+## Release Checklist
+
+Before running `npm run release`:
+
+- [ ] Update version in `package.json`
+- [ ] Update `CHANGELOG.md` with new features/fixes
+- [ ] Ensure all changes are committed to git
+- [ ] Verify tests pass: `npm test`
+- [ ] Check the build works: `npm run build`
+
+## Troubleshooting
+
+### "Working directory not clean" Error
+If `release:check` fails:
+```bash
+# Check what files have changes
+git status
+
+# Either commit the changes
+git add .
+git commit -m "Prepare for release"
+
+# Or stash them
+git stash
+```
+
+### Test Failures
+If `release:qa` fails during testing:
+```bash
+# Run tests individually to debug
+npm run test -- --verbose
+
+# Fix any failing tests, then retry
+npm run release:qa
+```
+
+### Build Errors
+If `release:build` fails:
+```bash
+# Check TypeScript errors
+npm run typecheck
+
+# Fix any compilation issues, then retry
+npm run release:build
+```
+
+## Advanced Usage
+
+### Dry Run
+To see what the release would do without making changes:
+```bash
+# Check git status (safe to run)
+npm run release:check
+
+# Run QA checks (safe to run)
+npm run release:qa
+
+# Build project (creates dist/ but no tags)
+npm run release:build
+```
+
+### Manual Tag Creation
+If you need to create a tag manually:
+```bash
+# Create tag for current version
+git tag v$(node -p "require('./package.json').version")
+
+# Push tag to remote
+git push origin v$(node -p "require('./package.json').version")
+```
+
+## Release History
+
+See [CHANGELOG.md](CHANGELOG.md) for detailed release history.