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 扩展共享该配置：
把仓库交给 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
安装脚本会：
- 用
npm ci安装锁定版本依赖； - 编译并运行完整测试；
- 把本机配置写到
.runtime/settings.json； - 使用
codex mcp add注册cuc-literature； - 执行安装诊断。
如果希望在其他项目目录也能用 $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
请在这个专用窗口中分别完成：
- 中国传媒大学统一身份认证；
- WOS 机构访问；
- IEEE Xplore 机构访问；
- 腾讯文档登录，并确认对目标文档有编辑和附件上传权限；
- 如果出现验证码，由用户自行完成。
完成后回到终端按回车，程序会重新检查会话。不要把日常 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 许可证只覆盖本仓库代码和文档。
