chore(doc): polish the Agents.md file (#222)

Signed-off-by: Marc Nuri <marc@marcnuri.com>

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)
+This Agents.md file provides comprehensive guidance for AI assistants and coding agents (like Claude, Gemini, Cursor, and others) to work with this codebase.
-server for Kubernetes and OpenShift.
 
-## 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.
+## Project Structure and Repository layout
-- `pkg/` – libraries grouped by domain (`kubernetes`, `mcp`, `output`, …).
+
+- 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-<os>-<arch>`) 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
+The JavaScript (`npm/`) and Python (`python/`) directories only wrap the compiled binary for distribution (npm and PyPI).
-distribution (npm and PyPI). Most changes will not require touching them
+Most changes will not require touching them unless the version or packaging needs to be updated.
-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
+`make build` will run `go fmt` and `go mod tidy` before compiling.
-resulting executable is `kubernetes-mcp-server`.
+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
+To run the server locally, you can use `npx`, `uvx` or execute the binary directly:
-configuration loading rules as `kubectl`. When started with `npx` or `uvx` it
+
-downloads and executes a platform specific binary. The running process then
+```bash
-reads the kubeconfig resolved from the `--kubeconfig` flag, the `KUBECONFIG`
+# Using npx (Node.js package runner)
-environment variable or the default `~/.kube/config` file. If those are not
+npx -y kubernetes-mcp-server@latest
-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
+# Using uvx (Python package runner)
-talk to whatever cluster your current kubeconfig points to (e.g. a local Kind
+uvx kubernetes-mcp-server@latest
-cluster).
+
+# 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
+The test suite relies on the `setup-envtest` tooling from `sigs.k8s.io/controller-runtime`.
-`sigs.k8s.io/controller-runtime`. The first run downloads a Kubernetes
+The first run downloads a Kubernetes `envtest` environment from the internet, so network access is required.
-`envtest` environment from the internet, so network access is required. Without
+Without it some tests will fail during setup.
-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
+The `lint` target downloads the specified `golangci-lint` version if it is not already present under `_output/tools/bin/`.
-already present under `_output/tools/bin/`.
 
 ## Dependencies
 
-When introducing new modules run `go mod tidy` (or `make tidy`) so that
+When introducing new modules run `make tidy` so that `go.mod` and `go.sum` remain tidy.
-`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`.