openalex-mcp-server

---

Ferramentas

Cinco ferramentas para consultar o catálogo de pesquisa acadêmica OpenAlex:

Nome da Ferramenta	Descrição
openalex_search_entities	Pesquise, filtre, ordene ou recupere por ID em todos os 8 tipos de entidade.
openalex_analyze_trends	Agregação por grupo para análise de tendências e distribuição.
openalex_resolve_name	Resolva um nome ou identificador (DOI, ORCID, ROR, PMID, PMCID, ISSN, ID OpenAlex) para um ID OpenAlex.
openalex_get_citation_graph	Percorra o grafo de citações um salto a partir de um trabalho inicial: cita, citado_por ou relacionado_a.
openalex_describe_fields	Liste nomes de campos válidos para filtro, agrupamento e seleção para um tipo de entidade — chame antes de construir uma consulta para evitar erros de campo inválido.

openalex_search_entities

Ferramenta principal de descoberta e consulta. Cobre todos os tipos de entidade do OpenAlex (trabalhos, autores, fontes, instituições, tópicos, palavras-chave, editores, financiadores).

• Recupere uma única entidade por ID (ID OpenAlex, DOI, ORCID, ROR, PMID, PMCID, ISSN). id tem precedência: critérios de busca passados junto com ele não são aplicados, e a resposta informa quais foram descartados em vez de ecoá-los como se tivessem sido executados. As validações exclusivas de busca (limite semântico de página, sample com cursor, seed sem sample) também são ignoradas — uma consulta nunca é rejeitada por parâmetros que ela ignora
• Busca por palavras-chave com operadores booleanos, frases entre aspas, curingas e correspondência difusa
• Modos de busca semântica exata e por IA
• Sintaxe de filtro rica: AND entre campos, OR dentro de campos (us|gb), NOT (!us), intervalos (2020-2024), comparações (>100)
• Seleção padrão sensata de campos por tipo de entidade, aplicada tanto a buscas quanto a consultas por ID — evita respostas excessivamente grandes; passe select para escolher campos, ou ["*"] para o registro completo
• Nomes de campos select inválidos produzem um erro listando os campos válidos para aquele tipo de entidade
• A saída formatada do MCP é um renderizador genérico de markdown — cada campo retornado é exibido sem codificação fixa por tipo de entidade
• Paginação por cursor e até 100 resultados por página; sort aceita uma única chave ou uma lista separada por vírgulas, com o prefixo de ordem decrescente - aplicado por chave
• display_name é anulável — o OpenAlex não possui título para paratexto e outros registros sem título, que passam direto em vez de falhar a página inteira

---

openalex_analyze_trends

Agregue entidades em grupos e conte-as para análise de tendências, distribuição e comparativa.

• Agrupe por qualquer campo suportado (ano de publicação, status de acesso aberto, instituição, país, tópico, etc.)
• Combine com filtros para delimitar a população antes da agregação
• Até 200 grupos por página com paginação por cursor
• Suporta include_unknown para mostrar entidades sem valor para o campo agrupado

---

openalex_resolve_name

A porta de entrada para transformar qualquer coisa que você tenha em um ID OpenAlex. Sempre use isto antes de filtrar por entidade — nomes são ambíguos, IDs não são.

• Um nome ou nome parcial executa uma busca de autocompletar: até 10 correspondências com dicas de desambiguação, ~200ms
• Um identificador resolve deterministicamente para o único registro que ele endereça — ID OpenAlex, DOI, ORCID, ROR, PMID, PMCID ou ISSN, puro ou em formato de URL. Sem necessidade de entity_type: o identificador determina o seu próprio
• Um identificador que não corresponde a nada retorna um resultado vazio nomeando o esquema, não conselhos de busca por nome
• Filtro opcional por tipo de entidade e filtros em nível de campo, aplicados a consultas por nome

---

openalex_get_citation_graph

Travessia de grafo de citações de um salto a partir de um trabalho inicial. Encapsula os filtros cites/cited_by/related_to do OpenAlex por trás de um argumento explícito direction para que os chamadores não precisem conhecer os nomes dos filtros.

• cites: trabalhos que citam o trabalho inicial (citações recebidas)
• cited_by: trabalhos que o trabalho inicial cita (sua lista de referências)
• related_to: "trabalhos relacionados" algorítmicos do OpenAlex (~8-30 típicos, pode ser vazio para trabalhos menos citados)
• Aceita IDs OpenAlex, DOIs, PMIDs, PMCIDs como seed_id; valida o trabalho inicial via uma consulta singleton /works/{id} antes de percorrer, então trabalhos inexistentes aparecem como NotFound
• Combina com filters/sort/select para estreitar o grafo (ex.: publication_year=">2020", is_oa="true")

---

openalex_describe_fields

Descubra nomes de campos válidos antes de construir uma consulta — evita erros 400 de campo inválido. Suportado por um catálogo gerado a partir da própria validação de campos do OpenAlex.

• Liste campos válidos para qualquer tipo de entidade e contexto (filter, group_by ou select)
• group_by retorna o subconjunto do conjunto filter que o OpenAlex pode agregar — campos de data bruta, operadores *.search e modificadores de intervalo from_*/to_* são excluídos
• Passe query (um nome parcial ou adivinhado) para classificar resultados por similaridade de nome — revela o campo certo quando você só sabe aproximadamente o que quer
• Complementa as sugestões classificadas "você quis dizer" agora anexadas a erros de campo inválido nas ferramentas de busca, tendências e grafo de citações

Prompts

