Scholar Engine MCP

Compilador semântico de literatura científica de alta velocidade e servidor FastMCP, alimentado por arXiv, OpenAlex, consultas HTTP range do DuckDB e TypeSafe Jev System One.

GitHubExperimente este MCPPatrocinado

Documentação

Scholar Engine MCP 🔬⚡

Compilador Semântico de Literatura Científica de Alta Velocidade & Servidor FastMCP
Desenvolvido com arXiv, OpenAlex, consultas de intervalo HTTP do DuckDB e TypeSafe Jev System One.

License: MIT Python 3.10+ FastMCP Powered by Jev

💡 Por que o Scholar Engine?

A Geração Aumentada por Recuperação (RAG) tradicional depende de similaridade vetorial densa (cos(query, chunk)). A similaridade vetorial é excelente para responder "qual texto se parece com minha consulta?", mas falha fundamentalmente em questões científicas estruturais e empíricas, como:

"Qual artigo publicado comprovou experimentalmente a redução de latência carregada em hardware fixo sem fio real, sem exigir PHY Wi-Fi 6?"

A busca vetorial retornará dezenas de artigos repletos de equações de simulação ou pesquisas teóricas que apenas mencionam "sem fio" e "latência" milhares de vezes.

Scholar Engine repensa a descoberta científica para agentes de IA combinando:

  1. Zero inchaço de armazenamento: Consulta diretamente o conjunto de dados Parquet de 3,15M arxiv-complete do Hugging Face usando consultas de intervalo HTTP do DuckDB. Não é necessário baixar um corpus de PDF de 16 TB.
  2. Enriquecimento do grafo de citações: Obtém instantaneamente métricas de citação e grafos de autores via OpenAlex.
  3. Portões semânticos probabilísticos (Jev System One): Perguntas em linguagem natural são compiladas em predicados probabilísticos persistentes de 154ms (ex.: P_real_hardware > 0.85, P_empirical > 0.75).
  4. Cache de predicados materializados: Predicados avaliados são armazenados em cache em bitmaps SQLite, permitindo que execuções subsequentes reutilizem julgamentos passados com custo zero de inferência.
  5. Portão Jev duplo (Pré-RAG e Pós-RAG):
    • Pré-RAG: Descarta artigos não empíricos ou irrelevantes antes da leitura do texto completo.
    • Pós-RAG: Verifica cada afirmação sintetizada pelo agente de raciocínio contra passagens de evidência extraídas (supported, partial, unsupported, contradicted).

📊 Matriz de Comparação

RecursoScholar MCPArXiv MCP TradicionalPaperQA2Elicit / Consensus
Interface PrincipalServidor FastMCP LocalMCP localBiblioteca Python / CLIAplicativo Web / SaaS fechado
Velocidade de BuscaSub-segundo a ~3s~1-2s30s - 90s~5s
Custo por Consulta<$0,001 (ou $0 em simulação)Gratuito (API com limite de taxa)$1,00 - $5,00+ / execuçãoAssinatura mensal
Acesso ao LaTeX de Texto CompletoSim (DuckDB HTTP Range)❌ (Somente resumo)Sim (Baixa PDFs completos)Índice proprietário
Filtragem Semântica por PredicadosSim (Jev System One)❌ Nenhum❌ NenhumFiltros heurísticos
Cache de Bitmaps de PredicadosSim (SQLite)❌ Nenhum❌ Nenhum❌ Nenhum
Verificação de Afirmação-EvidênciaSim (Verificador Pós-RAG)❌ NenhumSim (Loop pesado de LLM)Pontuação simples
Suporte a Ferramentas de AgenteClaude, Cursor, Codex, AGYParcial❌ Nenhum❌ Nenhum

🏛️ Arquitetura

