GitHub Actions: Automatisierte Veröffentlichungen

GitHub Actions: Automatisierte Veröffentlichungen

Richten Sie mit GitHub Actions einen automatisierten Veröffentlichungs‑Workflow für MCP‑Server ein.

Lernziele

Nach diesem Tutorial verfügen Sie über:

  • Einen GitHub‑Actions‑Workflow zur automatischen Server‑Veröffentlichung
  • Verständnis von GitHub‑OIDC‑Authentifizierung
  • Best‑Practices für automatisierte Veröffentlichungen
  • Funktionierende Beispiele für Node.js‑, Python‑ und Docker‑Projekte

Voraussetzungen

  • Kenntnis der allgemeinen Veröffentlichungsanforderungen (Paketvalidierung; siehe Veröffentlichungshandbuch)
  • Ein GitHub‑Repository mit Ihrem MCP‑Server‑Code

GitHub‑Actions einrichten

Schritt 1: Workflow‑Datei anlegen

Erstellen Sie .github/workflows/publish-mcp.yml. Nachfolgend ein Beispiel für ein NPM‑Paket; die Schritte für die MCP‑Registry sind für alle Pakettypen identisch:

name: Publish to MCP Registry

on:
  push:
    tags: ["v*"]  # Bei Version-Tags (z. B. v1.0.0) auslösen

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      id-token: write  # Für OIDC-Authentifizierung erforderlich
      contents: read

    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      - name: Setup Node.js  # Je nach Sprache/Stack anpassen
        uses: actions/setup-node@v5
        with:
          node-version: "lts/*"

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm run test --if-present

      - name: Build package
        run: npm run build --if-present

      - name: Publish to npm
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

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

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

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

Schritt 2: Secrets konfigurieren

Für Veröffentlichungen zur MCP‑Registry per GitHub‑OIDC sind keine Secrets erforderlich.

Für Ihre Paket‑Registry benötigen Sie ggf. Secrets. Im obigen Workflow z. B. ein NPM_TOKEN (unter Einstellungen → Secrets und Variablen → Actions hinzufügen).

Schritt 3: Taggen und veröffentlichen

Erstellen Sie ein Version‑Tag, um den Workflow zu triggern:

git tag v1.0.0
git push origin v1.0.0

Der Workflow führt Tests aus, baut Ihr Paket, veröffentlicht zu npm und veröffentlicht zur MCP‑Registry.

Authentifizierungsmethoden

GitHub Actions OIDC (empfohlen) 

- name: Login to MCP Registry
  run: mcp-publisher login github-oidc

Diese Methode wird empfohlen, weil sie:

  • Keine geheimen Schlüssel speichern
  • Integrierte GitHub‑Authentifizierung nutzen
  • Automatischer Zugriff auf Ihren GitHub‑Namensraum

GitHub Personal Access Token 

- name: Login to MCP Registry
  run: mcp-publisher login github --token ${{ secrets.GITHUB_TOKEN }}
  env:
    GITHUB_TOKEN: ${{ secrets.MCP_GITHUB_TOKEN }}

Fügen Sie ein GitHub‑PAT mit Repo‑Zugriff als Secret MCP_GITHUB_TOKEN hinzu.

DNS‑Authentifizierung

