NO-JIRA: Sync downstream

.github/workflows/release.yaml

@@ -12,11 +12,11 @@ concurrency:
 
 env:
   GO_VERSION: 1.23
-  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
   UV_PUBLISH_TOKEN: ${{ secrets.UV_PUBLISH_TOKEN }}
 
 permissions:
   contents: write
+  id-token: write  # Required for npmjs OIDC
   discussions: write
 
 jobs:
@@ -39,6 +39,12 @@ jobs:
           files: |
             LICENSE
             kubernetes-mcp-server-*
+      # Ensure npm 11.5.1 or later is installed (required for https://docs.npmjs.com/trusted-publishers)
+      - name: Setup node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          registry-url: 'https://registry.npmjs.org'
       - name: Publish npm
         run:
           make npm-publish

AGENTS.md

@@ -11,12 +11,15 @@ This MCP server enables AI assistants (like Claude, Gemini, Cursor, and others)
 - 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.
+    - `api/` - API-related functionality, tool definitions, and toolset interfaces.
     - `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.
+    - `toolsets/` - Toolset registration and management for MCP tools.
+    - `version/` - Version information management.
 - `.github/` – GitHub-related configuration (Actions workflows, issue templates...).
 - `docs/` – documentation files.
 - `npm/` – Node packages that wraps the compiled binaries for distribution through npmjs.com.
@@ -30,6 +33,21 @@ Implement new functionality in the Go sources under `cmd/` and `pkg/`.
 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.
 
+### Adding new MCP tools
+
+The project uses a toolset-based architecture for organizing MCP tools:
+
+- **Tool definitions** are created in `pkg/api/` using the `ServerTool` struct.
+- **Toolsets** group related tools together (e.g., config tools, core Kubernetes tools, Helm tools).
+- **Registration** happens in `pkg/toolsets/` where toolsets are registered at initialization.
+- Each toolset lives in its own subdirectory under `pkg/toolsets/` (e.g., `pkg/toolsets/config/`, `pkg/toolsets/core/`, `pkg/toolsets/helm/`).
+
+When adding a new tool:
+1. Define the tool handler function that implements the tool's logic.
+2. Create a `ServerTool` struct with the tool definition and handler.
+3. Add the tool to an appropriate toolset (or create a new toolset if needed).
+4. Register the toolset in `pkg/toolsets/` if it's a new toolset.
+
 ## Building
 
 Use the provided Makefile targets:
@@ -105,6 +123,45 @@ make lint
 
 The `lint` target downloads the specified `golangci-lint` version if it is not already present under `_output/tools/bin/`.
 
+## Additional Makefile targets
+
+Beyond the basic build, test, and lint targets, the Makefile provides additional utilities:
+
+**Local Development:**
+```bash
+# Setup a complete local development environment with Kind cluster
+make local-env-setup
+
+# Tear down the local Kind cluster
+make local-env-teardown
+
+# Show Keycloak status and connection info (for OIDC testing)
+make keycloak-status
+
+# Tail Keycloak logs
+make keycloak-logs
+
+# Install required development tools (like Kind) to ./_output/bin/
+make tools
+```
+
+**Distribution and Publishing:**
+```bash
+# Copy compiled binaries to each npm package
+make npm-copy-binaries
+
+# Publish the npm packages
+make npm-publish
+
+# Publish the Python packages
+make python-publish
+
+# Update README.md with the latest toolsets
+make update-readme-tools
+```
+
+Run `make help` to see all available targets with descriptions.
+
 ## Dependencies
 
 When introducing new modules run `make tidy` so that `go.mod` and `go.sum` remain tidy.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

Makefile

@@ -16,7 +16,7 @@ LD_FLAGS = -s -w \
 COMMON_BUILD_ARGS = -ldflags "$(LD_FLAGS)"
 
 GOLANGCI_LINT = $(shell pwd)/_output/tools/bin/golangci-lint
-GOLANGCI_LINT_VERSION ?= v2.2.2
+GOLANGCI_LINT_VERSION ?= v2.5.0
 
 # NPM version should not append the -dirty flag
 NPM_VERSION ?= $(shell echo $(shell git describe --tags --always) | sed 's/^v//')
@@ -71,16 +71,14 @@ npm-publish: npm-copy-binaries ## Publish the npm packages
 	$(foreach os,$(OSES),$(foreach arch,$(ARCHS), \
 		DIRNAME="$(BINARY_NAME)-$(os)-$(arch)"; \
 		cd npm/$$DIRNAME; \
-		echo '//registry.npmjs.org/:_authToken=$(NPM_TOKEN)' >> .npmrc; \
 		jq '.version = "$(NPM_VERSION)"' package.json > tmp.json && mv tmp.json package.json; \
-		npm publish; \
+		npm publish --tag latest; \
 		cd ../..; \
 	))
 	cp README.md LICENSE ./npm/kubernetes-mcp-server/
-	echo '//registry.npmjs.org/:_authToken=$(NPM_TOKEN)' >> ./npm/kubernetes-mcp-server/.npmrc
 	jq '.version = "$(NPM_VERSION)"' ./npm/kubernetes-mcp-server/package.json > tmp.json && mv tmp.json ./npm/kubernetes-mcp-server/package.json; \
 	jq '.optionalDependencies |= with_entries(.value = "$(NPM_VERSION)")' ./npm/kubernetes-mcp-server/package.json > tmp.json && mv tmp.json ./npm/kubernetes-mcp-server/package.json; \
-	cd npm/kubernetes-mcp-server && npm publish
+	cd npm/kubernetes-mcp-server && npm publish --tag latest
 
 .PHONY: python-publish
 python-publish: ## Publish the python packages
@@ -115,3 +113,43 @@ lint: golangci-lint ## Lint the code
 .PHONY: update-readme-tools
 update-readme-tools: ## Update the README.md file with the latest toolsets
 	go run ./internal/tools/update-readme/main.go README.md
+
+##@ Tools
+
+.PHONY: tools
+tools: ## Install all required tools (kind) to ./_output/bin/
+	@echo "Checking and installing required tools to ./_output/bin/ ..."
+	@if [ -f _output/bin/kind ]; then echo "[OK] kind already installed"; else echo "Installing kind..."; $(MAKE) -s kind; fi
+	@echo "All tools ready!"
+
+##@ Local Development
+
+.PHONY: local-env-setup
+local-env-setup: ## Setup complete local development environment with Kind cluster
+	@echo "========================================="
+	@echo "Kubernetes MCP Server - Local Setup"
+	@echo "========================================="
+	$(MAKE) tools
+	$(MAKE) kind-create-cluster
+	$(MAKE) keycloak-install
+	$(MAKE) build
+	@echo ""
+	@echo "========================================="
+	@echo "Local environment ready!"
+	@echo "========================================="
+	@echo ""
+	@echo "Configuration file generated:"
+	@echo "  _output/config.toml"
+	@echo ""
+	@echo "Run the MCP server with:"
+	@echo "  ./$(BINARY_NAME) --port 8008 --config _output/config.toml"
+	@echo ""
+	@echo "Or run with MCP inspector:"
+	@echo "  npx @modelcontextprotocol/inspector@latest \$$(pwd)/$(BINARY_NAME) --config _output/config.toml"
+
+.PHONY: local-env-teardown
+local-env-teardown: ## Tear down the local Kind cluster
+	$(MAKE) kind-delete-cluster
+
+# Include build configuration files
+-include build/*.mk