Files
paper-doc/deploy
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
..

部署到 k3s

paper-doc 的 MCP 服务跑在 k3s 里,命名空间 paper-doc,客户端通过 http://192.168.1.88:30931/mcp 连接。

为什么不是 paper_doc:Kubernetes 的命名空间名必须是 RFC 1123 label, 下划线不在允许的字符集里([a-z0-9]([-a-z0-9]*[a-z0-9])?),API Server 会直接拒绝。 所以命名空间用连字符 paper-doc;数据库名和表名仍然是 paper_doc,两者不冲突。

部署了什么

资源 名字 说明
Namespace paper-doc deploy/k8s/00-namespace.yaml
Deployment paper-doc-mcp 1 副本,跑 MCP 服务的 http 传输
Service paper-doc-mcp NodePort 30931 → 容器 8931
ConfigMap paper-doc-config 非敏感环境变量(数据库地址、监听配置)
Secret paper-doc-secrets DB_USER / DB_PASSWORD / MCP_HTTP_TOKEN
Secret aliyun-acr 镜像仓库拉取凭证(从 default 复制)

镜像:registry.cn-hangzhou.aliyuncs.com/mcp_skill/paper-doc-mcp:v2

数据库:TiDB 已经在这个集群里,Deployment 用集群内的 Service tidb-tidb.tidb:4000,而不是宿主机用的 NodePort 192.168.1.88:32738。 两者是同一份数据;集群内用 Service 的好处是节点地址变了也不用改配置。

访问地址

从哪里连 地址
宿主机 / 局域网 http://192.168.1.88:30931/mcp
集群内 Pod http://paper-doc-mcp.paper-doc.svc.cluster.local:8931/mcp
健康检查(免鉴权) http://192.168.1.88:30931/healthz、/readyz

除 /healthz 和 /readyz 外,所有请求都要带 Authorization: Bearer <MCP_HTTP_TOKEN>,否则返回 401。 Token 在 Secret 里,取法:

export KUBECONFIG=$HOME/.kube/config
kubectl -n paper-doc get secret paper-doc-secrets \
  -o jsonpath='{.data.MCP_HTTP_TOKEN}' | base64 -d; echo

日常操作

先记住这一句,否则 kubectl 会去读 root-only 的 /etc/rancher/k3s/k3s.yaml 并报 permission denied:

export KUBECONFIG=$HOME/.kube/config
# 状态
kubectl -n paper-doc get deploy,svc,pods
kubectl -n paper-doc logs deploy/paper-doc-mcp --tail=50

# 重新构建并推送镜像(需要一个 tag,见下面「两个坑」)
deploy/build-mcp-image.sh v3

# 发布新版本
kubectl -n paper-doc set image deployment/paper-doc-mcp \
  mcp=registry.cn-hangzhou.aliyuncs.com/mcp_skill/paper-doc-mcp:v3
kubectl -n paper-doc rollout status deployment/paper-doc-mcp

# 回滚
kubectl -n paper-doc rollout undo deployment/paper-doc-mcp

# 改配置 / 换 token
kubectl -n paper-doc edit configmap paper-doc-config
kubectl -n paper-doc create secret generic paper-doc-secrets \
  --from-literal=DB_USER='Govin' \
  --from-literal=DB_PASSWORD='<tidb-password>' \
  --from-literal=MCP_HTTP_TOKEN="$(openssl rand -hex 32)" \
  --dry-run=client -o yaml | kubectl apply -f -
kubectl -n paper-doc rollout restart deployment/paper-doc-mcp

验证部署——不是看 Pod 是不是 Running,而是真的用 MCP 客户端跑一遍:

cd backend
.venv/bin/python scripts/smoke_mcp.py \
  --url http://192.168.1.88:30931/mcp --token "$(cat /tmp/paper-mcp-token)"
# 47 项检查全过 = 集群里这套东西真的能写论文

构建:为什么是 DinD Pod

这台宿主机上没有容器运行时——k3s 用的是 containerd,节点上的 ctr / crictl 都是 k3s 的软链,谁都不能从 Dockerfile 构建。所以构建放在集群里一个临时的 docker-in-docker Pod 里做,源码通过 hostPath 挂进去(/workspace), 这样构建上下文就是当前工作区,未提交的改动也在里面。

deploy/build-mcp-image.sh 把这一整套包好了:起 Pod → 登录 → 构建 → 推送 → 删 Pod (trap 保证失败也会删)。仓库凭证是从集群里已有的 aliyun-acr-secret 读出来的, 所以脚本里没有任何密码,也不会进 shell history。

两个坑(都踩过了,别再踩)

1. 镜像 tag 复用会发布不出新代码。 Deployment 的 imagePullPolicy: IfNotPresent,节点按 tag 缓存镜像。 用同样的 :v1 重新构建推送后,Pod 重启拿到的还是旧镜像—— 现象是新 Pod 起来了、但行为跟没改一样。每次构建换一个 tag(v2、v3…), 或者临时把 imagePullPolicy 改成 Always(代价是每次启动都要连仓库)。

2. 源码权限 0600 会让容器读不到代码。 工作区的文件是 rw-------,COPY 会把权限一起带进镜像, 于是非 root(uid 10001)的容器启动即 can't open file '/app/scripts/mcp_server.py': [Errno 13] Permission denied, 然后 CrashLoopBackOff。Dockerfile 里 RUN chmod -R a+rX /app 解决—— 镜像里的东西只需要可读,不需要任何人可写。

探针:为什么是两个

探针 路径 语义
liveness /healthz 进程还活着吗——不碰数据库,所以数据库抖一下不会变成反复重启
readiness /readyz 现在能服务吗——执行 SELECT 1,TiDB 不通就把 Pod 摘出 Service,通了自动加回来

失败 readiness 只是把 Pod 从负载均衡里摘掉,失败 liveness 会杀掉进程。 数据库短暂不可用只应该是前者,所以这个分工是刻意的。

还没有部署的

  • REST API:同一个镜像,换 command 即可(uvicorn app.main:app --host 0.0.0.0 --port 8000), 再加一个 init 容器跑 alembic upgrade head。配置模板写在 deploy/k8s/10-paper-doc-mcp.yaml 末尾的注释里,解开注释即可。
  • 前端 SPA:需要额外构建(pnpm build)+ nginx 镜像,目前没做。

文件清单

deploy/
├── build-mcp-image.sh          # DinD 构建并推送镜像
├── README.md                   # 本文件
└── k8s/
    ├── 00-namespace.yaml
    ├── 10-paper-doc-mcp.yaml   # ConfigMap + Deployment + Service(含 API 的注释模板)
    └── secret.example.yaml     # Secret 模板,真值不入库