Files
paper-doc/deploy/k8s/10-paper-doc-mcp.yaml
T
govin 15955f552d backend: give the reference library the MCP tools it was missing, and fix the one that broke
The reference library landed with a full REST API and no MCP surface at all:
an agent could cite `reference_id: 42` — the citation is validated now — but
could not look up what 42 was, create it, or find out whether the library
already had it. That is the citation half of "generate the paper, then write it
in" missing, and it is the half an agent is worst at doing by hand.

Twelve tools, mirroring the REST surface plus one addition each way:

- `reference_*` — search, read, create, update, delete, plus
  `reference_import`, which takes a whole pasted bibliography in one call and
  reports what it skipped (an existing DOI or an identical title) and what it
  could not read, one bad entry at a time rather than losing the other nineteen;
  and `reference_citations`, which answers "what is this cited for" before a
  rename or a delete. `reference_list`'s keyword search across title, container,
  DOI and author names is the de-duplication path that `reference_import` uses.
- `reference_tag_*` — the five CRUD tools. Deleting a tag drops the labelling
  and leaves the literature, which is the opposite of what the field library
  needs and the same choice the REST route makes.

Two things had to be fixed to get here, both found by testing rather than
reading:

`template_list` was crashing. The rename that turned a heading into a title and
its use into a placement changed `TemplateListItem.field_count` to
`placement_count` and left the tool reading the old attribute, so the call died
with `Error executing tool template_list` — unreadable, and live in the
cluster. The suite passed 47 checks while this was broken because it never
called `template_list`: the uncovered tools were exactly the read-only ones, so
the write paths were all green and the browse path was not. The suite now
covers all 41 tools — 76 checks — and step 5 asserts the shape each read tool
returns, not merely that it returned.

`DOMAIN_REFUSALS` in the tool registry held one class, `UnknownReference`. The
tag rules arrived with the tag tools and raise two more, so 「标签不存在:9」 and
「标签「必读」已存在」 would have reached a model as `Error executing tool …`.
The tuple is now the list of every refusal a tool is expected to translate, and
a new one belongs in it on the day it is written.

`reference_update` takes its changes as one nested object rather than 38 keyword
parameters: a nested model keeps `model_fields_set`, so an omitted field stays
absent while an explicit null clears the column. Flattened, the two are
indistinguishable — every omitted field arrives as None — which is the same
problem `paper_update` solves by rebuilding its payload from what it was given.

Verified against the deployed service, not a local process: 76 checks pass over
the NodePort, then the same 76 over stdio and against a local HTTP server, and
the REST suite still passes its 55. The image is rebuilt as v4 and the
Deployment follows it, because `imagePullPolicy: IfNotPresent` means re-pushing
a tag the node already holds changes nothing.
2026-09-22 18:30:24 +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:v4
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:v4
# 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:v4
# 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}}