[RELEASE] Publish MCP server to the official Model Context Protocol registry

[manusa]

Description

Register and publish the kubernetes-mcp-server to the official Model Context Protocol registry. This will increase discoverability and provide a standardized way for users to find and install the MCP server.

Background

The MCP Registry is the official registry for Model Context Protocol servers. Publishing to this registry requires:

1. Package metadata updates (npm and Python)
2. A server.json manifest file
3. GitHub Actions workflow to automate publishing on releases

Requirements

1. npm Package Metadata Update

Modify build/node.mk to add the mcpName field to the generated package.json:

{
  "mcpName": "io.github.containers/kubernetes-mcp-server"
}

This field is required by the MCP Registry to identify the server.

2. Python Package Metadata Update

The MCP Registry requires Python packages to include an mcp-name metadata field in the package README. This metadata is parsed by the registry to associate the PyPI package with the MCP server entry.

Add the following line to the project's root README.md:

mcp-name: io.github.containers/kubernetes-mcp-server

This line can be placed at the bottom of the README or in a dedicated metadata section. The Python package already uses the root README via pyproject.toml:

readme = {file="README.md", content-type="text/markdown"}

Since build/python.mk copies the root README during the publish process, no additional changes are needed to the Python build configuration.

3. Server Manifest (server.json)

Maintain a server.json file in the repository root with the following structure:

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
  "name": "io.github.containers/kubernetes-mcp-server",
  "description": "A Model Context Protocol (MCP) server for Kubernetes and OpenShift",
  "status": "active",
  "repository": {
    "url": "https://github.com/containers/kubernetes-mcp-server",
    "source": "github"
  },
  "version": "0.0.0",
  "packages": [
    {
      "registryType": "npm",
      "registryBaseUrl": "https://registry.npmjs.org",
      "identifier": "kubernetes-mcp-server",
      "version": "0.0.0",
      "transport": {
        "type": "stdio"
      }
    },
    {
      "registryType": "pypi",
      "registryBaseUrl": "https://pypi.org",
      "identifier": "kubernetes-mcp-server",
      "version": "0.0.0",
      "runtimeHint": "uvx",
      "transport": {
        "type": "stdio"
      }
    }
  ]
}

The version fields use a placeholder value (0.0.0) that will be replaced by the workflow during publishing.

4. GitHub Actions Workflow

Create a new workflow file .github/workflows/release-mcp-registry.yaml that:

• Triggers:

  • workflow_run: After the Release workflow completes successfully
  • workflow_dispatch: Manual trigger with version input

• Version handling:

  • Git tags use v prefix (e.g., v0.0.51)
  • Version in server.json must be without prefix (e.g., 0.0.51)
  • Workflow strips the v prefix from the tag before updating server.json
  • For workflow_dispatch, the version input should be provided without the v prefix

• Steps:

  1. Checkout the repository

  2. Determine version (strip v prefix from tag or use manual input):

     - name: Get version
       id: version
       run: |
         if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
           echo "version=${{ inputs.version }}" >> $GITHUB_OUTPUT
         else
           echo "version=${GITHUB_REF_NAME#v}" >> $GITHUB_OUTPUT
         fi

  3. Update version in server.json (all version fields):

     - name: Update server.json version
       run: |
         jq --arg v "${{ steps.version.outputs.version }}" \
           '.version = $v | .packages[].version = $v' \
           server.json > server.json.tmp && mv server.json.tmp server.json

  4. Install mcp-publisher CLI:

     - name: Install mcp-publisher
       run: |
         curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher

  5. Authenticate using GitHub OIDC:

     - name: Authenticate to MCP Registry
       run: ./mcp-publisher login github-oidc

  6. Publish to MCP Registry:

     - name: Publish server to MCP Registry
       run: ./mcp-publisher publish

• Permissions required:

  permissions:
    id-token: write  # Required for OIDC authentication
    contents: read

Acceptance Criteria

• npm package.json includes mcpName field with value io.github.containers/kubernetes-mcp-server
• Root README.md includes mcp-name: io.github.containers/kubernetes-mcp-server
• server.json manifest file is committed to the repository with correct schema
• GitHub Actions workflow correctly strips v prefix from tag for versioning
• GitHub Actions workflow updates all version fields in server.json before publishing
• GitHub Actions workflow successfully publishes to MCP Registry after Release workflow completes
• Workflow can be manually triggered with a version input (without v prefix)
• kubernetes-mcp-server appears in the official MCP Registry

Tests

• Verify package.json generation includes mcpName field
• Verify root README.md contains the mcp-name metadata
• Verify server.json version replacement works correctly (test with jq command)
• Test workflow locally with act or similar tool (if possible)
• Dry-run publish to verify manifest validity before actual release

References

• MCP Registry Repository
• MCP Registry Publisher
• Server Schema