scholar-search
You can perform read-only bibliographic search and metadata retrieval across CNKI and Web of Science, then export records and monitor session/quota state.
Search CNKI (Chinese literature) and Web of Science (English literature) using keywords or professional query expressions, with pagination, limits, sorting, year/citation/impact-factor filters, field projection, optional abstracts, and count-only diagnostics.
Go deeper on Web of Science using
exclude_ut; usepageon CNKI, which has no exclusion field.Fetch full metadata for one record by URL or DOI, optionally including abstracts and selected fields.
Batch-fetch details for multiple records, with per-record success/failure reporting; risk blocks stop the batch.
Export records as RIS, EndNote, Markdown, or CSV, either inline or written to a file.
Check status: available channels, cooldown, remaining quota, bridge readiness, and a brief summary mode.
Operate within safety limits: read-only access, no PDF/full-text download, no third-party library ingestion, no CAPTCHA bypass, no bulk scraping, and immediate stop on risk blocks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@scholar-search 在知网检索钙钛矿太阳能电池的文献,按被引降序排列,每页50条"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
文溯 · wensu
!!! 注意不要用机构或大学的IP自动化访问这些网站,可能面临来自他们的处罚 !!!
只读的文献题录检索服务,以 MCP 工具或按需 CLI 的形式提供给 AI 客户端。微内核 + 渠道插件:
知网(CNKI) — 中文文献,中文检索式,17 个官方字段
Web of Science — 英文文献,
TS=/ALL=检索式,自带期刊影响因子(JCR),可筛选、可排序
万方、维普等以后按同一契约接入。
发行名 wensu(中文名「文溯」)。命令是
wensu,旧的scholar-search保留为兼容别名; Python 模块名仍是scholar_search,运行期目录仍是%LOCALAPPDATA%\scholar-search,老配置无需改动。
独立项目,非官方,与任何数据库运营方无隶属、合作或授权关系。
它能做什么
关键词检索:标题、作者、刊名、年份、被引、下载、详情链接
专业检索式:知网官方 17 个字段(
SU/TKA/KY/TI/FT/AU/FI/RP/AF/FU/AB/CO/RF/CLC/LY/DOI/CF), 支持and/*、or/+、not/-、%与括号翻页:每次 1 页,页码 1–3;每页 20 或 50 条
排序:相关度 / 发表时间降序 / 被引降序
单篇详情:摘要、关键词、作者单位、卷期页、DOI
导出:RIS / EndNote 纯文本,保留页面给出的文献类型(期刊 / 学位论文 / 会议 / 图书 / 报纸…)
Related MCP server: CNKI Search MCP Server
它不做什么
不下载 PDF / CAJ,不调用任何下载接口,不碰全文
不把题录写入 Zotero / EndNote / Mendeley。只输出 RIS / EndNote 文本, 导入由你自己在软件里完成(原因见 ADR 0006)
不破解验证码,遇到验证页立即停机,等你人工处理
不做批量抓取,没有"爬全库"模式,日上限 300 次由内核强制
不实现来源类型筛选(传了会明确报错);年份筛选只作用于本次已抓取的记录
安全边界
约束 | 值 |
动作词汇 | 固定九个: |
任意 JS | 没有。扩展只认这九个动作,选择器由计划带下来 |
域名 | 白名单,由渠道 manifest 声明,内核与宿主双重校验 |
最小间隔 | 3000 ms 硬下限,外加 0–1.2 s 随机抖动,并发 1 |
单次计划 | ≤ 40 个动作 / ≤ 200 s |
每日配额 | 300 个网络动作(读类动作不计数) |
风控 | 验证页 / 验证码 / 403 / 登录跳转 → 立即终止,返回 |
凭证 | 零。不读也不存任何账号、Cookie、会话材料 |
工作原理
MCP 客户端 ──stdio / HTTP──▶ MCP server
│
内核:契约 / 策略 / 风控 / 计划 / 审计 / 缓存
│
渠道插件 channels/cnki/ 与 channels/webofscience/
│
桥接适配器 ──TCP(loopback+token)──▶ 原生宿主
│
stdio │ 浏览器原生消息
▼
扩展 ──▶ 你的浏览器你不需要开调试端口,也不需要交出浏览器控制权:扩展只做九个通用动作, 站点知识(选择器、流程、解析)全部在 Python 侧的渠道插件里。
快速开始
前置:Windows、Python 3.11+、Edge(或 Chrome)。浏览器侧目前只在 Windows 上提供。
# 1) 装包(已发布到 PyPI;离线时用 Releases 里的 wheel)
pip install wensu
# 2) 一条命令装好浏览器资源与原生宿主
wensu setup
# 3) 装扩展(只需一次):edge://extensions → 开发者模式
# → 加载解压缩的扩展 → 选 wensu setup 打印的 extension 目录
# 扩展 ID 由 manifest 里的 key 固定,恒为 gmaimbocfjkolcpljeekjcomakipoaph
# 4) 验证
wensu statuswensu setup 把资源放到 %LOCALAPPDATA%\scholar-search\browser,注册 Edge/Chrome 的原生宿主,并打印
扩展目录;它不写系统目录,也不需要管理员权限。想自己指定位置或只复制资源,用
wensu setup --target <目录> / wensu setup --no-host。
status 里 bridge_ready: true 就通了。
更细的步骤(新建独立 Edge 环境、多浏览器、扩展 ID 对不上等)见 浏览器环境与扩展。让 agent 帮你装,见 skills/scholar-install。
接入 MCP 客户端
stdio 方式(Claude Desktop、Cursor 等用 JSON 配置的客户端;Codex 用 config.toml,见 Codex 接入):
{
"mcpServers": {
"wensu": {
"command": "wensu",
"args": ["serve", "--transport", "stdio"]
}
}
}HTTP 方式(本地回环 + 令牌):
wensu serve --transport http --host 127.0.0.1 --port 8765令牌在首次启动时写入 %LOCALAPPDATA%\scholar-search\http-token,请求带
Authorization: Bearer <token>,端点 http://127.0.0.1:8765/mcp。
细节见 docs/integration/dsh.md。
工具
工具 | 参数 | 返回 |
|
|
|
|
| 单条完整题录(含摘要、DOI、卷期页) |
|
|
|
|
| 纯文本;给了 |
|
| 渠道、剩余配额、冷却状态、桥接是否就绪 |
include_abstract 默认 false,fields 可把响应压到只留需要的键(url 与额度字段总是保留)。
检索后的详情不一定免费:WoS 的列表抓取会播种完整详情,detail 命中缓存扣 0;知网的列表
不播种详情,第一次 detail 需要一次网络动作,扣 1。同一篇再取则扣 0。
search 的年份筛选是客户端筛选:只对本次抓到的那一页生效,total 仍是站点总数。
筛选后为空说明目标年份不在这一页,换页或换检索式,不要连续翻页扫库。
并发
一个浏览器 profile 同一时间只应服务一个 agent。
同一 profile 下的检索与详情由同一把跨进程事务锁串行化:一条检索从提交到读取期间持有整把锁,
detail 和 journal 也拿同一把,所以它们不会插进检索的中途。后到的请求排队等待,不会读到
别人的页面。
多个 profile 时,每个浏览器有自己的 host。host 无法报告自己属于哪个 profile——它读的是同一份
browser.json——所以当有多个 host 且它们声称同一个 profile 时,工具会拒绝连接并说明原因,
而不是随机挑一个。目前可行的多 profile 用法是:一个 profile 一个 host,用 WENSU_PROFILE
指定本次调用使用哪个;无法消歧时请关掉多余浏览器。
升级到新版本
pip install --upgrade wensu
wensu setup --force
# 重启 MCP 客户端,让它重新拉起 server 进程要点:
必须重启 MCP 客户端。server 是 stdio 子进程,模块在启动时导入,换文件不会热生效。
扩展通常不用重装:Python 侧改动不影响扩展;只有
extension/里的 JS 或manifest.json变了才需要重新加载扩展。原生宿主在升级后要重跑
wensu setup --force(它负责写清单、注册表项和低完整性标签)。--force只覆盖复制出去的资源,不动已记录的浏览器配置。如果你用wensu browser adopt指定过专用 profile,升级后它仍然有效。要连浏览器配置一起重置, 用wensu setup --force --reset-browser——这会把browser.json换成默认的profiles/edge,原来的窗口和已经装好的扩展不会跟着迁移。
完整流程、目录布局与回滚见 docs/operations.md。
状态
当前版本见 wensu --version(pip install wensu 即可,PyPI 与 GitHub Release 同步)。真机验证过的能力:
能力 | 状态 |
知网关键词检索 | 通过( |
知网专业检索式 | 通过( |
知网翻页 1–3 | 通过 |
知网每页 50 条 | 通过 |
知网排序(时间 / 被引) | 通过,稳定降序 |
知网单篇详情 | 通过(含摘要、作者单位、卷期页) |
导出 RIS / EndNote | 通过(图书 → |
WoS 关键词检索 | 通过( |
WoS 专业检索式 | 通过( |
WoS 翻页第 2 页 | 通过(50 条,与第 1 页无重叠) |
WoS 影响因子 | 通过(记录自带 |
WoS 摘要按需取 | 通过(检索时播种缓存, |
检索失败了?先看这三条
这个 MCP 报告"检索失败"时,九成不是 MCP 的问题,而是浏览器或网络环境。 按下面的顺序排查, 不要反复重试(重试只会消耗配额,遇到风控还会触发 24 小时冷却)。
1. 代理软件对知网做了 TLS 中间人(国内最常见)
现象:search 返回 sleep failed: content_not_ready 或 type failed: bridge.timeout;
去看浏览器,窗口标题是「隐私错误」,页面上写着
NET::ERR_CERT_COMMON_NAME_INVALID,地址是 kns.cnki.net。
原因:Clash / v2ray / 其他系统代理把 kns.cnki.net 的证书换成了自己的,证书名对不上,
浏览器拒绝加载,页面变成错误页——错误页上没有人注入内容脚本,动作自然全部失败。
容易误判的地方:用 PowerShell 的 Invoke-WebRequest 或 curl 访问同一个地址会返回 200,
因为命令行工具不走系统代理设置。于是很容易得出"网站是好的,是 MCP 坏了"的结论——恰恰相反。
处理:让 cnki.net 直连。任选其一:
# 在代理软件里加规则(推荐,持久)
DOMAIN-SUFFIX,cnki.net → DIRECT# 或者把它加进 Windows 的代理例外,然后重启浏览器
$key = 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Internet Settings'
$cur = (Get-ItemProperty $key).ProxyOverride
if ($cur -notmatch 'cnki\.net') {
Set-ItemProperty $key -Name ProxyOverride -Value ($cur.TrimEnd(';') + ';*.cnki.net;cnki.net')
}验证:在那个浏览器窗口里打开 https://kns.cnki.net/kns8s/search,能看到检索框就对了。
2. 全新浏览器环境被要求人工验证
新 profile 没有 Cookie 与访问历史,第一次检索多半会落到知网的「安全验证」页,工具会正确返回
blocked 并上 24 小时冷却。这不是故障:在那个窗口里人工过验证,然后
wensu reset --confirm,再检索一次。详见
浏览器环境。
3. 窗口不在前台,定时器被节流
浏览器把后台窗口的定时器按整秒分桶,暂停动作会迟到,表现为 bridge.timeout 且
duration_ms 贴着超时值。把知网窗口切到前台、只留一个可见窗口再试。
更多排障(宿主没起来、goto 超时、配额用尽等)见运维手册。
目录
src/scholar_search/core/ 内核:契约、注册表、策略、风控、审计、缓存、导出
src/scholar_search/channels/ 渠道插件(cnki/2026.10、webofscience/2026.11)
src/scholar_search/adapters/ 浏览器适配器(bridge 生产 / fixture 测试)
src/scholar_search/transports/ stdio 与 HTTP
native-host/ 原生消息宿主(纯通讯层,Windows)
extension/ 浏览器扩展(九个动作,零站点知识)
schemas/ 记录与工具 JSON Schema
skills/ 给 agent 的技能说明
docs/ 架构、ADR、协议、运维、接入说明
tests/ 单元 + 契约 + fixture 回放文档
文档 | 内容 |
分层、请求流、策略与风控、扩展点 | |
目录布局、部署、升级、回滚、排障 | |
站点变了改哪里、怎么验证 | |
新建独立 Edge 环境、装扩展、扩展 ID | |
手动导入 RIS 的步骤(不做自动化) | |
推送、tag、CI 与发布 | |
新增渠道要实现的接口 | |
宿主与扩展的帧格式与校验 | |
关键决策记录 | |
线上踩过的坑与结论 |
合规声明
本项目仅用于个人学术研究中的题录检索。使用者应遵守目标站点的服务条款与所在机构的 使用规定。项目本身不附带任何数据、凭证或会话材料,也不提供把数据灌入第三方系统的能力。
来源与致谢
本仓库的代码是为本项目独立编写的,没有复制任何外部项目的源码文件、模块或函数。 沿用的只有三样:知网页面的 CSS 选择器字符串(属于 DOM 事实)、交互步骤的先后顺序 (由站点决定)、以及已知坑的知识(例如常驻隐藏的验证码 DOM)。这些做法受到三个公开的 MIT 项目启发:
浏览器通道、微内核结构、策略/风控引擎、解析器与导出层都是本项目自己的设计,与它们不同 (对照见 借鉴对照表)。完整的来源声明、依赖许可与 fixture 脱敏说明见 NOTICE。
tests/fixtures/ 下的页面快照已脱敏:摘要、作者、单位、关键词全部替换为合成占位文本,
邮箱与会话参数已删除,只保留标记结构、类名和公开的题录事实(标题、刊名、卷期页、DOI)。
License
MIT,见 LICENSE。
Available Tools
5 toolsdetailA
Fetch full metadata for one record.
url may be either the URL search returned, or a bare DOI such as
10.13841/j.cnki.jxsj.2026.11.001. CNKI detail URLs are several hundred
characters of encrypted signature — this one has no parameters but v= —
so passing them back verbatim is easy to truncate. A DOI is short, stable and
already in every record.
include_abstract defaults to false, matching search: a CNKI abstract
runs about 1200 characters and a WoS one about 1000, which is most of what a
detail response weighs. A caller that wants the volume, issue, pages and DOI
should not pay for text it will not read. fields projects the rest, and
always keeps url so the record stays followable.
A DOI costs one extra search to resolve into a URL, because that is the only way to reach the detail page. A URL that is already cached costs nothing.
channel is optional: it is inferred from the URL's host, or from the DOI
prefix. Pass it only to override that inference.
Inputs: url (required), fields, channel, include_abstract. Returns: object
detail_manyA
Fetch several records in one call.
Each lookup costs the same as detail and they run in sequence on purpose:
the policy layer serialises network actions anyway, so firing them in
parallel would only queue them while each held a timeout budget.
include_abstract and fields behave as in detail. A batch of twelve
abstracts is roughly 14 KB, so the default is off here too — this is the call
that most needs it, since the cost multiplies by the batch size.
A failure on one record does not abandon the rest — the response is
{"results": [{"url", "ok", "record"|"error"}], "ok_count", "failed_count"},
so a caller can retry just the ones that failed.
A risk block is the exception: it stops the batch. detail returns a
status: "blocked" payload rather than raising, so this loop used to file it
under ok: true and carry on — reporting a batch as successful while the
site was asking the caller to stop. AGENTS.md requires stopping on a block,
and a batch that keeps visiting after one is exactly the behaviour that rule
exists to prevent.
Inputs: urls (required), fields, channel, include_abstract. Returns: object
exportB
Render records as RIS or EndNote text.
With out_path, the text is written there and not returned: a caller
that wants 143 records on disk should not have to pull them through its
context to do it. Without it, the text comes back inline as before.
include_abstract defaults to false here even though the records may carry
one. An AB field roughly quadruples an RIS entry, and an export is usually
for a reference manager, which fetches abstracts on its own.
Inputs: records (required), format, out_path, include_abstract. Returns: object
searchA
Search a channel for bibliographic records. Read-only.
channel: "cnki" (default; Chinese literature, Chinese queries) or "webofscience" (English literature; also accepts a Web of Science expression such as TS=(ionic AND actuator) AND PY=(2021-2026) — with no year range the last five years are applied inside the expression).
Returns a shortlist by default: abstracts are omitted unless include_abstract is true, and sort_by / min_citations / sources_only filter locally without any browser action. For the full record call detail(url), which infers the channel from the URL.
Whether detail is free depends on the channel. A Web of Science search
captures full records, so a following detail is served from the cache at no
cost; a CNKI search captures only the list, so the first detail for a record
still needs one network action. Asking twice for the same record is always
free.
An empty records list is a normal answer, not a failure: read total and
dropped_year before concluding that a topic has no papers.
To get more records, the channel decides which lever exists. Web of
Science has exclude_ut: pass back the UT values you already have (the last
segment of each record's url) and the same query returns the records you
have not seen. Do that rather than asking for a deeper page — each
exclusion call is one independent request, while each page turn re-submits the
query and keeps a result list open. CNKI has no exclusion field, so page is
how you go further there.
total is the site's count for the query, before any local filter. With
a year range applied, total: 363 alongside nine records does NOT mean
"363 papers in that year" — it means the site matched 363 and this page lost
11 of its 20 to the year filter. filters.year_scope: "page" says so
explicitly, and filters.dropped.year gives the count. To get a year-accurate
total, put the year in the query (PY=(2026) on Web of Science,
SU='x' and 年='2026' on CNKI) or use site_sort=date and read the newest
page. empty_reason: "all_dropped_by_year" is the case where the whole page
was filtered away.
min_impact_factor is honoured by channels that ship journal metrics (currently webofscience); records whose journal has no metric are dropped, which lowers recall by design.
Two parameters sort and they are not interchangeable:
site_sort(relevance/date/citation) asks the site to re-sort. That is two extra clicks and costs quota.local_sort(none/citations/year) re-orders the page already in hand: free, no browser action, no quota.
Which parameters cost a fetch. The fetched page is cached as the site
returned it, and every local view is derived from it, so these are free even
when they change: limit, include_abstract, sort_by / local_sort,
min_citations, min_impact_factor, sources_only, fields. These are a
different request and cost a fetch: query, channel, site_sort, page,
year_from / year_to, exclude_ut.
The older names sort and sort_by still work and mean the same thing; the
new names say which one is which.
fields projects each record to the listed keys (plus url, which detail
needs). include_abstract on 25 rows is tens of kilobytes; most callers want
a title, a year and a DOI.
count_only drops records entirely and returns the count plus the
diagnostics that explain it. Testing whether an expression parses and matches
anything should not cost a full page of context: the recorded advice was
limit: 1, fields: ["title"], which still returns a record.
Inputs: query (required), page, sort, limit, +14 more. Returns: object
statusA
Session state: channels, cooldown, quota, bridge readiness.
brief returns only version, bridge_ready, bridge_last_seen,
quota_remaining and cooldown_until. The full payload is about 500 tokens,
more than a search, and three of its blocks — channel_capabilities,
detail_capabilities, action_cost — are static. Poll brief while planning
and read the full answer once.
Inputs: brief. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct operation: session diagnostics (status), discovery (search), single-record retrieval (detail), batch retrieval (detail_many), and formatting (export). The only near-overlap is detail vs detail_many, but the one-vs-many distinction is explicit and unlikely to cause misselection.
The set mixes noun-only names (status, detail), verb names (search, export), and noun_snake (detail_many). It remains readable, but it does not follow a single predictable verb_noun or other consistent pattern.
Five tools is tightly scoped for a scholarly search server: one for status, one for discovery, two for record retrieval, and one for export. Each earns its place without redundancy.
The surface covers discovery, full-record retrieval (single and batch), export, and session diagnostics, which is the core lifecycle for bibliographic search. Minor gaps like no dedicated channel-listing tool or related-work traversal are workable through existing tools or outside the stated purpose.
Maintenance
Related MCP Connectors
Read-only search and retrieval of published books, articles and authors, with public catalog links.
Read-only MCP tools for AI agent discovery, structured resources, and NIULAI information.
Search MCP servers, agent skills and AI tools by task. Read-only, no API key.
Search Chinese books with Douban ratings, AI book guides and curated toplists. Free, no API key.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables AI agents to search and retrieve academic papers from China National Knowledge Infrastructure (CNKI), supporting various search types including subject, keyword, author, and DOI lookups.321-
- FlicenseNot gradedqualityNot gradedmaintenanceAn MCP server for searching Chinese academic papers and core journal information across multiple free platforms like Baidu Scholar and the National Center for Philosophy and Social Sciences. It enables users to retrieve metadata for social science and STEM research papers without requiring API keys.-
- AlicenseAqualityDmaintenanceEnables AI assistants to search and retrieve paper information from CNKI (China National Knowledge Infrastructure), supporting 15 search types, pagination, sorting, and detailed metadata extraction.31MIT
- AlicenseAqualityBmaintenanceEnables AI to search, filter, and process CNKI academic literature through natural language, including structured search, metadata retrieval, full-text reading, citation export, and PDF/CAJ download.912GPL 3.0