backend: give the reference library the MCP tools it was missing, and fix the one that broke

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.
This commit is contained in:
2026-09-22 18:30:24 +08:00
parent a29badd362
commit 15955f552d
10 changed files with 1085 additions and 75 deletions
+312 -61
View File
@@ -43,13 +43,15 @@ from mcp.client.stdio import StdioServerParameters, stdio_client # noqa: E402
from sqlalchemy import or_, select # noqa: E402
from app.db.session import SessionLocal # noqa: E402
from app.models import Paper, Reference, Template # noqa: E402
from app.models import Paper, Reference, ReferenceTag, Template # noqa: E402
SERVER_SCRIPT = BACKEND_DIR / "scripts" / "mcp_server.py"
_checks = 0
_created_papers: list[int] = []
_created_templates: list[int] = []
_created_references: list[int] = []
_created_tags: list[int] = []
def check(label: str, condition: bool, detail: str = "") -> None:
@@ -97,15 +99,6 @@ async def expect_error(session: ClientSession, tool: str, **arguments: Any) -> s
)
class _Box:
"""A one-slot holder, so the citation helper can read what the context set."""
value: int | None = None
_CITATION_REFERENCE_ID = _Box()
def pick_template() -> tuple[int, list[dict[str, Any]]]:
"""The template with the most titles, and its outline as the tools see it."""
with SessionLocal() as db:
@@ -154,8 +147,7 @@ async def connect(url: str | None, token: str | None) -> AsyncIterator[ClientSes
async def run(url: str | None = None, token: str | None = None) -> int:
with reference_for_citation():
return await _run(url, token)
return await _run(url, token)
async def _run(url: str | None = None, token: str | None = None) -> int:
@@ -175,11 +167,20 @@ async def _run(url: str | None = None, token: str | None = None) -> int:
print("\n1. tool discovery")
listed = await session.list_tools()
names = {tool.name for tool in listed.tools}
check("29 tools are published", len(names) == 29, f"got {len(names)}")
check("the whole surface is published", len(names) == 41, f"got {len(names)}")
check(
"every group is reachable",
{"paper_write", "paragraph_write", "sentence_add", "template_get", "field_list"}
{
"paper_write",
"paragraph_write",
"sentence_add",
"template_get",
"field_list",
"reference_create",
"reference_tag_create",
}
<= names,
", ".join(sorted(names)),
)
check(
"no tool returns a structured envelope",
@@ -243,7 +244,66 @@ async def _run(url: str | None = None, token: str | None = None) -> int:
json.dumps(written, ensure_ascii=False),
)
print("\n5. a heading the template does not have is refused, with candidates")
print("\n5. every read tool answers")
# The read-only tools are what a suite forgets, and they are where a
# rename bites: `template_list` read a schema attribute that no longer
# existed and crashed with an unreadable "Error executing tool" while
# every other check here passed, because nothing called it. Each
# assertion below is about the *shape* a caller depends on, not merely
# that the call came back.
templates = await call(session, "template_list", page_size=50)
check(
"template_list lists the paper's template",
any(item["id"] == template_id for item in templates["items"]),
json.dumps(templates, ensure_ascii=False)[:300],
)
check(
"and reports how many fields it places",
all(isinstance(item.get("fields"), int) for item in templates["items"]),
json.dumps(templates["items"], ensure_ascii=False)[:300],
)
fetched_template = await call(session, "template_get", template_id=template_id)
positions = [item["position"] for item in fetched_template["fields"]]
check(
"template_get returns the outline already ordered",
positions == sorted(positions) and len(positions) == len(outline),
json.dumps(positions),
)
library = await call(session, "field_list", page_size=5)
check(
"field_list pages the library",
library["total"] >= 1 and len(library["items"]) <= 5,
json.dumps({key: library[key] for key in ("total", "page_size", "pages")}),
)
one_field = await call(session, "field_get", field_id=library["items"][0]["id"])
check(
"field_get returns that same entry",
one_field["id"] == library["items"][0]["id"],
json.dumps(one_field, ensure_ascii=False),
)
listed_papers = await call(session, "paper_list", keyword="SMOKE MCP")
check(
"paper_list finds the paper by title",
any(item["id"] == paper["id"] for item in listed_papers["items"]),
json.dumps(listed_papers, ensure_ascii=False)[:300],
)
fetched_paper = await call(session, "paper_get", paper_id=paper["id"])
check(
"paper_get reports the four sentences written so far",
fetched_paper["sentences"] == 4,
json.dumps(fetched_paper, ensure_ascii=False),
)
paragraphs = await call(session, "paragraph_list", paper_id=paper["id"])
check(
"paragraph_list covers every position the template defines",
len(paragraphs["items"]) == len(positions),
f"{len(paragraphs['items'])} vs {len(positions)}",
)
print("\n6. a heading the template does not have is refused, with candidates")
message = await expect_error(
session,
"paragraph_write",
@@ -253,7 +313,7 @@ async def _run(url: str | None = None, token: str | None = None) -> int:
)
check("the refusal lists the real headings", first in message, message)
print("\n6. read one paragraph back")
print("\n7. read one paragraph back")
paragraph = await call(
session, "paragraph_get", paper_id=paper["id"], heading=first
)
@@ -264,14 +324,162 @@ async def _run(url: str | None = None, token: str | None = None) -> int:
json.dumps(paragraph["sentences"], ensure_ascii=False),
)
print("\n7. append a sentence with a citation")
print("\n8. the reference library")
tag = await call(
session, "reference_tag_create", name="SMOKE MCP 标签", color="#123456"
)
_created_tags.append(tag["id"])
check("a tag can be created", tag["name"] == "SMOKE MCP 标签", json.dumps(tag, ensure_ascii=False))
created_reference = await call(
session,
"reference_create",
reference={
"type": "journal-article",
"title": "SMOKE MCP 文献",
"container_title": "Journal of Smoke Tests",
"publication_year": 2024,
"volume": "12",
"issue": "3",
"pages": "45-67",
"doi": "10.1000/smoke.mcp.001",
"language": "en",
"authors": [
{"name": "Smith, John", "family_name": "Smith", "given_name": "John"},
{"name": "张三", "role": "editor"},
],
"tag_ids": [tag["id"]],
},
)
reference_id = created_reference["id"]
_created_references.append(reference_id)
check(
"authors keep the order they were sent in",
[author["name"] for author in created_reference["authors"]] == ["Smith, John", "张三"],
json.dumps(created_reference["authors"], ensure_ascii=False),
)
check(
"and the tag is attached",
[item["name"] for item in created_reference["tags"]] == ["SMOKE MCP 标签"],
json.dumps(created_reference["tags"], ensure_ascii=False),
)
tags = await call(session, "reference_tag_list", keyword="SMOKE MCP")
check(
"reference_tag_list counts the literature under the tag",
any(item["id"] == tag["id"] and item["references"] == 1 for item in tags["items"]),
json.dumps(tags, ensure_ascii=False)[:300],
)
one_tag = await call(session, "reference_tag_get", tag_id=tag["id"])
check(
"reference_tag_get returns that same tag",
one_tag["id"] == tag["id"] and one_tag["references"] == 1,
json.dumps(one_tag, ensure_ascii=False),
)
retagged = await call(
session,
"reference_tag_update",
tag_id=tag["id"],
color="#ABCDEF",
note="测试备注",
)
check(
"reference_tag_update changes only what it was given",
retagged["color"] == "#ABCDEF"
and retagged["note"] == "测试备注"
and retagged["name"] == "SMOKE MCP 标签",
json.dumps(retagged, ensure_ascii=False),
)
unlabelled_note = await call(
session, "reference_tag_update", tag_id=tag["id"], clear_note=True
)
check(
"clear_note takes the note back off",
"note" not in unlabelled_note,
json.dumps(unlabelled_note, ensure_ascii=False),
)
by_doi = await call(session, "reference_list", keyword="10.1000/smoke.mcp.001")
check(
"reference_list finds it by DOI",
any(item["id"] == reference_id for item in by_doi["items"]),
json.dumps(by_doi, ensure_ascii=False)[:300],
)
check(
"a row carries its citation count",
all(isinstance(item.get("citations"), int) for item in by_doi["items"]),
json.dumps(by_doi["items"], ensure_ascii=False)[:300],
)
fetched_reference = await call(session, "reference_get", reference_id=reference_id)
check(
"reference_get returns the whole record",
fetched_reference["doi"] == "10.1000/smoke.mcp.001"
and fetched_reference["container_title"] == "Journal of Smoke Tests",
json.dumps(fetched_reference, ensure_ascii=False)[:300],
)
patched = await call(
session,
"reference_update",
reference_id=reference_id,
changes={"note": "由测试写入", "publication_year": 2025},
)
check(
"reference_update changes only what it was given",
patched["publication_year"] == 2025 and patched["title"] == "SMOKE MCP 文献",
json.dumps(patched, ensure_ascii=False)[:300],
)
cleared = await call(
session, "reference_update", reference_id=reference_id, changes={"note": None}
)
check(
"an explicit null clears the field",
"note" not in cleared,
json.dumps(cleared, ensure_ascii=False)[:200],
)
imported = await call(
session,
"reference_import",
references=[
{"title": "SMOKE MCP 导入一", "publication_year": 2020},
{"title": "SMOKE MCP 导入二", "publication_year": 2021},
{"title": "SMOKE MCP 文献", "doi": "10.1000/smoke.mcp.001"},
{"title": " ", "type": "journal-article"},
],
)
imported_ids = [item["id"] for item in imported["created"]]
_created_references.extend(imported_ids)
check(
"import creates the entries that are new",
len(imported["created"]) == 2,
json.dumps(imported, ensure_ascii=False)[:400],
)
check(
"skips the one the library already has, naming it",
len(imported["skipped"]) == 1
and imported["skipped"][0]["existing_id"] == reference_id,
json.dumps(imported["skipped"], ensure_ascii=False),
)
check(
"and reports the bad entry without losing the rest",
len(imported["failed"]) == 1 and imported["failed"][0]["title"].strip() == "",
json.dumps(imported["failed"], ensure_ascii=False),
)
print("\n9. append a sentence with a citation")
added = await call(
session,
"sentence_add",
paper_id=paper["id"],
heading=first,
content="A cited sentence.",
citations=[{"quote": "引用的原话", "reference_id": _reference_id()}],
citations=[{"quote": "引用的原话", "reference_id": reference_id}],
)
check("appended", added["sentence"]["content"] == "A cited sentence.")
check("the citation is stored", added["sentence"]["citations"][0]["quote"] == "引用的原话")
@@ -283,7 +491,51 @@ async def _run(url: str | None = None, token: str | None = None) -> int:
json.dumps(after["sentences"][-1], ensure_ascii=False),
)
print("\n8. edit one sentence without touching its paragraph")
print("\n10. a cited reference cannot be deleted")
citations = await call(session, "reference_citations", reference_id=reference_id)
check(
"the reference reports the sentence citing it",
citations["total"] == 1
and citations["items"][0]["paper_id"] == paper["id"]
and citations["items"][0]["quote"] == "引用的原话",
json.dumps(citations, ensure_ascii=False)[:400],
)
message = await expect_error(session, "reference_delete", reference_ids=[reference_id])
check("deleting it is refused with the count", "1 处引用" in message, message)
cited = await call(session, "sentence_list", paper_id=paper["id"])
sentence_id = next(row["id"] for row in cited["items"] if row["citations"])
await call(
session,
"sentence_update",
paper_id=paper["id"],
sentence_id=sentence_id,
citations=[],
)
check(
"clearing the citation frees the reference",
(await call(session, "reference_citations", reference_id=reference_id))["total"] == 0,
)
freed = await call(session, "reference_delete", reference_ids=reference_id)
check("now it deletes", freed["deleted"] == 1, json.dumps(freed, ensure_ascii=False))
_created_references.remove(reference_id)
batch = await call(session, "reference_delete", reference_ids=imported_ids)
check(
"a batch delete takes the imported ones too",
batch["deleted"] == len(imported_ids),
json.dumps(batch, ensure_ascii=False),
)
for imported_id in imported_ids:
_created_references.remove(imported_id)
dropped = await call(session, "reference_tag_delete", tag_ids=tag["id"])
check("and the tag goes with it", dropped["deleted"] == 1, json.dumps(dropped, ensure_ascii=False))
_created_tags.remove(tag["id"])
print("\n11. edit one sentence without touching its paragraph")
edited = await call(
session,
"sentence_update",
@@ -295,7 +547,7 @@ async def _run(url: str | None = None, token: str | None = None) -> int:
still = await call(session, "paragraph_get", paper_id=paper["id"], heading=first)
check("the other sentences kept their ids", still["sentences"][1]["id"] == after["sentences"][1]["id"])
print("\n9. delete one sentence")
print("\n12. delete one sentence")
before = await call(session, "sentence_list", paper_id=paper["id"])
await call(
session,
@@ -310,7 +562,7 @@ async def _run(url: str | None = None, token: str | None = None) -> int:
f"{before['total']} -> {remaining['total']}",
)
print("\n10. write a whole generated document in one call")
print("\n13. write a whole generated document in one call")
generated = "\n".join(
[f"# {item['name']}" + "\n" + f"{item['name']}的正文写在标题下面。这句话是第二句。"
for item in outline]
@@ -325,7 +577,7 @@ async def _run(url: str | None = None, token: str | None = None) -> int:
)
check("nothing was left unmatched", "unmatched" not in whole, json.dumps(whole, ensure_ascii=False))
print("\n11. read the paper as a document")
print("\n14. read the paper as a document")
document = await call(session, "paper_document", paper_id=paper["id"])
check("the text carries every heading", all(item["name"] in document["text"] for item in outline))
check("and every paragraph", document["text"].count("正文写在标题下面") == len(outline))
@@ -341,11 +593,11 @@ async def _run(url: str | None = None, token: str | None = None) -> int:
),
)
print("\n12. search across papers")
print("\n15. search across papers")
found = await call(session, "sentence_search", keyword="正文写在标题下面", paper_id=paper["id"])
check("the search finds what was written", found["total"] >= 1, str(found["total"]))
print("\n13. move a paragraph, then clear the one it moved onto")
print("\n16. move a paragraph, then clear the one it moved onto")
home = outline[0]
target = outline[1]
relocation = await call(
@@ -377,7 +629,7 @@ async def _run(url: str | None = None, token: str | None = None) -> int:
after_clear = await call(session, "paragraph_get", paper_id=paper["id"], position=target["position"])
check("and the paragraph is empty", after_clear["sentences"] == [], json.dumps(after_clear, ensure_ascii=False))
print("\n14. the field library round-trips")
print("\n17. the field library round-trips")
field = await call(session, "field_create", name="SMOKE MCP 字段", level=2, font_size=9.5)
check("created with its typography", field["level"] == 2 and field["font_size"] == 9.5, json.dumps(field, ensure_ascii=False))
renamed = await call(session, "field_update", field_id=field["id"], name="SMOKE MCP 字段(改)")
@@ -386,7 +638,7 @@ async def _run(url: str | None = None, token: str | None = None) -> int:
check("deleted while no template places it", dropped["deleted"] == 1, json.dumps(dropped, ensure_ascii=False))
check("and it is reported as found, not missing", dropped["missing"] == [], json.dumps(dropped, ensure_ascii=False))
print("\n15. switch the template and keep the content")
print("\n18. switch the template and keep the content")
spare = await call(
session,
"template_create",
@@ -430,15 +682,15 @@ async def _run(url: str | None = None, token: str | None = None) -> int:
json.dumps(switched_document, ensure_ascii=False)[:400],
)
print("\n16. a template in use cannot be deleted")
print("\n19. a template in use cannot be deleted")
message = await expect_error(session, "template_delete", template_ids=spare["id"])
check("the refusal names the blocker", "SMOKE MCP 模板" in message, message)
print("\n17. deleting a paper needs an explicit confirmation")
print("\n20. deleting a paper needs an explicit confirmation")
message = await expect_error(session, "paper_delete", paper_ids=paper["id"])
check("the refusal explains itself", "confirm=true" in message, message)
print("\n18. delete the paper and the template")
print("\n21. delete the paper and the template")
deleted = await call(session, "paper_delete", paper_ids=paper["id"], confirm=True)
check("deleted", deleted["deleted"] == 1, json.dumps(deleted, ensure_ascii=False))
_created_papers.remove(paper["id"])
@@ -450,38 +702,6 @@ async def _run(url: str | None = None, token: str | None = None) -> int:
return 0
@contextmanager
def reference_for_citation() -> Iterator[int]:
"""A library entry the citation checks can point at.
A citation names real literature now, so the test has to have some: the MCP
surface has no reference tools yet, and this creates the row directly.
"""
with SessionLocal() as db:
reference = Reference(type="journal-article", title="SMOKE MCP 文献")
db.add(reference)
db.commit()
db.refresh(reference)
reference_id = reference.id
_CITATION_REFERENCE_ID.value = reference_id
try:
yield reference_id
finally:
with SessionLocal() as db:
stored = db.get(Reference, reference_id)
if stored is not None:
db.delete(stored)
db.commit()
_CITATION_REFERENCE_ID.value = None
def _reference_id() -> int:
"""The id the current citation check should use."""
if _CITATION_REFERENCE_ID.value is None:
raise AssertionError("no reference in scope for this citation check")
return _CITATION_REFERENCE_ID.value
def _field_id(name: str) -> int:
"""The library field behind a heading name, for the template-create step."""
from app.models import TemplateTitle
@@ -511,6 +731,24 @@ def cleanup() -> None:
db.delete(template)
db.commit()
print(f"cleaned up templates {_created_templates}")
# References go before tags: a reference carries tag links, and a tag
# deleted out from under one would leave the link pointing at nothing.
if _created_references:
with SessionLocal() as db:
for reference in db.scalars(
select(Reference).where(Reference.id.in_(_created_references))
).all():
db.delete(reference)
db.commit()
print(f"cleaned up references {_created_references}")
if _created_tags:
with SessionLocal() as db:
for tag in db.scalars(
select(ReferenceTag).where(ReferenceTag.id.in_(_created_tags))
).all():
db.delete(tag)
db.commit()
print(f"cleaned up tags {_created_tags}")
def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
@@ -546,6 +784,19 @@ def main(argv: list[str] | None = None) -> int:
).all()
for template in stale_templates:
db.delete(template)
# References and tags from a run that died before cleanup: the suite
# creates them through the tools now, so a failure between the two
# steps leaves rows the next run would trip over (a duplicate tag name
# refuses the create outright).
for reference in db.scalars(
select(Reference).where(Reference.title.like("SMOKE MCP%"))
).all():
db.delete(reference)
db.flush()
for tag in db.scalars(
select(ReferenceTag).where(ReferenceTag.name.like("SMOKE MCP%"))
).all():
db.delete(tag)
db.commit()
try: