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:
+44
-9
@@ -11,6 +11,8 @@
|
||||
- 工具数量:**29 个**,按 `paper_` / `paragraph_` / `sentence_` / `template_` / `field_` 五组前缀
|
||||
- 协议:MCP 2024-11-05 ~ 2025-11-25(官方 Python SDK `mcp>=2.2,<3` 协商)
|
||||
- 传输:`stdio`(本地拉起)与 `streamable-http`(远程连接,支持 Bearer 口令),另兼容旧 `sse`
|
||||
- **已经部署在 k3s 里**:命名空间 `paper-doc`,端点 `http://192.168.1.88:30931/mcp`
|
||||
(打包、发布、回滚见 [deploy/README.md](../deploy/README.md))
|
||||
|
||||
---
|
||||
|
||||
@@ -48,7 +50,32 @@ tools : 29 field=5, paper=9, paragraph=5, sentence=5, template=5
|
||||
|
||||
从任何工作目录都能跑(脚本自己锚定 `sys.path`),所以客户端不需要配 `cwd`。
|
||||
|
||||
### 1.3 streamable-http(推荐给远程/常驻)
|
||||
### 1.3 连已经在跑的那一个(k3s 里)
|
||||
|
||||
不用自己起进程——服务已经部署好了:
|
||||
|
||||
```
|
||||
http://192.168.1.88:30931/mcp # 局域网 / 宿主机
|
||||
http://paper-doc-mcp.paper-doc.svc.cluster.local:8931/mcp # 集群内 Pod
|
||||
```
|
||||
|
||||
除 `/healthz`、`/readyz` 外都要带 `Authorization: Bearer <MCP_HTTP_TOKEN>`。
|
||||
取口令:
|
||||
|
||||
```bash
|
||||
export KUBECONFIG=$HOME/.kube/config
|
||||
kubectl -n paper-doc get secret paper-doc-secrets -o jsonpath='{.data.MCP_HTTP_TOKEN}' | base64 -d; echo
|
||||
```
|
||||
|
||||
自检与验证:
|
||||
|
||||
```bash
|
||||
curl -s http://192.168.1.88:30931/readyz
|
||||
cd backend && .venv/bin/python scripts/smoke_mcp.py \
|
||||
--url http://192.168.1.88:30931/mcp --token '<口令>' # 47 项检查
|
||||
```
|
||||
|
||||
### 1.4 streamable-http(自己起一个)
|
||||
|
||||
```bash
|
||||
cd /data/project/paper/backend
|
||||
@@ -63,7 +90,7 @@ cd /data/project/paper/backend
|
||||
|
||||
也可以用环境变量代替参数:`MCP_TRANSPORT` / `MCP_HOST` / `MCP_PORT` / `MCP_PATH` / `MCP_HTTP_TOKEN`。
|
||||
|
||||
### 1.4 跑冒烟测试
|
||||
### 1.5 跑冒烟测试
|
||||
|
||||
```bash
|
||||
cd /data/project/paper/backend
|
||||
@@ -185,15 +212,21 @@ enabled = true
|
||||
|
||||
> 参考:[Codex MCP Servers 文档](https://mintlify.wiki/openai/codex/configuration/mcp-servers)
|
||||
|
||||
### 2.4 远程(Windows 上的 Claude Code / Codex 连这台服务器)
|
||||
### 2.4 远程(Windows 上的 Claude Code / Codex)
|
||||
|
||||
三种做法,任选:
|
||||
服务已经部署在 k3s 里,直接连它就行,客户端填:
|
||||
|
||||
1. **HTTP + 口令**(最省事):服务器上跑 HTTP 模式,客户端填
|
||||
`http://192.168.1.88:8931/mcp` + `Authorization: Bearer ...`。
|
||||
2. **SSH 包一层 stdio**:客户端 `command = "ssh"`,让远端执行 `mcp_server.py`,
|
||||
协议走 SSH 的 stdin/stdout(见 ssh_intranet_skill 的 SSH_ASKPASS 写法)。
|
||||
3. **Tailscale + HTTP**:走 `100.64.0.1` 内网地址,仍然建议带口令。
|
||||
```
|
||||
URL: http://192.168.1.88:30931/mcp
|
||||
Header: Authorization: Bearer <MCP_HTTP_TOKEN>
|
||||
```
|
||||
|
||||
走 Tailscale 的机器把地址换成 `http://100.64.0.1:30931/mcp`(NodePort 在节点上监听,
|
||||
两个地址都通)。
|
||||
|
||||
不想暴露端口的话,还有一条 SSH 包 stdio 的路子:客户端 `command = "ssh"`,
|
||||
让远端执行 `mcp_server.py`,协议走 SSH 的 stdin/stdout
|
||||
(见 ssh_intranet_skill 的 SSH_ASKPASS 写法)。
|
||||
|
||||
---
|
||||
|
||||
@@ -472,4 +505,6 @@ MCP 独有:`paper_outline`(写前看骨架)、`paper_write` / `paper_write
|
||||
| HTTP 返回 421 | 绑定了非 127.0.0.1 但没走本次启动的 DNS-rebinding 关闭逻辑——确认用的是本项目入口,别包了一层反向代理改 Host |
|
||||
| DSH 里工具不出现 | 检查 cordis.patch.yml 的条目是否写在 `insert:` 里;`failOnStartupError: false` 会把启动期连接失败吞掉,看 dsh-web 日志确认 |
|
||||
| 工具调用超时 | DSH/Codex 侧加大 `toolCallTimeoutMs` / `tool_timeout_sec`;`paper_write_text` 写整篇会慢一些 |
|
||||
| k3s 里连不上 | `kubectl -n paper-doc get pods` 看是否 Ready;`/readyz` 返回 503 说明 TiDB 不通(`kubectl -n paper-doc logs deploy/paper-doc-mcp`) |
|
||||
| 改了代码但行为没变 | 镜像 tag 没换:`imagePullPolicy: IfNotPresent` 会继续用节点上缓存的同名镜像,换个 tag 重新构建 |
|
||||
| 日志里出现非 JSON 的 stdout 输出 | 不要在这个进程里 `print`——stdio 传输下会污染协议流(本项目的诊断都走 stderr) |
|
||||
|
||||
+28
-2
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user