flowchart TD
    subgraph INGESTION["1. Zero-Storage Discovery"]
        ARXIV["arXiv Atom API (Search & Metadata)"]
        OPENALEX["OpenAlex Graph API (Citations & Authors)"]
        HF["Hugging Face arxiv-complete (3.15M Papers)"]
        DUCKDB["DuckDB HTTP Range Scanner (Targeted LaTeX fetch)"]
        HF --> DUCKDB
    end

    subgraph ENGINE["2. Scholar Semantic Engine"]
        DISCOVER["Candidate Retrieval Engine"]
        ARXIV --> DISCOVER
        OPENALEX --> DISCOVER
        DUCKDB --> DISCOVER

        subgraph GATES["Jev System One Gates"]
            PRE_RAG["Pre-RAG Gate (P_empirical, P_applicable)"]
            POST_RAG["Post-RAG Verifier (Claim vs Evidence)"]
            PRED_CACHE[("SQLite Predicate Cache & Bitmaps")]
        end

        DISCOVER --> PRE_RAG
        PRE_RAG <--> PRED_CACHE
        PRE_RAG --> POST_RAG
        POST_RAG <--> PRED_CACHE
    end

    subgraph MCP_INTERFACE["3. FastMCP Server Interface"]
        TOOL_SEARCH["scholar_search (Fast paper discovery)"]
        TOOL_INSPECT["scholar_inspect (Deep paper metrics & OpenAlex)"]
        TOOL_RESEARCH["scholar_research (Full autonomous loop)"]
    end

    ENGINE --> MCP_INTERFACE
    MCP_INTERFACE --> CLIENTS["AI Agents: Claude Desktop, Cursor, Codex, Antigravity"]

🚀 Início Rápido

1. Instalação

# Clone the repository
git clone https://github.com/wolverin0/scholar-mcp.git
cd scholar-mcp

# Install dependencies (or install in a virtual environment)
pip install -e .

2. Configuração (.env)

Copie .env.example para .env:

cp .env.example .env

# Optional: TypeSafe Jev API Key for live 154ms System One probabilistic decisions
# If unset, Scholar Engine automatically runs in high-fidelity deterministic simulation mode!
TYPESAFE_API_KEY=your_typesafe_key_here

3. Executar Testes

Verifique se tudo está funcionando localmente:

pytest -v

🤖 Configuração do Servidor MCP

Adicione o Scholar Engine às suas ferramentas de agente favoritas:

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "scholar": {
      "command": "python",
      "args": ["-m", "scholar.mcp.server"],
      "env": {
        "TYPESAFE_API_KEY": "your_key_here"
      }
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "scholar": {
      "command": "python",
      "args": ["-m", "scholar.mcp.server"]
    }
  }
}

Antigravity / Wezbridge (.mcp.json)

{
  "mcpServers": {
    "scholar": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "scholar.mcp.server"]
    }
  }
}

🛠️ Referência de Ferramentas FastMCP

1. scholar_search

Busque rapidamente artigos científicos no arXiv por tópico, palavra-chave ou título, com filtragem opcional por ano de publicação.

  • Argumentos:
    • query (str): Tópico ou palavras-chave da busca (ex.: "loaded latency wifi").
    • limit (int, padrão=5): Número de candidatos a retornar.
    • year_min (int, opcional): Ano mínimo de publicação (ex.: 2022).
    • year_max (int, opcional): Ano máximo de publicação (ex.: 2026).
  • Retorno: Lista JSON estruturada de IDs, títulos, categorias, resumos e links para PDF.

2. scholar_inspect

Inspecione um artigo em detalhes pelo seu ID no arXiv. Combina métricas de citação do OpenAlex, autores e predicados semânticos armazenados.

  • Argumentos:
    • paper_id (str): ID do artigo no arXiv (ex.: "2007.07174" ou "2306.04338").
  • Retorno: Resumo completo, categorias, contagens de citações, DOI, ID no OpenAlex e características semânticas em cache.

3. scholar_verify_claim

