Build container images for easy MCP use

This commit is contained in:
Wolfgang Nagele 2026-11-05 10:07:37 -05:00 • committed by Frederic Jung
parent 908f2e0de9
commit 9c8cda44c1
No known key found for this signature in database
6 changed files with 174 additions and 0 deletions

4
.dockerignore Normal file
View file

@ -0,0 +1,4 @@
.git
.github
node_modules
_site

View file

@ -73,3 +73,10 @@ jobs:
# Pre-releases are for testing and never go live. # Pre-releases are for testing and never go live.
if: steps.v.outputs.skip == 'false' && steps.v.outputs.pre == 'false' 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 }}" 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 }}"

72
.github/workflows/docker.yml vendored Normal file
View file

@ -0,0 +1,72 @@
name: Build and push Docker image
# Every push to main publishes :latest and :<sha>. A release publishes :<version>
# 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/<owner>/<repo>, 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

16
docker/Dockerfile Normal file
View file

@ -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"]

View file

@ -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

View file

@ -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 - **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 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 ## The clock
Every session has one of two clocks, and `schema` (section `mode`) says which: Every session has one of two clocks, and `schema` (section `mode`) says which: