Files
paper-doc/backend/app/mcp/tools/registry.py
T
govin ebaf9e558b backend: let a model put a figure in the paper, and set a formula's alignment
Two things the editor gained and MCP could not do, both because the tool layer
had been told about the domain's columns by hand.

**A figure.** Bytes go to MinIO and the sentence keeps a Markdown address, so a
picture is ordinary text — which means the writing tools already carry it, and
the only half a model cannot do is the upload: it has bytes and no way to send
multipart. `image_upload` takes base64 and answers with the URL, the Markdown
and the *sentence object* the editor produces when a picture is dropped in, so a
figure is written by putting that object into `sentences` unchanged. It does not
fetch a URL the caller names: a service inside the cluster that will GET any
address it is handed is an SSRF primitive aimed at everything beside it.

The width argument is the reader's rule or it is refused. `{width=70%}` is
parsed by `frontend/src/utils/rich.ts`, and a value it cannot read is not an
error there — the picture just prints at its natural size. A size that silently
does not apply is worse than a refusal, so the syntax and the range (pixels
1–4000, per cent 1–100) are mirrored in `app/mcp/tools/images.py`, with the
usual comment naming the other side.

`paragraph_text` also had to learn what a figure is: a sentence holding nothing
but an image is a 插图 — the view prints it on its own line with the brackets'
text as its caption — and the text a tool hands back broke lines around a
display formula but not around a picture. Same rule as `figureOf`, same pair of
implementations, same warning about changing both.

**A formula's alignment.** `paper_sentence.formula_align` reached the editor and
the REST API and stopped there: `SentenceSpec` had no such field, so a model that
sent one got a successful call and a centred formula. The column is now declared,
carried through every write path and reported by every read path.

That is the second column lost the same way, so the fix is structural rather
than another two edits. `SENTENCE_FIELDS` is read from
`app.schemas.paper.SentenceInput` instead of written out, the payload is built
by one `sentence_payload()`, and the three append paths spread
`SentenceCreate(**item.model_dump())` rather than copying fields. One edit
remains — declaring the field in `specs.py` — and smoke_mcp.py's first step
compares the two field sets, so forgetting it now fails the suite instead of
losing the field. `sort` is declared too, which it never was: a model that sent
one had it dropped in silence.

smoke_mcp.py: 99 checks to 119. The figure step uploads a real 1x1 GIF (the same
bytes twice, and the key is the same object), writes the returned sentence as it
came back, checks the paragraph prints it alone on its line and that an image
inside a sentence does not break the line, and takes the four refusals — not a
picture, an unparseable size, an out-of-range one, not base64. The alignment step
writes a right-aligned formula, moves the sentence to left on its own, and takes
the paragraph to another position to prove the setting travels with it.

Deployed as v6, and the pod now carries MINIO_ENDPOINT (the in-cluster Service)
plus the two credential keys from the Secret; without them the image tool answers
with the missing variable names and every writing tool still works.
2026-09-24 10:54:27 +08:00

96 lines
3.5 KiB
Python

"""Tool registration helpers.
One shape, one place
--------------------
Every tool in this project returns a JSON string, and that is a decision
rather than a default: :func:`mcp_tool` registers with
``structured_output=False`` so a result travels as a text block and nothing
else. The alternative — letting the SDK infer a structured output schema from
the ``-> str`` annotation — publishes a ``{"result": "..."}`` envelope and
sends the same JSON twice, once as ``structuredContent`` and once as text.
Half the clients read only one of the two, and the other half reads both and
pays for the duplication twice.
So a tool is registered by::
@mcp_tool(server, title="列出论文")
def paper_list(...) -> str:
\"\"\"Short description — this text is what the model reads.\"\"\"
The docstring becomes the tool description verbatim, which makes it the most
expensive string in the project: it is sent with every request. Keep it to the
one or two lines a model needs to choose the tool, and put the reasoning in
the module docstring instead, where it costs nothing per request.
"""
from __future__ import annotations
from functools import wraps
from collections.abc import Callable
from typing import Any, TypeVar
from mcp.server.mcpserver import MCPServer
from mcp.server.mcpserver.exceptions import ToolError
from app.core.storage import StorageUnavailable, UnsupportedImage
from app.crud.reference import UnknownReference
from app.crud.reference_tag import DuplicateTagName, UnknownTag
F = TypeVar("F", bound=Callable[..., Any])
#: Refusals the data layer raises on purpose. Each one already carries a
#: message written for a reader; the only thing missing is the translation into
#: the transport's own error type, which is the whole job of the wrapper below.
#:
#: A tuple rather than a single class because there is one of these per rule,
#: and the tag rules arrived with the tag tools: catching only the reference one
#: would have let 「标签不存在:9」 reach the model as an unreadable
#: "Error executing tool ...", which is the exact failure this wrapper exists to
#: prevent. A new domain refusal belongs in this tuple on the day it is written.
#:
#: The two storage ones are here for the same reason. A bucket that is not
#: configured and a file that is not a picture are both answers rather than
#: faults — "缺少 MINIO_ENDPOINT" and "只接受 PNG / JPEG / GIF / WebP" are the
#: two things a caller can act on, and neither survives the wrapper as a stack
#: trace.
DOMAIN_REFUSALS = (
UnknownReference,
UnknownTag,
DuplicateTagName,
StorageUnavailable,
UnsupportedImage,
)
def mcp_tool(
server: MCPServer,
*,
name: str | None = None,
title: str | None = None,
) -> Callable[[F], F]:
"""Register one tool as unstructured text output."""
def decorator(fn: F) -> F:
@wraps(fn)
def wrapper(*args: Any, **kwargs: Any) -> Any:
# A refusal from the data layer becomes a message the model can read
# and retry against. Left unhandled it would reach the client as
# "Error executing tool ...", which says nothing about what to fix.
try:
return fn(*args, **kwargs)
except DOMAIN_REFUSALS as error:
raise ToolError(str(error)) from error
server.add_tool(
wrapper,
name=name or fn.__name__,
title=title,
structured_output=False,
)
return wrapper # type: ignore[return-value]
return decorator
__all__ = ["DOMAIN_REFUSALS", "mcp_tool"]