CUC Literature MCP：中传 SCI 论文检索、PDF 下载与腾讯文档同步

一个运行在用户电脑上的 TypeScript STDIO MCP，配套可被 Codex 自动发现的 Skill。它使用独立、持久化的 Chrome 或 Edge 配置访问 Web of Science、IEEE/开放全文和腾讯文档，不调用 OpenAI API，也不会读取或返回账号密码和 Cookie。

当前版本：0.1.0。这是面向中国传媒大学机构访问场景的第一版。WOS、IEEE 和腾讯文档均为网页自动化适配器；网站改版后可能需要更新选择器。工具遇到不确定页面时会停止并返回可恢复错误，不会绕过验证码、登录或付费限制。

目录

• 能做什么
• 工作边界
• 让 Codex 指导安装
• Windows 快速安装
• macOS 快速安装
• 首次登录
• 开始使用
• 配置与输出
• MCP 工具
• 升级与卸载
• 常见问题
• 开发和测试

能做什么

• 在 WOS Core Collection 构造并执行高级检索；
• 默认检索中国传媒大学2024年至当前年份的 SCI-EXPANDED 论文；
• 围绕无线通信、通信导航融合、通信感知一体化扩展 RIS、语义通信、近场定位、卫星通信、SAGIN、毫米波、太赫兹、MIMO、NOMA、车联网、无人机通信、信道编码和6G等紧邻主题；
• 按 DOI → WOS号 → 标准化题名去重；
• 从腾讯正式工作表只读提取“期刊—2025中科院大类分区”映射；
• 按 IEEE 机构正式PDF → 出版商开放PDF → 预印本/作者公开稿的顺序尝试下载；
• 只保存 HTTPS、具有 %PDF 文件头、大小合理并通过 SHA-256 校验的文件；
• 增量同步到腾讯文档的非正式工作表，保护人工备注和已有附件；
• 按年份倒序，同年份按 1区 Top → 1区 → 2区 Top → 2区 → 3区 → 4区 → 待核验 整行排序；
• 把运行进度保存在本地，可在登录或验证码处理后用原 run_id 继续。

工作边界

本项目不会：

• 提供或共享中国传媒大学、WOS、IEEE、腾讯文档账号；
• 传输账号密码、Cookie 或浏览器配置；
• 绕过统一身份认证、验证码、机构权限或付费墙；
• 把未知中科院分区猜成“未收录”；
• 自动修改正式来源工作表“工作表1”；
• 授予论文 PDF 的再分发权。

每位使用者都必须拥有相应数据库和腾讯文档的合法访问权限。公开仓库不包含任何个人腾讯文档链接、浏览器登录态或已下载PDF。

让 Codex 指导安装

OpenAI 官方说明，Codex 会从仓库路径上的 .agents/skills 发现项目 Skill，本地 STDIO MCP 可以通过 codex mcp add 注册；ChatGPT 桌面应用、Codex CLI 和 IDE 扩展共享该配置：

• OpenAI：Build skills
• OpenAI：Model Context Protocol
• OpenAI：Windows desktop app

把仓库交给 Codex 后，可以直接发送：

请先完整阅读仓库根目录的 AGENTS.md 和 README.md。
检查我的操作系统、Node.js、Codex 和浏览器环境，指导并执行本项目安装。
不要读取或复制 .runtime/chrome-profile，不要询问我的密码、Cookie或验证码。
安装前向我索取一个有编辑权限的腾讯表格URL；目标工作表使用“MCP测试”。
安装后执行 doctor，打开专用浏览器让我自行完成WOS、IEEE和腾讯文档登录，并告诉我如何开始第一次检索。

Codex 应按照 AGENTS.md 执行。登录、验证码和腾讯文档授权必须由用户在可见浏览器中亲自完成。

Windows 快速安装

1. 前置条件

• Windows 11，推荐；
• ChatGPT Windows 桌面应用或 Codex CLI；
• Node.js 20 或以上；
• Google Chrome，或 Microsoft Edge；
• Git，可选，也可以下载 ZIP。

可以在 PowerShell 检查：

node --version
npm --version
codex --version

如果没有 Node.js：

winget install OpenJS.NodeJS.LTS

如果没有 Git：

winget install Git.Git

安装后重新打开 PowerShell。

2. 获取仓库

git clone https://github.com/SHENAO1/cuc-literature-mcp.git
cd cuc-literature-mcp

