15955f552d
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.
83 lines
3.1 KiB
Python
83 lines
3.1 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.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.
|
|
DOMAIN_REFUSALS = (UnknownReference, UnknownTag, DuplicateTagName)
|
|
|
|
|
|
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"]
|