feat(codex)!: install a configurable local plugin

.github/workflows/ci-cd.yml

@@ -100,15 +100,11 @@ jobs:
           echo "Manifest template is valid (JSON + required fields)"
         working-directory: packages/gitlab-mcp
 
-      # Builds the plugin with the directory submission rules from the built CLI,
+      # Builds the plugin with the directory submission rules,
       # so a missing asset, a bad skill header or an embedded secret fails the PR.
       - name: Validate Codex plugin package
-        run: >-
-          node dist/src/main.js plugin build --public
-          --endpoint https://mcp.example.com/mcp
-          --privacy-url https://example.com/privacy
-          --terms-url https://example.com/terms
-          --out "$RUNNER_TEMP/codex-plugin"
+        run: |
+          node -e 'require("./dist/src/cli/plugin/build.js").buildPlugin({flavor: "public", endpoint: "https://mcp.example.com/mcp", privacyPolicyUrl: "https://example.com/privacy", termsOfServiceUrl: "https://example.com/terms", outDir: process.env.RUNNER_TEMP + "/codex-plugin"})'
         working-directory: packages/gitlab-mcp
 
       # The repository marketplace (.agents/plugins and plugins/ at the repo root) is
@@ -125,12 +121,38 @@ jobs:
 
       # Installs that package into a real Codex CLI and runs install, disable, enable,
       # upgrade, reinstall and uninstall against the installed copy.
+      - name: Build configurable Codex plugin archive
+        run: >-
+          node scripts/build-codex-plugin.mjs "$RUNNER_TEMP/codex-configurable"
+        working-directory: packages/gitlab-mcp
+
       - name: Codex plugin lifecycle
         run: |
           npm install --prefix "$RUNNER_TEMP/codex-cli" --no-save --no-package-lock @openai/codex@0.163.0
           node scripts/codex-plugin-lifecycle.mjs --codex "$RUNNER_TEMP/codex-cli/node_modules/.bin/codex" "$RUNNER_TEMP/codex-plugin"
+          node --test tests/scripts/plugin-artifact.test.mjs
+          node scripts/qualify-codex-plugin.mjs --archive "$RUNNER_TEMP/codex-configurable/gitlab-mcp-codex.zip" --coverage --codex "$RUNNER_TEMP/codex-cli/node_modules/.bin/codex"
         working-directory: packages/gitlab-mcp
 
+      - name: Upload Codex plugin archive
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
+        with:
+          name: codex-plugin
+          path: |
+            ${{ runner.temp }}/codex-configurable/gitlab-mcp-codex.zip
+            ${{ runner.temp }}/codex-configurable/gitlab-mcp-codex.zip.sha256
+          compression-level: 0
+          if-no-files-found: error
+          retention-days: 7
+
+      - name: Upload Codex plugin contract coverage
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./packages/gitlab-mcp/coverage/plugin.lcov.info
+          flags: codex-plugin
+          fail_ci_if_error: false
+
       - name: Upload build artifacts
         uses: actions/upload-artifact@v7
         with:
@@ -340,22 +362,22 @@ jobs:
     steps:
       - name: Summary
         run: |
-          echo "## Pipeline Summary" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "## Pipeline Summary" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
 
           if [[ "${{ needs.quality-checks.result }}" == "success" ]]; then
-            echo "✅ Quality checks: Passed" >> $GITHUB_STEP_SUMMARY
+            echo "✅ Quality checks: Passed" >> "$GITHUB_STEP_SUMMARY"
           else
-            echo "❌ Quality checks: Failed" >> $GITHUB_STEP_SUMMARY
+            echo "❌ Quality checks: Failed" >> "$GITHUB_STEP_SUMMARY"
           fi
 
           if [[ "${{ needs.docker-build.result }}" == "success" ]]; then
-            echo "✅ Docker build: Passed" >> $GITHUB_STEP_SUMMARY
+            echo "✅ Docker build: Passed" >> "$GITHUB_STEP_SUMMARY"
           elif [[ "${{ needs.docker-build.result }}" == "skipped" ]]; then
-            echo "⏭️ Docker build: Skipped" >> $GITHUB_STEP_SUMMARY
+            echo "⏭️ Docker build: Skipped" >> "$GITHUB_STEP_SUMMARY"
           else
