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:
+106
-5
@@ -7,8 +7,8 @@
|
||||
用 `paragraph_write` / `sentence_update` 微调 → `paper_document` 读回来检查。
|
||||
|
||||
- 代码:`backend/app/mcp/`(工具实现)、`backend/scripts/mcp_server.py`(入口)
|
||||
- 冒烟测试:`backend/scripts/smoke_mcp.py`(真 MCP 客户端跑 47 项检查,stdio 与 HTTP 都过)
|
||||
- 工具数量:**29 个**,按 `paper_` / `paragraph_` / `sentence_` / `template_` / `field_` 五组前缀
|
||||
- 冒烟测试:`backend/scripts/smoke_mcp.py`(真 MCP 客户端跑 76 项检查、覆盖 41/41 个工具,stdio 与 HTTP 都过)
|
||||
- 工具数量:**41 个**,按 `paper_` / `paragraph_` / `sentence_` / `template_` / `field_` / `reference_` / `reference_tag_` 七组前缀
|
||||
- 协议:MCP 2024-11-05 ~ 2025-11-25(官方 Python SDK `mcp>=2.2,<3` 协商)
|
||||
- 传输:`stdio`(本地拉起)与 `streamable-http`(远程连接,支持 Bearer 口令),另兼容旧 `sse`
|
||||
- **已经部署在 k3s 里**:命名空间 `paper-doc`,端点 `http://192.168.1.88:30931/mcp`
|
||||
@@ -98,10 +98,10 @@ cd /data/project/paper/backend
|
||||
.venv/bin/python scripts/smoke_mcp.py --url http://127.0.0.1:8931/mcp --token 你的口令 # 连已有的 HTTP 服务
|
||||
```
|
||||
|
||||
同一个套件 **47 项检查**跑两种传输,覆盖 18 个步骤:建论文 → 看骨架 → 按标题写段落 →
|
||||
同一个套件 **76 项检查**跑两种传输,覆盖 21 个步骤:建论文 → 看骨架 → 按标题写段落 →
|
||||
定位失败时列出候选标题 → 读段落/追加带引用的句子 → 只改一句 → 删一句 → 整篇一次写入 →
|
||||
读全文 → 跨论文搜索 → 搬段落 → 清空段落 → 字段库增删改 → 建/改模板 → 换模板后正文不丢 →
|
||||
删模板被拒 → 删论文要确认 → 清理。写真实数据,结束时自己删干净。
|
||||
文献库增删改查与批量导入 → 引用守卫(被引用的文献删不掉)→ 删模板被拒 → 删论文要确认 → 清理。写真实数据,结束时自己删干净。
|
||||
|
||||
---
|
||||
|
||||
@@ -323,6 +323,66 @@ Header: Authorization: Bearer <MCP_HTTP_TOKEN>
|
||||
|
||||
---
|
||||
|
||||
### 3.6 参考文献 references(7 个)
|
||||
|
||||
参考文献库是引用的另一半:句子上的 `reference_id` 指向它。建文献前**先用 `reference_list` 查重**——
|
||||
`keyword` 会同时搜题名、副题名、期刊名、DOI、关键词、备注和作者名。
|
||||
|
||||
| 工具 | 作用 | 关键参数 |
|
||||
|---|---|---|
|
||||
| `reference_list` | 检索文献库(也是查重路径) | `keyword?` `type?` `year?` `cited_only?` `tag_ids?` `page?` `page_size?` |
|
||||
| `reference_get` | 取一条文献的全部字段 | `reference_id` |
|
||||
| `reference_create` | 新增一条 | `reference`(对象,见下)|
|
||||
| `reference_update` | 改字段,只传要改的 | `reference_id`、`changes` |
|
||||
| `reference_delete` | 删(被引用的会被拒) | `reference_ids`(int 或数组) |
|
||||
| `reference_import` | **一次录入一批**,自动跳过重复 | `references`(数组)、`skip_duplicates?` |
|
||||
| `reference_citations` | **这条文献被哪些句子引用了** | `reference_id` |
|
||||
|
||||
`reference_create` 的 `reference` 对象(39 个字段,全都有默认值,能填多少填多少):
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"type": "journal-article", // journal-article / book / book-chapter / conference-paper /
|
||||
// thesis / patent / standard / report / newspaper-article /
|
||||
// web-page / dataset / software / preprint / other
|
||||
"title": "题名(必填)",
|
||||
"authors": [ // 顺序即印刷顺序
|
||||
{"name": "Smith, John", "family_name": "Smith", "given_name": "John"},
|
||||
{"name": "张三", "role": "editor"} // role: author(默认)/ editor / translator / compiler
|
||||
],
|
||||
"container_title": "期刊名", "volume": "12", "issue": "3", "pages": "45-67",
|
||||
"publication_year": 2024, "doi": "10.1000/xyz", "url": "…",
|
||||
"keywords": "…", "abstract": "…", "note": "…", "language": "en",
|
||||
"isbn": "…", "issn": "…", "patent_number": "…", "standard_number": "…",
|
||||
"accessed_date": "2024-05-01", "citation_key": "smith2024flood",
|
||||
"tag_ids": [3, 7]
|
||||
}
|
||||
```
|
||||
|
||||
`reference_update` 的 `changes` 只写要改的字段;**传 `null` 表示清空该字段**(不传就是不动):
|
||||
|
||||
```jsonc
|
||||
{"name": "reference_update", "arguments": {
|
||||
"reference_id": 42,
|
||||
"changes": {"publication_year": 2025, "doi": "10.1000/xyz-v2", "note": null}
|
||||
}}
|
||||
```
|
||||
|
||||
`authors` 和 `tag_ids` 一给就是**整体替换**(`tag_ids: []` 清空标签)。
|
||||
|
||||
### 3.7 文献标签 reference_tag(5 个)
|
||||
|
||||
标签不是分类,是标记(「必读」「方法」「待核实」)。删标签**不会**动文献——只掉标记;
|
||||
删文献则要求它没被引用。
|
||||
|
||||
| 工具 | 作用 | 关键参数 |
|
||||
|---|---|---|
|
||||
| `reference_tag_list` | 列标签(含每个标签下几条文献)| `keyword?` `page?` `page_size?` |
|
||||
| `reference_tag_get` | 取一个标签 | `tag_id` |
|
||||
| `reference_tag_create` | 新建(名称唯一)| `name`、`color?` `note?` |
|
||||
| `reference_tag_update` | 改名/颜色/备注 | `tag_id`、`name?` `color?` `note?` `clear_note?` |
|
||||
| `reference_tag_delete` | 删标签(文献不受影响)| `tag_ids`(int 或数组)|
|
||||
|
||||
## 4. 典型用法
|
||||
|
||||
### 4.1 AI 写完,整篇一次灌进去(主推)
|
||||
@@ -423,6 +483,36 @@ Header: Authorization: Bearer <MCP_HTTP_TOKEN>
|
||||
|
||||
---
|
||||
|
||||
### 4.7 文献:查重 → 录入 → 引用 → 复查
|
||||
|
||||
```jsonc
|
||||
// 1) 先查库里有没有(DOI / 题名 / 作者都能搜)
|
||||
{"name": "reference_list", "arguments": {"keyword": "10.1000/xyz"}}
|
||||
|
||||
// 2) 没有就录;一次一批更省事(重复的会自动跳过,坏的逐条报告,不连累其它条)
|
||||
{"name": "reference_import", "arguments": {"references": [
|
||||
{"type": "journal-article", "title": "A flood study", "container_title": "J. Hydrol.",
|
||||
"publication_year": 2023, "volume": "61", "issue": "2", "pages": "1-18",
|
||||
"doi": "10.1000/xyz", "authors": [{"name": "Smith, John"}]},
|
||||
{"type": "book", "title": "另一本书", "publisher": "某出版社", "publication_year": 2019,
|
||||
"authors": [{"name": "张三"}]}
|
||||
]}}
|
||||
// → {"created":[{"id":42,…},{"id":43,…}], "skipped":[{"title":"…","existing_id":7}], "failed":[…]}
|
||||
|
||||
// 3) 写正文时引用它(citations 里给 reference_id 和引用的原话)
|
||||
{"name": "paragraph_write", "arguments": {
|
||||
"paper_id": 96, "heading": "2 Related Work",
|
||||
"sentences": [{"content": "已有研究指出……", "citations": [{"quote": "引用的原话", "reference_id": 42}]}]
|
||||
}}
|
||||
|
||||
// 4) 改稿前先看影响面:这条文献被哪些句子用了
|
||||
{"name": "reference_citations", "arguments": {"reference_id": 42}}
|
||||
// → {"total":2, "items":[{"paper_id":96,"position":30,"paragraph":"2 Related Work","sentence_id":512,"quote":"引用的原话"}]}
|
||||
```
|
||||
|
||||
删文献时如果它还被引用,会被拒绝并报出「(N 处引用)」——先按上面第 4 步找到那些句子、
|
||||
用 `sentence_update(citations=[])` 摘掉引用,再删。
|
||||
|
||||
## 5. 返回值与错误约定
|
||||
|
||||
- **成功**:`content[0].text` 是一段 JSON 字符串。例如 `paper_list` 返回
|
||||
@@ -437,6 +527,11 @@ Header: Authorization: Bearer <MCP_HTTP_TOKEN>
|
||||
| 删除模板被拒 | `以下模板正被论文使用,请先用 paper_update 给论文切换模板:“…”(2 篇论文)` |
|
||||
| 删字段被拒 | `以下字段正被模板使用,请先用 template_update 从模板里移除:“…”(1 个模板)` |
|
||||
| 删论文没确认 | `…确认无误后请带 confirm=true 重新调用` |
|
||||
| 删被引用的文献 | `以下文献正被论文引用,请先在段落里移除对应引用:“…”(2 处引用)` |
|
||||
| 引用了不存在的文献 | `参考文献不存在:42` |
|
||||
| 给文献打了不存在的标签 | `标签不存在:9` |
|
||||
| 标签重名 | `标签「必读」已存在` |
|
||||
| 文献字段不合法 | `文献不合法(type):文献类型只能是:journal-article、book、…` |
|
||||
| 参数写错 | SDK 层的参数校验错误(列出哪个字段不合法) |
|
||||
|
||||
所有消息都写成"哪里错 + 怎么修",因为读它的是模型,它据此重试一次就能成功。
|
||||
@@ -489,7 +584,13 @@ REST 和 MCP 同时生效。这让"网页里看到的"和"AI 写进去的"永远
|
||||
| 改一句 | `PATCH /api/papers/{id}/sentences/{id}` | `sentence_update` |
|
||||
| 搜句子 | —(MCP 专有) | `sentence_search` |
|
||||
| 建模板 | `POST /api/templates` | `template_create` |
|
||||
| 字段库 | `/api/template-field-library` | `field_*` |
|
||||
| 字段库 | `/api/templates/titles` | `field_*` |
|
||||
| 列/搜文献 | `GET /api/references` | `reference_list` |
|
||||
| 建文献 | `POST /api/references` | `reference_create` |
|
||||
| 改文献 | `PATCH /api/references/{id}` | `reference_update` |
|
||||
| 删文献 | `DELETE /api/references/{id}` | `reference_delete` |
|
||||
| 谁引用了它 | `GET /api/references/{id}/citations` | `reference_citations` |
|
||||
| 文献标签 | `/api/reference-tags` | `reference_tag_*` |
|
||||
|
||||
MCP 独有:`paper_outline`(写前看骨架)、`paper_write` / `paper_write_text`(批量写入)、
|
||||
`paragraph_move`、`sentence_search`。
|
||||
|
||||
+15
-1
@@ -464,6 +464,8 @@ written by an agent is indistinguishable from one written by hand. What
|
||||
| `paper_write` / `paper_write_text` | "generate the paper, then put it in" is one intention, not thirty round trips |
|
||||
| `paper_delete` refuses once before it deletes | a cascading delete has no undo in a tool call |
|
||||
| `sentence_search` across papers | the job is consistency — one paper says 洪水损失, the next must not say GUL |
|
||||
| `reference_*` and `reference_tag_*` | the reference library is what makes a citation mean something; an agent that can cite id 42 but cannot look up what 42 *is* is writing blind |
|
||||
| `reference_import` | "here are the twenty references I cited" is one intention, and twenty round trips would spend twenty schemas on it |
|
||||
|
||||
Two transports are served from one build: `stdio`, which is what a client
|
||||
spawns, and `streamable-http`, which is what a client on another machine
|
||||
@@ -486,7 +488,19 @@ a database that is briefly unreachable cannot become a restart loop, while
|
||||
readiness runs `SELECT 1` so the pod leaves the Service's endpoints while TiDB
|
||||
is down and rejoins when it is not.
|
||||
|
||||
Two decisions are worth knowing before adding a tool. **Results are registered
|
||||
Two shape decisions are worth knowing before adding a tool. **A nested argument
|
||||
model keeps `model_fields_set`**, which a flattened signature cannot: 38
|
||||
bibliographic fields spread across keyword parameters would arrive with the
|
||||
omitted ones indistinguishable from explicit nulls, so `reference_update` takes
|
||||
its changes as one object and forwards only the keys the caller actually wrote.
|
||||
And **a domain refusal belongs in `DOMAIN_REFUSALS`** in `tools/registry.py` on
|
||||
the day it is written — `UnknownReference` was translated there when the
|
||||
reference tools were still to come, and the tag rules (`UnknownTag`,
|
||||
`DuplicateTagName`) had to be added when those tools landed, because an
|
||||
unlisted refusal reaches the model as `Error executing tool …` and says nothing
|
||||
about what to fix.
|
||||
|
||||
Two more decisions are worth knowing. **Results are registered
|
||||
with `structured_output=False`**: inferred from a `-> str` annotation, the SDK
|
||||
publishes a `{"result": …}` envelope and sends the JSON twice, once as
|
||||
`structuredContent` and once as text, and clients that read only one of the two
|
||||
|
||||
Reference in New Issue
Block a user