Files
paper-doc/deploy/k8s/10-paper-doc-mcp.yaml
T
govin 9f2bbe50eb backend: let a model ask for a line break, and read the 参考文献 list back
The paper model gained two things while the MCP layer was not looking, and
both were invisible from a tool call.

`paper_sentence.line_break_before` — the flag a paragraph needs so a formula,
a list of items or an author line can start a line of its own — was not in
`SentenceSpec`, and `sentence_inputs` dropped it on the floor: a model could
write the field, watch the call succeed, and get prose back. It is now part of
every write path (`paragraph_write`, `paper_write`, `sentence_add`,
`sentence_update`) and of every read path (`sentence_row` reports it, so a
model can see the lines before moving one). Two bugs fell out of doing it
properly:

* `paragraph_move` rebuilt its sentences without the flag, so moving a
  paragraph that carried a formula turned it into prose. It also passed the
  *source* sorts through, which interleaved the moved sentences with the
  target's own — the merged paragraph read in an order neither writer wrote.
  Both are fixed; the tool now appends, as its own description promised.
* `document_text` printed a formula run into the sentence before it. The paper
  view renders `$$…$$` as a block, so the seam rules are now the same in both
  places, with a comment on each side naming the other.

`PaperDocumentRead.references` and `reference_style` — the per-work 参考文献
list the backend now assembles and formats — were reachable over REST but not
over MCP: `paper_document(format="json")` returned citations and nothing to
point them at, even though docs/MCP.md already described the list. The json
form now carries the entries (index, reference_id, text, missing, citations)
and the style name, so a model quotes the bibliography instead of assembling a
second one out of the same fields.

smoke_mcp.py grows from 76 checks to 99 over two new steps — the line-break
step pins the display-formula rule, the marker toggle and the moving case; the
bibliography step cites one work from two sentences and checks that the text,
the entry and both markers agree on one number.
2026-09-23 11:49:39 +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:v5
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:v5
# 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:v5
# 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}}