Omnisearch MCP

Servidor Model Context Protocol (MCP) para agentes LLM pesquisarem literatura acadêmica, resolverem PDFs open-access, baixarem/lerem papers e pesquisarem bibliotecas locais de PDFs.

Fontes suportadas

• IEEE Xplore via API oficial ou CAPES/CAFe proxy + cookies persistidos

• arXiv

• ACM Digital Library metadata via CrossRef

• CrossRef

• Semantic Scholar

• CORE

• Scite.ai

• Consensus.app

• Unpaywall para resolver PDFs open-access por DOI

• PDF local: indexação, busca e extração de texto

Related MCP server: Academia MCP

Instalação

git clone https://github.com/all3yp/omnisearch-mcp
cd omnisearch-mcp
uv sync
uv run playwright install chromium
cp .env.example .env

Edite .env conforme necessário:

CONTACT_EMAIL=seu-email@example.com
SEMANTIC_SCHOLAR_API_KEY=
CORE_API_KEY=
IEEE_XPLORE_API_KEY=

CAFE_INSTITUTION_ID=
CAFE_USERNAME=
CAFE_PASSWORD=
SCITE_EMAIL=
SCITE_PASS=
CONSENSUS_EMAIL=
CONSENSUS_PASS=
PLAYWRIGHT_BROWSER_PATH=

Comandos para usuário humano

Rodar servidor MCP

uv run omnisearch-mcp

Login e persistência de sessão

Recomendado: rode em modo visível na primeira vez, principalmente CAPES/IEEE, para completar MFA/CAPTCHA/SSO se aparecer.

uv run omnisearch-login-all
uv run omnisearch-capes-login
uv run omnisearch-scite-login
uv run omnisearch-consensus-login

Depois que funcionar visivelmente, você pode tentar headless:

uv run omnisearch-login-all --headless
uv run omnisearch-capes-login --headless
uv run omnisearch-scite-login --headless
uv run omnisearch-consensus-login --headless

Os scripts salvam:

• estado do navegador em .omnisearch/sessions/*.storage.json;

• cookies derivados no .env para os adapters HTTP.

Esses arquivos contêm segredos de sessão e são ignorados pelo Git.

Testes

uv run --group dev pytest

Se o uv falhar no Git Bash/Windows por trampoline, use:

/c/Users/alley/Code/alley/python/omnisearch-mcp/.venv/Scripts/python.exe -m pytest tests/ -v --tb=short

Como configurar no Claude Code

Na raiz do projeto, adicione o MCP ao Claude Code:

claude mcp add omnisearch-mcp -- uv run omnisearch-mcp

Ou use configuração JSON equivalente:

{
  "mcpServers": {
    "omnisearch-mcp": {
      "command": "uv",
      "args": ["run", "omnisearch-mcp"],
      "cwd": "C:/Users/alley/Code/alley/python/omnisearch-mcp"
    }
  }
}

Depois reinicie/recarregue o Claude Code e use ferramentas como:

• search_all

• search_ieee

• resolve_oa_url

• download_paper

• read_paper_content

• index_pdf_library

• search_pdf_library

Como configurar no Codex / OpenAI Codex CLI

Adicione o servidor MCP no arquivo de configuração do Codex com o comando abaixo:

[mcp_servers.omnisearch-mcp]
command = "uv"
args = ["run", "omnisearch-mcp"]
cwd = "C:/Users/alley/Code/alley/python/omnisearch-mcp"

Se seu cliente Codex usar JSON em vez de TOML, use:

{
  "mcpServers": {
    "omnisearch-mcp": {
      "command": "uv",
      "args": ["run", "omnisearch-mcp"],
      "cwd": "C:/Users/alley/Code/alley/python/omnisearch-mcp"
    }
  }
}

Ferramentas MCP principais

Como a busca IEEE/CAPES funciona

O login CAPES abre navegador via Playwright, persiste storage_state e deriva cookies HTTP. CAPES/IEEE está atrás do Akamai (não Cloudflare), então usa Playwright puro; apenas o Consensus.app usa CloakBrowser, pois é o único provedor com exposição confirmada ao Cloudflare (cf_clearance/__cf_bm).

Antes de salvar, o script CAPES valida a sessão com uma busca real:

POST {CAPES_PROXY_URL}/rest/search

Payload mínimo:

{
  "newsearch": true,
  "queryText": "machine learning",
  "returnType": "SEARCH",
  "rowsPerPage": 1
}

Só salva se o endpoint retornar JSON compatível com IEEE. Se receber HTML/login/401/403/redirect, não salva e pede relogin humano.

Quando não há IEEE_XPLORE_API_KEY, o adapter search_ieee usa uma sessão CAPES/IEEE persistida no navegador. Ele abre diretamente a busca avançada, seleciona até 50 itens por página e avança pelas páginas até atingir max_results ou esgotar os resultados da IEEE.

Skill para agentes consumidores

Agentes que usam este MCP devem seguir .github/skills/omnisearch-mcp/SKILL.md. A skill documenta o contrato das tools, limites por fonte, formato dos resultados, autenticação e a responsabilidade do agente chamador por qualquer síntese ou saída estruturada.

Instruções para agentes quando auth falhar

Se uma tool retornar auth_required: true:

1. Pare de tentar a mesma busca em loop.

2. Leia provider, command e agent_instruction.

3. Peça ao humano para rodar o comando indicado.

4. Aguarde o humano confirmar que o login terminou.

5. Tente a tool novamente uma vez.

6. Se falhar de novo, reporte bloqueio de autenticação e use fontes públicas se possível.

Exemplo de resposta de auth:

{
  "auth_required": true,
  "provider": "ieee",
  "action": "human_relogin_required",
  "command": "uv run omnisearch-capes-login --headless",
  "agent_instruction": "Stop retrying this provider. Ask the human to run the command, wait for login completion, then retry the same tool once.",
  "results": []
}

Para search_all, veja também:

{
  "auth_required_sources": ["ieee", "scite", "consensus"],
  "agent_instruction": "For sources in auth_required_sources, do not retry in a loop..."
}

Prioridade de relogin

1. CAPES/IEEE: uv run omnisearch-capes-login em modo visível é o caminho mais confiável.

2. Scite: uv run omnisearch-scite-login.

3. Consensus: uv run omnisearch-consensus-login.

Notas de segurança

• .env, .omnisearch/ e *.storage.json contêm segredos de sessão.

• Não imprima cookies, storage state, senhas ou tokens em logs/prompts.

• use_scihub é False por padrão. Use apenas quando você tiver direito legítimo de acesso ao paper e aceitar o risco legal local.

Créditos

Fork ampliado de ieee-research-mcp, criado por Kevin Zhao.