Skip to content

chore(ci): build, boot and stop each changed server's Docker image - #5631

Open
cliffhall wants to merge 3 commits into
v2/mainfrom
v2/chore/5598-docker-image-check
Open

cliffhall wants to merge 3 commits into
v2/mainfrom
v2/chore/5598-docker-image-check

Conversation

@cliffhall

Copy link
Copy Markdown
Member

Closes #5598

Description

Nothing built the seven servers' Docker images: no workflow, and no stage of the pre-push gate. This adds one check, npm run image-smoke (scripts/image-smoke.mjs), and runs it in both tiers.

For each server a change touches, it:

  1. Builds the image with the command its Dockerfile documents (the repository root as the context for a TypeScript server, the server's directory for a Python one).
  2. Boots it the way a client configuration does, docker run -i, connects an MCP client over the container's stdio, and looks for one named tool in tools/list.
  3. Stops it with docker stop, for the two images that stop on their own today (everything, memory), and fails if Docker had to kill the container (exit 137).
  4. For memory, makes a write before the stop and checks that the graph's directory holds the graph and nothing else afterwards, so no lock or temporary save file outlives the stop (memory: clean up active lock files on exit and termination signals #5485).

The three questions the issue left open, and what this PR does about each:

Question Answer in this PR
Each image a PR changes, or all seven? The images the change touches, selected the way the interface diff selects servers: a file under src/<server>/; for a TypeScript server the root .npmrc or tsconfig.json, or a lockfile edit that changes a package it installs; every image when the image tooling changes. A manual run of the workflow builds all seven.
Is memory's docker stop behavior asserted? Yes: the container exits on its own, and /data holds only memory.jsonl after a write and a stop. The lock is held only for the milliseconds of a write, so what is asserted is that none is left, not that a held one was removed mid-write.
Gate stage, or CI-only? A gate stage, the last one. A change that touches no image builds nothing and needs no Docker. One that does needs a running daemon and fails without one rather than skipping.

That last row is the judgment call a reviewer may want to change. The alternative is CI-only with a recorded exception, like the Windows legs. I chose the gate stage because the selection keeps Docker out of most gate runs, and a warm build-and-boot is a few seconds per image.

cleanStop is in the script's table, not read from the image's STOPSIGNAL, so deleting that line from a Dockerfile cannot delete the check with it. The other five images are killed at the timeout today; that is #5611, not this PR.

Server Details

None (repository-wide): CI, the pre-push gate and their documentation. No server's code or Dockerfile changes.

  • scripts/image-smoke.mjs, scripts/image-smoke.test.mjs: the check and its tests.
  • .github/workflows/image-smoke.yml: Choose the images to build, then one Image <server> leg per selected image. No job holds a credential or pushes an image.
  • package.json: the image-smoke script, appended to local:gate:stages.
  • scripts/interface-diff.mjs: resolveBase and changesSince are exported, so both checks read the change the same way.
  • AGENTS.md, docs/quality-gate.md, the pre-push-gate and local-dev skills: the new stage, what selects an image, and how to read a failure.

Motivation and Context

#5598. The v2.5.0 release changed three Dockerfiles (#5483, #5485) and the release verification built and exercised the images by hand, because nothing else would have.

How Has This Been Tested?

No client-observable surface, so these are targeted probes. All run locally on macOS (arm64) with Docker Desktop 4.93.0, engine 29.8.1.

The claim. Before this PR, grep -ri docker .github/workflows scripts package.json matched only the docker:// handling in the action-ref tooling. All seven Dockerfiles build today, with --no-cache: 5 to 17 seconds each.

All seven images pass (npm run image-smoke -- --all, warm layers, 21 seconds in total):

image-smoke — everything …
image-smoke —   built mcp-image-smoke/everything:local
image-smoke —   booted; tools/list has `echo`
image-smoke —   stopped on its own (exit 0)
image-smoke — ok    everything (2512ms)
image-smoke — memory …
image-smoke —   built mcp-image-smoke/memory:local
image-smoke —   booted; tools/list has `read_graph`
image-smoke —   stopped on its own (exit 130)
image-smoke —   /data holds only memory.jsonl
image-smoke — ok    memory (3701ms)
…
image-smoke — OK (7 images built and booted)

Planted defects, each made to fail and then reverted:

Planted Result
STOPSIGNAL SIGINT deleted from src/everything/Dockerfile FAIL everything: `docker stop` had to kill it after 10s (exit 137)
COPY nothing-here /x appended to src/git/Dockerfile FAIL git: `docker build -t mcp-image-smoke/git:local .` failed (1) with the build log's tail
src/time/Dockerfile's entrypoint renamed to mcp-server-tyme FAIL time: Connection closed, with the container's stderr exec: mcp-server-tyme: not found

Deleting STOPSIGNAL from src/memory/Dockerfile still passes (exit 143): the server handles SIGTERM itself, so the image's stop behavior did not regress, and the check reports that correctly.

Selection. On this branch --list selects all seven, because the image tooling itself changed, so this PR's own CI run builds every image. The script tests cover the rest: one server's directory, the root files, a lockfile edit that reaches one server and one that reaches none.

No daemon. The script tests drive main with a docker that fails docker version: a selected image exits 1 with "no Docker daemon answered", and a change that touches no image passes without calling Docker at all.

The gate. npm run local:gate exits 0 with the new stage in it.

Breaking Changes

None for users. For maintainers: a push that touches a server's image now needs a running Docker daemon for the gate to pass.

Types of changes

  • Bug fix
  • New feature (a new CI check and gate stage)
  • Breaking change
  • Documentation update

Checklist

  • I have read the MCP Protocol Documentation (not applicable: no protocol surface changes; the check only calls tools/list and one existing tool)
  • My changes follow MCP security best practices (the workflow's jobs hold a read-only token, no persisted credentials, and push nothing)
  • I have updated the server's README accordingly (not applicable: no server changes; AGENTS.md, docs/quality-gate.md and two skills are updated)
  • I have added a changeset (not applicable: nothing a TypeScript server publishes changes)
  • I have tested this with an LLM client (not applicable: no server-facing change; the probes above stand in)
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have documented all environment variables and configuration options (not applicable: none added)

Additional context

  • The version PRs get no run of this workflow: their events start no pull_request run, and nothing can dispatch a workflow whose file is not yet on main. They change version metadata only. Wiring a dispatch after the next milestone merge is possible if wanted.
  • Images are tagged mcp-image-smoke/<server>:local and each run reuses the tag; containers are removed by the check.

🤖 Generated with Claude Code

No workflow or gate stage built the seven servers' Docker images, so a
Dockerfile change reached a release with nothing checking that the image
still built, booted or stopped cleanly (#5598).

Add `npm run image-smoke` (scripts/image-smoke.mjs): for each server a
change touches it builds the image with the documented command, lists its
tools over `docker run -i`, and for the two images that stop on their own
(everything, memory) asserts `docker stop` does not have to kill them. For
memory it also writes first and checks no lock file outlives the stop.

It runs in CI (image-smoke.yml, one leg per selected image) and as the
last local:gate stage, with the same selection. A change that touches no
image needs no Docker; one that does fails without a daemon rather than
skipping.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Signed-off-by: cliffhall <cliff@futurescale.com>
@cliffhall cliffhall added the v2 label Nov 18, 2026
@changeset-bot

changeset-bot Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 4ac4319

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The smoke gate can connect to the wrong Docker daemon because its transport omits Docker environment settings, and interrupted runs can leave containers running.

2 open issues
What changed in this PR

Adds Docker image checks to CI and the local pre-push gate, addressing #5598 without changing server code or Dockerfiles.

Changes:

  • Builds affected images and verifies their tools through an MCP client over container stdio.
  • Checks clean shutdown for everything and memory, plus leftover files after a memory write.
  • Adds image selection, regression tests, and documentation; Docker is required only when images are selected.
File Description
scripts/​lib/​workflow-gate.test.mjs Requires the image smoke gate stage.
scripts/​interface-diff.mjs Exports shared change-detection helpers.
scripts/​image-smoke.test.mjs Tests selection, Docker operations, and failure handling.
scripts/​image-smoke.mjs Implements image build, boot, and shutdown checks.
package.json Adds the command and pre-push gate stage.
docs/​quality-gate.md Documents selection, requirements, and assertions.
AGENTS.md Updates repository guidance for image checks.
.github/​workflows/​image-smoke.yml Runs CI checks per selected image.
.claude/​skills/​pre-push-gate/​SKILL.md Documents troubleshooting and rerun commands.
.claude/​skills/​local-dev/​SKILL.md Updates Docker guidance to reference the gate.

Review effort: Balanced

Comment thread scripts/image-smoke.mjs Resolved
Comment thread scripts/image-smoke.mjs Resolved
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

everything: MCP interface diff

Base: 7f383a8e0f34 (Merge pull request #5597 from modelcontextprotocol/changeset-release/v2/main)
Head: the build in this checkout, at 87487e1c2afb (Merge 4ac4319 into 7f383a8)

Diffed because it was named (--server).

✅ No interface changes detected.

Tools Prompts Resources Resource templates
Base 22 4 8 5
Head 22 4 8 5

Updated by this run for 4ac43190cd3527c63fa639123e7de753861b41f3.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

time: MCP interface diff

Base: 7f383a8e0f34 (Merge pull request #5597 from modelcontextprotocol/changeset-release/v2/main)
Head: the build in this checkout, at 87487e1c2afb (Merge 4ac4319 into 7f383a8)

Diffed because it was named (--server).

✅ No interface changes detected.

Tools Prompts Resources Resource templates
Base 3 0 0 0
Head 3 0 0 0

Updated by this run for 4ac43190cd3527c63fa639123e7de753861b41f3.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

sequentialthinking: MCP interface diff

Base: 7f383a8e0f34 (Merge pull request #5597 from modelcontextprotocol/changeset-release/v2/main)
Head: the build in this checkout, at 87487e1c2afb (Merge 4ac4319 into 7f383a8)

Diffed because it was named (--server).

✅ No interface changes detected.

Tools Prompts Resources Resource templates
Base 1 0 0 0
Head 1 0 0 0

Updated by this run for 4ac43190cd3527c63fa639123e7de753861b41f3.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

git: MCP interface diff

Base: 7f383a8e0f34 (Merge pull request #5597 from modelcontextprotocol/changeset-release/v2/main)
Head: the build in this checkout, at 87487e1c2afb (Merge 4ac4319 into 7f383a8)

Diffed because it was named (--server).

✅ No interface changes detected.

Tools Prompts Resources Resource templates
Base 14 2 0 0
Head 14 2 0 0

Updated by this run for 4ac43190cd3527c63fa639123e7de753861b41f3.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

fetch: MCP interface diff

Base: 7f383a8e0f34 (Merge pull request #5597 from modelcontextprotocol/changeset-release/v2/main)
Head: the build in this checkout, at 87487e1c2afb (Merge 4ac4319 into 7f383a8)

Diffed because it was named (--server).

✅ No interface changes detected.

Tools Prompts Resources Resource templates
Base 1 1 0 0
Head 1 1 0 0

Updated by this run for 4ac43190cd3527c63fa639123e7de753861b41f3.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

memory: MCP interface diff

Base: 7f383a8e0f34 (Merge pull request #5597 from modelcontextprotocol/changeset-release/v2/main)
Head: the build in this checkout, at 87487e1c2afb (Merge 4ac4319 into 7f383a8)

Diffed because it was named (--server).

✅ No interface changes detected.

Tools Prompts Resources Resource templates
Base 9 0 1 0
Head 9 0 1 0

Updated by this run for 4ac43190cd3527c63fa639123e7de753861b41f3.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

filesystem: MCP interface diff

Base: 7f383a8e0f34 (Merge pull request #5597 from modelcontextprotocol/changeset-release/v2/main)
Head: the build in this checkout, at 87487e1c2afb (Merge 4ac4319 into 7f383a8)

Diffed because it was named (--server).

✅ No interface changes detected.

Tools Prompts Resources Resource templates
Base 16 0 0 1
Head 16 0 0 1

Updated by this run for 4ac43190cd3527c63fa639123e7de753861b41f3.

…iner on an interrupt

The stdio transport's default environment drops DOCKER_HOST, DOCKER_CONTEXT
and the TLS settings, so `docker run` could reach a different daemon from
the build. An interrupt skipped the cleanup and left the named container
behind.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Signed-off-by: cliffhall <cliff@futurescale.com>
@cliffhall

Copy link
Copy Markdown
Member Author

Copilot round 1: two findings, both defects in the new script, both fixed in d2a7528.

  • The boot could reach a different Docker daemon from the build. The stdio transport's default environment drops DOCKER_HOST, DOCKER_CONTEXT and the TLS settings. The transport now gets the process's whole environment.
  • An interrupted run left its container behind. SIGINT and SIGTERM handlers now remove the container and exit 130 or 143; they are unregistered when the check ends. Interrupting a real run mid-boot left nothing.

The gate exits 0 on d2a7528.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The smoke test’s shared image tag can be overwritten by overlapping standalone runs, causing a run to validate another checkout’s image and falsely pass.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Medium severity Use a per-run or immutable image reference for smoke tests

scripts/​image-smoke.mjs:275

The fixed tag lets overlapping runs test the wrong checkout's image. The lease serializes local:gate, but not the documented standalone npm run image-smoke command: run A can finish building, run B can replace this tag, and A's subsequent docker run then boots B's image. Both checks can pass because they look for the same tool name, even if A's image cannot boot. Use a per-run tag, or capture the build's immutable image ID and boot that instead.

2 resolved since last review

Review effort: Balanced

The per-server tag is shared by every checkout, so another run could move
it between this run's build and its boot. The build now writes its image
ID (--iidfile) and the boot runs that.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Signed-off-by: cliffhall <cliff@futurescale.com>
@cliffhall

Copy link
Copy Markdown
Member Author

Copilot round 2: no open issues on the round-1 fixes, and one previously missed finding, which is in the review body and has no thread, so it is answered here.

  • The shared image tag could be moved by an overlapping run. mcp-image-smoke/<server>:local is one tag per server across every checkout, so another checkout's run could retag it between this run's build and its boot, and the boot would pass on the wrong image. Fixed in 4ac4319: the build writes its image ID (--iidfile) and the boot runs that ID. The tag stays, for the layer cache and for running an image by hand. Script tests pin that the boot uses the ID and that a build reporting no ID fails.

The gate exits 0 on 4ac4319.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues block the Docker image validation changes.

No open issues 🎉

Review effort: Balanced

@cliffhall

Copy link
Copy Markdown
Member Author

Copilot round 3 on 4ac4319: approval recommended, no open issues. The review loop ends here on a clean round.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

CI: no workflow builds or boots the servers' Docker images

2 participants