也可以从 GitHub 的 Code → Download ZIP 下载并解压，然后在该目录打开 PowerShell。

3. 执行安装

把下面的示例链接替换成你有编辑权限的腾讯表格链接：

Set-ExecutionPolicy -Scope Process Bypass
./scripts/install.ps1 `
  -TencentDocUrl "https://docs.qq.com/sheet/你的文档ID" `
  -BrowserChannel chrome

使用 Edge：

./scripts/install.ps1 `
  -TencentDocUrl "https://docs.qq.com/sheet/你的文档ID" `
  -BrowserChannel msedge

安装脚本会：

1. 用 npm ci 安装锁定版本依赖；
2. 编译并运行完整测试；
3. 把本机配置写到 .runtime/settings.json；
4. 使用 codex mcp add 注册 cuc-literature；
5. 执行安装诊断。

如果希望在其他项目目录也能用 $cuc-literature-search，增加：

-InstallGlobalSkill

完整 Windows 说明见 docs/WINDOWS.md。

macOS 快速安装

git clone https://github.com/SHENAO1/cuc-literature-mcp.git
cd cuc-literature-mcp
chmod +x scripts/install.sh scripts/uninstall.sh
./scripts/install.sh \
  --tencent-doc-url "https://docs.qq.com/sheet/你的文档ID" \
  --browser-channel chrome

可选的全局 Skill：

./scripts/install.sh \
  --tencent-doc-url "https://docs.qq.com/sheet/你的文档ID" \
  --install-global-skill

完整说明见 docs/MACOS.md。Linux/WSL 可以构建和运行协议测试，但本项目依赖可见桌面浏览器，第一版主要支持 Windows 原生和 macOS。

首次登录

安装后运行：

npm run login

工具会启动独立浏览器配置目录：

.runtime/chrome-profile

请在这个专用窗口中分别完成：

1. 中国传媒大学统一身份认证；
2. WOS 机构访问；
3. IEEE Xplore 机构访问；
4. 腾讯文档登录，并确认对目标文档有编辑和附件上传权限；
5. 如果出现验证码，由用户自行完成。

完成后回到终端按回车，程序会重新检查会话。不要把日常 Chrome 的用户目录复制到 .runtime，也不要把 .runtime 分享给别人。

诊断当前会话：

npm run diagnose

安装诊断：

npm run doctor

完成安装或修改 MCP 配置后，重启 ChatGPT/Codex。

开始使用

在本仓库打开新的 Codex 会话，输入：

使用 $cuc-literature-search 检索中国传媒大学2024年以来无线通信、通信导航融合和通信感知一体化相关SCI论文，写入默认腾讯文档并下载PDF。

如果安装了全局 Skill，也可以在其他项目中这样调用。

正常编排顺序：

check_browser_session
  → refresh_partition_map
  → create_search_run
  → search_wos
  → download_fulltext
  → sync_results
  → get_run_status

出现 login_required、captcha_required 或 needs_user_action 时，不要新建运行。完成页面操作后让 Codex使用原 run_id 重试。详细示例见 docs/USAGE.md。

配置与输出

本机设置

安装器把非敏感设置写入：

.runtime/settings.json

该文件不会提交到 Git。重新配置：

npm run configure -- \
  --tencent-doc-url "https://docs.qq.com/sheet/你的文档ID" \
  --browser-channel chrome \
  --source-sheet "工作表1" \
  --target-sheet "MCP测试" \
  --pdf-directory "output/pdfs"

