# clusterport

clusterport is a small MCP server and CLI for core Kubernetes work.
It is a clean-room rebuild of a core subset — twelve tools — from
the documented surface of the community Flux159
mcp-server-kubernetes: get, describe and fetch logs; apply and
create; delete, scale and patch; rollout actions and context
switching; plus `kubectl explain` and API-resource listing.

Everything runs through the host's real `kubectl`. Each call is
built as an argument array and spawned directly — never a shell
string — so resource names, namespaces and patches cannot be
reinterpreted as shell syntax. Manifests are never written to temp
files or shell redirects: `kubectl_apply` sends its manifest over
stdin (`kubectl apply -f -`), and `kubectl_create` generates a
minimal manifest spec from its parameters and creates it from stdin
the same way (`kubectl create -f -`). The executor is injectable,
which is how the test suite verifies the exact argument arrays and
stdin payloads with a fake.

Deliberately omitted: port-forward long-lived sessions,
exec-into-pod, the helm tools, install/uninstall addon operations,
non-resource URL operations, watch/streaming, and node operations
such as cordon, taint or drain.

The host needs a working `kubectl` and cluster credentials. When
kubectl is absent, calls fail honestly with the underlying spawn
error (ENOENT) instead of a fabricated result. The published
container image bundles no kubectl binary: it expects a host
executor and says so in its Dockerfile.

## Install

```bash
npx @reneturcios/clusterport kubectl-get pods -n default
docker run -i ghcr.io/cloudcorprecords/clusterport
```

## CLI

```bash
clusterport kubectl-get <resource_type> [name] [-n namespace] [-o format]
clusterport kubectl-describe <resource_type> <name> [-n namespace]
clusterport kubectl-logs <name> [-n namespace] [-c container]
clusterport kubectl-apply "<manifest yaml>" [-n namespace] [--dry-run]
clusterport kubectl-create <resource_type> <name> [--image img] [-n namespace]
clusterport kubectl-delete <resource_type> <name> [-n namespace]
clusterport kubectl-scale <resource_type> <name> <replicas> [-n namespace]
clusterport kubectl-patch <resource_type> <name> '<json patch>' [-n namespace]
clusterport kubectl-rollout <resource_type> <name> <action> [-n namespace]
clusterport kubectl-context <current|list|use> [name]
clusterport explain-resource <resource> [--api-version v]
clusterport list-api-resources [kind]
clusterport --version
```

Exit codes: `0` success, `1` kubectl error, `2` usage error.

## MCP server

```bash
npx -y @reneturcios/clusterport mcp
```

```json
{
  "mcpServers": {
    "clusterport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/clusterport", "mcp"]
    }
  }
}
```

### Tools

| Tool | Input | What it does |
| --- | --- | --- |
| `kubectl_get` | `resource_type` (required), `name`, `namespace`, `output_format` | `kubectl get -o json` by default; JSON parsed. |
| `kubectl_describe` | `resource_type`, `name` (required), `namespace` | `kubectl describe`. |
| `kubectl_logs` | `name` (required), `namespace`, `container` | `kubectl logs`. |
| `kubectl_apply` | `manifest` (required), `namespace`, `dry_run` | `kubectl apply -f -`, manifest over stdin. |
| `kubectl_create` | `resource_type`, `name` (required), `namespace`, `image` | Generated spec created via `kubectl create -f -` over stdin. |
| `kubectl_delete` | `resource_type`, `name` (required), `namespace` | `kubectl delete`. |
| `kubectl_scale` | `resource_type`, `name`, `replicas` (required), `namespace` | `kubectl scale --replicas=n`. |
| `kubectl_patch` | `resource_type`, `name`, `patch` (required), `namespace` | `kubectl patch -p`. |
| `kubectl_rollout` | `resource_type`, `name`, `action` (required), `namespace` | `kubectl rollout <action> <type>/<name>`. |
| `kubectl_context` | `operation` (required: current, list, use), `name` | `kubectl config` current/get/use-context. |
| `explain_resource` | `resource` (required), `api_version` | `kubectl explain`. |
| `list_api_resources` | `kind` (optional) | `kubectl api-resources`, parsed, kind-filtered. |

Executor failures — a missing kubectl binary, an unreachable
cluster, a nonexistent resource — are reported as tool errors
carrying the underlying message.

## Development

```bash
npm install
npm run build
npm test
npm run dev
```

Tests run entirely on a fake executor: exact argument arrays, stdin
manifest passing for apply/create, output parsing, and error
propagation. No live cluster is touched.

## License

MIT — see `LICENSE`.