# Google Scholar Labs Search (AJG 2024 MCP 适配版)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Protocol: MCP](https://img.shields.io/badge/MCP-2024--11--05-green.svg)](https://modelcontextprotocol.io/)
[![Tests: Offline Deterministic](https://img.shields.io/badge/tests-offline_passing-brightgreen.svg)](tests/)

面向本地大模型与 AI 智能体（Agent）的 **Model Context Protocol (MCP)** 服务。通过用户已登录的本地浏览器会话检索 **Google Scholar Labs** 学术文献，并严格依据 **AJG 2024 (Academic Journal Guide / ABS)** 权威期刊分级目录进行同行评议期刊筛选。

[English](README.en.md) | [简体中文](README.md)

---

## 终端 Dry-Run 离线演示

![Google-scholar-labs-ajg-mcp Dry-Run 流程演示](assets/demo.gif)

---

## 核心特性

- **严格的 AJG 2024 期刊分级筛选**：将检索到的文献出版物（Venue）与官方 AJG 2024 目录严格匹配（默认 ABS2+：`2`、`3`、`4`、`4*`），支持自定义星级门槛与学科大类筛选（如 `FINANCE`、`ACCOUNT`、`STRAT`、`ECON`、`ORMAN` 等）。
- **透明的剔除记录（Exclusion Transparency）**：不符合条件的文献（如预印本 arXiv/SSRN、未被 AJG 收录的期刊、星级低于设定门槛或学科不匹配）均在 `exclusions` 中完整记录并说明具体原因，杜绝将非核心刊物误判为合格文献。
- **全量合格结果输出**：返回当前检索页所有满足评级条件的论文，不人为截断为固定前 3 篇。
- **人机协同安全交接（Human-in-the-Loop Handoff）**：遇到 Google 登录验证或验证码（CAPTCHA）时立即安全暂停，返回 `handoff_required: true`，由用户在本地浏览器界面中手工完成验证，绝不尝试暴力绕过或窃取凭证。
- **本地优先与零遥测**：完全运行于本地环境，通过标准 Stdio JSON-RPC 2.0 通信，不向任何第三方服务器上传凭证或搜索记录。
- **零外部依赖核心解析**：内置核心期刊目录与纯标准库 XLSX 解析器，即使在无外部 Excel 文件的 CI 或纯净环境中也能执行完整的确定性测试。

---

## 架构与工作流

```
[ AI 智能体 (Codex / Claude / Cursor / Windsurf) ]
                         │
              (Stdio JSON-RPC 2.0)
                         ▼
             [ ScholarLabsMCPServer ]
                │                  │
                │ (Dry-Run / Mock) │ (浏览器自动化模式)
                ▼                  ▼
         [ 快速 Schema 验证 ]    [ CloakBrowser 会话 ]
                                   │ (本地持久化 Profile)
                                   ▼
                         [ Google Scholar Labs ]
                                   │ (HTML DOM 卡片提取)
                                   ▼
                          [ 候选论文卡片 ]
                                   │
                                   ▼
                          [ AJG 2024 匹配引擎 ]
                        ┌──────────┴──────────┐
                        ▼                     ▼
                 [ 合格文献列表 ]       [ 剔除记录 ]
                        └──────────┬──────────┘
                                   ▼
                     [ 结构化 JSON 响应结果 ]
```

---

## 安装与配置

### 环境要求

- Python 3.10 或更高版本
- （执行真实自动化搜索时可选）`cloakbrowser` 库与 Chromium 浏览器环境

### 1. 源码安装

```bash
git clone https://github.com/divenire990/Google-scholar-labs-ajg-mcp.git
cd Google-scholar-labs-ajg-mcp
pip install -e .
```

安装开发与构建依赖：

```bash
pip install -e ".[dev]"
# 或者仅安装打包构建依赖：
pip install -e ".[build]"
```

### 2. 构建分发包 (sdist & wheel)

构建源码分发包（`.tar.gz`）与二进制 Wheel（`.whl`）：

```bash
pip install build
python -m build
```

构建生成的文件位于 `dist/` 目录中（已被 `.gitignore` 自动忽略）。

### 3. 环境变量配置（可选）

复制 `.env.example` 为 `.env` 或在终端中配置环境变量：

```bash
# 本地浏览器持久化 Profile 路径（保存 Google 登录态）
export SCHOLAR_LABS_BROWSER_PROFILE="$HOME/.scholar-labs/browser-profile"

# 自定义 AJG2024.xlsx 数据文件路径（未设置时自动使用内置核心期刊或 data/AJG2024.xlsx）
export AJG_DATA_PATH="/path/to/AJG2024.xlsx"
```

---

## MCP 客户端配置

将 `google-scholar-labs-ajg-mcp` 添加至您的 AI 客户端配置中：

### Claude Desktop / Claude Code (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "google-scholar-labs-ajg-mcp": {
      "command": "python",
      "args": ["-m", "scholar_labs.mcp_server"],
      "env": {
        "SCHOLAR_LABS_BROWSER_PROFILE": "/path/to/your/browser-profile",
        "AJG_DATA_PATH": "/path/to/AJG2024.xlsx"
      }
    }
  }
}
```

### Codex / Windsurf / Cursor (`mcp.json` 或 `.toml`)

```toml
[mcp_servers.google_scholar_labs_ajg_mcp]
command = "python"
args = ["-m", "scholar_labs.mcp_server"]
```

---

## 工具接口说明：`scholar_labs_search`

### 输入参数

| 参数名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| `query` | `string` | *(必填)* | 提交给 Google Scholar Labs 的学术检索主题、问题或关键词。 |
| `min_stars` | `string` | `"2"` | 最低 AJG 星级筛选门槛（`"1"`, `"2"`, `"3"`, `"4"`, `"4*"`）。默认为 `"2"`（即 ABS2+）。 |
| `fields` | `array[string]` | `null` | 可选的学科领域代码列表（例如 `["ACCOUNT", "FINANCE", "STRAT", "ECON"]`）。 |
| `max_candidates` | `integer` | `15` | 首次解析提取的最大候选卡片数。 |
| `headless` | `boolean` | `true` | 是否以无头模式运行浏览器。 |
| `profile_dir` | `string` | `null` | 自定义持久化 Profile 目录路径（覆盖环境变量）。 |
| `dry_run` | `boolean` | `false` | Dry-run 模式：仅验证查询与 AJG 匹配引擎，不启动浏览器。 |
| `mock_html` | `string` | `null` | 用于离线评估与测试的 Mock HTML 内容。 |

### 输出响应示例

```json
{
  "status": "ok | blocked | no_results | error",
  "message": "执行结果摘要",
  "query": "dynamic strategic deviation and earnings management",
  "min_stars": "2",
  "fields_filter": ["FINANCE", "ACCOUNT"],
  "total_candidates_found": 8,
  "qualified_count": 3,
  "exclusion_count": 5,
  "qualified_papers": [
    {
      "title": "Corporate Governance and Financial Reporting Quality",
      "authors": "J Smith, A Taylor",
      "year": 2022,
      "venue": "Journal of Financial Economics",
      "scholar_url": "https://doi.org/10.1016/j.jfineco.2022.01.001",
      "annotation": "Investigates the causal link between strategic board adjustments and reporting accuracy.",
      "citation_signal": "Cited by 142",
      "position": 1,
      "raw_text": "...",
      "ajg_info": {
        "official_title": "Journal of Financial Economics",
        "ajg_star": "4*",
        "field": "FINANCE",
        "is_ft50": true,
        "is_utd24": true,
        "print_issn": "0304-405X"
      },
      "rank_score": 51.9
    }
  ],
  "exclusions": [
    {
      "title": "Machine Learning in Financial Forecasting",
      "venue": "arXiv preprint arXiv:2104.01234",
      "reason": "unmatched_venue",
      "details": "Venue 'arXiv preprint' not found in AJG 2024 journal index",
      "position": 3
    }
  ],
  "handoff_required": false,
  "handoff_url": null
}
```

---

## 离线测试与验证

运行确定性单元测试：

```bash
python -m unittest discover -s tests -p "test_*.py"
```

所有测试均在 2 秒内完成，无任何网络或浏览器依赖。

---

## 隐私、安全与合规声明

1. **安全交接与零绕过原则**：本工具绝不尝试自动化破解 Google CAPTCHA 验证码，绝不收集、导出或传输用户 Google 账号密码。遇验证要求时立即暂停并提示用户手动处理。
2. **本地凭证隔离**：所有 Cookie 和登录会话均保存在用户指定的本地 Profile 目录中，不进行任何远程同步。
3. **合规提示**：Google Scholar Labs 为 Google 旗下实验性学术产品，使用者须自行遵守 Google 服务条款与学术检索规范。

---

## 上游归属与开源协议

本项目基于 **MIT License** 开源。详见 [LICENSE](LICENSE) 文件。

### 归属致谢
本项目是在原 **Scholar Labs Search** 项目概念基础上演进与扩展的独立适配版本，新增了：
- AJG 2024 (ABS) 学术期刊分级筛选与加权排序
- 结构化剔除分类机制（Exclusion Transparency）
- 标准 Model Context Protocol (MCP) JSON-RPC 协议适配
- 确定性离线测试套件与安全交接架构