From f19b337d7b077c6c0f9bfe833d266e5bce33f6ac Mon Sep 17 00:00:00 2001 From: Wolfgang Nagele Date: Thu, 5 Nov 2026 10:07:37 -0500 Subject: [PATCH] Build container images for easy MCP use --- .dockerignore | 4 ++ .github/workflows/auto-release.yml | 7 +++ .github/workflows/docker.yml | 72 ++++++++++++++++++++++++++++++ docker/Dockerfile | 16 +++++++ docker/docker-entrypoint.sh | 42 +++++++++++++++++ docs/MCP.md | 33 ++++++++++++++ 6 files changed, 174 insertions(+) create mode 100644 .dockerignore create mode 100644 .github/workflows/docker.yml create mode 100644 docker/Dockerfile create mode 100644 docker/docker-entrypoint.sh diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..dbdaf41 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,4 @@ +.git +.github +node_modules +_site diff --git a/.github/workflows/auto-release.yml b/.github/workflows/auto-release.yml index 29bfba0..aa3bdfc 100644 --- a/.github/workflows/auto-release.yml +++ b/.github/workflows/auto-release.yml @@ -73,3 +73,10 @@ jobs: # Pre-releases are for testing and never go live. if: steps.v.outputs.skip == 'false' && steps.v.outputs.pre == 'false' run: gh workflow run release.yml --repo "$GITHUB_REPOSITORY" --ref "${{ steps.v.outputs.tag }}" -f tag="${{ steps.v.outputs.tag }}" + + - name: Publish the Docker image + # Same pattern as the deploy above: the image is built and pushed from the + # release tag by docker.yml. Pre-releases get one too: an image tag is + # pulled on purpose, so a test image costs nothing. + if: steps.v.outputs.skip == 'false' + run: gh workflow run docker.yml --repo "$GITHUB_REPOSITORY" --ref "${{ steps.v.outputs.tag }}" -f tag="${{ steps.v.outputs.tag }}" diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml new file mode 100644 index 0000000..d62dc9a --- /dev/null +++ b/.github/workflows/docker.yml @@ -0,0 +1,72 @@ +name: Build and push Docker image + +# Every push to main publishes :latest and :. A release publishes : +# built from its tag: auto-release.yml dispatches this workflow alongside the Pages +# deploy, because releases created with the workflow token do not fire the +# "released" event. Hand-published releases fire it directly. +on: + push: + branches: [main] + release: + types: [released, prereleased] + workflow_dispatch: + inputs: + tag: + description: Existing release tag to build (e.g. v2.10.0); empty builds main + required: false + +permissions: + contents: read + packages: write + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + ref: ${{ github.event.release.tag_name || inputs.tag }} + + - name: Work out the image tags + id: tags + env: + TAG: ${{ github.event.release.tag_name || inputs.tag }} + run: | + set -euo pipefail + # The image is named after this repository (ghcr.io//, lowercased). + image=ghcr.io/${GITHUB_REPOSITORY,,} + if [ -n "$TAG" ]; then + want="v$(jq -r .version package.json)" + if [ "$TAG" != "$want" ]; then + echo "::error::Release tag $TAG does not match package.json version ($want)" + exit 1 + fi + echo "tags=$image:${TAG#v}" >> "$GITHUB_OUTPUT" + else + echo "tags=$image:latest,$image:$GITHUB_SHA" >> "$GITHUB_OUTPUT" + fi + + - name: Set up QEMU + uses: docker/setup-qemu-action@v3 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Log in to GitHub Container Registry + uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Build and push + uses: docker/build-push-action@v6 + with: + context: . + file: docker/Dockerfile + platforms: linux/amd64,linux/arm64 + push: true + tags: ${{ steps.tags.outputs.tags }} + cache-from: type=gha + cache-to: type=gha,mode=max diff --git a/docker/Dockerfile b/docker/Dockerfile new file mode 100644 index 0000000..1228b19 --- /dev/null +++ b/docker/Dockerfile @@ -0,0 +1,16 @@ +FROM node:26-slim + +COPY . /series-of-tubes +WORKDIR /series-of-tubes + +RUN npm install + +COPY docker/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh +RUN chmod +x /usr/local/bin/docker-entrypoint.sh \ + && chown -R node:node /series-of-tubes + +USER node + +EXPOSE 8080 7777 + +ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"] diff --git a/docker/docker-entrypoint.sh b/docker/docker-entrypoint.sh new file mode 100644 index 0000000..1d5938d --- /dev/null +++ b/docker/docker-entrypoint.sh @@ -0,0 +1,42 @@ +#!/usr/bin/env bash +set -u +cd /series-of-tubes + +# MCP_MODE picks what runs: browser (default) serves the game page and relays the +# player's tab to the MCP server; headless runs a game of its own, no page needed. +mode=${MCP_MODE:-browser} +case "$mode" in + browser|headless) ;; + *) echo "[entrypoint] MCP_MODE must be browser or headless, not '$mode'" >&2; exit 1 ;; +esac + +# Everything after the image name is passed to the MCP server as well +# (node scripts/mcp.js --help lists the options). +extra=("$@") + +# A container needs 0.0.0.0 to be reachable at all; default --http unless given. +http=(--http 0.0.0.0:7777) +for a in "${extra[@]}"; do [ "$a" = --http ] && http=(); done + +pids=() +start() { "$@" & pids+=("$!"); } + +shutdown() { + trap '' TERM INT + kill -TERM "${pids[@]}" 2>/dev/null + wait "${pids[@]}" 2>/dev/null + exit 0 +} +trap shutdown TERM INT + +if [ "$mode" = browser ]; then + start npm run dev -- --host 0.0.0.0 --port 8080 + start npm run mcp -- --browser "${http[@]}" "${extra[@]}" +else + start npm run mcp -- "${http[@]}" "${extra[@]}" +fi + +status=0 +wait -n || status=$? +echo "[entrypoint] a process exited with status $status; stopping the container" >&2 +shutdown diff --git a/docs/MCP.md b/docs/MCP.md index 4398617..4c6b590 100644 --- a/docs/MCP.md +++ b/docs/MCP.md @@ -77,6 +77,39 @@ claude mcp add --transport http seriesoftubes http://127.0.0.1:7777/mcp - **Either session.** `--http` works headless and with `--browser` alike: then a client elsewhere drives the game in the player's tab, while the relay stays where `npm run dev` put it. +### In a container + +Every push to `main` and every release publishes a multi-arch (amd64/arm64) image at +`ghcr.io/fjaeckel/seriesoftubes`, built from the repo by the `docker.yml` workflow: `latest` and the commit SHA on +pushes, the release's version (pre-releases included) on releases. It packages the dev server and the MCP server; +`node scripts/mcp.js --help` options go after the image name, and `--http 0.0.0.0:7777` is the default (a container +bound to loopback would be unreachable; pass your own `--http` to override). + +`MCP_MODE=headless` runs just the MCP server with a game of its own; the default (`browser`) also serves the +development page so a browser tab can play it, as above. + +```sh +docker run -d -p 7777:7777 -e MCP_MODE=headless ghcr.io/fjaeckel/seriesoftubes +claude mcp add --transport http seriesoftubes http://127.0.0.1:7777/mcp + +# Options are passed to scripts/mcp.js; the token is its own env var. +docker run -d -p 7777:7777 -e MCP_MODE=headless -e SOT_MCP_TOKEN=secret \ + ghcr.io/fjaeckel/seriesoftubes --clock realtime --pace 60000 + +# The browser session: open http://localhost:8080, then Settings → Agent API. +docker run -d -p 8080:8080 -p 7777:7777 ghcr.io/fjaeckel/seriesoftubes +``` + +`load_save` and `export_save` take JSON only unless the server runs with `--save-dir`; mount a volume for it: + +```sh +docker run -d -p 7777:7777 -e MCP_MODE=headless -v sot-saves:/saves \ + ghcr.io/fjaeckel/seriesoftubes --save-dir /saves +``` + +What "Over HTTP" says applies to the container too: the mapped port is reachable by anything that can reach the host, +so set a token before exposing one, and there is no TLS. + ## The clock Every session has one of two clocks, and `schema` (section `mode`) says which: