MCP Server Kubernetes Release Process and npm Publication Guide

The MCP server for Kubernetes publishes to npm automatically when you push a git tag matching the v* pattern, triggering a CI/CD pipeline that runs integration tests, bumps versions, builds the bundle, and deploys to multiple registries.

The flux159/mcp-server-kubernetes repository automates its entire release workflow through GitHub Actions. When maintainers push a semver tag, the pipeline in .github/workflows/cd.yml handles testing, versioning, building, and publishing to npm without manual intervention.

Automated Release Trigger

Pushing a git tag that follows the v{major}.{minor}.{patch} semver pattern automatically initiates the release process. The workflow defined in .github/workflows/cd.yml listens for these tags via the on: push: tags: - v* trigger condition.

CI/CD Pipeline Execution Flow

The continuous deployment pipeline executes nine distinct stages to ensure quality and distribution across multiple platforms.

1. Integration Testing in Minikube

Before any publication occurs, the workflow validates the codebase against a live Kubernetes environment. The pipeline installs dependencies, configures Minikube, starts a kubectl proxy, and executes the full test suite using bun run test. This step ensures the MCP server functions correctly against real cluster APIs.

2. Automated Version Bumping

The workflow uses the reecetech/version-increment GitHub Action to calculate the next patch version automatically. It exposes the new version as steps.version.outputs.current-version, eliminating manual version string updates in package.json.

3. Cross-Repository Version Synchronization

The npm run version:update command executes a helper script at scripts/update-version.js that propagates the new version across all relevant files. This updates package.json, manifest.json, CITATION.cff, README.md, and gemini-extension.json to maintain consistency throughout the repository.

4. Production Build Compilation

The bun run build command compiles TypeScript source code into the dist/ directory, creating the production-ready bundle required for npm distribution.

5. npm Registry Publication with Provenance

Node.js 20 is configured in the environment, npm is upgraded to the latest version, and the package is published using npm publish --provenance. This command uploads the MCP server to the npm registry with cryptographic provenance metadata, enhancing supply chain security.

6. Helm Chart Distribution

The pipeline rewrites version fields in helm-chart/Chart.yaml, packages the Helm chart, and pushes it to the GitHub Container Registry (GHCR). This makes the Kubernetes deployment manifests available at ghcr.io synchronized with the npm release.

7. Container Image and Release Assets

Using Docker Buildx, the workflow builds multi-architecture images and pushes them to Docker Hub with both latest and version-specific tags. Simultaneously, it generates the mcp-server-kubernetes.mcpb bundle via bun run buildmcpb and uploads this artifact alongside a source zip archive to the corresponding GitHub Release page.

Manual Release Initiation

While fully automated, maintainers can manually trigger the pipeline by creating and pushing a local tag.

# Ensure you are on the main branch with latest changes

git checkout main
git pull origin main

# Create a semver tag (the workflow handles patch increments)

git tag v2.6.0

# Push the tag to trigger the CD pipeline

git push origin v2.6.0

After pushing, monitor the execution status in the GitHub Actions tab under the cd workflow. The pipeline requires no further interaction to complete the npm publication and asset distribution.

Critical Source Files

Several files define and support the release architecture:

• .github/workflows/cd.yml — The complete CI/CD definition orchestrating tests, version bumps, builds, npm publishing, Helm packaging, Docker builds, and asset uploads.
• scripts/update-version.js — Node.js helper invoked by npm run version:update to synchronize version strings across multiple repository files.
• package.json — Contains npm package metadata and serves as the source of truth for the published version.
• helm-chart/Chart.yaml — Helm chart definition updated automatically during the release process to match the npm version.
• Dockerfile — Multi-stage build instructions used by Docker Buildx to create the container images published to Docker Hub.

Summary

• Tag-based automation: Pushing a v* tag triggers the entire release pipeline defined in .github/workflows/cd.yml.
• Zero-touch versioning: The reecetech/version-increment action and scripts/update-version.js handle all version string updates automatically.
• Multi-registry deployment: Each release publishes to npm with provenance, pushes Helm charts to GHCR, uploads Docker images to Docker Hub, and attaches assets to GitHub Releases.
• Quality gating: Minikube integration tests run before any publication occurs, preventing broken releases from reaching the npm registry.

Frequently Asked Questions

What version format should I use when creating a release tag?

Use semantic versioning prefixed with the letter v, such as v2.6.0 or v1.0.0-beta.1. The workflow trigger specifically matches the pattern v* in .github/workflows/cd.yml. The pipeline automatically handles patch increments and cross-file version synchronization once the tag is pushed.

Does the workflow require manual version updates in package.json before tagging?

No. The reecetech/version-increment GitHub Action calculates the next version automatically when the workflow runs. The npm run version:update script then propagates this version to package.json, manifest.json, and other configuration files. You only need to push the initial tag; the system handles the rest.

How does the MCP server publish to npm with provenance metadata?

The pipeline executes npm publish --provenance using Node.js 20 after upgrading npm to the latest version. This flag generates cryptographic attestations linking the package to its source repository and build process, which are stored alongside the package in the npm registry for enhanced supply chain verification.

Can I publish to npm manually without using the GitHub Actions workflow?

While technically possible for repository maintainers with npm credentials, the repository is designed for tag-triggered automation. Manual publication would bypass the Minikube testing, version synchronization, and multi-registry distribution (Helm, Docker) that the .github/workflows/cd.yml pipeline provides. Using the automated process ensures consistency across all distribution channels.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}