topaz-thesis-review-mcp

支持 stdio 与 streamable-http 两种传输方式的 MCP Server，已内置 30 个硕士论文评审相关工具（核心能力已真实实现，其他为基础版）。

MCP 协议版本与生命周期（2024-11-05）

本服务实现 Model Context Protocol 2024-11-05，与 Claw、Cursor、MateClaw 等客户端的 stdio MCP 连接方式对齐：

stdio 传输帧格式（重要）

官方 @modelcontextprotocol/sdk 的 stdio 使用 逐行 JSON（NDJSON）：每条消息一行，以 \\n 结束（serializeMessage 为 JSON.stringify(msg) + '\\n'），不是 HTTP 风格的 Content-Length 头。

• 默认（推荐）：MCP_STDIO_FRAMING 未设置或为 ndjson 时，本服务与上述 SDK 一致，可与 MateClaw 正常握手。
• 旧版兼容：仅当自行对接旧脚本时，可设 MCP_STDIO_FRAMING=content-length，使用 Content-Length: …\\r\\n\\r\\n + body。

握手顺序简述：

1. 客户端发送 initialize（含 protocolVersion、clientInfo 等）。
2. 服务端返回 InitializeResult：protocolVersion（回显客户端请求版本）、capabilities（含 tools: {}）、serverInfo；可选 instructions（见环境变量）。
3. 客户端在收到 initialize 的响应后，应发送 notifications/initialized（通知，无 id，无需响应）。部分客户端（含个别 Claw 版本）可能省略该步。
4. 之后客户端可调用 tools/list、tools/call、ping 等。