-            echo "❌ Docker build: Failed" >> $GITHUB_STEP_SUMMARY
+            echo "❌ Docker build: Failed" >> "$GITHUB_STEP_SUMMARY"
           fi
 
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "ℹ️ Release and publishing handled by [Release workflow](${{ github.server_url }}/${{ github.repository }}/actions/workflows/release-please.yml)" >> $GITHUB_STEP_SUMMARY
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "ℹ️ Release and publishing handled by [Release workflow](${{ github.server_url }}/${{ github.repository }}/actions/workflows/release-please.yml)" >> "$GITHUB_STEP_SUMMARY"

.github/workflows/release-please.yml

@@ -170,6 +170,14 @@ jobs:
         run: ./scripts/prepare-release.sh "${{ needs.release-please.outputs.release-version }}"
         working-directory: packages/gitlab-mcp
 
+      - name: Build configurable Codex marketplace
+        working-directory: packages/gitlab-mcp
+        run: node scripts/build-codex-plugin.mjs codex-release
+
+      - name: Verify the exact Codex release archive
+        working-directory: packages/gitlab-mcp
+        run: node scripts/qualify-codex-plugin.mjs --archive codex-release/gitlab-mcp-codex.zip
+
       # Note: server.json version is updated by release-please extra-files.
       # Dynamic counts (README.md, package.json manifest) are updated by prepare-release.sh
       # locally for the build but NOT committed back — they'll be current in the next release PR.
@@ -234,6 +242,17 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Upload Codex marketplace to GitHub Release
+        uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3
+        with:
+          tag_name: ${{ needs.release-please.outputs.release-tag }}
+          fail_on_unmatched_files: true
+          files: |
+            packages/gitlab-mcp/codex-release/gitlab-mcp-codex.zip
+            packages/gitlab-mcp/codex-release/gitlab-mcp-codex.zip.sha256
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
       # Publish Docker images
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
@@ -373,17 +392,36 @@ jobs:
         working-directory: packages/gitlab-mcp
         run: '"$GITHUB_WORKSPACE/mcp-publisher" publish'
 
