Files
paper-doc/docs/MCP.md
T
govin b97aab6f30 docs: describe the citation styles and the per-work numbering
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.
2026-09-22 21:50:39 +08:00

28 KiB
Raw Blame History

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。

参考:Codex 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 读全文(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)