Verifica uma afirmação empírica ou científica contra o resumo/texto completo de um artigo específico. Extrai a passagem de evidência mais relevante com offsets exatos de caracteres (start_char, end_char, source_field, doc_id).

  • Argumentos:
    • claim (str): Proposição empírica específica (ex.: "Method achieves sub-5ms latency under load").
    • paper_id (str): ID do artigo a ser verificado.
  • Retorno: Status (supported, contradicted, unsupported), pontuação de probabilidade, fonte de proveniência (live vs heuristic) e trechos exatos de evidência com offsets de caracteres.

4. scholar_verify_predicate

Avalia diretamente uma proposição booleana ou probabilística contra qualquer estado ou passagem de texto usando a semântica TypeSafe Jev System One.

  • Argumentos:
    • state_text (str): Evidência ou passagem de texto a ser avaliada.
    • question (str): Pergunta da proposição (ex.: "Does this passage report an in-vivo experiment?").
  • Retorno: Probabilidade em [0.0, 1.0], latência em ms e proveniência (live vs heuristic).

5. scholar_research

Loop autônomo de descoberta científica:

  1. Descobre candidatos no arXiv.
  2. Executa o portão semântico Jev System One para filtrar artigos não empíricos ou incompatíveis.
  3. Resolve grafos de citação e verifica afirmações contra o texto de evidência com trechos exatos.
  • Argumentos:
    • query (str): Pergunta de pesquisa ou tópico de engenharia.
    • domain (str, padrão="general"): Dica de domínio (ex.: "wireless", "databases", "ai").
    • threshold (float, padrão=0.50): Pontuação mínima de probabilidade necessária para passar nos portões semânticos.
    • limit (int, padrão=10): Número máximo de candidatos a avaliar.
  • Retorno: Artigos sobreviventes com respaldo de evidência, métricas de confiança, trechos exatos de evidência e detalhamento de auditoria dos itens descartados.

🏛️ Consenso Arquitetural de IA Tri-Modelo (Claude, Codex, Gemini)

A arquitetura v1.1 do Scholar Engine foi refinada e auditada por meio de um debate estruturado de IA em 3 rodadas entre as famílias de LLM de fronteira:

  • Anthropic Claude (Fable 5.1 / nível Opus): Segurança de sistemas, rastreamento de caracteres em nível de trecho e harness de regressão CI.
  • OpenAI Codex (GPT 6 Astra / nível Codex): Pipeline de verificação em 3 estágios (Retrieval -> Extraction -> Assessment), segurança MCP limitada e isolamento de parâmetros.
  • Google Gemini (Gemini 3.8 Flash / nível Gemini 2.5): Facetas de metadados sensíveis ao contexto, trilhas de auditoria para retratações e resiliência multimodelo.

Leia os logs completos e não editados do debate e o roteiro arquitetural:

🧪 Harness de Avaliação CI e Suíte de Testes

O Scholar Engine inclui um harness de avaliação abrangente com 50 benchmarks em tests/test_eval_harness.py:

  • Integridade de Offsets de Trechos: Verifica se os trechos de evidência extraídos correspondem a fatias exatas de string nos documentos de origem.
  • Detecção de Contradições: Testa refutação ativa e detecção de negação.
  • Abstenção por Evidência Insuficiente: Valida que artigos não relacionados geram abstenções em vez de falsos positivos.
  • Resiliência Adversarial: Testa resistência contra injeção de prompt em texto acadêmico não confiável (ex.: instruções que tentam sobrescrever limites de verificação).
  • Demarcação de Proveniência: Garante que cada afirmação declare explicitamente sua fonte (API live vs fallback heuristic).

Execute a suíte de testes completa:

python -m pytest tests -v

💻 Uso via CLI

Você também pode usar o Scholar Engine diretamente do seu terminal:

# Search arXiv papers
scholar search "neural network verification" --limit 5

# Inspect a paper with OpenAlex citation metrics
scholar inspect "1711.00455"

# Run the autonomous semantic research loop
scholar research "wireless loaded latency scheduler" --threshold 0.50 --limit 10

📄 Licença

Licença MIT. Consulte LICENSE para detalhes.