stdio 传输（默认宽松）：默认不因缺少 notifications/initialized 而拦截 tools/*，避免在仅实现「initialize → tools/list」的客户端里表现为连不上 / 无法列出工具。若需按规范做严格校验，请设置 MCP_STRICT_LIFECYCLE=1（未满足顺序时返回 -32002）。

streamable-http：当前实现为无会话状态的 HTTP JSON-RPC，不强制上述 stdio 门禁（便于本地 POST /mcp 调试）。

Claw / MateClaw 已配置 npx 仍失败（Windows 常见）

日志若出现 MCP connect timeout after 15000ms（或类似「连接超时」），通常不是生命周期 -32002，而是下面两类之一：

1. npx -y 首次拉包超过客户端超时（常见 15s）
   npx 第一次执行要从 registry 下载并解压包，网络慢时很容易 >15s，MateClaw 在握手完成前就判定超时。
   处理：在终端先执行一次（把包装进本机缓存）：
   npx -y topaz-thesis-review-mcp@latest
   看到进程起来后再到 MateClaw 里点重连；或改用下面「直连 node」方式，避免每次依赖 npx 解析。

2. stdio 应对的是 npx 父进程，而不是最终跑 MCP 的 node 子进程
   部分 Electron 客户端对 多层 cmd → npx → node 的管道处理不稳定，表现为一直等不到握手 → 超时。
   推荐（最稳）：全局安装后，用 node.exe 直接执行包里的 server.mjs，不要经 npx：

   npm i -g topaz-thesis-review-mcp
   npm root -g

   假设 npm root -g 输出为 C:\Users\你\AppData\Roaming\npm\node_modules，则在 MateClaw 中配置：

   • Command：C:\Program Files\nodejs\node.exe（按本机 Node 安装路径修改）
   • Args（空格分隔为两段）：
     C:\Users\你\AppData\Roaming\npm\node_modules\topaz-thesis-review-mcp\server.mjs

   这样 stdin/stdout 只经过 一个 Node 进程，握手最快、也最符合 MCP stdio 预期。

3. PATH 与终端不一致（日志里没有 resolved PATH 或仍报找不到命令时）：把 Command 改为 node.exe / npx.cmd 的绝对路径（见上）。

4. 若日志为 -32002：参见上文 MCP_STRICT_LIFECYCLE；请使用默认宽松的 1.2.1+，且不要对 MateClaw 设置 MCP_STRICT_LIFECYCLE=1（除非确认客户端会发 notifications/initialized）。

5. 若日志为 MCP error -32000: Connection closed：先确认已升级到 1.3.0+（stdio 默认 NDJSON，与 MateClaw 内置 SDK 一致；旧版仅用 Content-Length 会导致握手失败）。若仍断开，再检查 protocolVersion 回显（需 1.2.2+）与 node.exe + server.mjs 路径是否正确。

环境变量（常用）

| 变量 | 说明 | |------|------| | MCP_TRANSPORT | stdio（默认）或 streamable-http | | MCP_STRICT_LIFECYCLE | 设为 1 时，stdio 下必须在 notifications/initialized 之后才允许 tools/*（规范审计用） | | MCP_LENIENT_LIFECYCLE | 设为 0 时与 MCP_STRICT_LIFECYCLE=1 等效（兼容旧文档写法） | | MCP_HTTP_HOST / MCP_HTTP_PORT / MCP_HTTP_PATH | HTTP 模式监听地址、端口、路径（默认 127.0.0.1、8765、/mcp） | | MCP_INCLUDE_INSTRUCTIONS | 设为 1 时，initialize 响应附带 instructions 字段（部分旧客户端可省略） | | MCP_STDIO_FRAMING | ndjson（默认，与官方 SDK / MateClaw 一致）或 content-length（旧脚本） |

开发自检

克隆仓库并 npm install 后可运行：

npm run smoke:mcp

用于验证 initialize → notifications/initialized → tools/list 是否通过。

启动方式

从 npm 安装使用（推荐：Claw / Cursor 等走 stdio）

安装包后，用全局命令或 npx 启动（无需先 git clone）：

npx -y topaz-thesis-review-mcp

在 MCP 客户端中通常配置为：

• 传输方式：stdio
• Command：npx
• Args：-y topaz-thesis-review-mcp

兼容旧命令名（仍指向同一入口）：thesis-review-mcp。

从本仓库克隆运行（开发 / 可选 HTTP）

若你在本机克隆了本仓库并执行了 npm install，可选用下列方式。

stdio（本地源码）

npm run start
# 或：node ./server.mjs

streamable-http（本地 HTTP，便于浏览器或仅支持 URL 的客户端调试）

npm run start:http

默认监听：

• MCP：http://127.0.0.1:8765/mcp
• 健康检查：http://127.0.0.1:8765/health

Cursor 示例（见仓库内 cursor.mcp.json）：

{
  "mcpServers": {
    "thesis-review-mcp": {
      "transport": "streamable-http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

30个工具

1. pdf_parse_document
2. pdf_extract_toc
3. pdf_extract_sections
4. detect_format_issues
5. extract_figures_tables
6. extract_references
7. academic_dimension_scoring
8. language_quality_check
9. generate_review_bundle
10. export_review_reports
11. citation_style_consistency_check
12. reference_freshness_analyzer
13. methodology_risk_detector
14. argument_chain_validator
15. plagiarism_risk_heuristics
16. terminology_consistency_check
17. critical_sentence_polisher
18. action_items_planner
19. batch_review_runner
20. review_history_store
21. compare_revision_diff
22. discipline_profile_loader
23. policy_rule_loader
24. explain_score_trace
25. qa_query_review
26. mcp_health_check
27. schema_validate
28. audit_log_write
29. redact_sensitive_data
30. confidence_estimator

入参约定（统一）

所有工具输入 arguments 结构：

{
  "request_id": "optional-trace-id",
  "payload": {}
}

当前状态说明

• 已实现 MCP 2024-11-05 生命周期、initialize / notifications/initialized、tools/list、tools/call。
• 30个工具均可被调用并返回统一结构。
• 已真实实现全部 30 个工具（规则/统计/启发式实现），可直接用于端到端流程。

依赖安装

在项目目录执行：

npm install

当前依赖：

• pdf-parse
• ajv

npm 发布

已提供发布指引：PUBLISHING.md。

快速发布流程：

npm login
npm pack --dry-run
npm publish --access public

一键联调脚本

已提供脚本：scripts/run-review-pipeline.mjs

执行示例：

npm run pipeline -- --pdf "D:\path\your-thesis.pdf" --out "D:\path\review-output" --discipline "工科"

可选参数：

• --rule "D:\path\policy.txt"：加载你自己的评审规则文本

脚本将按 MCP 调用顺序自动执行：

1. PDF解析
2. 目录/章节/参考文献提取
3. 格式审查、学术评估、逻辑校验、语言审查
4. 生成 bundle
5. 导出四份报告

输出包括：

• format-report-*.md
• academic-report-*.md
• language-report-*.md
• final-decision-*.md
• review-bundle-*.json
• pipeline-debug.json