PowerShell 可以把反斜杠续行改为一行，或使用反引号 `。

环境变量优先于 .runtime/settings.json：

变量	用途	默认值
CUC_LITERATURE_HOME	项目绝对路径	当前工作目录
CUC_TENCENT_DOC_URL	腾讯表格链接	必填，无公开默认值
CUC_SOURCE_SHEET	分区映射来源表	工作表1
CUC_TARGET_SHEET	MCP写入目标表	MCP测试
CUC_PDF_DIR	PDF目录	output/pdfs
CUC_BROWSER_CHANNEL	chrome或msedge	chrome
CUC_WOS_URL	WOS入口覆盖	中传机构入口
CUC_IEEE_URL	IEEE入口覆盖	中传图书馆IEEE入口
CUC_HEADLESS	测试用无头模式，设为1启用	不启用

腾讯文档表头

目标工作表固定写入 A—J：

论文题目、作者、年份、期刊、SCI索引、WOS号、DOI、
中科院SCI分区（2025大类）、PDF附件、学校数据库下载核验/未下载原因

• MCP 生成的 J 列以 [MCP] 开头；
• 已有非 [MCP] 人工备注不覆盖；
• 已有 PDF 附件不重复上传；
• 临时 K 列只用于整行排序，完成后清空；
• 目标工作表与来源工作表同名时程序拒绝运行。

本地文件

output/pdfs/<年份>/                 通过校验的PDF
.runtime/runs/<run-id>.json         可恢复进度
.runtime/chrome-profile/            独立浏览器登录态
.runtime/partition-map.csv          本地分区映射
config/partition-overrides.csv      可提交的人工分区覆盖

分区覆盖 CSV 格式：

journal,normalized_journal,partition,top,source
IEEE Access,ieee access,2区,false,override

MCP 工具

工具	主要输入	作用
check_browser_session	open_login_window	检查 WOS、IEEE、腾讯文档会话
refresh_partition_map	文档URL、来源工作表	只读提取期刊分区并生成本地映射
create_search_run	主题、年份、单位、输出位置	创建 run_id 和 WOS 查询式
search_wos	run_id	检索、完整记录导出、筛选和去重
download_fulltext	run_id	下载并验证有权获取的PDF
sync_results	run_id	增量写表、上传附件、整行排序
get_run_status	run_id	查看阶段、错误、输出和待操作项

所有工具返回简短文本和结构化 JSON。命中超过500篇时会停止，避免不受控批量操作。

升级与卸载

升级

git pull
./scripts/install.ps1 -TencentDocUrl "https://docs.qq.com/sheet/你的文档ID"

macOS：

git pull
./scripts/install.sh --tencent-doc-url "https://docs.qq.com/sheet/你的文档ID"

安装器只替换同名 cuc-literature MCP，不修改其他 MCP 配置。

Windows 卸载

只移除 MCP 注册，保留登录态、运行记录和PDF：

./scripts/uninstall.ps1

同时移除本地运行态和全局 Skill：

./scripts/uninstall.ps1 -RemoveRuntime -RemoveGlobalSkill

只有明确希望删除下载的论文时才增加：

-RemoveDownloadedPdfs

macOS 对应参数见 ./scripts/uninstall.sh --help或 docs/MACOS.md。

常见问题

codex 命令不存在

先确认 ChatGPT/Codex 已安装并重启终端。也可以在 ChatGPT 桌面应用中打开 Settings → MCP servers → Add server，选择 STDIO，手动填写 Node 路径和 dist/server.js。详细步骤见 docs/TROUBLESHOOTING.md。

PowerShell 禁止运行脚本

只对当前窗口临时放行：

Set-ExecutionPolicy -Scope Process Bypass

找不到 Chrome

安装 Chrome，或者重新执行安装并指定：

-BrowserChannel msedge

WOS 或 IEEE 一直要求登录

确认使用的是工具启动的专用浏览器窗口，且当前网络/账号具有中国传媒大学数据库权限。校外访问可能还需要学校允许的 VPN 或统一身份认证。

腾讯文档能打开但不能写入

确认文档不是只读共享，并拥有编辑、创建工作表和上传附件权限。第一版依赖腾讯表格网页UI；页面改版可能触发 TENCENT_UI_CHANGED 等错误。

为什么有论文没有PDF

常见原因包括机构无权限、无PDF入口、登录失效、验证码、HTML伪PDF、附件超过限制或只有不接受的版本。元数据仍可写入，J列会记录标准化原因。

更多错误码和恢复方式见 docs/TROUBLESHOOTING.md。

开发和测试

npm ci
npm run check
npm test
npm run validate:skill

测试覆盖：

• WOS查询、筛选、导出解析和500篇安全边界；
• DOI/WOS/题名标准化及去重；
• 中科院分区解析和排序；
• PDF文件头、大小和SHA-256校验；
• 人工备注保护；
• WOS、IEEE、腾讯文档合成页面状态；
• MCP工具枚举、Schema、错误结构和编译后STDIO握手。

GitHub Actions 在 Windows、macOS 和 Ubuntu 上执行构建与测试。真实机构登录后的端到端测试不会在公共 CI 中运行。

贡献前请阅读 CONTRIBUTING.md，安全问题请阅读 SECURITY.md。架构说明见 docs/ARCHITECTURE.md。

许可证

MIT。数据库、出版商页面、腾讯文档及下载论文分别受其自身条款和版权约束；MIT 许可证只覆盖本仓库代码和文档。