Repository: containers/kubernetes-mcp-server

Issue:
There should be an AGENTS.md so code agents have a starting point
Make it easier on code agents to do the right thing right away. We should provide an AGENTS.md that outline the project from a code standpoint; outlines what code does what and generally makes it easier for code agents to pitch in to help the project.

I already made a PR: https://github.com/containers/kubernetes-mcp-server/pull/204

Hints from issue comments:
@bentito: Just to give some context:

This is a community blog promoting and explaining the `AGENTS.md` standard: https://agentsmd.net/

OpenAI's `codex` agent looks for `AGENTS.md` on startup:
https://platform.openai.com/docs/codex/overview#how-it-works

The `Jules` coding agent does so as well: https://platform.openai.com/docs/codex/overview#how-it-works

The `Aider` coding agent is considering supporting this standard: https://github.com/aider-ai/aider/issues/4363



Solution patch:
diff --git a/AGENTS.md b/AGENTS.md
index 1b67cbb..854cfe5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,25 +1,34 @@
-# AGENTS
-
-This repository contains a Go implementation of a Model Context Protocol (MCP)
-server for Kubernetes and OpenShift.
-
-## Repository layout
-
-- `cmd/kubernetes-mcp-server/` – entry point and Cobra CLI.
-- `pkg/` – libraries grouped by domain (`kubernetes`, `mcp`, `output`, …).
+# Project Agents.md for Kubernetes MCP Server
+
+This Agents.md file provides comprehensive guidance for AI assistants and coding agents (like Claude, Gemini, Cursor, and others) to work with this codebase.
+
+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).
+
+## 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-<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
-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`.
diff --git a/pkg/mcp/mcp.go b/pkg/mcp/mcp.go
index 96705cb..fb2ceff 100644
--- a/pkg/mcp/mcp.go
+++ b/pkg/mcp/mcp.go
@@ -1,6 +1,7 @@
 package mcp
 
 import (
+	"bytes"
 	"context"
 	"fmt"
 	"k8s.io/klog/v2"
@@ -171,6 +172,12 @@ func contextFunc(ctx context.Context, r *http.Request) context.Context {
 func toolCallLoggingMiddleware(next server.ToolHandlerFunc) server.ToolHandlerFunc {
 	return func(ctx context.Context, ctr mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 		klog.V(5).Infof("mcp tool call: %s(%v)", ctr.Params.Name, ctr.Params.Arguments)
+		if ctr.Header != nil {
+			buffer := bytes.NewBuffer(make([]byte, 0))
+			if err := ctr.Header.Write(buffer); err == nil {
+				klog.V(7).Infof("mcp tool call headers: %s", buffer)
+			}
+		}
 		return next(ctx, ctr)
 	}
 }



Test patch:
diff --git a/pkg/mcp/common_test.go b/pkg/mcp/common_test.go
index 0ffe7b8..8e4e49d 100644
--- a/pkg/mcp/common_test.go
+++ b/pkg/mcp/common_test.go
@@ -6,8 +6,6 @@ import (
 	"encoding/json"
 	"flag"
 	"fmt"
-	"k8s.io/klog/v2"
-	"k8s.io/klog/v2/textlogger"
 	"net/http/httptest"
 	"os"
 	"path/filepath"
@@ -36,6 +34,8 @@ import (
 	"k8s.io/client-go/tools/clientcmd"
 	"k8s.io/client-go/tools/clientcmd/api"
 	toolswatch "k8s.io/client-go/tools/watch"
+	"k8s.io/klog/v2"
+	"k8s.io/klog/v2/textlogger"
 	"k8s.io/utils/ptr"
 	"sigs.k8s.io/controller-runtime/pkg/envtest"
 	"sigs.k8s.io/controller-runtime/tools/setup-envtest/env"
diff --git a/pkg/mcp/mcp_tools_test.go b/pkg/mcp/mcp_tools_test.go
index d450d27..2280c49 100644
--- a/pkg/mcp/mcp_tools_test.go
+++ b/pkg/mcp/mcp_tools_test.go
@@ -140,4 +140,16 @@ func TestToolCallLogging(t *testing.T) {
 			}
 		})
 	})
+	testCaseWithContext(t, &mcpContext{logLevel: 7}, func(c *mcpContext) {
+		_, _ = c.callTool("configuration_view", map[string]interface{}{
+			"minified": false,
+		})
+		t.Run("Logs tool call headers", func(t *testing.T) {
+			expectedLog := "mcp tool call headers: Accept-Encoding: gzip"
+			if !strings.Contains(c.logBuffer.String(), expectedLog) {
+				t.Errorf("Expected log to contain '%s', got: %s", expectedLog, c.logBuffer.String())
+			}
+		})
+
+	})
 }