deploy: run the MCP server in k3s under the paper-doc namespace

The server has to be reachable by the Harness, Claude Code and Codex, and all
three of those are clients of an address rather than of a source tree — a
stdio child process only serves whichever machine spawned it. So it is packaged
and deployed: namespace `paper-doc`, one Deployment, one NodePort Service at
`http://192.168.1.88:30931/mcp` behind a bearer token, talking to the
in-cluster TiDB Service rather than the node's NodePort.

The namespace is `paper-doc` and not `paper_doc`, which is not a preference:
a namespace name is an RFC 1123 label, underscores are outside that alphabet,
and the API server rejects it outright. The database keeps its underscore.

Two routes were added to the server for the deployment, and they are the only
unauthenticated ones. `/healthz` answers "is this process alive" without
touching anything, `/readyz` answers "can it serve" by running `SELECT 1`. The
split is the point: a failing readiness probe takes the pod out of the
Service's endpoints and puts it back when TiDB returns, while a failing
liveness probe kills a process that was working correctly.

There is no container runtime on this host — k3s runs containerd and neither
`ctr` nor `crictl` builds from a Dockerfile — so `deploy/build-mcp-image.sh`
builds inside a throwaway privileged docker-in-docker pod, mounting the working
tree through a hostPath so the build context is the tree you are looking at,
uncommitted edits included. It reads the registry credentials out of the
cluster's own pull secret, so no password is in the script or in a shell
history. One Dockerfile serves both entry points, because the API and the MCP
server share the domain layer and differ by one argv.

Verified against the deployed Service, not against a local process: 47 MCP
checks pass over the NodePort, and the Node MCP SDK — the one the Harness's
mcp-client plugin uses — lists all 29 tools and calls them. The same 47 pass in
stdio and against a local HTTP server, and the REST suite still passes its 45.
This commit is contained in:
2026-09-21 00:08:17 +08:00
parent 5a6461eeec
commit 7e7820f823
10 changed files with 735 additions and 14 deletions
+133
View File
@@ -0,0 +1,133 @@
#!/usr/bin/env bash
# Build the paper-doc image and push it to the registry the cluster pulls from.
#
# Why a pod builds it
# -------------------
# There is no container runtime on this host: k3s runs containerd, and the
# binaries on the node are the k3s ones (`ctr`, `crictl`), neither of which
# builds from a Dockerfile. So the build runs where a builder already exists —
# a privileged docker-in-docker pod inside the cluster — and the source reaches
# it through a hostPath mount rather than `kubectl cp`, which keeps the build
# context exactly the working tree you are looking at, uncommitted edits
# included.
#
# The credentials are read out of the cluster's own pull secret rather than
# taken as arguments, so this script has none in it and nothing is pasted into a
# shell history.
#
# Usage (from anywhere):
#
# deploy/build-mcp-image.sh # tag :v1
# deploy/build-mcp-image.sh v2 # tag :v2
# IMAGE=... deploy/build-mcp-image.sh # a different repository entirely
#
# Prerequisite: `export KUBECONFIG=$HOME/.kube/config` (the k3s binary defaults
# to /etc/rancher/k3s/k3s.yaml, which is root-only on this host).
set -euo pipefail
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
TAG="${1:-v1}"
IMAGE="${IMAGE:-registry.cn-hangzhou.aliyuncs.com/mcp_skill/paper-doc-mcp:${TAG}}"
BUILD_NAMESPACE="${BUILD_NAMESPACE:-default}"
BUILD_POD="${BUILD_POD:-dind-build-paper-doc}"
REGISTRY_HOST="${IMAGE%%/*}"
# The old build pod is what proved this image is already on the node; the same
# one is used here so a rebuild does not have to reach docker.io, which this
# network cannot.
BUILDER_IMAGE="${BUILDER_IMAGE:-docker:27-dind}"
export KUBECONFIG="${KUBECONFIG:-$HOME/.kube/config}"
log() { printf '\n=== %s\n' "$*"; }
cleanup() {
log "removing the build pod"
kubectl -n "$BUILD_NAMESPACE" delete pod "$BUILD_POD" --ignore-not-found --wait=false >/dev/null 2>&1 || true
}
trap cleanup EXIT
log "build context: $REPO_ROOT/backend"
log "image: $IMAGE"
kubectl -n "$BUILD_NAMESPACE" delete pod "$BUILD_POD" --ignore-not-found >/dev/null 2>&1 || true
log "starting the docker-in-docker builder"
# `DOCKER_TLS_CERTDIR=""` keeps the daemon on tcp://localhost:2375 inside the
# pod, so `docker` in the same container needs no certificate dance. The pod is
# privileged because that is what a docker daemon needs; it lives for the length
# of one build and is deleted by the trap.
cat <<YAML | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
name: ${BUILD_POD}
namespace: ${BUILD_NAMESPACE}
labels:
app.kubernetes.io/name: paper-doc
app.kubernetes.io/component: image-build
spec:
restartPolicy: Never
containers:
- name: dind
image: ${BUILDER_IMAGE}
securityContext:
privileged: true
env:
- name: DOCKER_TLS_CERTDIR
value: ""
volumeMounts:
- name: workspace
mountPath: /workspace
- name: docker-storage
mountPath: /var/lib/docker
volumes:
- name: workspace
hostPath:
path: ${REPO_ROOT}
type: Directory
- name: docker-storage
emptyDir: {}
YAML
log "waiting for the daemon"
kubectl -n "$BUILD_NAMESPACE" wait --for=condition=Ready "pod/$BUILD_POD" --timeout=180s
for _ in $(seq 1 30); do
if kubectl -n "$BUILD_NAMESPACE" exec "$BUILD_POD" -- docker info >/dev/null 2>&1; then
break
fi
sleep 2
done
kubectl -n "$BUILD_NAMESPACE" exec "$BUILD_POD" -- docker info --format 'daemon ok: {{.ServerVersion}}'
log "logging in to $REGISTRY_HOST"
# Read out of the pull secret the cluster already uses: the push credential and
# the pull credential are the same account, and a second copy of it in a script
# is a second place it can go stale.
kubectl -n default get secret aliyun-acr-secret -o jsonpath='{.data.\.dockerconfigjson}' \
| base64 -d \
| python3 -c '
import json, sys
auth = next(iter(json.load(sys.stdin)["auths"].values()))
print(auth["username"], auth["password"])
' \
| kubectl -n "$BUILD_NAMESPACE" exec -i "$BUILD_POD" -- sh -c \
'read -r user pass; printf "%s" "$pass" | docker login -u "$user" --password-stdin "$0"' "$REGISTRY_HOST"
log "building"
# --network=host: the build needs the same mirror access the node has for pip,
# and the pod's own network namespace would otherwise be a second, untested path
# to the internet.
kubectl -n "$BUILD_NAMESPACE" exec "$BUILD_POD" -- \
docker build --network=host --tag "$IMAGE" /workspace/backend
log "pushing"
kubectl -n "$BUILD_NAMESPACE" exec "$BUILD_POD" -- docker push "$IMAGE"
log "done: $IMAGE"
cat <<EOF
Next:
kubectl -n paper_doc set image deployment/paper-doc-mcp mcp=$IMAGE
kubectl -n paper_doc rollout status deployment/paper-doc-mcp
EOF