Google Scholar Labs Search (Versión adaptada a MCP AJG 2024)

Servicio Model Context Protocol (MCP) para grandes modelos locales y agentes de IA (Agent). Recupera literatura académica de Google Scholar Labs aprovechando la sesión ya iniciada del navegador local del usuario, y filtra las revistas revisadas por pares siguiendo estrictamente el directorio de clasificación de revistas autorizado AJG 2024 (Academic Journal Guide / ABS).

English | 简体中文

Demostración offline de Dry-Run en la terminal

Características principales

• Filtrado estricto por clasificación de revistas AJG 2024: compara estrictamente las publicaciones (Venue) de la literatura recuperada con el directorio oficial AJG 2024 (de forma predeterminada ABS2+: 2, 3, 4, 4*). Admite umbrales de estrellas personalizados y el filtrado por grandes áreas disciplinarias (como FINANCE, ACCOUNT, STRAT, ECON, ORMAN, etc.).

• Registro transparente de exclusiones (Exclusion Transparency): las publicaciones que no cumplen las condiciones (como preprints de arXiv/SSRN, revistas no incluidas en AJG, estrellas por debajo del umbral o áreas disciplinarias sin coincidencia) quedan íntegramente registradas en exclusions con el motivo específico, lo que evita que publicaciones no esenciales se clasifiquen erróneamente como literatura válida.

• Salida completa de resultados válidos: devuelve todas las publicaciones de la página de resultados actual que cumplen las condiciones de clasificación, sin truncarlas artificialmente a las 3 primeras.

• Transferencia segura con intervención humana (Human-in-the-Loop Handoff): ante la verificación de inicio de sesión de Google o un CAPTCHA, se pausa de inmediato de forma segura y devuelve handoff_required: true; el usuario completa la verificación manualmente en la interfaz del navegador local. Nunca se intenta eludirla por la fuerza ni robar credenciales.

• Local primero y cero telemetría: se ejecuta por completo en el entorno local y se comunica mediante Stdio JSON-RPC 2.0 estándar, sin enviar credenciales ni historiales de búsqueda a servidores de terceros.

• Núcleo de análisis sin dependencias externas: incluye un directorio central de revistas integrado y un analizador XLSX de biblioteca estándar pura, lo que permite ejecutar pruebas deterministas completas incluso en un CI o en entornos limpios sin archivos Excel externos.

Arquitectura y flujo de trabajo

[ 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 响应结果 ]

Instalación y configuración

Requisitos del entorno

• Python 3.10 o superior

• (Opcional para ejecutar búsquedas automatizadas reales) biblioteca cloakbrowser y entorno del navegador Chromium

1. Instalación desde el código fuente

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

Instale las dependencias de desarrollo y compilación:

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

2. Compilación de paquetes de distribución (sdist & wheel)

Compile el paquete de distribución de código fuente (.tar.gz) y la Wheel binaria (.whl):

pip install build
python -m build

Los archivos generados por la compilación se encuentran en el directorio dist/ (ignorados automáticamente por .gitignore).

3. Configuración de variables de entorno (opcional)

Copie .env.example a .env o configure las variables de entorno en la terminal:

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

Configuración del cliente MCP

Añada google-scholar-labs-ajg-mcp a la configuración de su cliente de IA:

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 o .toml)

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

Descripción de la interfaz de la herramienta: scholar_labs_search

Parámetros de entrada

Ejemplo de la respuesta de salida

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

Pruebas y verificación sin conexión

Ejecute las pruebas unitarias deterministas:

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

Todas las pruebas se completan en menos de 2 segundos, sin dependencias de red ni de navegador.

Declaración de privacidad, seguridad y cumplimiento

1. Principio de transferencia segura y cero evasión: esta herramienta nunca intenta descifrar automáticamente los CAPTCHA de Google, ni recopila, exporta o transmite las contraseñas de las cuentas de Google del usuario. Cuando se encuentra un requisito de verificación, se pausa de inmediato y se solicita al usuario que la resuelva manualmente.

2. Aislamiento local de credenciales: todas las cookies y sesiones de inicio de sesión se guardan en el directorio de perfil (Profile) local especificado por el usuario, sin ningún tipo de sincronización remota.

3. Aviso de cumplimiento: Google Scholar Labs es un producto académico experimental de Google; los usuarios deben cumplir por su cuenta las condiciones del servicio de Google y las normas de búsqueda académica.

Atribución al proyecto original y licencia de código abierto

Este proyecto se publica bajo la Licencia MIT. Consulte el archivo LICENSE.

Agradecimientos de atribución

Este proyecto es una versión adaptada independiente que evoluciona y amplía el concepto del proyecto original Scholar Labs Search, con las siguientes incorporaciones:

• Filtrado por clasificación de revistas académicas AJG 2024 (ABS) y ordenación ponderada

• Mecanismo estructurado de clasificación de exclusiones (Exclusion Transparency)

• Adaptación del protocolo estándar Model Context Protocol (MCP) JSON-RPC

• Conjunto de pruebas deterministas sin conexión y arquitectura de transferencia segura