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.
Records the decisions the 参考文献 list now rests on: a citation is a place in
the text and an entry is a work, so a paper with 86 citations to 65 works lists
65 entries; the entries are written by `app/citation_styles` and a client prints
them verbatim; a gap is reported through `missing` rather than quietly rendered
as a shorter entry.
Also documents `scripts/check_citation_styles.py` — the formatter is checked
with no server and no database, because a wrong branch prints something that
looks like a bibliography entry instead of failing loudly — and why the
reference smoke test now stamps a token into everything it creates.
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.
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.
`docs/MCP.md` is the manual a person needs to put this in front of an agent:
the 29 tools with their arguments, the workflow ("generate, then write it in"
in one call, versus paragraph by paragraph), the error contract, and the exact
configuration for the three clients in play — the Harness's
`cordis.patch.yml`, Claude Code's `claude mcp add` and `.mcp.json`, and Codex's
`config.toml` — including the note that a new Harness entry has to sit inside
the `insert:` list or it is silently treated as an override of an entry that
does not exist.
`overview.md` gains the section that belongs in a design document rather than a
manual: why the MCP surface is shaped differently from the REST one, and the
two rules a new tool has to follow — keep the docstring to a line or two,
because it is sent with every request, and register with
`structured_output=False`, because the inferred envelope sends the same JSON
twice and clients disagree about which copy counts.