Files
paper-doc/backend/app/mcp/tools/registry.py
T
govin d7bb777264 backend: add the reference library (参考文献)
One table per document the writer has read, and one for its contributors:

    reference          id, type, title, subtitle, title_translated,
                       container_title, volume, issue, pages, publisher,
                       publisher_place, event_*, publication_year/month/day,
                       accessed_date, doi, isbn, issn, url, patent_*,
                       standard_number, report_number, arxiv_id, abstract,
                       keywords, note, citation_key, language
    reference_author   reference_id, sort, name, family_name, given_name, role

The field set is the intersection of the formats a paper has to survive, taken
from the CSL JSON schema (103 fields, 45 types — what Zotero, Mendeley and
Pandoc exchange) against GB/T 7714-2015, BibTeX and RIS. The mapping is on
`app.models.reference` rather than in a commit message, because the next person
to add a column needs it more than this one does. Three decisions worth naming:

* **Partial dates.** Year, month and day are separate nullable integers, which
  is CSL's `issued`: a book has a year, a newspaper article a day, a patent its
  公告日期, and nothing invents the rest.
* **Contributors are rows, not a column.** A citation prints an ordered list
  with 编 / 译 marks, and styles rewrite names (「张三」 / "Zhang, S." /
  "S. Zhang"), so the printed form and its two halves are stored separately —
  display reads `name`, a reformatting style reads the halves, and an
  institutional author has neither.
* **`volume` / `issue` / `pages` are strings.** Journals print `12(Suppl.)`,
  `S1` and `e12345`, and a citation reproduces what is printed.

The library is global: the same article is cited from several papers, so the
entry cannot belong to one of them. The citation stays on the paper side in
`paper_sentence_reference`, which now carries a real foreign key to `reference`
(`ON DELETE RESTRICT`) — the column had been a loose integer waiting for this
table. A sentence may quote several documents and a document may be quoted by
many sentences, which is why the relation is a table and not a column on
`paper_sentence`.

Refusals are raised once, in the data layer, as `UnknownReference`, and
translated where each caller speaks: `400` with the offending ids for REST (one
exception handler, no route carries the check), a readable tool error for MCP
(one wrapper in the tool registry). Neither entry point can skip it, so the
foreign key never has to be the thing that complains.

API: `/references` CRUD plus batch delete, and `/references/{id}/citations` for
the reverse lookup — "where have I used this article?" — which is what tells a
writer whether an entry is safe to delete.

Verified: 29 new checks in `scripts/smoke_references.py` (partial dates, DOI
normalisation, author order and roles, search by author/type/year/cited, the
citation round trip, 400 on a phantom id, 409 on a cited entry), the paper
suite's 45 and the MCP suite's 47 still pass. The MCP suite now cites a real
entry instead of a phantom id, which is what an agent has to do now.
2026-09-22 17:13:32 +08:00

71 lines
2.3 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
F = TypeVar("F", bound=Callable[..., Any])
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 UnknownReference 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__ = ["mcp_tool"]