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
+28 -2
View File
@@ -332,7 +332,7 @@ connects to (behind a bearer token). The package is split so that only
```
app/mcp/
├── server.py transports, CLI, and the instructions sent at initialize
├── server.py transports, CLI, health probes, the instructions sent at initialize
├── support.py sessions, JSON shaping, heading resolution, the one text splitter
├── specs.py the shapes a model may send (a paragraph, a sentence, a citation)
├── selfcheck.py --check: connect once and print the tool surface
@@ -340,6 +340,12 @@ app/mcp/
by register_all(), each tool three lines around an app.crud call
```
`/healthz` and `/readyz` exist for Kubernetes and are the only unauthenticated
routes. They answer different questions on purpose: liveness touches nothing, so
a database that is briefly unreachable cannot become a restart loop, while
readiness runs `SELECT 1` so the pod leaves the Service's endpoints while TiDB
is down and rejoins when it is not.
Two decisions are worth knowing before adding a tool. **Results are registered
with `structured_output=False`**: inferred from a `-> str` annotation, the SDK
publishes a `{"result": …}` envelope and sends the JSON twice, once as
@@ -499,8 +505,13 @@ paper-doc/
│ │ └── views/ # route-level components (papers/, templates/)
│ ├── package.json
│ └── vite.config.ts
├── deploy/ # packaging and the k3s manifests
│ ├── build-mcp-image.sh # build + push the image from a DinD pod
│ ├── k8s/ # namespace, ConfigMap, Deployment, Service
│ └── README.md
└── docs/ # project documentation
└── OVERVIEW.md
├── OVERVIEW.md
└── MCP.md # the MCP manual: tools, workflows, client configs
```
## Getting Started
@@ -584,3 +595,18 @@ cd backend
.venv/bin/python scripts/mcp_server.py --check
.venv/bin/python scripts/smoke_mcp.py
```
**Deployment**
The MCP server runs in k3s in the `paper-doc` namespace and is reached at
`http://192.168.1.88:30931/mcp`, behind a bearer token. 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, with the working tree mounted in
through a hostPath so the build context is what you are actually looking at.
The database is the in-cluster TiDB Service (`tidb-tidb.tidb:4000`), not the
NodePort the host uses. `deploy/README.md` has the commands, the two traps
worth knowing (a reused image tag silently keeps the cached image; `COPY`
carries the working tree's `0600` file mode into the image and a non-root
container then cannot read its own code), and how to add the REST API to the
same namespace.