Skip to content

Offer the Docker image as an OCI package in server.json - #572

Open
JeroenDeDauw wants to merge 1 commit into
masterfrom
oci-package-entry
Open

Offer the Docker image as an OCI package in server.json#572
JeroenDeDauw wants to merge 1 commit into
masterfrom
oci-package-entry

Conversation

@JeroenDeDauw

Copy link
Copy Markdown
Member

Docker builds the MCP catalog that Docker Desktop imports from the MCP
registry, taking oci packages with a stdio transport and skipping npm
ones. Our entry had only npm and mcpb packages, so the server was absent
from that catalog.

The image defaults to the HTTP transport, which serves a deployment
rather than one local client, and the deployment docs rely on that
default; the package entry pins MCP_TRANSPORT=stdio instead of
changing the image. It declares only the environment variables that
change behaviour on stdio, leaving out the HTTP and OAuth-proxy ones.

Three constraints come with the entry:

  • Ownership of an OCI package is proven by resolving the image and
    reading an io.modelcontextprotocol.server.name label, so the
    Dockerfile now carries one.
  • The registry rejects a version field on an OCI package, so the
    released version lives in the image tag, which
    scripts/update-server-json-oci.cjs rewrites like its npm and mcpb
    siblings do for their identifiers.
  • Publishing resolves that image, so it has to exist first. The release
    workflow now calls publish-image and waits for it; on v0.17.0 the
    image landed 105 seconds after the release job had finished, so
    publishing an OCI package would have failed. The image's cosign
    identity is unchanged, because a certificate issued to a called
    workflow carries that workflow's ref, which is what
    docs/deployment.md verifies against.

Verified against docker/mcp-gateway's TransformToDocker, which rejects
the current entry as incompatible server: no compatible packages and
accepts this one. The published image speaks MCP over stdio with the
override: initialize, 29 tools, and a get-page call against English
Wikipedia.

Considered, omitted: a bind mount for config.json. The server has no
environment variable for naming a wiki, so a catalog user gets English
Wikipedia plus whatever add-wiki registers at runtime. A --mount
runtime argument would express the mount, but the gateway resolves an
unset config variable to the empty string, leaving :/app/config.json
and a container that refuses to start for everyone who wants the
default.

AI-authored — Claude Code, Opus 5 (max); detailed spec from @JeroenDeDauw, executed by a subagent, no redirections; diff not yet human-reviewed; new tests written and seen failing without the change, full suite + lint + typecheck + server.json schema validation green locally, catalog transform and published image exercised locally, CI not yet run.

Docker builds the MCP catalog that Docker Desktop imports from the MCP
registry, taking `oci` packages with a stdio transport and skipping npm
ones. Our entry had only npm and mcpb packages, so the server was absent
from that catalog.

The image defaults to the HTTP transport, which serves a deployment
rather than one local client, and the deployment docs rely on that
default; the package entry pins `MCP_TRANSPORT=stdio` instead of
changing the image. It declares only the environment variables that
change behaviour on stdio, leaving out the HTTP and OAuth-proxy ones.

Three constraints come with the entry:

- Ownership of an OCI package is proven by resolving the image and
  reading an `io.modelcontextprotocol.server.name` label, so the
  Dockerfile now carries one.
- The registry rejects a `version` field on an OCI package, so the
  released version lives in the image tag, which
  `scripts/update-server-json-oci.cjs` rewrites like its npm and mcpb
  siblings do for their identifiers.
- Publishing resolves that image, so it has to exist first. The release
  workflow now calls `publish-image` and waits for it; on v0.17.0 the
  image landed 105 seconds after the release job had finished, so
  publishing an OCI package would have failed. The image's cosign
  identity is unchanged, because a certificate issued to a called
  workflow carries that workflow's ref, which is what
  `docs/deployment.md` verifies against.

Verified against docker/mcp-gateway's `TransformToDocker`, which rejects
the current entry as `incompatible server: no compatible packages` and
accepts this one. The published image speaks MCP over stdio with the
override: `initialize`, 29 tools, and a `get-page` call against English
Wikipedia.

Considered, omitted: a bind mount for `config.json`. The server has no
environment variable for naming a wiki, so a catalog user gets English
Wikipedia plus whatever `add-wiki` registers at runtime. A `--mount`
runtime argument would express the mount, but the gateway resolves an
unset config variable to the empty string, leaving `:/app/config.json`
and a container that refuses to start for everyone who wants the
default.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant