Files
paper-doc/docs/MCP.md
T
govin 15955f552d 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.
2026-09-22 18:30:24 +08:00

612 lines
28 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# MCP 服务(paper-doc-mcp)
把 paper-doc 的论文、段落、句子、模板、字段库能力暴露成 **Model Context Protocol** 工具,
让 Claude Code、Codex、DeepSeek Harness(DSH)等任何 MCP 客户端直接增删改查论文。
**一句话用法**:AI 生成完整论文 → 调 `paper_write_text` 一次写入 →
用 `paragraph_write` / `sentence_update` 微调 → `paper_document` 读回来检查。
- 代码:`backend/app/mcp/`(工具实现)、`backend/scripts/mcp_server.py`(入口)
- 冒烟测试:`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`
(打包、发布、回滚见 [deploy/README.md](../deploy/README.md))
---
## 1. 快速开始
### 1.1 自检(先确认能连数据库)
```bash
cd /data/project/paper/backend
.venv/bin/python scripts/mcp_server.py --check
```
输出示例:
```
paper-doc MCP 1.0.0 (name=paper-doc)
database : mysql+pymysql://Govin:***@192.168.1.88:32738/paper_doc
rows : paper=1, template=3, paper_sentence=6, template_field_library=20
tools : 29 field=5, paper=9, paragraph=5, sentence=5, template=5
- paper_list
...
```
连不上数据库会打印失败原因并返回非 0——这是最常见的"工具调不动"根因,
所以接入任何客户端前先跑一次。
### 1.2 stdio(推荐给本地客户端)
客户端自己拉起进程,通过 stdin/stdout 讲 JSON-RPC:
```bash
/data/project/paper/backend/.venv/bin/python \
/data/project/paper/backend/scripts/mcp_server.py
```
从任何工作目录都能跑(脚本自己锚定 `sys.path`),所以客户端不需要配 `cwd`。
### 1.3 连已经在跑的那一个(k3s 里)
不用自己起进程——服务已经部署好了:
```
http://192.168.1.88:30931/mcp # 局域网 / 宿主机
http://paper-doc-mcp.paper-doc.svc.cluster.local:8931/mcp # 集群内 Pod
```
除 `/healthz`、`/readyz` 外都要带 `Authorization: Bearer <MCP_HTTP_TOKEN>`。
取口令:
```bash
export KUBECONFIG=$HOME/.kube/config
kubectl -n paper-doc get secret paper-doc-secrets -o jsonpath='{.data.MCP_HTTP_TOKEN}' | base64 -d; echo
```
自检与验证:
```bash
curl -s http://192.168.1.88:30931/readyz
cd backend && .venv/bin/python scripts/smoke_mcp.py \
--url http://192.168.1.88:30931/mcp --token '<口令>' # 47 项检查
```
### 1.4 streamable-http(自己起一个)
```bash
cd /data/project/paper/backend
.venv/bin/python scripts/mcp_server.py \
--transport http --host 0.0.0.0 --port 8931 --token '你的口令'
```
- 端点:`http://<host>:8931/mcp`
- 设了 `--token` 后,每个请求都要带 `Authorization: Bearer <口令>`,否则 `401`
- 绑定非 127.0.0.1 时会自动关掉 DNS-rebinding 保护(否则客户端用局域网域名访问会被 421),
此时**口令就是唯一的门**——不设口令会打印警告
也可以用环境变量代替参数:`MCP_TRANSPORT` / `MCP_HOST` / `MCP_PORT` / `MCP_PATH` / `MCP_HTTP_TOKEN`。
### 1.5 跑冒烟测试
```bash
cd /data/project/paper/backend
.venv/bin/python scripts/smoke_mcp.py # 自己拉起 stdio 子进程
.venv/bin/python scripts/smoke_mcp.py --url http://127.0.0.1:8931/mcp --token 你的口令 # 连已有的 HTTP 服务
```
同一个套件 **76 项检查**跑两种传输,覆盖 21 个步骤:建论文 → 看骨架 → 按标题写段落 →
定位失败时列出候选标题 → 读段落/追加带引用的句子 → 只改一句 → 删一句 → 整篇一次写入 →
读全文 → 跨论文搜索 → 搬段落 → 清空段落 → 字段库增删改 → 建/改模板 → 换模板后正文不丢 →
文献库增删改查与批量导入 → 引用守卫(被引用的文献删不掉)→ 删模板被拒 → 删论文要确认 → 清理。写真实数据,结束时自己删干净。
---
## 2. 客户端配置
### 2.1 DeepSeek Harness(DSH)
编辑 `~/.dsh/profiles/web/cordis.patch.yml`,**新条目必须放进 `insert:` 列表**
(裸条目会被当成"覆盖已有 id",profile 里没有该 id 时只 warn 后静默跳过)。
stdio(Harness 自己拉起进程,最简单):
```yaml
- insert:
- id: mcp-paper-doc
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: paper
transport: stdio
command: /data/project/paper/backend/.venv/bin/python
args:
- /data/project/paper/backend/scripts/mcp_server.py
cwd: /data/project/paper/backend
toolCallTimeoutMs: 60000
failOnStartupError: false # 连不上也不影响 Harness 启动
```
streamable-http(服务常驻,多个客户端共用):
```yaml
- insert:
- id: mcp-paper-doc
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: paper
transport: streamable-http
url: http://127.0.0.1:8931/mcp
headers:
Authorization: Bearer 你的口令
toolCallTimeoutMs: 60000
failOnStartupError: false
```
`serverName: paper` 决定了模型看到的工具名是 `mcp__paper__paper_write_text` 这种形式。
web profile 是 `patchReload: live`,保存后通常热加载;不行就重启 dsh-web。
### 2.2 Claude Code
本地 stdio:
```bash
claude mcp add paper -- /data/project/paper/backend/.venv/bin/python \
/data/project/paper/backend/scripts/mcp_server.py
```
远程 HTTP(带口令):
```bash
claude mcp add --transport http paper http://192.168.1.88:8931/mcp \
--header "Authorization: Bearer 你的口令"
```
或者项目根目录放 `.mcp.json` 提交进仓库,团队直接共享:
```json
{
"mcpServers": {
"paper": {
"type": "stdio",
"command": "/data/project/paper/backend/.venv/bin/python",
"args": ["/data/project/paper/backend/scripts/mcp_server.py"],
"env": {}
}
}
}
```
查看与调试:`claude mcp list`、`claude mcp get paper`、会话里 `/mcp`。
### 2.3 Codex CLI
编辑 `~/.codex/config.toml`。
本地 stdio(`~/.codex/config.toml`):
```toml
[mcp_servers.paper]
command = "/data/project/paper/backend/.venv/bin/python"
args = ["/data/project/paper/backend/scripts/mcp_server.py"]
enabled = true
# 可选:数据库配置(不写就读 backend/.env)
[mcp_servers.paper.env]
# DB_HOST = "192.168.1.88"
# DB_PORT = "32738"
```
远程 streamable-http:
```toml
[mcp_servers.paper]
url = "http://192.168.1.88:8931/mcp"
bearer_token_env_var = "PAPER_MCP_TOKEN" # 口令放环境变量,别写进配置文件
enabled = true
```
命令行管理:`codex mcp list` / `codex mcp add` / `codex mcp get paper`。
> 参考:[Codex MCP Servers 文档](https://mintlify.wiki/openai/codex/configuration/mcp-servers)
### 2.4 远程(Windows 上的 Claude Code / Codex)
服务已经部署在 k3s 里,直接连它就行,客户端填:
```
URL: http://192.168.1.88:30931/mcp
Header: Authorization: Bearer <MCP_HTTP_TOKEN>
```
走 Tailscale 的机器把地址换成 `http://100.64.0.1:30931/mcp`(NodePort 在节点上监听,
两个地址都通)。
不想暴露端口的话,还有一条 SSH 包 stdio 的路子:客户端 `command = "ssh"`,
让远端执行 `mcp_server.py`,协议走 SSH 的 stdin/stdout
(见 ssh_intranet_skill 的 SSH_ASKPASS 写法)。
---
## 3. 工具参考
约定:
- 工具名即函数名;`(可选)` 的参数可以不传,其余必填。
- 返回一律是 **JSON 文本**(不是结构化对象),字段为 `None` 的一律不输出。
- 失败不是抛异常,而是 `isError: true` + 一句中日文都看得懂的说明(例如
`论文 999999 不存在`、`模板“X”已存在`、`请先用 paper_update 给论文切换模板:…`)。
### 3.1 论文 papers(9 个)
| 工具 | 作用 | 关键参数 |
|---|---|---|
| `paper_list` | 列论文(不含正文),返回 id/标题/模板/进度 | `keyword?` `status?` `template_id?` `page?` `page_size?` |
| `paper_get` | 取一篇论文的元信息与进度 | `paper_id` |
| `paper_create` | 新建论文(只写元信息) | `title`、`template_id?` `author?` `status?` `keywords?` `target_journal?` |
| `paper_update` | 改元信息 / 换模板 | `paper_id`、`title?` `template_id?` `clear_template?` `author?` `status?` `keywords?` `target_journal?` |
| `paper_delete` | 删论文(连句子引用) | `paper_ids`(int 或数组)、`confirm=true` 必填 |
| `paper_outline` | **写之前先看**:每段 position/标题/已写句数 | `paper_id` |
| `paper_document` | 读全文 | `paper_id`、`format?`(`text`/`json`/`both`)`include_empty?` `citations?` |
| `paper_write` | **批量写段落**(按标题或位置) | `paper_id`、`paragraphs`、`mode?`(`replace`/`append`) |
| `paper_write_text` | **整篇一次写入**(Markdown 标题分段) | `paper_id`、`text`、`split?` `mode?` `strict?` |
`paper_update` 的语义:不传 = 不改;传空字符串 = 清空该文本字段;`clear_template: true` 才能把模板置空。
换 `template_id` 只是重塑标题,正文按位置留在原地,不丢。
`paper_delete` 必须先被拒一次(告诉你删掉什么、不可恢复),确认后才带 `confirm=true` 重调。
### 3.2 段落 paragraphs(5 个)
段落 = 位置。它由模板定义,或者由内容占据;**没有 `paragraph_create`**——往空位置写内容就是创建它。
| 工具 | 作用 | 关键参数 |
|---|---|---|
| `paragraph_list` | 段落骨架 + 预览 | `paper_id`、`include_empty?` `preview?` |
| `paragraph_get` | 读一段:拼好的正文、逐句 id/内容/引用/分隔符 | `paper_id`、`position?` `heading?` |
| `paragraph_write` | 写一段(覆盖或追加) | `paper_id`、`position?` `heading?`、`sentences?` `text?` `split?` `citations?` `mode?` |
| `paragraph_delete` | 清空该段全部句子(段落仍在) | `paper_id`、`position?` `heading?` |
| `paragraph_move` | 整段搬到另一个位置(接在目标段之后) | `paper_id`、`position?` `heading?`、`target_position?` `target_heading?` |
定位规则:`position` 直接采用(包括模板没定义的位置,会以"未设定"渲染);
`heading` 按模板解析,忽略编号、空格和大小写,所以下面三种写法等价:
```
"1. Introduction" / "1 Introduction" / "Introduction"
```
匹配不上或匹配到多个时,错误消息里会带上**模板里真实可用的标题列表**,
模型据此改一次就能成功。
### 3.3 句子 sentences(5 个)
一句一行。改一句话不要重写整段——重写会让整段的句子 id 全变,而引用是挂在 id 上的。
| 工具 | 作用 | 关键参数 |
|---|---|---|
| `sentence_list` | 列句子(可只列某段) | `paper_id`、`position?` `heading?` `include_empty?` |
| `sentence_add` | 段尾追加一句(可带引用) | `paper_id`、`content`、`position?` `heading?` `citations?` `sort?` |
| `sentence_update` | 改正文 / 改所属段 / 改排序 / 整组换引用 | `paper_id`、`sentence_id`、`content?` `position?` `sort?` `citations?` |
| `sentence_delete` | 删一句(连引用) | `paper_id`、`sentence_id` |
| `sentence_search` | **跨论文搜句子**(保持术语一致) | `keyword`、`paper_id?` `limit?` |
### 3.4 模板 templates(5 个)
模板就是结构:论文的标题是**每次渲染现读模板**得到的,所以改模板会影响所有用它的论文,
删模板会被拒绝(错误消息会说明有几篇论文在用、该怎么换)。
| 工具 | 作用 | 关键参数 |
|---|---|---|
| `template_list` | 列模板(含字段数) | `keyword?` `page?` `page_size?` |
| `template_get` | 取完整大纲 + 被几篇论文使用 | `template_id` |
| `template_create` | 新建模板 | `name`、`abstract?`、`field_ids?`(按顺序)或 `fields?`(`[{field_id, sort}]`) |
| `template_update` | 改名/改说明/整组换字段 | `template_id`、`name?` `abstract?` `clear_abstract?` `field_ids?` `fields?` |
| `template_delete` | 删模板 | `template_ids`(int 或数组) |
`field_ids: [2, 6, 9]` 会自动编号成 `sort = 10, 20, 30`——留出间隙,
以后想插一个字段不用重排其余所有位置。
### 3.5 字段库 fields(5 个)
字段库是"模板能用的所有标题"的目录,全局共享。编号写在 `name` 里,由人决定,系统不改写;
`level` 只影响缩进,不构成父子关系——所以同一个二级标题可以出现在多个一级标题下。
| 工具 | 作用 | 关键参数 |
|---|---|---|
| `field_list` | 列字段库(建模板前先查 id) | `keyword?` `level?` `page?` `page_size?` |
| `field_get` | 取一个字段 + 被几个模板使用 | `field_id` |
| `field_create` | 加一个标题字段 | `name`、`level?` `font_size?` `font_color?` |
| `field_update` | 改名/层级/字号/颜色 | `field_id`、`name?` `level?` `font_size?` `font_color?` |
| `field_delete` | 删字段(仍被模板使用会被拒) | `field_ids`(int 或数组) |
---
### 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 写完,整篇一次灌进去(主推)
```jsonc
// 1) 先看骨架,拿到真实标题
{"name": "paper_outline", "arguments": {"paper_id": 96}}
// → {"paper": {...}, "paragraphs": [{"position": 10, "heading": "0 Abstract", "sentences": 0}, ...]}
// 2) 把生成的论文按标题切好,一次写入
{"name": "paper_write_text", "arguments": {
"paper_id": 96,
"text": "# 0 Abstract\n摘要第一句。摘要第二句。\n\n# 1 Introduction\n引言第一句。引言第二句。\n\n## 2 Related Work\n相关工作……",
"split": "sentence" // 中文长句按 。!? 切;一行一句则用 "line"
}}
// → {"paper_id": 96, "written": [{"position": 10, "heading": "0 Abstract", "sentences": 2}, ...],
// "total_sentences": 24}
```
`split` 三种模式:
| 模式 | 含义 | 什么时候用 |
|---|---|---|
| `line`(默认) | 一行 = 一句 | 文本本身已经一行一句(最保险,不猜) |
| `sentence` | 按 `。!?` 和英文 `.?!` 切句 | 一整段挤在一行时的中文长文 |
| `paragraph` | 整段 = 一句 | 你确实想让它是一句 |
> `sentence` 会避开小数点(`3.14`)和 `et al.` / `i.e.` 这类缩写,但它仍然是"猜"。
> 想完全不猜,就直接给 `sentences` 数组。
标题识别两种形态:Markdown 标题行(`# 0 Abstract`),或**与模板完全同名的独立一行**
(把 `paper_outline` 的标题原样抄下来最稳)。前面没有标题的内容会被丢弃;
一个都没匹配上则整次调用报错,不会写半截。
### 4.2 分批写(更长、更可控)
```jsonc
{"name": "paper_write", "arguments": {
"paper_id": 96,
"mode": "replace",
"paragraphs": [
{"heading": "0 Abstract", "sentences": ["摘要第一句。", "摘要第二句。"]},
{"heading": "2 Related Work",
"text": "相关工作这一段我整段给。第二句在这里。",
"split": "sentence"},
{"position": 70, "sentences": [
{"content": "带引用的一句。", "citations": [{"quote": "被引用的原话", "reference_id": 12}]}
]}
]
}}
// → {"paper_id": 96, "written": [{"position": 10, "heading": "0 Abstract", "sentences": 2}, ...],
// "total_sentences": 5}
```
`mode: "append"` 改成追加,不动该段已有内容。
### 4.3 微调:只动一句话
```jsonc
{"name": "paragraph_get", "arguments": {"paper_id": 96, "heading": "1 Introduction"}}
// → {"sentences": [{"id": 501, "sort": 1, "content": "…", "separator_before": ""}, …]}
{"name": "sentence_update", "arguments": {
"paper_id": 96, "sentence_id": 501, "content": "改写后的这一句。"
}}
// → 只改这一句,其余句子 id 不变,挂在它们身上的引用不受影响
```
### 4.4 保持术语一致
```jsonc
{"name": "sentence_search", "arguments": {"keyword": "洪水损失", "limit": 20}}
// → 全库已写过的相关句子(带 paper_id / sentence_id),用来对齐说法
```
### 4.5 换模板(重塑结构但不丢正文)
```jsonc
{"name": "paper_update", "arguments": {"paper_id": 96, "template_id": 3}}
// → {"template_changed": true, ...}
{"name": "paper_document", "arguments": {"paper_id": 96, "format": "json", "include_empty": true}}
// → {"paragraphs": [{"position": 10, "heading": "摘要", "matched": true, ...},
// {"position": 70, "matched": false, ...}]} ← 新模板没有的位置仍在,标记未匹配
```
### 4.6 从零建一套模板
```jsonc
{"name": "field_list", "arguments": {"keyword": "方法", "page_size": 20}}
{"name": "field_create", "arguments": {"name": "8. Limitations", "level": 1, "font_size": 12, "font_color": "#1F1F1F"}}
{"name": "template_create", "arguments": {
"name": "期刊 A 模板",
"abstract": "投期刊 A 用",
"field_ids": [1, 2, 6, 9, 14, 18]
}}
{"name": "paper_create", "arguments": {"title": "新论文", "template_id": 4}}
```
---
### 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` 返回
`{"items": [...], "total": 1, "page": 1, "page_size": 20, "pages": 1}`。
- **失败**:`isError: true`,`text` 是人话,例如:
| 场景 | 消息 |
|---|---|
| 找不到 | `论文 999 不存在` |
| 标题对不上 | `模板里没有标题“X”。可用标题:0 Abstract(10)、1 Introduction(20)…` |
| 标题有二义 | `标题“X”匹配到多个段落(…),请写完整标题或直接用 position` |
| 删除模板被拒 | `以下模板正被论文使用,请先用 paper_update 给论文切换模板:“…”(2 篇论文)` |
| 删字段被拒 | `以下字段正被模板使用,请先用 template_update 从模板里移除:“…”(1 个模板)` |
| 删论文没确认 | `…确认无误后请带 confirm=true 重新调用` |
| 删被引用的文献 | `以下文献正被论文引用,请先在段落里移除对应引用:“…”(2 处引用)` |
| 引用了不存在的文献 | `参考文献不存在:42` |
| 给文献打了不存在的标签 | `标签不存在:9` |
| 标签重名 | `标签「必读」已存在` |
| 文献字段不合法 | `文献不合法(type):文献类型只能是:journal-article、book、…` |
| 参数写错 | SDK 层的参数校验错误(列出哪个字段不合法) |
所有消息都写成"哪里错 + 怎么修",因为读它的是模型,它据此重试一次就能成功。
- **段落拼接**:`separator_before` 是服务端算好的段间分隔符(`""` 或一个空格)。
客户端打印 `separator_before + content`,**自己不要再加空格**。
---
## 6. 设计说明(为什么是这样)
**三个入口,一个领域层。** REST API、MCP 服务、seed 脚本最终都调用 `app.crud`,
校验都过 `app.schemas`。MCP 层不重新实现任何业务规则——在 CRUD 层修的规则,
REST 和 MCP 同时生效。这让"网页里看到的"和"AI 写进去的"永远一致。
**工具结果是手搓的紧凑 JSON,不是 schema dump。** 工具结果按 token 计费,
`PaperRead.model_dump()` 会把 `created_at`/`updated_at`/四个计数字段塞进每一行。
所以 `*_row` 只挑模型真正要读的字段,`clean()` 把 `None` 全部丢掉。
**段落按 position 存储,但工具接受 heading。** `paper_sentence` 记住"我在第 7 段"
(`paper_template_filed_sort`),这是文档渲染需要的、也是换模板不丢正文的原因。
但没人知道"1. Introduction"恰好是 `sort = 20`,所以工具用 heading 也能定位,
由服务端翻译。两者都接受,冲突时以 `position` 为准。
**切句是显式选项,不是默认行为。** 项目原则是"编辑器里一行就是一句,
写入路径不切任何文本"(见 `docs/OVERVIEW.md`)。只有 `text` + `split` 这条路会切,
默认还是 `line`。已存文本永远不会被重新切分。
**删除要二次确认。** `paper_delete` 第一次调用必定被拒并说明后果,
因为一次误删会连带整篇的句子和引用,而这在 MCP 里没有回收站。
**结果不带结构化输出。** 工具用 `structured_output=False` 注册:
返回 `-> str` 时 SDK 会自动包一层 `{"result": ...}` 并把同一份 JSON
同时放进 `structuredContent` 和 `content`,一半客户端只读其中一个——
不如统一成文本,所有客户端都读得到。
---
## 7. 与 REST API 的对照
| 能力 | REST | MCP |
|---|---|---|
| 列论文 | `GET /api/papers` | `paper_list` |
| 建论文 | `POST /api/papers` | `paper_create` |
| 换模板 | `PATCH /api/papers/{id}` | `paper_update(template_id=…)` |
| 读全文 | `GET /api/papers/{id}/document` | `paper_document` |
| 读一段 | `GET /api/papers/{id}/paragraphs/{sort}` | `paragraph_get` |
| 整段重写 | `PUT /api/papers/{id}/paragraphs/{sort}` | `paragraph_write` |
| 加一句 | `POST /api/papers/{id}/sentences` | `sentence_add` |
| 改一句 | `PATCH /api/papers/{id}/sentences/{id}` | `sentence_update` |
| 搜句子 | —(MCP 专有) | `sentence_search` |
| 建模板 | `POST /api/templates` | `template_create` |
| 字段库 | `/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`。
---
## 8. 排障
| 现象 | 原因 / 处理 |
|---|---|
| 客户端显示连不上、工具列表为空 | 先跑 `--check`;多数是数据库不通(`backend/.env` 的 `DB_*`) |
| HTTP 返回 401 | 口令没带或不对,检查 `Authorization: Bearer <token>` |
| HTTP 返回 421 | 绑定了非 127.0.0.1 但没走本次启动的 DNS-rebinding 关闭逻辑——确认用的是本项目入口,别包了一层反向代理改 Host |
| DSH 里工具不出现 | 检查 cordis.patch.yml 的条目是否写在 `insert:` 里;`failOnStartupError: false` 会把启动期连接失败吞掉,看 dsh-web 日志确认 |
| 工具调用超时 | DSH/Codex 侧加大 `toolCallTimeoutMs` / `tool_timeout_sec`;`paper_write_text` 写整篇会慢一些 |
| k3s 里连不上 | `kubectl -n paper-doc get pods` 看是否 Ready;`/readyz` 返回 503 说明 TiDB 不通(`kubectl -n paper-doc logs deploy/paper-doc-mcp`) |
| 改了代码但行为没变 | 镜像 tag 没换:`imagePullPolicy: IfNotPresent` 会继续用节点上缓存的同名镜像,换个 tag 重新构建 |
| 日志里出现非 JSON 的 stdout 输出 | 不要在这个进程里 `print`——stdio 传输下会污染协议流(本项目的诊断都走 stderr) |