Files
paper-doc/deploy/k8s/10-paper-doc-mcp.yaml
T
govin 7e7820f823 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.
2026-09-21 00:08:17 +08:00

193 lines
6.2 KiB
YAML

# paper-doc MCP server: ConfigMap, Deployment, Service.
#
# The REST API and the MCP server are the same image with different commands.
# Only the MCP server is deployed here, because that is what a client connects
# to; the API is described in a commented block at the end of this file rather
# than deployed, so that turning it on is a decision rather than a surprise.
#
# The database is TiDB, already running in this cluster as `tidb-tidb.tidb:4000`
# — the in-cluster Service, not the 32738 NodePort the host uses. Both reach the
# same rows; the Service is the one that survives the node's address changing.
---
apiVersion: v1
kind: ConfigMap
metadata:
name: paper-doc-config
namespace: paper-doc
labels:
app.kubernetes.io/name: paper-doc
data:
DB_HOST: tidb-tidb.tidb
DB_PORT: "4000"
DB_NAME: paper_doc
APP_NAME: paper-doc API
DEBUG: "false"
# The container's own defaults, restated here because the Deployment is where
# a reader looks for them.
MCP_TRANSPORT: http
MCP_HOST: 0.0.0.0
MCP_PORT: "8931"
MCP_PATH: /mcp
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: paper-doc-mcp
namespace: paper-doc
labels:
app.kubernetes.io/name: paper-doc
app.kubernetes.io/component: mcp
spec:
# One replica. The server is stateless — every tool opens its own database
# session and closes it — so scaling is safe, but a second replica would only
# add connections to TiDB without adding throughput a model can use.
replicas: 1
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 1
maxUnavailable: 0
selector:
matchLabels:
app.kubernetes.io/name: paper-doc
app.kubernetes.io/component: mcp
template:
metadata:
labels:
app.kubernetes.io/name: paper-doc
app.kubernetes.io/component: mcp
spec:
imagePullSecrets:
- name: aliyun-acr
securityContext:
runAsNonRoot: true
runAsUser: 10001
fsGroup: 10001
seccompProfile:
type: RuntimeDefault
containers:
- name: mcp
image: registry.cn-hangzhou.aliyuncs.com/mcp_skill/paper-doc-mcp:v2
imagePullPolicy: IfNotPresent
ports:
- name: http
containerPort: 8931
envFrom:
- configMapRef:
name: paper-doc-config
env:
- name: DB_USER
valueFrom:
secretKeyRef:
name: paper-doc-secrets
key: DB_USER
- name: DB_PASSWORD
valueFrom:
secretKeyRef:
name: paper-doc-secrets
key: DB_PASSWORD
# Without it the HTTP transport is unauthenticated. The server warns
# on stderr when it binds a non-loopback address and finds no token,
# which is the only signal a reader gets that this key is missing.
- name: MCP_HTTP_TOKEN
valueFrom:
secretKeyRef:
name: paper-doc-secrets
key: MCP_HTTP_TOKEN
# Readiness asks the database; liveness does not. A TiDB blip should
# take the pod out of the Service's endpoints and put it back when the
# blip ends — not restart a process that is working correctly.
readinessProbe:
httpGet:
path: /readyz
port: http
initialDelaySeconds: 5
periodSeconds: 10
timeoutSeconds: 5
failureThreshold: 3
livenessProbe:
httpGet:
path: /healthz
port: http
initialDelaySeconds: 10
periodSeconds: 30
timeoutSeconds: 5
failureThreshold: 3
resources:
requests:
cpu: 50m
memory: 128Mi
limits:
cpu: 1000m
memory: 512Mi
securityContext:
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
capabilities:
drop: ["ALL"]
volumeMounts:
- name: tmp
mountPath: /tmp
volumes:
- name: tmp
emptyDir: {}
---
apiVersion: v1
kind: Service
metadata:
name: paper-doc-mcp
namespace: paper-doc
labels:
app.kubernetes.io/name: paper-doc
app.kubernetes.io/component: mcp
spec:
# NodePort, not ClusterIP: the clients that matter here are not in the
# cluster. The Harness, Claude Code and Codex all run on the node or on a
# machine on the LAN, and `http://192.168.1.88:30931/mcp` is the same address
# from both. In-cluster callers use the ClusterIP on port 8931.
type: NodePort
selector:
app.kubernetes.io/name: paper-doc
app.kubernetes.io/component: mcp
ports:
- name: http
port: 8931
targetPort: http
nodePort: 30931
# --- the REST API, if you want it in the cluster too -------------------------
#
# Same image, different command; it needs no MCP_HTTP_TOKEN and answers on 8000.
# The schema has to exist before the API serves it, which is what the init
# container is for:
#
# ---
# apiVersion: apps/v1
# kind: Deployment
# metadata:
# name: paper-doc-api
# namespace: paper-doc
# spec:
# replicas: 1
# selector:
# matchLabels: {app.kubernetes.io/name: paper-doc, app.kubernetes.io/component: api}
# template:
# metadata:
# labels: {app.kubernetes.io/name: paper-doc, app.kubernetes.io/component: api}
# spec:
# imagePullSecrets: [{name: aliyun-acr}]
# initContainers:
# - name: migrate
# image: registry.cn-hangzhou.aliyuncs.com/mcp_skill/paper-doc-mcp:v2
# command: ["alembic", "upgrade", "head"]
# envFrom: [{configMapRef: {name: paper-doc-config}}]
# env: [...] # the same three secret keys as above
# containers:
# - name: api
# image: registry.cn-hangzhou.aliyuncs.com/mcp_skill/paper-doc-mcp:v2
# command: ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
# ports: [{name: http, containerPort: 8000}]
# envFrom: [{configMapRef: {name: paper-doc-config}}]
# env: [...]
# readinessProbe: {httpGet: {path: /api/health, port: http}}