Prompt	Descrição
openalex_literature_review	Guia uma busca sistemática de literatura: formule consulta, busque, filtre, analise rede de citações, sintetize descobertas.
openalex_research_landscape	Analisa o panorama de pesquisa para um tópico: tendências de volume, principais autores/instituições, taxas de acesso aberto, fontes de financiamento.

Recursos

Construído sobre @cyanheads/mcp-ts-core:

• Definições declarativas de ferramentas — um arquivo por ferramenta, o framework cuida do registro e validação
• Tratamento unificado de erros em todas as ferramentas
• Autenticação plugável (none, jwt, oauth)
• Backends de armazenamento intercambiáveis via framework (não usado atualmente por este servidor)
• Logging estruturado com rastreamento OpenTelemetry opcional
• Executa localmente (stdio/HTTP) ou em Docker a partir do mesmo código

Específico do OpenAlex:

• Cliente de API tipado com normalização automática de IDs (DOI, ORCID, ROR, PMID, PMCID, ISSN, URLs OpenAlex)
• Reconstrução de resumos a partir de índices invertidos — texto simples em vez da codificação posicional do OpenAlex
• Códigos de status HTTP mapeados para classes de erro MCP específicas (400 → InvalidParams, 422 → ValidationError, 429 → RateLimited, etc.) com mensagens upstream exibidas
• Cada ferramenta que chama a API reporta quanto a chamada gastou do orçamento diário do OpenAlex e quanto resta, para que uma varredura paginada possa ser precificada antes de executar em vez de terminar em 429. Uma conta com saldo pré-pago também vê isso, pois continua servindo quando a cota do dia acaba
• Repetições de requisição cientes de timeout e suporte a cancelamento via AbortSignal

Começando

Instância Pública Hospedada

Uma instância pública está disponível em https://openalex.caseyjhand.com/mcp — sem necessidade de instalação. Aponte qualquer cliente MCP para ela via Streamable HTTP:

{
  "mcpServers": {
    "openalex-mcp-server": {
      "type": "streamable-http",
      "url": "https://openalex.caseyjhand.com/mcp"
    }
  }
}

Auto-hospedado / Local

Adicione à configuração do seu cliente MCP (ex.: claude_desktop_config.json):

{
  "mcpServers": {
    "openalex-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/openalex-mcp-server"],
      "env": {
        "OPENALEX_API_KEY": "your-openalex-api-key"
      }
    }
  }
}

OPENALEX_API_KEY é opcional — defina-o para uma chave de conta OpenAlex gratuita para limites de taxa com chave e orçamento sob o preço baseado em uso do OpenAlex, ou omita-o para acesso anônimo. Defina OPENALEX_MAILTO para um e-mail se quiser se identificar para o OpenAlex (o pool educado).

Pré-requisitos

• Bun v1.3.0 ou superior (para desenvolvimento)

Instalação

1. Clone o repositório:

git clone https://github.com/cyanheads/openalex-mcp-server.git

2. Navegue para o diretório:

cd openalex-mcp-server

3. Instale as dependências:

bun install

Configuração

Variável	Descrição	Padrão
OPENALEX_API_KEY	Opcional. Chave de API da conta OpenAlex, enviada upstream como api_key= (gratuita em openalex.org/settings/api). Sem ela, limites de taxa anônimos se aplicam.	—
OPENALEX_MAILTO	Opcional. E-mail enviado upstream como mailto= para se identificar para o OpenAlex (o pool educado). Um identificador de cortesia, separado da chave de API.	—
OPENALEX_BASE_URL	URL base da API OpenAlex.	https://api.openalex.org
MCP_TRANSPORT_TYPE	Transporte: stdio ou http.	stdio
MCP_HTTP_PORT	Porta para o servidor HTTP.	3010
MCP_AUTH_MODE	Modo de autenticação: none, jwt ou oauth.	none
MCP_ALLOWED_ORIGINS	Lista de permissão separada por vírgulas de cabeçalhos Origin do navegador para transporte HTTP. Não definido = somente loopback; defina como * para desabilitar.	somente loopback
MCP_LOG_LEVEL	Nível de log (RFC 5424).	debug
LOGS_DIR	Diretório para arquivos de log (somente Node.js).	<project-root>/logs
OTEL_ENABLED	Habilita instrumentação OpenTelemetry (spans, métricas, logs de conclusão).	false

Executando o Servidor

Desenvolvimento Local

• Compile e execute a versão de produção:

  bun run build
  bun run start:http   # or start:stdio
  

• Execute verificações e testes:

  bun run devcheck     # Lints, formats, type-checks
  bun run test         # Runs test suite
  

Docker

docker build -t openalex-mcp-server .
docker run -e OPENALEX_API_KEY=your-key -p 3010:3010 openalex-mcp-server

Estrutura do Projeto

Diretório	Propósito
src/mcp-server/tools/definitions/	Definições de ferramentas (*.tool.ts).
src/mcp-server/prompts/definitions/	Definições de prompts (*.prompt.ts).
src/services/openalex/	Serviço de cliente da API OpenAlex e tipos de domínio.
src/config/	Análise e validação de variáveis de ambiente com Zod.
tests/	Testes unitários e de integração, espelhando a estrutura src/.

Guia de Desenvolvimento

Veja CLAUDE.md para diretrizes de desenvolvimento e regras arquiteturais. A versão resumida:

• Handlers lançam, o framework captura — sem try/catch na lógica de ferramentas
• Use ctx.log para logging, ctx.state para armazenamento
• Sempre resolva nomes para IDs via openalex_resolve_name antes de usá-los em filtros

Contribuindo

Issues e pull requests são bem-vindos. Execute as verificações antes de enviar:

bun run devcheck
bun run test

Licença

Apache-2.0 — veja LICENSE para detalhes.