Records the decisions the 参考文献 list now rests on: a citation is a place in the text and an entry is a work, so a paper with 86 citations to 65 works lists 65 entries; the entries are written by `app/citation_styles` and a client prints them verbatim; a gap is reported through `missing` rather than quietly rendered as a shorter entry. Also documents `scripts/check_citation_styles.py` — the formatter is checked with no server and no database, because a wrong branch prints something that looks like a bibliography entry instead of failing loudly — and why the reference smoke test now stamps a token into everything it creates.
28 KiB
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)
1. 快速开始
1.1 自检(先确认能连数据库)
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:
/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>。
取口令:
export KUBECONFIG=$HOME/.kube/config
kubectl -n paper-doc get secret paper-doc-secrets -o jsonpath='{.data.MCP_HTTP_TOKEN}' | base64 -d; echo
自检与验证:
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(自己起一个)
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 跑冒烟测试
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 自己拉起进程,最简单):
- 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(服务常驻,多个客户端共用):
- 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:
claude mcp add paper -- /data/project/paper/backend/.venv/bin/python \
/data/project/paper/backend/scripts/mcp_server.py
远程 HTTP(带口令):
claude mcp add --transport http paper http://192.168.1.88:8931/mcp \
--header "Authorization: Bearer 你的口令"
或者项目根目录放 .mcp.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):
[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:
[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。
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 |
读全文(format=text 时末尾附 Springer 格式的参考文献表) |
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 重调。
paper_document 的 text 里,正文的上标编号与末尾参考文献表的序号是同一个号:同一篇文献被引多次只占一个号、只列一条。
json 里对应的是 references(每条一个文献,text 就是排好版的条目)与 reference_style(当前是 springer),
以及 citations(每处引用一行,带自己的 index)。条目里缺哪些字段,看那条的 missing(如 ["卷期页码"]),
不要自己去猜或补一个看起来合理的年份。
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 个字段,全都有默认值,能填多少填多少):
{
"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 表示清空该字段(不传就是不动):
{"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 写完,整篇一次灌进去(主推)
// 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 分批写(更长、更可控)
{"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 微调:只动一句话
{"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 保持术语一致
{"name": "sentence_search", "arguments": {"keyword": "洪水损失", "limit": 20}}
// → 全库已写过的相关句子(带 paper_id / sentence_id),用来对齐说法
4.5 换模板(重塑结构但不丢正文)
{"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 从零建一套模板
{"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 文献:查重 → 录入 → 引用 → 复查
// 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) |