From 7c446e75ad01b4c28746042539884e4109e4d21c Mon Sep 17 00:00:00 2001 From: Mikel Olasagasti Uranga Date: Fri, 24 Apr 2026 12:11:46 +0200 Subject: [PATCH] feat(oci): add support for Quay.io registry (#1150) Adds support for the Quay.io container registry to the OCI validator. This allows MCP servers hosted on Quay.io to be registered and validated by the official registry. ## Motivation and Context Quay.io is a major, trusted public OCI registry widely used by the cloud-native and open-source communities. Currently, attempting to publish a server using a Quay image results in an unsupported OCI registry error. This change enables developers to use Quay.io as a first-class hosting option for their MCP server images. ## How Has This Been Tested? - **Unit Tests:** Updated `internal/validators/registries/oci_test.go` to transition Quay.io from a rejected test case to an allowed one. - **Pattern Matching:** Verified that the allowlist correctly handles both specific image identifiers and general pattern matching for the `quay.io` host. - **Local Validation:** Ran `make check` to ensure no regressions in the existing OCI validation logic. ## Breaking Changes No. This is an additive change that expands the allowlist of supported registries. Existing configurations are unaffected. ## Types of changes - [ ] Bug fix (non-breaking change which fixes an issue) - [x] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update ## Checklist - [x] I have read the [MCP Documentation](https://modelcontextprotocol.io) - [x] My code follows the repository's style guidelines - [x] New and existing tests pass locally - [x] I have added appropriate error handling - [x] I have added or updated documentation as needed ## Additional context The implementation follows the existing pattern for OCI registries: 1. Added a `RegistryURLQuay` constant to `pkg/model` for consistency. 2. Hardcoded `quay.io` into the `allowedOCIRegistries` map in the validator to minimize architectural complexity. 3. Updated all relevant documentation files (`package-types.mdx`, `generic-server-json.md`, and `official-registry-requirements.md`) to ensure the source of truth is updated across the project. 4. Validation remains scoped to public images; no private registry authentication was added for this host. Signed-off-by: Mikel Olasagasti Uranga Co-authored-by: Radoslav Dimitrov --- .../modelcontextprotocol-io/package-types.mdx | 3 ++- .../server-json/generic-server-json.md | 20 ++++++++++++++++ .../official-registry-requirements.md | 1 + internal/validators/registries/oci.go | 3 +++ internal/validators/registries/oci_test.go | 24 ++++++++++++------- pkg/model/constants.go | 7 +++--- tools/validate-examples/main.go | 2 +- 7 files changed, 47 insertions(+), 13 deletions(-) diff --git a/docs/modelcontextprotocol-io/package-types.mdx b/docs/modelcontextprotocol-io/package-types.mdx index 9014302..b7a31b9 100644 --- a/docs/modelcontextprotocol-io/package-types.mdx +++ b/docs/modelcontextprotocol-io/package-types.mdx @@ -131,6 +131,7 @@ For Docker/OCI images, the MCP Registry currently supports: - Docker Hub (`docker.io`) - GitHub Container Registry (`ghcr.io`) +- Quay.io (`quay.io`) - Google Artifact Registry (any `*.pkg.dev` domain) - Azure Container Registry (`*.azurecr.io`) - Microsoft Container Registry (`mcr.microsoft.com`) @@ -156,7 +157,7 @@ Docker/OCI images use `"registryType": "oci"` in `server.json`. For example: } ``` -The format of `identifier` is `registry/namespace/repository:tag`. For example, `docker.io/user/app:1.0.0` or `ghcr.io/user/app:1.0.0`. The tag can also be specified as a digest. +The format of `identifier` is `registry/namespace/repository:tag`. For example, `docker.io/user/app:1.0.0`, `ghcr.io/user/app:1.0.0`, or `quay.io/myorg/my-mcp-server:1.0.0`. The tag can also be specified as a digest. ### Ownership Verification diff --git a/docs/reference/server-json/generic-server-json.md b/docs/reference/server-json/generic-server-json.md index 1b1aff1..bb5cc44 100644 --- a/docs/reference/server-json/generic-server-json.md +++ b/docs/reference/server-json/generic-server-json.md @@ -264,6 +264,26 @@ This will essentially instruct the MCP client to execute `dnx Knapcode.SampleMcp } ``` +The same `registryType` / `identifier` pattern works for other supported OCI hosts. For example, an image on Quay.io: + +```json +{ + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", + "name": "io.github.example/quay-sample-mcp", + "description": "Example MCP server distributed as an OCI image on Quay.io", + "version": "1.0.0", + "packages": [ + { + "registryType": "oci", + "identifier": "quay.io/myorg/my-mcp-server:1.0.0", + "transport": { + "type": "stdio" + } + } + ] +} +``` + ### Remote Server Example ```json diff --git a/docs/reference/server-json/official-registry-requirements.md b/docs/reference/server-json/official-registry-requirements.md index 494458f..ec456cc 100644 --- a/docs/reference/server-json/official-registry-requirements.md +++ b/docs/reference/server-json/official-registry-requirements.md @@ -36,6 +36,7 @@ Only trusted public registries are supported. Private registries and alternative - **Docker/OCI**: - Docker Hub (`docker.io`) - GitHub Container Registry (`ghcr.io`) + - Quay.io (`quay.io`) - Google Artifact Registry (`*.pkg.dev`) - Azure Container Registry (`*.azurecr.io`) - Microsoft Container Registry (`mcr.microsoft.com`) diff --git a/internal/validators/registries/oci.go b/internal/validators/registries/oci.go index 6932d7f..d4ab56c 100644 --- a/internal/validators/registries/oci.go +++ b/internal/validators/registries/oci.go @@ -33,6 +33,8 @@ var allowedOCIRegistries = map[string]bool{ "index.docker.io": true, // Docker Hub index // GitHub Container Registry "ghcr.io": true, + // Red Hat Quay + "quay.io": true, // Microsoft Container Registry "mcr.microsoft.com": true, // Google Artifact Registry (*.pkg.dev pattern handled in isAllowedRegistry) @@ -49,6 +51,7 @@ var allowedOCIRegistries = map[string]bool{ // Supported registries: // - Docker Hub (docker.io) // - GitHub Container Registry (ghcr.io) +// - Quay.io (quay.io) // - Google Artifact Registry (*.pkg.dev) // - Microsoft Container Registry (mcr.microsoft.com) func ValidateOCI(ctx context.Context, pkg model.Package, serverName string) error { diff --git a/internal/validators/registries/oci_test.go b/internal/validators/registries/oci_test.go index 634e2e5..fddf446 100644 --- a/internal/validators/registries/oci_test.go +++ b/internal/validators/registries/oci_test.go @@ -66,6 +66,13 @@ func TestValidateOCI_RegistryAllowlist(t *testing.T) { errorMsg: "missing required annotation", mustNotContainMsg: "unsupported OCI registry", }, + { + name: "Quay.io should be allowed", + identifier: "quay.io/prometheus/node-exporter:v1.7.0", + expectError: true, + errorMsg: "missing required annotation", + mustNotContainMsg: "unsupported OCI registry", + }, // Removed ACR test with non-existent host - ACR support is tested elsewhere // Disallowed registries @@ -75,12 +82,6 @@ func TestValidateOCI_RegistryAllowlist(t *testing.T) { expectError: true, errorMsg: "unsupported OCI registry", }, - { - name: "Quay.io should be rejected", - identifier: "quay.io/test/image:latest", - expectError: true, - errorMsg: "unsupported OCI registry", - }, { name: "ECR Public should be rejected", identifier: "public.ecr.aws/test/image:latest", @@ -134,8 +135,9 @@ func TestValidateOCI_RegistryAllowlist(t *testing.T) { } func TestValidateOCI_RegistryPatterns(t *testing.T) { - // This test verifies registry pattern matching (wildcards like *.azurecr.io and *.pkg.dev) - // without relying on external images that may not exist + // Verifies allowlist behavior: wildcard hosts (*.azurecr.io, *.pkg.dev) and fixed hosts + // like quay.io. shouldFail=false means the error must not be "unsupported OCI registry" + // (validation may still error later, for example missing annotation or image not found). tests := []struct { name string identifier string @@ -156,6 +158,12 @@ func TestValidateOCI_RegistryPatterns(t *testing.T) { identifier: "us-west1-docker.pkg.dev/project/repo/image:tag", shouldFail: false, }, + { + name: "Quay.io host should be allowed", + identifier: "quay.io/nonexistent/mcp-registry-fake-repo:v1", + // Past allowlist; fake repo typically yields "does not exist", not unsupported registry + shouldFail: false, + }, { name: "GCR should be rejected at registry check", identifier: "gcr.io/project/image:latest", diff --git a/pkg/model/constants.go b/pkg/model/constants.go index e817f2a..ead176d 100644 --- a/pkg/model/constants.go +++ b/pkg/model/constants.go @@ -11,11 +11,12 @@ const ( // Registry Base URLs - supported package registry base URLs const ( - RegistryURLNPM = "https://registry.npmjs.org" - RegistryURLPyPI = "https://pypi.org" - RegistryURLNuGet = "https://api.nuget.org/v3/index.json" RegistryURLGitHub = "https://github.com" RegistryURLGitLab = "https://gitlab.com" + RegistryURLNPM = "https://registry.npmjs.org" + RegistryURLNuGet = "https://api.nuget.org/v3/index.json" + RegistryURLPyPI = "https://pypi.org" + RegistryURLQuay = "https://quay.io" ) // Transport Types - supported remote transport protocols diff --git a/tools/validate-examples/main.go b/tools/validate-examples/main.go index 54a7e4b..2f8be56 100644 --- a/tools/validate-examples/main.go +++ b/tools/validate-examples/main.go @@ -33,7 +33,7 @@ func main() { func runValidation() error { // Define what we validate and how - expectedServerJSONCount := 15 + expectedServerJSONCount := 16 targets := []validationTarget{ { path: filepath.Join("docs", "reference", "server-json", "generic-server-json.md"),