From 4a7e05151a6d013de3bba81143151603d84e9256 Mon Sep 17 00:00:00 2001 From: Marc Nuri Date: Thu, 31 Jul 2025 09:55:51 +0200 Subject: [PATCH] chore(doc): polish the Agents.md file (#222) Signed-off-by: Marc Nuri --- AGENTS.md | 101 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 68 insertions(+), 33 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1b67cbb..854cfe5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,25 +1,34 @@ -# AGENTS +# Project Agents.md for Kubernetes MCP Server -This repository contains a Go implementation of a Model Context Protocol (MCP) -server for Kubernetes and OpenShift. +This Agents.md file provides comprehensive guidance for AI assistants and coding agents (like Claude, Gemini, Cursor, and others) to work with this codebase. -## Repository layout +This repository contains the kubernetes-mcp-server project, +a powerful Go-based Model Context Protocol (MCP) server that provides native Kubernetes and OpenShift cluster management capabilities without external dependencies. +This MCP server enables AI assistants (like Claude, Gemini, Cursor, and others) to interact with Kubernetes clusters using the Model Context Protocol (MCP). -- `cmd/kubernetes-mcp-server/` – entry point and Cobra CLI. -- `pkg/` – libraries grouped by domain (`kubernetes`, `mcp`, `output`, …). +## Project Structure and Repository layout + +- Go package layout follows the standard Go conventions: + - `cmd/kubernetes-mcp-server/` – main application entry point using Cobra CLI framework. + - `pkg/` – libraries grouped by domain. + - `config/` – configuration management. + - `helm/` - Helm chart operations integration. + - `http/` - HTTP server and authorization middleware. + - `kubernetes/` - Kubernetes client management, authentication, and access control. + - `mcp/` - Model Context Protocol (MCP) server implementation with tool registration and STDIO/HTTP support. + - `output/` - output formatting and rendering. +- `.github/` – GitHub-related configuration (Actions workflows, issue templates...). +- `docs/` – documentation files. +- `npm/` – Node packages that wraps the compiled binaries for distribution through npmjs.com. +- `python/` – Python package providing a script that downloads the correct platform binary from the GitHub releases page and runs it for distribution through pypi.org. +- `Dockerfile` - container image description file to distribute the server as a container image. - `Makefile` – tasks for building, formatting, linting and testing. -- `npm/` – Node packages that wrap the compiled binary. The `kubernetes-mcp-server` package - defines a small launcher in `bin/index.js` which resolves the platform specific - optional dependency (`kubernetes-mcp-server--`) and executes it. -- `python/` – Python package providing a script that downloads the correct - platform binary from the GitHub releases page and runs it. ## Feature development Implement new functionality in the Go sources under `cmd/` and `pkg/`. -The JavaScript and Python directories only wrap the compiled binary for -distribution (npm and PyPI). Most changes will not require touching them -unless the version or packaging needs to be updated. +The JavaScript (`npm/`) and Python (`python/`) directories only wrap the compiled binary for distribution (npm and PyPI). +Most changes will not require touching them unless the version or packaging needs to be updated. ## Building @@ -33,8 +42,8 @@ make build make build-all-platforms ``` -`make build` will run `go fmt` and `go mod tidy` before compiling. The -resulting executable is `kubernetes-mcp-server`. +`make build` will run `go fmt` and `go mod tidy` before compiling. +The resulting executable is `kubernetes-mcp-server`. ## Running @@ -46,15 +55,33 @@ make build npx @modelcontextprotocol/inspector@latest $(pwd)/kubernetes-mcp-server ``` -The server is typically run locally and connects to the cluster using the same -configuration loading rules as `kubectl`. When started with `npx` or `uvx` it -downloads and executes a platform specific binary. The running process then -reads the kubeconfig resolved from the `--kubeconfig` flag, the `KUBECONFIG` -environment variable or the default `~/.kube/config` file. If those are not -present and the process executes inside a pod it falls back to in-cluster -configuration. This means that `npx kubernetes-mcp-server` on a workstation will -talk to whatever cluster your current kubeconfig points to (e.g. a local Kind -cluster). +To run the server locally, you can use `npx`, `uvx` or execute the binary directly: + +```bash +# Using npx (Node.js package runner) +npx -y kubernetes-mcp-server@latest + +# Using uvx (Python package runner) +uvx kubernetes-mcp-server@latest + +# Binary execution +./kubernetes-mcp-server +``` + +This MCP server is designed to run both locally and remotely. + +### Local Execution + +When running locally, the server connects to a Kubernetes or OpenShift cluster using the kubeconfig file. +It reads the kubeconfig from the `--kubeconfig` flag, the `KUBECONFIG` environment variable, or defaults to `~/.kube/config`. + +This means that `npx -y kubernetes-mcp-server@latest` on a workstation will talk to whatever cluster your current kubeconfig points to (e.g. a local Kind cluster). + +### Remote Execution + +When running remotely, the server can be deployed as a container image in a Kubernetes or OpenShift cluster. +The server can be run as a Deployment, StatefulSet, or any other Kubernetes resource that suits your needs. +The server will automatically use the in-cluster configuration to connect to the Kubernetes API server. ## Tests @@ -64,10 +91,9 @@ Run all Go tests with: make test ``` -The test suite relies on the `setup-envtest` tooling from -`sigs.k8s.io/controller-runtime`. The first run downloads a Kubernetes -`envtest` environment from the internet, so network access is required. Without -it some tests will fail during setup. +The test suite relies on the `setup-envtest` tooling from `sigs.k8s.io/controller-runtime`. +The first run downloads a Kubernetes `envtest` environment from the internet, so network access is required. +Without it some tests will fail during setup. ## Linting @@ -77,13 +103,11 @@ Static analysis is performed with `golangci-lint`: make lint ``` -The `lint` target downloads the specified `golangci-lint` version if it is not -already present under `_output/tools/bin/`. +The `lint` target downloads the specified `golangci-lint` version if it is not already present under `_output/tools/bin/`. ## Dependencies -When introducing new modules run `go mod tidy` (or `make tidy`) so that -`go.mod` and `go.sum` remain tidy. +When introducing new modules run `make tidy` so that `go.mod` and `go.sum` remain tidy. ## Coding style @@ -91,3 +115,14 @@ When introducing new modules run `go mod tidy` (or `make tidy`) so that - Tests are written with the standard library `testing` package. - Build, test and lint steps are defined in the Makefile—keep them working. +## Distribution Methods + +The server is distributed as a binary executable, a Docker image, an npm package, and a Python package. + +- **Native binaries** for Linux, macOS, and Windows are available in the GitHub releases. +- A **container image** (Docker) is built and pushed to the `quay.io/manusa/kubernetes_mcp_server` repository. +- An **npm** package is available at [npmjs.com](https://www.npmjs.com/package/kubernetes-mcp-server). + It wraps the platform-specific binary and provides a convenient way to run the server using `npx`. +- A **Python** package is available at [pypi.org](https://pypi.org/project/kubernetes-mcp-server/). + It provides a script that downloads the correct platform binary from the GitHub releases page and runs it. + It provides a convenient way to run the server using `uvx` or `python -m kubernetes_mcp_server`.