-  # Job 3: Sync generated metadata into the open release PR
-  # When release-please updates (not merges) the release PR, regenerate the
-  # dynamic artifacts (package.json MCP manifest + tool counts, README counts,
-  # server.json description) and commit them onto the PR branch so the committed
-  # state always matches what will be published — alongside the version bump and
-  # CHANGELOG that already live on that branch.
-  #
-  # Loop-safe: this pushes to the release PR branch, and the workflow only triggers
-  # on push to main, so the commit never re-triggers the workflow. release-please
-  # may rebuild its PR branch on the next push to main; this job re-runs then and
-  # re-applies the metadata, so the PR is current whenever it is merged.
+  notify-plugin-marketplace:
+    name: Refresh the shared plugin marketplace
+    runs-on: ubuntu-latest
+    needs: [release-please, post-release]
+    if: needs.release-please.outputs.release-created == 'true' && needs.post-release.result == 'success'
+    permissions: {}
+    steps:
+      - name: Generate marketplace dispatch token
+        uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3
+        id: marketplace-token
+        with:
+          app-id: ${{ secrets.RELEASER_APP_ID }}
+          private-key: ${{ secrets.RELEASER_APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+          repositories: repo
+          permission-contents: write
+
+      - name: Request publication of the released plugin
+        env:
+          GH_TOKEN: ${{ steps.marketplace-token.outputs.token }}
+          RELEASE_TAG: ${{ needs.release-please.outputs.release-tag }}
+        run: |
+          jq -n --arg tag "$RELEASE_TAG" '{event_type: "refresh-gitlab-mcp-plugin", client_payload: {release_tag: $tag}}' \
+            | gh api --method POST repos/structured-world/repo/dispatches --input -
+
+  # Sync generated metadata into the open release PR. After its version bump,
+  # regenerate package manifests, README counts and the registry description.
+  # This pushes to the release PR branch while the workflow triggers on main,
+  # so it does not create a publication loop. If release-please rebuilds that
+  # branch on the next main push, this job reapplies the generated metadata.
   sync-release-pr:
     name: Sync generated metadata into release PR
     runs-on: ubuntu-latest
@@ -493,6 +531,7 @@ jobs:
                 echo "📦 npm: @structured-world/gitlab-mcp@${{ needs.release-please.outputs.release-version }}"
                 echo "🐳 Docker: ghcr.io/${{ env.IMAGE_NAME }}:${{ needs.release-please.outputs.release-version }}"
                 echo "📦 MCPB: gitlab-mcp-${{ needs.release-please.outputs.release-version }}.mcpb"
+                echo "📦 Codex: gitlab-mcp-codex.zip and SHA-256 checksum"
                 echo "🌐 MCP Registry: io.github.structured-world/gitlab-mcp"
               else
                 echo "❌ Post-release publish failed"

README.md

@@ -5,6 +5,7 @@
 Advanced GitLab MCP server: 64 CQRS tools exposing 235 GitLab operations across 26 entity types. The tool catalog and parameters are filtered to each instance's GitLab version, tier, and token scopes, so the agent sees only what the connected instance actually supports.
 
 [![Install in Claude Desktop](https://img.shields.io/badge/Claude_Desktop-Install_Extension-F97316?style=for-the-badge)](https://gitlab-mcp.sw.foundation/downloads/gitlab-mcp-12.1.0.mcpb)
+[![Set up in Codex](https://img.shields.io/badge/Codex-Setup_%26_Download-111827?style=for-the-badge)](https://gitlab-mcp.sw.foundation/guide/installation/codex#install-from-a-release)
 [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_Server-007ACC?style=for-the-badge&logo=visualstudiocode&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22gitlab-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40structured-world%2Fgitlab-mcp%22%5D%7D)
 [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_MCP_Server-24bfa5?style=for-the-badge&logo=visualstudiocode&logoColor=white)](vscode-insiders:mcp/install?%7B%22name%22%3A%22gitlab-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40structured-world%2Fgitlab-mcp%22%5D%7D)
 
@@ -38,7 +39,7 @@ This is a monorepo with two npm packages:
 
 | Client | Setup |
 |--------|-------|
-| **Codex (CLI and desktop)** | [Local MCP registration or remote HTTP server](https://gitlab-mcp.sw.foundation/guide/installation/codex) |
+| **Codex (CLI and desktop)** | [Configurable local plugin, local MCP registration or HTTP server](https://gitlab-mcp.sw.foundation/guide/installation/codex) |
 | **Antigravity CLI (`agy`)** | [Workspace MCP configuration and tested compatibility](https://gitlab-mcp.sw.foundation/clients/antigravity) |
 | Claude Desktop | [Desktop extension or MCP configuration](https://gitlab-mcp.sw.foundation/clients/claude-desktop) |
 | Claude Code | [CLI or MCP configuration](https://gitlab-mcp.sw.foundation/clients/claude-code) |
@@ -48,6 +49,22 @@ This is a monorepo with two npm packages:
 | Cline | [MCP configuration](https://gitlab-mcp.sw.foundation/clients/cline) |
 | Roo Code | [MCP configuration](https://gitlab-mcp.sw.foundation/clients/roo-code) |
 
+The Codex plugin can be installed before configuring a target. Its connection
+panel supports a GitLab instance with a locally started core server, or an existing
+HTTP MCP server. The local plugin requires Node.js 24+; credentials are entered in
+its private panel. See the installation guide for marketplace setup and authentication.
+
+The [shared sw.foundation marketplace](https://repo.sw.foundation/plugins/) lists
+verified releases. Add it once with `codex plugin marketplace add structured-world/repo --sparse .agents/plugins`,
+then install GitLab MCP from that catalog after its first configurable plugin release.
+
+Download the ready-made [Codex marketplace ZIP](https://github.com/structured-world/gitlab-mcp/releases/latest/download/gitlab-mcp-codex.zip)
+and its [SHA-256 checksum](https://github.com/structured-world/gitlab-mcp/releases/latest/download/gitlab-mcp-codex.zip.sha256)
+from GitHub Releases. It includes the local runtime and dependencies, separately from
+the Claude Desktop MCPB bundles. Add the extracted marketplace once, then install
+through Codex. An install link requires an already configured marketplace; downloading
+the ZIP does not install it automatically. Older releases may not contain these assets.
+
 With the Codex CLI installed and `GITLAB_API_URL` and `GITLAB_TOKEN` set in your
 environment, run `npx @structured-world/gitlab-mcp install --codex` to register a
 local server. For Antigravity, add the server

packages/gitlab-mcp-db/README.md

@@ -5,6 +5,7 @@
 Advanced GitLab MCP server: 64 CQRS tools exposing 235 GitLab operations across 26 entity types. The tool catalog and parameters are filtered to each instance's GitLab version, tier, and token scopes, so the agent sees only what the connected instance actually supports.
 
 [![Install in Claude Desktop](https://img.shields.io/badge/Claude_Desktop-Install_Extension-F97316?style=for-the-badge)](https://gitlab-mcp.sw.foundation/downloads/gitlab-mcp-12.1.0.mcpb)
+[![Set up in Codex](https://img.shields.io/badge/Codex-Setup_%26_Download-111827?style=for-the-badge)](https://gitlab-mcp.sw.foundation/guide/installation/codex#install-from-a-release)
 [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_Server-007ACC?style=for-the-badge&logo=visualstudiocode&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22gitlab-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40structured-world%2Fgitlab-mcp%22%5D%7D)
 [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_MCP_Server-24bfa5?style=for-the-badge&logo=visualstudiocode&logoColor=white)](vscode-insiders:mcp/install?%7B%22name%22%3A%22gitlab-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40structured-world%2Fgitlab-mcp%22%5D%7D)
 
@@ -38,7 +39,7 @@ This is a monorepo with two npm packages:
 
 | Client | Setup |
 |--------|-------|
-| **Codex (CLI and desktop)** | [Local MCP registration or remote HTTP server](https://gitlab-mcp.sw.foundation/guide/installation/codex) |
+| **Codex (CLI and desktop)** | [Configurable local plugin, local MCP registration or HTTP server](https://gitlab-mcp.sw.foundation/guide/installation/codex) |
 | **Antigravity CLI (`agy`)** | [Workspace MCP configuration and tested compatibility](https://gitlab-mcp.sw.foundation/clients/antigravity) |
 | Claude Desktop | [Desktop extension or MCP configuration](https://gitlab-mcp.sw.foundation/clients/claude-desktop) |
 | Claude Code | [CLI or MCP configuration](https://gitlab-mcp.sw.foundation/clients/claude-code) |
@@ -48,6 +49,22 @@ This is a monorepo with two npm packages:
 | Cline | [MCP configuration](https://gitlab-mcp.sw.foundation/clients/cline) |
 | Roo Code | [MCP configuration](https://gitlab-mcp.sw.foundation/clients/roo-code) |
 
+The Codex plugin can be installed before configuring a target. Its connection
+panel supports a GitLab instance with a locally started core server, or an existing
+HTTP MCP server. The local plugin requires Node.js 24+; credentials are entered in
+its private panel. See the installation guide for marketplace setup and authentication.
+
+The [shared sw.foundation marketplace](https://repo.sw.foundation/plugins/) lists
+verified releases. Add it once with `codex plugin marketplace add structured-world/repo --sparse .agents/plugins`,
+then install GitLab MCP from that catalog after its first configurable plugin release.
+
+Download the ready-made [Codex marketplace ZIP](https://github.com/structured-world/gitlab-mcp/releases/latest/download/gitlab-mcp-codex.zip)
+and its [SHA-256 checksum](https://github.com/structured-world/gitlab-mcp/releases/latest/download/gitlab-mcp-codex.zip.sha256)
+from GitHub Releases. It includes the local runtime and dependencies, separately from
+the Claude Desktop MCPB bundles. Add the extracted marketplace once, then install
+through Codex. An install link requires an already configured marketplace; downloading
+the ZIP does not install it automatically. Older releases may not contain these assets.
+
 With the Codex CLI installed and `GITLAB_API_URL` and `GITLAB_TOKEN` set in your
 environment, run `npx @structured-world/gitlab-mcp install --codex` to register a
 local server. For Antigravity, add the server