Google Scholar Labs Search (адаптированная версия AJG 2024 MCP)

Сервис Model Context Protocol (MCP) для локальных больших языковых моделей и AI-агентов (Agent). Выполняет поиск академических публикаций в Google Scholar Labs через локальную браузерную сессию пользователя, где уже выполнен вход, и строго фильтрует рецензируемые журналы в соответствии с авторитетным классификатором журналов AJG 2024 (Academic Journal Guide / ABS).

English | Китайский (упрощённый)

Офлайн-демонстрация Dry-Run в терминале

Ключевые особенности

• Строгая фильтрация по категориям журналов 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 на чисто стандартной библиотеке позволяют выполнять полные детерминированные тесты даже в CI или чистых средах без внешних Excel-файлов.

Архитектура и рабочий процесс

[ 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. Установка из исходного кода

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

Установка зависимостей для разработки и сборки:

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

2. Сборка дистрибутивов (sdist и wheel)

Собрать исходный дистрибутив (.tar.gz) и бинарный Wheel (.whl):

pip install build
python -m build

Собранные файлы находятся в каталоге dist/ (автоматически игнорируются через .gitignore).

3. Настройка переменных окружения (опционально)

Скопируйте .env.example в .env или настройте переменные окружения в терминале:

# 本地浏览器持久化 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)

{
  "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)

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

Описание интерфейса инструмента: scholar_labs_search

Входные параметры

Пример выходного ответа

{
  "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
}

Офлайн-тестирование и проверка

Запустите детерминированные модульные тесты:

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

Заявление о конфиденциальности, безопасности и соответствии требованиям

1. Принцип безопасной передачи и нулевого обхода: инструмент никогда не пытается автоматически взламывать капчу Google CAPTCHA, не собирает, не экспортирует и не передаёт пароли учётных записей Google. При требовании проверки немедленно приостанавливает работу и предлагает пользователю обработать её вручную.

2. Локальная изоляция учётных данных: все файлы Cookie и сеансы входа сохраняются в указанном пользователем локальном каталоге Profile, без какой-либо удалённой синхронизации.

3. Уведомление о соответствии: Google Scholar Labs — экспериментальный академический продукт компании Google; пользователи обязаны самостоятельно соблюдать условия обслуживания Google и нормы академического поиска.

Атрибуция вышестоящего проекта и лицензия с открытым исходным кодом

Этот проект распространяется с открытым исходным кодом под лицензией MIT License. Подробнее см. в файле LICENSE.

Благодарность за атрибуцию

Этот проект является независимой адаптированной версией, развивающей и расширяющей концепцию оригинального проекта Scholar Labs Search, с добавлением:

• Фильтрация по категориям академических журналов AJG 2024 (ABS) и взвешенная сортировка

• Структурированный механизм классификации исключений (Exclusion Transparency)

• Адаптация стандартного протокола Model Context Protocol (MCP) JSON-RPC

• Детерминированный набор офлайн-тестов и архитектура безопасной передачи