Für Domain‑Namensräume (com.yourcompany/*):

- name: Login to MCP Registry
  run: |
    echo "${{ secrets.MCP_PRIVATE_KEY }}" > key.pem
    mcp-publisher login dns --domain yourcompany.com --private-key-file key.pem

Fügen Sie Ihren Ed25519‑Private‑Key als Secret MCP_PRIVATE_KEY hinzu.

Beispiele für mehrere Sprachen

Node.js/NPM‑Projekt 

name: Publish NPM MCP Server

on:
  push:
    tags: ["v*"]

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read

    steps:
      - uses: actions/checkout@v5
      
      - uses: actions/setup-node@v5
        with:
          node-version: "lts/*"
          registry-url: "https://registry.npmjs.org"

      - run: npm ci
      - run: npm test
      - run: npm run build --if-present
      
      - name: Publish to NPM
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

      - name: Install MCP Publisher
        run: |
          curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.0.0/mcp-publisher_1.0.0_linux_amd64.tar.gz" | tar xz mcp-publisher

      - name: Publish to MCP Registry
        run: |
          ./mcp-publisher login github-oidc
          ./mcp-publisher publish

Python/PyPI‑Projekt 

name: Publish Python MCP Server

on:
  push:
    tags: ["v*"]

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read

    steps:
      - uses: actions/checkout@v5
      
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install build twine

      - name: Build package
        run: python -m build

      - name: Publish to PyPI
        uses: pypa/gh-action-pypi-publish@release/v1
        with:
          password: ${{ secrets.PYPI_API_TOKEN }}

      - name: Install MCP Publisher
        run: |
          curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.0.0/mcp-publisher_1.0.0_linux_amd64.tar.gz" | tar xz mcp-publisher

      - name: Publish to MCP Registry
        run: |
          ./mcp-publisher login github-oidc
          ./mcp-publisher publish

Docker/OCI‑Projekt 

name: Publish Docker MCP Server

on:
  push:
    tags: ["v*"]

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
      packages: write

    steps:
      - uses: actions/checkout@v5

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}

      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: |
            ${{ steps.meta.outputs.labels }}
            io.modelcontextprotocol.server.name=io.github.${{ github.repository_owner }}/my-server

      - name: Install MCP Publisher
        run: |
          curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.0.0/mcp-publisher_1.0.0_linux_amd64.tar.gz" | tar xz mcp-publisher

      - name: Publish to MCP Registry
        run: |
          ./mcp-publisher login github-oidc
          ./mcp-publisher publish

NuGet/.NET‑Projekt 

name: Publish NuGet MCP Server

on:
  push:
    tags: ["v*"]

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read

    steps:
      - uses: actions/checkout@v5
      
      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: "8.0.x"

      - name: Restore dependencies
        run: dotnet restore

      - name: Build
        run: dotnet build --configuration Release --no-restore

      - name: Test
        run: dotnet test --no-restore --verbosity normal

      - name: Pack
        run: dotnet pack --configuration Release --no-build --output ./artifacts

      - name: Publish to NuGet
        run: dotnet nuget push ./artifacts/*.nupkg --api-key ${{ secrets.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json

      - name: Install MCP Publisher
        run: |
          curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.0.0/mcp-publisher_1.0.0_linux_amd64.tar.gz" | tar xz mcp-publisher

      - name: Publish to MCP Registry
        run: |
          ./mcp-publisher login github-oidc
          ./mcp-publisher publish

Tipps zur Versionssynchronisierung

Mit den folgenden Methoden halten Sie Paketversion und server.json automatisch synchron:

- name: Update server.json version
  run: |
    VERSION=${GITHUB_REF#refs/tags/v}
    jq --arg v "$VERSION" '.version = $v' server.json > tmp && mv tmp server.json

Erweiterte Konfiguration

Bedingte Veröffentlichung

Nur unter bestimmten Bedingungen zur Registry veröffentlichen:

- name: Publish to MCP Registry
  if: startsWith(github.ref, 'refs/tags/v') && !contains(github.ref, '-')
  run: |
    ./mcp-publisher login github-oidc
    ./mcp-publisher publish

Veröffentlichung für mehrere Umgebungen

Für unterschiedliche Umgebungen unterschiedliche Konfiguration verwenden:

- name: Publish to MCP Registry
  run: |
    ./mcp-publisher login github-oidc
    if [[ "${{ github.ref }}" == *"-alpha"* ]]; then
      ./mcp-publisher publish --file=server-alpha.json
    else
      ./mcp-publisher publish
    fi

Fehlermeldungen/Benachrichtigungen

Benachrichtigung bei Fehlschlägen hinzufügen:

- name: Notify on failure
  if: failure()
  uses: actions/github-script@v7
  with:
    script: |
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: '❌ Veröffentlichung zur MCP Registry fehlgeschlagen. Bitte prüfen Sie die Actions‑Logs.'
      })

Best Practices

1. Release‑Tags verwenden 

# Nur auf Release‑Tags triggern
on:
  push:
    tags: ["v*"]

2. Nach Validierung veröffentlichen 

- name: Validate before publish
  run: |
    ./mcp-publisher publish --dry-run

3. Abhängigkeiten cachen 

- name: Cache dependencies
  uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

4. Matrix‑Builds

Für mehrere Versionen testen:

strategy:
  matrix:
    node-version: [18, 20, 22]

Fehlerbehebung

“Authentication failed” (Authentifizierung fehlgeschlagen)

  • Stellen Sie id-token: write für OIDC ein
  • Secret‑Konfiguration prüfen

“Package validation failed” (Paketvalidierung fehlgeschlagen)

  • Stellen Sie sicher, dass Ihr Paket zunächst erfolgreich in Ihrem Registry (NPM, PyPI usw.) veröffentlicht wurde
  • Stellen Sie sicher, dass Sie die erforderlichen Prüfschritte im Veröffentlichungstutorial abgeschlossen haben

“Version mismatch” (Versionskonflikt)

  • Stellen Sie sicher, dass die Version in server.json der Paketversion entspricht
  • Versions‑Sync‑Skript verwenden

“Rate limiting” (Ratenbegrenzung)

  • Schnell aufeinanderfolgende Releases vermeiden
  • Geeignete Retry‑Logik implementieren

Praxisbeispiele

Sehen Sie sich diese realen Workflows für automatisierte Veröffentlichungen an:

Nächste Schritte

Lernen Sie den manuellen Veröffentlichungsprozess kennen Beherrschen Sie die mcp‑publisher‑Befehle Best Practices zur Versionsverwaltung Namensräume und Sicherheit verstehen
Vorteile der Automatisierung: GitHub Actions stellt sicher, dass jede Veröffentlichung getestet, gebaut und validiert wird – das reduziert manuelle Fehler und erhöht die Qualität.