k8stools 2.0.4__tar.gz → 2.2.0__tar.gz

k8stools-2.2.0/CHANGELOG.md

@@ -0,0 +1,210 @@
+# Changelog
+
+All notable changes to k8stools. Versions follow [semantic versioning](https://semver.org/);
+dates are release-tag dates.
+
+## 2.2.0 — 2026-09-28
+
+### Added
+- **`count` and `first_seen` on events** (issue #8). `get_pod_events` and
+  `get_events` now report how many occurrences Kubernetes combined into each
+  event record, and how long ago the first one was, next to `last_seen`. For a
+  crash-looping container this gives the restart rate directly: on one cluster,
+  a `Created` count of 579 over 2 days 8 hours is a restart every ~5.8 minutes,
+  a number agents kept getting wrong from the other durations. The tool
+  descriptions explain the window the count covers and warn that `BackOff`
+  counts are several times the number of restarts. `print_pod_events` and
+  `print_events` gain a COUNT column.
+- Captures store both fields; captures from before 2.2.0 replay them as `None`.
+
+### Fixed
+- **Replayed `captured_at` was on a different clock** (issue #7).
+  `get_cluster_info` returned the date in the capture file while every other
+  replayed timestamp was re-anchored to the server's start, so a pod killed
+  "5 minutes ago" appeared beside a capture taken a month ago. `captured_at` is
+  now the replay's anchor (the server's start time); the recorded date is in the
+  startup log and on `MockState.captured_at`.
+- **Replayed logs kept their original timestamps.** Log line timestamps were not
+  re-anchored, so they contradicted every other replayed time, and
+  `since_seconds` (compared against the replay's "now") returned an empty log for
+  any capture older than the window, as if the container had logged nothing.
+  The kubelet's timestamp prefix on each line is now moved like every other
+  datetime, keeping its original precision and format. Timestamps an application
+  writes inside its messages are left as recorded.
+- **Events recorded through `events.k8s.io/v1` had no time.** Their core/v1 view
+  leaves `lastTimestamp` empty and records the time in `eventTime` (and
+  repetition in `series`), so `last_seen` came back `None`. Both are now read
+  when the older fields are empty.
+
+## 2.1.0 — 2026-09-28
+
+### Added
+- **Cluster selection.** `k8s-mcp-server` and `k8s-capture-state` take
+  `--kubeconfig PATH` and `--context NAME`; the context can also be pinned with
+  the `K8STOOLS_CONTEXT` environment variable. The order is flag, then
+  `KUBECONFIG` / `K8STOOLS_CONTEXT`, then `~/.kube/config` and its
+  `current-context`. The MCP server binds at startup and logs which cluster it is
+  answering from. Direct Python callers can call `k8s_tools.configure(kubeconfig,
+  context)`. See README, "Selecting a cluster".
+- **`get_cluster_info` tool.** Reports which cluster the tools answer from: source
+  (`kubeconfig`, `in-cluster` or `capture`), context, API server URL, kubeconfig
+  path and server version. It never returns credentials. Replayed, it reports
+  `source="capture"` and when the capture was taken, so an agent can tell replayed
+  evidence from a live cluster.
+- **Captures record their cluster**: the context, server URL and server version
+  are stored in a new optional `cluster` key, which `get_cluster_info` reads on
+  replay. The kubeconfig path is left out: it names a file on the capturing
+  machine. Older captures still load; older readers ignore the key.
+- **`ContainerStateTerminated.ran_for`**: how long a terminated container instance
+  ran (`finished_at - started_at`), as a whole-second duration. It gives the
+  number an agent otherwise has to subtract, and often mixes up with how much
+  time the container's log covers or how often it restarts.
+  `get_pod_container_statuses` documents what it is not.
+- `k8s_tools.Interval`, a duration type for a fixed span between two moments, next
+  to `Duration` (an age). Capture replay advances ages with the replay clock but
+  reads intervals back unchanged.
+
+### Changed
+- **A cluster selection that cannot be loaded is an error.** A given
+  `--kubeconfig`, `--context` or `K8STOOLS_CONTEXT` that fails to load (missing
+  file, misspelled context) stops the MCP server and fails a capture, with the new
+  `K8sClusterSelectionError`. Previously every load failure fell back to in-cluster
+  config, which inside a pod meant silently binding to the pod's own cluster. With
+  no selection, the in-cluster fallback is unchanged, and the server still starts
+  when no configuration can be loaded.
+- **All tools share one cluster binding, made once.** The core, apps and batch API
+  clients used to load the kubeconfig separately, each on first use, so a
+  `kubectl config use-context` between a server's first pod query and its first
+  deployment query left it answering from two clusters. A running server now
+  ignores later changes to the kubeconfig's current context.
+- **k8stools no longer sets the kubernetes client's process-wide default
+  configuration.** Its binding uses a configuration of its own. Python code that
+  relied on k8stools having loaded the kubeconfig for its own kubernetes calls
+  must now load it itself (`kubernetes.config.load_kube_config()`).
+- `--kubeconfig` and `--context` are rejected with `--mock` or `--state-file`,
+  which serve a capture rather than a cluster.
+- `k8s-mcp-client` passes `K8STOOLS_CONTEXT` through to the server it starts, as
+  it already did `KUBECONFIG`.
+
+## 2.0.4 — 2026-09-19
+
+### Fixed
+- **Pod logs arrived as a single unusable `b'...'` line** (issue #6). Since
+  kubernetes 36 the log endpoint's body reaches the client as `bytes`, and the
+  generated client turned it into `repr(bytes)`. Logs are now decoded where the
+  API is called, with invalid bytes replaced rather than failing the call, which
+  fixes the log tools, the Job/CronJob log readers and `k8s-capture-state` at once.
+- Redaction handles `bytes` values explicitly.
+
+### Documentation
+- `previous=True` has three Kubernetes behaviors that look like bugs (identical
+  output during CrashLoopBackOff, a restart shifting the window between calls, and
+  a reclaimed log answering 200 with an error message). They are documented in the
+  tool's description and the README rather than changed.
+
+## 2.0.3 — 2026-09-17
+
+### Fixed
+- **Duration fields failed strict schema validation.** Ages serialized with
+  fractional seconds (`"P2DT5M27.978616S"`), which the `format: "duration"` grammar
+  their own schema declares does not allow, so an MCP client that validates
+  structured output (ajv does) rejected every list tool on every row. Durations are
+  now whole, non-negative seconds (`k8s_tools.Duration`); a cluster clock ahead of
+  ours no longer yields a negative age.
+- **Redaction blacked out whole values.** One secret-shaped substring replaced an
+  entire ConfigMap value, making config-as-JSON unreadable. Tokens (AWS keys, JWTs)
+  are now replaced where they sit. PEM private keys are still removed whole. A value
+  that parses as JSON is searched field by field, which also catches a
+  `{"password": ...}` inside it that was previously missed.
+
+## 2.0.2 — 2026-09-12
+
+Includes the 2.0.1 packaging fix, which was tagged but not published.
+
+### Changed
+- `k8s-mcp-client` always starts the server with the current interpreter
+  (`python -m k8stools.mcp_server`) instead of looking for `k8s-mcp-server` next
+  to `argv[0]`, and no longer prints a leftover debug line.
+- `twine` and `build` dropped from the dev dependencies (uv replaces both).
+
+### Fixed
+- `rich` and `pydantic` are declared as runtime dependencies. `k8s-mcp-client`
+  imported `rich`, which was only a dev dependency, so it failed with
+  `ModuleNotFoundError` on any install from PyPI (2.0.0 and all earlier releases).
+
+## 2.0.1 — 2026-09-12 (tagged, not published)
+
+- The packaging fix listed under 2.0.2.
+
+## 2.0.0 — 2026-09-12
+
+### Added
+- **Mock state capture and replay.** `k8s-capture-state` snapshots a live cluster
+  into one JSON file, and `k8s-mcp-server --state-file FILE` replays it through all
+  19 tools, so agents can be tested against realistic scenarios with no cluster.
+  `--state-time frozen` pins every age for repeatable test suites.
+  Previous-instance logs are captured, and captures can be written and read
+  gzipped. Design: `designs/mock-state-capture.md`.
+
+### Changed (breaking)
+- `mock_tools` serves one captured cluster (the built-in OTel Demo snapshot by
+  default): a pod not in the capture does not exist for any tool, instead of
+  getting a synthesized answer.
+- Redaction's key-name rule matches whole words and exempts a field named exactly
+  `key`, which in the Kubernetes API is always structural. On a real 38-pod cluster
+  this went from 139 redactions to 5, still catching all 3 real secrets.
+
+## 1.2.0 — 2026-09-11
+
+### Added
+- `get_replicaset_summaries`: a Deployment's replica sets, which are its change
+  history, sorted oldest revision first. Filtered to one deployment, the last entry
+  is its current revision, so "when did this last change, and what changed" is one
+  call.
+
+## 1.1.0 — 2026-09-06
+
+Delivered the Priority-1 batch from a heavy RCA user's feature request, plus the
+cross-cutting redaction ask, and upgraded core dependencies.
+
+### Added
+- `get_configmap_summaries` / `get_configmap`: ConfigMap listing and full-content
+  read.
+- `get_cronjob_summaries` / `get_job_summaries`: CronJob and Job spec and status,
+  including the pod template's container images and env; `owner` links a Job back
+  to its CronJob.
+- `get_logs_for_job` / `get_logs_for_cronjob`: find the most recent pod of a Job,
+  or the most recent run of a CronJob, and return its logs.
+- `get_pvc_summaries`: PVC listing with `mounted_by` pod resolution, which surfaces
+  orphaned PVCs.
+- `get_events`: cluster- or namespace-wide events with server-side filtering
+  (`reason`, `involved_kind`, `involved_name`, `event_type`).
+- `get_statefulset_summaries`: StatefulSet summaries mirroring
+  `DeploymentSummary`.
+- `get_logs_for_pod_and_container`: `tail`, `since_seconds` and `previous`
+  (previous-instance logs, for crash-loop analysis).
+- `get_node_summaries`: `capacity`, `allocatable`, `conditions`, `taints`, `labels`.
+- `get_service_summaries`: `selector`, `labels`, `annotations`.
+- **Secret redaction**: one pass at the MCP server's output boundary, on by
+  default, opt-out with `--no-redact` or `K8STOOLS_REDACT=0`. It matches by value
+  shape (AWS keys, JWTs, PEM private keys) and by key/env-var name
+  (`key|secret|token|password|credential`), replacing matches with a visible
+  `[REDACTED]` marker. Direct Python callers get raw values and can call
+  `redaction.redact_object` themselves.
+
+### Changed
+- `mcp` 1.12 → 2.1.1 (FastMCP → MCPServer), `kubernetes` 33.1 → 36.0.3.
+
+## 1.0.1 — 2025-07-29
+
+- README fixes.
+
+## 1.0.0 — 2025-07-28
+
+- First stable release: kubectl-style read-only tools for namespaces, nodes, pods,
+  container statuses, pod events, pod specs, logs, deployments and services, with
+  mock versions, as Python functions or through an MCP server.
+
+## 0.1.0, 0.1.2 — 2025-07-21, 2025-07-23
+
+- Initial releases (0.1.1 was tagged but not published).

{k8stools-2.0.4 → k8stools-2.2.0}/CLAUDE.md

@@ -24,11 +24,21 @@ tests/
   test_capture.py            - Capture serialization round-trip and capture-time redaction
   test_k8s_tools_realk8s.py  - Integration tests (real cluster, auto-skipped if unreachable)
   test_mock_tools.py         - Tests for mock_tools module (incl. parity with k8s_tools.TOOLS)
+  test_events.py             - Event aggregation (count/first_seen), incl. the events.k8s.io fallback
+  test_cluster_binding.py    - Cluster selection: configure(), the shared binding, get_cluster_info, server flags
   test_log_decoding.py       - Log decoding at the API boundary (bytes vs str), `previous` plumbing, log redaction
   test_mcp_client.py         - MCP client tests
   test_version.py            - Asserts pyproject and package __version__ agree
 ```
 
+## Changelog
+
+`CHANGELOG.md` records user-visible changes per release, newest first. Add to the
+top entry (`## X.Y.Z — unreleased` until tagged) in the same change that makes
+them, and call out behavior changes under **Changed**. It links from the README and
+from the package metadata (`[project] urls`), so it shows on PyPI. `docs/ROADMAP.md`
+holds only planned and deferred work.
+
 ## Environment setup
 
 ```bash
@@ -76,6 +86,12 @@ This is the same rule `MockState`'s replay clock already applies, for the same
 reason. `tests/test_duration_format.py` checks each model's serialized output
 against the format its own schema declares.
 
+`Duration` means an *age* (time from some moment until now). For a fixed span
+between two moments — `ContainerStateTerminated.ran_for` — use `k8s_tools.Interval`,
+which has the same normalization and schema. The difference is capture replay:
+`MockState` advances every age by the time since the server started, so a span
+declared as `Duration` grows on replay (a 60s run read back as 1d+60s a day in).
+
 Use snake_case field names. Include `pod_name`/`namespace` in container-level models for context.
 
 All tools are collected in the `TOOLS` list in `k8s_tools.py` for agent/MCP registration.
@@ -109,7 +125,7 @@ raise K8sConfigError("Could not load kube config")   # config/connection problem
 raise K8sApiError(f"Error fetching pods: {e}")        # API operation failures
 ```
 
-## Global API client
+## Cluster binding and the global API clients
 
 Lazy singleton initialization pattern used throughout:
 
@@ -119,7 +135,33 @@ if K8S is None:
     K8S = _get_api_client()
 ```
 
-`_get_api_client()` calls `config.load_kube_config()`, which respects the `KUBECONFIG` environment variable.
+`_get_api_client()`, `_get_apps_v1_api_client()` and `_get_batch_v1_api_client()`
+all build on **one** `ApiClient`, the process's cluster binding (`_BINDING`),
+resolved once by `configure(kubeconfig, context)` — called at startup by both CLIs —
+or lazily on first use. Invariants:
+
+- **One binding for every API group.** The helpers used to load the kubeconfig
+  separately on each group's first use, and each API object snapshots the global
+  default `Configuration` when constructed, so a `kubectl config use-context`
+  between a server's first pod query and its first deployment query split it
+  across two clusters. Don't reintroduce a per-helper `load_kube_config()`.
+- **An explicit selection never falls back to in-cluster config.** The client
+  raises the same `ConfigException` for a misspelled context as for a missing
+  kubeconfig; falling back would bind a server in a pod to the pod's own cluster.
+  An explicit selection that fails raises `K8sClusterSelectionError` (a
+  `K8sConfigError`), which stops the MCP server; with no selection, the server
+  starts anyway and each call reports the problem, as it always has.
+- **The binding never touches the process-wide default `Configuration`** (it passes
+  `client_configuration`), so library callers' own kubernetes clients are left alone.
+- Resolution: `--kubeconfig` / argument, then `KUBECONFIG`, then `~/.kube/config`;
+  `--context` / argument, then `K8STOOLS_CONTEXT`, then `current-context`. There is
+  deliberately no `K8STOOLS_KUBECONFIG`: `KUBECONFIG` already is that variable.
+  The kubernetes client reads `KUBECONFIG` once, at import
+  (`KUBE_CONFIG_DEFAULT_LOCATION`), so setting it at runtime has no effect.
+
+`get_cluster_info` reports the binding. Its replay counterpart answers from the
+capture's optional top-level `cluster` record (context, server, server version —
+never the kubeconfig path) with `source="capture"`.
 
 ## Using tools directly in an agent
 
@@ -145,6 +187,10 @@ k8s-mcp-server --mock
 k8s-mcp-server --state-file incident-1234.json
 k8s-mcp-server --state-file incident-1234.json --state-time frozen
 
+# Pin a cluster (default: KUBECONFIG / ~/.kube/config and its current-context)
+k8s-mcp-server --kubeconfig ~/.kube/prod.yaml --context prod-eu
+K8STOOLS_CONTEXT=prod-eu k8s-mcp-server
+
 # Disable secret redaction (on by default)
 k8s-mcp-server --no-redact
 ```
@@ -168,6 +214,16 @@ Invariants worth preserving when touching this code:
   replay — "deployment 8d old, current replica set 7h34m old, so it was upgraded
   7h34m ago". The replay clock quantizes to whole seconds and samples once per
   query to keep that exact; don't reintroduce per-field `datetime.now()`.
+  One clock for everything replay returns: datetimes are re-anchored so
+  capture time becomes server start time, and that includes
+  `get_cluster_info().captured_at` (the anchor itself) and the kubelet's
+  timestamp prefix on each log line (`_reanchor_log`). Anything that reports a
+  time from the file verbatim contradicts the rest. Tests that capture and
+  replay at the same instant cannot see this; use a capture date in the past.
+  Only ages advance: an `Interval` field is stored under the same `_seconds` key
+  but read back unchanged. Replay tests that freeze the clock can't tell the two
+  apart (frozen elapsed time is zero), so test a new duration field on an
+  advancing clock with a `server_start_time` in the past.
 - **`MockState` must match the real tool's documented behavior**, not just its
   types — filter semantics, result ordering (`get_replicaset_summaries` re-sorts
   at query time), and which failures raise vs. return empty.

{k8stools-2.0.4 → k8stools-2.2.0}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.5
 Name: k8stools
-Version: 2.0.4
+Version: 2.2.0
 Summary: Tools and an MCP server for building Kubernetes agents
 Project-URL: Homepage, https://github.com/BenedatLLC/k8stools
+Project-URL: Changelog, https://github.com/BenedatLLC/k8stools/blob/main/CHANGELOG.md
 Author: Jeff Fischer
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -273,10 +274,14 @@ This installs three commands: `k8s-mcp-server` (the MCP server), `k8s-mcp-client
 (a client for manual testing), and `k8s-capture-state` (snapshot a cluster to a
 replayable file).
 
+What changed in each release is in the
+[changelog](https://github.com/BenedatLLC/k8stools/blob/main/CHANGELOG.md).
+
 ## Current tools
 
 These are the tools we define:
 
+* `get_cluster_info` - which cluster the tools are answering from: kubeconfig context, API server URL and version, or the capture being replayed
 * `get_namespaces` - get a list of namespaces, like `kubectl get namespace`
 * `get_node_summaries` - get a list of nodes, like `kubectl get nodes -o wide` (includes capacity/allocatable/conditions/taints/labels)
 * `get_pod_summaries` - get a list of pods, like `kubectl get pods -o wide`
@@ -333,13 +338,25 @@ result = agent.run_sync("What is the status of the pods in my cluster?")
 print(result.output)
 ```
 
+The tools use `KUBECONFIG` (or `~/.kube/config`) and its current context. To pin a
+cluster instead, call `configure` before the first tool call:
+
+```python
+from k8stools import k8s_tools
+
+k8s_tools.configure(kubeconfig="~/.kube/prod.yaml", context="prod-eu")
+```
+
+See [Selecting a cluster](#selecting-a-cluster) for how the selection is resolved.
+
 ### Using via MCP
 The script `k8s-mcp-server` provides an MCP server for the same set of tools.
 Here are the command line arguments for the server:
 ```
 usage: k8s-mcp-server [-h] [--transport {streamable-http,stdio}] [--host HOST] [--port PORT]
-                      [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--debug] [--mock]
-                      [--state-file FILE] [--state-time {advancing,frozen}] [--no-redact]
+                      [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--debug]
+                      [--kubeconfig PATH] [--context NAME] [--mock] [--state-file FILE]
+                      [--state-time {advancing,frozen}] [--no-redact]
 
 Run the MCP server.
 
@@ -352,6 +369,11 @@ options:
   --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                         Log level [default: INFO]
   --debug               Enable debug mode [default: False]
+  --kubeconfig PATH     Kubeconfig file to use [default: KUBECONFIG, then ~/.kube/config]
+  --context NAME        Kubeconfig context to use [default: K8STOOLS_CONTEXT, then the
+                        kubeconfig's current-context]. A kubeconfig or context that is given but
+                        cannot be loaded stops the server rather than falling back to another
+                        cluster.
   --mock                Run mock versions of the tools that don't need a cluster
   --state-file FILE     Serve a captured cluster snapshot from FILE (implies --mock)
   --state-time {advancing,frozen}
@@ -359,6 +381,48 @@ options:
   --no-redact           Disable secret redaction of tool output (on by default)
 ```
 
+#### Selecting a cluster
+
+Each server answers from exactly one cluster, chosen at startup:
+
+| | Kubeconfig file | Context |
+|---|---|---|
+| 1st | `--kubeconfig PATH` | `--context NAME` |
+| 2nd | `KUBECONFIG` | `K8STOOLS_CONTEXT` |
+| 3rd | `~/.kube/config` | the file's `current-context` |
+
+With none of these given and no usable kubeconfig, the server falls back to the
+in-cluster service account, as when it runs in a pod.
+
+The server logs the binding when it starts:
+
+```
+WARNING:root:Bound to cluster: context 'prod-eu' at https://prod-eu.example:6443 (kubeconfig: /home/me/.kube/prod.yaml)
+```
+
+and the `get_cluster_info` tool reports it to an agent, so an agent can check which
+cluster it is talking to without leaving MCP.
+
+A few rules keep a server from quietly answering from the wrong cluster:
+
+* **An explicit selection never falls back.** If a `--kubeconfig`, `--context` or
+  `K8STOOLS_CONTEXT` is given but cannot be loaded (a missing file, a misspelled
+  context), the server exits with an error. It does not fall back to in-cluster
+  config, which in a pod would silently mean *that pod's* cluster.
+* **The binding is made once.** Every tool shares it, and it does not follow later
+  changes to the kubeconfig: running `kubectl config use-context` does not
+  repoint a server that is already running.
+* **`--kubeconfig` and `--context` are rejected with `--mock` or `--state-file`**,
+  which serve a capture rather than a cluster.
+
+To serve two clusters, run two servers:
+
+```sh
+k8s-mcp-server --transport=streamable-http --port=8001 --context prod-eu
+k8s-mcp-server --transport=streamable-http --port=8002 \
+    --kubeconfig ~/.kube/eks.yaml --context staging
+```
+
 #### Use MCP with the stdio transport
 The *stdio* transport is best for use with local Coding Agents, like GitHub CoPilot or Cursor.
 It is the default, so you can run the `k8s-mcp-server` script without arguments. Here's an example
@@ -381,7 +445,8 @@ This assumes the following:
 1. The Python virtual environment is expected to be in `.venv` under the root of your VSCode workspace
 2. You have installed the k8stools package into your workspace
 3. The environment file `.envrc` contains any variables you need defined. In particular, you may need to
-   set `KUBECONFIG` to point to your `kubectl` config file.
+   set `KUBECONFIG` to point to your `kubectl` config file, and `K8STOOLS_CONTEXT` to pin a context
+   (or pass `--kubeconfig` / `--context` in `args`).
 
 #### Use MCP with the streamable HTTP transport
 The *streamable http* transport is enabled with the command line option `--transport=streamable-http`. It will
@@ -466,7 +531,8 @@ k8s-mcp-server --state-file incident-1234.json
 ### `k8s-capture-state` options
 
 ```
-usage: k8s-capture-state [-h] [--namespace NS [NS ...]] [-o FILE] [--no-logs]
+usage: k8s-capture-state [-h] [--namespace NS [NS ...]] [-o FILE]
+                         [--kubeconfig PATH] [--context NAME] [--no-logs]
                          [--max-log-lines MAX_LOG_LINES] [--no-previous-logs]
                          [--no-redact]
                          [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
@@ -479,6 +545,11 @@ options:
                         captured in full.
   -o FILE, --output FILE
                         Output file [default: k8s-state-<timestamp>.json]
+  --kubeconfig PATH     Kubeconfig file to capture from [default: KUBECONFIG,
+                        then ~/.kube/config]
+  --context NAME        Kubeconfig context to capture from [default:
+                        K8STOOLS_CONTEXT, then the kubeconfig's current-
+                        context]
   --no-logs             Skip container logs
   --max-log-lines MAX_LOG_LINES
                         Log lines to capture per container [default: 1000]
@@ -507,11 +578,16 @@ Everything the tools can read, so that every tool answers on replay:
 
 | | |
 |---|---|
+| Cluster | context name, API server URL and version, so `get_cluster_info` answers on replay (not the kubeconfig path, which names a file on the capturing machine) |
 | Cluster-wide | namespaces, nodes |
 | Per namespace | deployments, replica sets, services, statefulsets, cronjobs, jobs, PVCs, events |
 | ConfigMaps | summary **and** full contents, so `get_configmap` works too |
 | Per pod | summary, labels, container statuses, spec, and per-container logs |
 
+A cluster is selected exactly as for the MCP server (see [Selecting a
+cluster](#selecting-a-cluster)), and a selection that cannot be loaded fails the
+capture.
+
 `--namespace` restricts only the namespaced resources; namespaces and nodes are
 always captured in full so the cluster still makes sense.
 
@@ -608,6 +684,15 @@ long session cannot see ages drift between its first tool call and its last.
 a suite that believed it had frozen the clock and had not would be flaky with no
 visible cause.)
 
+Absolute times are replayed the same way: every timestamp a tool returns is moved
+so the moment of capture becomes the moment the server started. A container killed
+5 minutes before the capture reads as killed 5 minutes before server start, and
+`get_cluster_info`'s `captured_at` is that start time, not the date in the file,
+so the agent sees one consistent clock. Log line timestamps (the kubelet's
+prefix) are moved too, so `since_seconds` works on a capture of any age;
+timestamps an application writes inside its own log messages are left as
+recorded. The file's own capture date is in the server's startup log.
+
 ### Replaying from Python
 
 For a test suite, skip the server and load the capture directly. `MockState` has

{k8stools-2.0.4 → k8stools-2.2.0}/README.md

@@ -54,10 +54,14 @@ This installs three commands: `k8s-mcp-server` (the MCP server), `k8s-mcp-client
 (a client for manual testing), and `k8s-capture-state` (snapshot a cluster to a
 replayable file).
 
+What changed in each release is in the
+[changelog](https://github.com/BenedatLLC/k8stools/blob/main/CHANGELOG.md).
+
 ## Current tools
 
 These are the tools we define:
 
+* `get_cluster_info` - which cluster the tools are answering from: kubeconfig context, API server URL and version, or the capture being replayed
 * `get_namespaces` - get a list of namespaces, like `kubectl get namespace`
 * `get_node_summaries` - get a list of nodes, like `kubectl get nodes -o wide` (includes capacity/allocatable/conditions/taints/labels)
 * `get_pod_summaries` - get a list of pods, like `kubectl get pods -o wide`
@@ -114,13 +118,25 @@ result = agent.run_sync("What is the status of the pods in my cluster?")
 print(result.output)
 ```
 
+The tools use `KUBECONFIG` (or `~/.kube/config`) and its current context. To pin a
+cluster instead, call `configure` before the first tool call:
+
+```python
+from k8stools import k8s_tools
+
+k8s_tools.configure(kubeconfig="~/.kube/prod.yaml", context="prod-eu")
+```
+
+See [Selecting a cluster](#selecting-a-cluster) for how the selection is resolved.
+
 ### Using via MCP
 The script `k8s-mcp-server` provides an MCP server for the same set of tools.
 Here are the command line arguments for the server:
 ```
 usage: k8s-mcp-server [-h] [--transport {streamable-http,stdio}] [--host HOST] [--port PORT]
-                      [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--debug] [--mock]
-                      [--state-file FILE] [--state-time {advancing,frozen}] [--no-redact]
+                      [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--debug]
+                      [--kubeconfig PATH] [--context NAME] [--mock] [--state-file FILE]
+                      [--state-time {advancing,frozen}] [--no-redact]
 
 Run the MCP server.
 
@@ -133,6 +149,11 @@ options:
   --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                         Log level [default: INFO]
   --debug               Enable debug mode [default: False]
+  --kubeconfig PATH     Kubeconfig file to use [default: KUBECONFIG, then ~/.kube/config]
+  --context NAME        Kubeconfig context to use [default: K8STOOLS_CONTEXT, then the
+                        kubeconfig's current-context]. A kubeconfig or context that is given but
+                        cannot be loaded stops the server rather than falling back to another
+                        cluster.
   --mock                Run mock versions of the tools that don't need a cluster
   --state-file FILE     Serve a captured cluster snapshot from FILE (implies --mock)
   --state-time {advancing,frozen}
@@ -140,6 +161,48 @@ options:
   --no-redact           Disable secret redaction of tool output (on by default)
 ```
 
+#### Selecting a cluster
+
+Each server answers from exactly one cluster, chosen at startup:
+
+| | Kubeconfig file | Context |
+|---|---|---|
+| 1st | `--kubeconfig PATH` | `--context NAME` |
+| 2nd | `KUBECONFIG` | `K8STOOLS_CONTEXT` |
+| 3rd | `~/.kube/config` | the file's `current-context` |
+
+With none of these given and no usable kubeconfig, the server falls back to the
+in-cluster service account, as when it runs in a pod.
+
+The server logs the binding when it starts:
+
+```
+WARNING:root:Bound to cluster: context 'prod-eu' at https://prod-eu.example:6443 (kubeconfig: /home/me/.kube/prod.yaml)
+```
+
+and the `get_cluster_info` tool reports it to an agent, so an agent can check which
+cluster it is talking to without leaving MCP.
+
+A few rules keep a server from quietly answering from the wrong cluster:
+
+* **An explicit selection never falls back.** If a `--kubeconfig`, `--context` or
+  `K8STOOLS_CONTEXT` is given but cannot be loaded (a missing file, a misspelled
+  context), the server exits with an error. It does not fall back to in-cluster
+  config, which in a pod would silently mean *that pod's* cluster.
+* **The binding is made once.** Every tool shares it, and it does not follow later
+  changes to the kubeconfig: running `kubectl config use-context` does not
+  repoint a server that is already running.
+* **`--kubeconfig` and `--context` are rejected with `--mock` or `--state-file`**,
+  which serve a capture rather than a cluster.
+
+To serve two clusters, run two servers:
+
+```sh
+k8s-mcp-server --transport=streamable-http --port=8001 --context prod-eu
+k8s-mcp-server --transport=streamable-http --port=8002 \
+    --kubeconfig ~/.kube/eks.yaml --context staging
+```
+
 #### Use MCP with the stdio transport
 The *stdio* transport is best for use with local Coding Agents, like GitHub CoPilot or Cursor.
 It is the default, so you can run the `k8s-mcp-server` script without arguments. Here's an example
@@ -162,7 +225,8 @@ This assumes the following:
 1. The Python virtual environment is expected to be in `.venv` under the root of your VSCode workspace
 2. You have installed the k8stools package into your workspace
 3. The environment file `.envrc` contains any variables you need defined. In particular, you may need to
-   set `KUBECONFIG` to point to your `kubectl` config file.
+   set `KUBECONFIG` to point to your `kubectl` config file, and `K8STOOLS_CONTEXT` to pin a context
+   (or pass `--kubeconfig` / `--context` in `args`).
 
 #### Use MCP with the streamable HTTP transport
 The *streamable http* transport is enabled with the command line option `--transport=streamable-http`. It will
@@ -247,7 +311,8 @@ k8s-mcp-server --state-file incident-1234.json
 ### `k8s-capture-state` options
 
 ```
-usage: k8s-capture-state [-h] [--namespace NS [NS ...]] [-o FILE] [--no-logs]
+usage: k8s-capture-state [-h] [--namespace NS [NS ...]] [-o FILE]
+                         [--kubeconfig PATH] [--context NAME] [--no-logs]
                          [--max-log-lines MAX_LOG_LINES] [--no-previous-logs]
                          [--no-redact]
                          [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
@@ -260,6 +325,11 @@ options:
                         captured in full.
   -o FILE, --output FILE
                         Output file [default: k8s-state-<timestamp>.json]
+  --kubeconfig PATH     Kubeconfig file to capture from [default: KUBECONFIG,
+                        then ~/.kube/config]
+  --context NAME        Kubeconfig context to capture from [default:
+                        K8STOOLS_CONTEXT, then the kubeconfig's current-
+                        context]
   --no-logs             Skip container logs
   --max-log-lines MAX_LOG_LINES
                         Log lines to capture per container [default: 1000]
@@ -288,11 +358,16 @@ Everything the tools can read, so that every tool answers on replay:
 
 | | |
 |---|---|
+| Cluster | context name, API server URL and version, so `get_cluster_info` answers on replay (not the kubeconfig path, which names a file on the capturing machine) |
 | Cluster-wide | namespaces, nodes |
 | Per namespace | deployments, replica sets, services, statefulsets, cronjobs, jobs, PVCs, events |
 | ConfigMaps | summary **and** full contents, so `get_configmap` works too |
 | Per pod | summary, labels, container statuses, spec, and per-container logs |
 
+A cluster is selected exactly as for the MCP server (see [Selecting a
+cluster](#selecting-a-cluster)), and a selection that cannot be loaded fails the
+capture.
+
 `--namespace` restricts only the namespaced resources; namespaces and nodes are
 always captured in full so the cluster still makes sense.
 
@@ -389,6 +464,15 @@ long session cannot see ages drift between its first tool call and its last.
 a suite that believed it had frozen the clock and had not would be flaky with no
 visible cause.)
 
+Absolute times are replayed the same way: every timestamp a tool returns is moved
+so the moment of capture becomes the moment the server started. A container killed
+5 minutes before the capture reads as killed 5 minutes before server start, and
+`get_cluster_info`'s `captured_at` is that start time, not the date in the file,
+so the agent sees one consistent clock. Log line timestamps (the kubelet's
+prefix) are moved too, so `since_seconds` works on a capture of any age;
+timestamps an application writes inside its own log messages are left as
+recorded. The file's own capture date is in the server's startup log.
+
 ### Replaying from Python
 
 For a test suite, skip the server and load the capture directly. `MockState` has