# 学术文献 MCP（多站点）

在本机运行的学术文献工具服务：通过 MCP stdio 接入 Claude、Cursor、Codex 等客户端，
提供 **检索 → 收集 → 下载** 闭环。

- **Web of Science**：Clarivate Starter API 检索 + 浏览器/开放获取下载
- **万方、维普**：机构订阅下的浏览器会话检索与全文下载（无需下载 Chromium，直接用本机 Edge）
- 三站输出同一套 `Record`，检索、去重、评分、存储、引文导出完全复用
- 架构见 [docs/DESIGN.md](docs/DESIGN.md)，中文站点细节见 [docs/CN_SITES.md](docs/CN_SITES.md)，
  新站点接入见 [docs/EXTENDING.md](docs/EXTENDING.md)

## 能力矩阵

| 站点 | 检索 | 结构化检索 | 题录补全 | PDF 下载 | 期刊指标 | 状态 |
|---|:---:|:---:|:---:|:---:|:---:|---|
| Web of Science | ✅ | ✅ | 基础题录（摘要视套餐） | ✅（订阅/OA） | 代理分 | 需 API Key |
| 万方 | ✅ | ✅ | ✅（摘要/关键词/DOI） | ✅（机构会话） | 无 | 需 Edge + 机构登录 |
| 维普 | ✅ | ✅ | ✅（摘要/关键词） | ✅（机构会话） | 无 | 需 Edge + 机构登录 |
| 中国知网 | ✅ | ✅ | ✅（摘要/关键词/基金/单位） | ✅（PDF/CAJ） | 无 | 需有头 Edge + 机构 IP |

`site="auto"` 只选择可无人值守工作的站点（当前是 WoS）；万方/维普/知网需显式指定站点，
避免一次普通检索突然弹出浏览器窗口。知网还要求**有头浏览器**：普通 HTTP 请求会被跳转滑块验证。

`list_sites` 会实时返回这份矩阵（以代码声明为准）。

## 快速开始

```bash
# 1. 安装
python -m pip install -e .
# 万方/维普/知网（或 WoS 的机构 PDF）需要浏览器驱动；不需要下载 Chromium
python -m pip install -e ".[browser]"
# 浏览器直接使用本机已安装的 Microsoft Edge（其次 Chrome），无需 playwright install

# 2. 配置
cp .env.example .env
# 编辑 .env，至少填入 ACADEMIC_MCP_WOS_API_KEY

# 3. 自检（不联网、不启动服务）
python -m academic_mcp check

# 4. 导出工具 schema（可选）
python -m academic_mcp schema --out docs/tool-schema.json

# 5. 启动 stdio 服务
python -m academic_mcp

# 或者以 HTTP 方式供远程/服务化 agent 接入（只监听回环）
python -m academic_mcp --transport http --port 8931
```

> 没有 API Key 时不会崩溃：`search` 返回 `status=failed` 与
> `SITE_NOT_CONFIGURED`（含配置提示）；`list_sites`、`diagnostics` 仍可用。
> `pytest` 内含本地 mock WoS API 与万方/维普/知网仿真页，可在无凭据、无外网的情况下
> 验证检索→详情→PDF 的完整链路（使用本机 Edge 的有头/无头模式）。

客户端配置示例：

```json
{
  "mcpServers": {
    "academic": {
      "command": "python",
      "args": ["-m", "academic_mcp"],
      "cwd": "F:/WorkBuddyAI/文献收集MCP",
      "env": {
        "ACADEMIC_MCP_WOS_API_KEY": "你的 Clarivate API Key",
        "ACADEMIC_MCP_DATA_DIR": "F:/WorkBuddyAI/文献收集MCP/data",
        "ACADEMIC_MCP_UNPAYWALL_EMAIL": "you@example.com"
      }
    }
  }
}
```

> API Key 申请：<https://developer.clarivate.com> → 注册应用 → 订阅 Web of Science
> Starter API。逐字段填写要点、免费档配额预算与验证步骤见
> [docs/WOS_KEY_SETUP.md](docs/WOS_KEY_SETUP.md)。
>
> 万方/维普/知网的登录、凭证、参数与异常处理见 [docs/CN_SITES.md](docs/CN_SITES.md)。
>
> **字段边界**：Starter API 稳定提供题名、作者、来源、年卷期页、DOI、关键词、
> 被引次数与 WoS 链接；**不保证返回摘要、机构、基金**。没有摘要的记录会标记为
> `detail_level=list`，评分只使用题名/关键词/被引等可得证据，不会把列表级记录
> 伪装成摘要级证据。若需要摘要与基金，需订阅 Expanded API（扩展点已预留）。

## 接入 Agent

配置只是第一步，真正决定效果的是 agent 怎么调。完整说明见
[docs/AGENT_INTEGRATION.md](docs/AGENT_INTEGRATION.md)，包含：

- 三种接入形态（stdio / streamable-http / 进程内）的取舍；
- WorkBuddy、Claude Desktop、Cursor、VS Code、Claude Code 的配置位置与差异；
- 工具调用链与参数策略（任务信封 → 轮询 → 快照 → 导出）；
- **可直接粘贴的系统提示词**：[examples/system-prompt.md](examples/system-prompt.md)；
- 错误码处置表、验证清单、排障表。

可运行的客户端示例（无需 API Key 即可验证链路）：

```bash
python examples/agent_client.py --demo                          # 进程内 mock WoS，跑通全流程
python examples/agent_client.py --query "algorithmic management" --limit 10
python examples/agent_client.py --url http://127.0.0.1:8931/mcp  # 连 HTTP 服务
```

```text
[3] 检索 completed：候选 3，相关 2，入选 2
     1. [2023] Algorithmic management and worker autonomy in platform work · JOURNAL OF MANAGEMENT ST
[6] gbt7714 引文：
ZHANG S, LI S. Algorithmic management and worker autonomy in platform work[J]. JOURNAL OF MANAGEMENT STUDIES, 2023, 60(2): 101-130.
```

> 桌面客户端记住三点：`command` 用解释器绝对路径、`cwd` 指向项目根、`env` 显式给
> Key 和数据目录。`.env` 只在 `cwd` 下才会被读取。


## 工具

| 工具 | 作用 |
|---|---|
| `list_sites` | 站点与能力矩阵 |
| `search` | 研究检索：概念规划、多通道、去重、增强、反馈、评分 |
| `structured_search` | 布尔表达式（`{field,value,match}` / `{op,and|or|not,items}`） |
| `search_results` | 本地分页读取检索快照，不联网 |
| `get_metadata` | 批量题录补全，可 `local_only` / `refresh` |
| `download_paper` | WoS：订阅会话 → 开放获取 → 出版商页面；万方/维普/知网：机构会话详情页下载；知网支持 PDF/CAJ |
| `export_citations` | GB/T 7714、APA、MLA、Chicago、Vancouver、BibTeX、RIS、EndNote、CSL-JSON、JSON、CSV、Markdown、custom |
| `session_status` / `login` | 四站会话状态与登录（中文站点需显式传 `site`） |
| `operation_status` / `operation_control` | 长轮询、取消、继续、恢复浏览器 |
| `diagnostics` | 本地诊断，不联网 |

### 典型调用

```text
search(query="算法管理 与 劳动者自主性", concept_groups=[["算法管理","algorithmic management"],["劳动者自主性","worker autonomy"]], year_from=2020, limit=20)
→ {operation_id, status:"running"|"completed", result:{search_id, candidate_count, results:[...]}}

search_results(search_id="op_...", scope="selected", view="compact")
get_metadata(search_id="op_...", limit=10)
download_paper(record_ref="wos:WOS:000...")
export_citations(search_id="op_...", format="gbt7714")
```

## 设计要点

1. **任务化**：联网工具返回任务信封，`operation_status(wait_seconds<=55)` 长轮询；
   中断可 `continue`，已抓取的详情不会重复请求。
2. **单一节流点**：所有请求先扣预算、再取限速槽位；验证码时全局暂停新请求。
3. **能力协商**：站点声明 `SiteCapabilities`，缺失能力返回明确错误，流水线自动降级。
4. **站点只做翻译**：查询编译、响应解析、下载解析属于适配器；去重、评分、筛选、
   存储、引文属于通用层。
5. **证据边界**：`detail_level` 区分列表级/详情级；无 JCR 时质量分标注 `proxy`；
   下载失败说明解析链断在哪一步，不猜、不绕过付费墙。

## 目录

```
academic_mcp/
  core/            # 站点无关：base, registry, pipeline, ranking, jobs, store, citations
  transports/      # httpx 客户端、Playwright 会话
  sites/
    webofscience/  # query / parsers / api / web / selectors / site
    wanfang/       # query / parsers / selectors / site（浏览器会话）
    vip/           # query / parsers / selectors / site（浏览器会话）
  tools/           # MCP 工具实现
  server.py        # MCPServer 注册
tests/             # 完整测试（含本地 mock WoS API 端到端）
examples/          # agent 侧客户端、客户端配置、系统提示词
docs/              # DESIGN / CN_SITES / CNKI_FEASIBILITY / AGENT_INTEGRATION / EXTENDING / WOS_KEY_SETUP / tool-schema
```

## 配置项

| 变量 | 默认 | 说明 |
|---|---|---|
| `ACADEMIC_MCP_DATA_DIR` | `./data` | 数据库、下载、导出、浏览器 profile |
| `ACADEMIC_MCP_WOS_API_KEY` | — | Clarivate API Key（检索必需） |
| `ACADEMIC_MCP_WOS_API_BASE` | 官方 Starter API | 便于代理/测试 |
| `ACADEMIC_MCP_WOS_DB` | `WOS` | WoS 数据库缩写 |
| `ACADEMIC_MCP_WOS_ENABLE_BROWSER` | `false` | 启用机构订阅 PDF 通道 |
| `ACADEMIC_MCP_UNPAYWALL_EMAIL` | — | 开放获取查询的联系邮箱 |
| `ACADEMIC_MCP_REQUEST_INTERVAL_MS` | `600` | 请求间隔 |
| `ACADEMIC_MCP_MAX_INFLIGHT` | `3` | 并发上限 |
| `ACADEMIC_MCP_INLINE_WAIT_SECONDS` | `40` | 工具调用内等待时间 |
| `ACADEMIC_MCP_BROWSER_HEADLESS` | `false` | 登录/验证建议保持有头 |
| `ACADEMIC_MCP_BROWSER_CHANNEL` | 自动 | 留空自动用 Edge，其次 Chrome；可强制 `msedge`/`chrome` |
| `ACADEMIC_MCP_BROWSER_EXECUTABLE` | — | 非标准安装路径时指定浏览器可执行文件 |
| `ACADEMIC_MCP_WANFANG_*` | — | `USERNAME/PASSWORD/LOGIN_MODE/INSTITUTION/BASE_URL/DETAIL_BASE` |
| `ACADEMIC_MCP_VIP_*` | — | `USERNAME/PASSWORD/LOGIN_MODE/INSTITUTION/BASE_URL` |
| `ACADEMIC_MCP_CREDENTIAL_FILE` | `data/credentials.json` | 凭证 JSON（明文，建议 600 权限） |
| `ACADEMIC_MCP_SESSION_PROBE_TTL` | `120` | 会话状态缓存秒数 |
| `ACADEMIC_MCP_ENABLED_SITES` | `wos,wanfang,vip` | 启用的站点 |

## 测试

```bash
python -m pytest -q
```

覆盖：三站查询编译、DOM/JSON 容错解析、去重、相关性/质量评分、检索流水线、
SQLite 存储、13 种引文格式、任务预算/取消/超时快照/人工等待、凭证解析与脱敏、
统一文件命名、重试与 HTTP 状态分类。

端到端：本地 mock WoS API 跑通检索→收集→导出；本地仿真万方/维普/知网页面 + 本机 Edge
跑通检索→详情补全→PDF 下载→台账与命名（无需真实机构账号）。

## 合规与限制

- **不绕过付费墙**：只使用用户自身机构订阅（可见浏览器会话）或合法开放获取副本。
- **不代管凭据**：浏览器登录由用户在弹出窗口完成，密码不经过 MCP 进程。
- **不伪造指标**：Starter API 不提供 JCR 影响因子/分区，质量分为代理值并明确标注。
- **浏览器选择器**集中在各站 `selectors.py`，UI 改版时只改一个文件；API 通道不受影响。
- 万方/维普/知网依赖机构订阅与内网/VPN 权限；能登录不等于有全文权限，下载失败会如实报告
  `FORBIDDEN`/`DOWNLOAD_UNAVAILABLE`，不做付费墙绕过。
- 万方详情页与两站的真实 PDF 下载仍需用你的机构账号做一次回归（见
  [docs/CN_SITES.md](docs/CN_SITES.md) 第 9.2 节）。