OpenAlex Author Disambiguation

Desambiguar autores y resolver instituciones usando la API de OpenAlex.org.

Documentación

Servidor MCP de Desambiguación de Autores de OpenAlex

Un servidor optimizado de Protocolo de Contexto de Modelo (MCP) para la desambiguación de autores e investigación académica utilizando la API de OpenAlex.org. Diseñado específicamente para agentes de IA con estructuras de datos optimizadas y funcionalidad mejorada.

🎯 Características Clave

🔍 Capacidades Principales

Desambiguación Avanzada de Autores: Maneja transiciones de carrera complejas y variaciones de nombres
Resolución de Instituciones: Afiliaciones actuales y pasadas con seguimiento de transiciones
Recuperación de Trabajos Académicos: Artículos de revistas, cartas y documentos de investigación
Análisis de Citas: Índice h, recuento de citas y métricas de impacto
Integración ORCID: Coincidencia de mayor precisión con identificadores ORCID

🚀 Optimizado para Agentes de IA

Datos Simplificados: Enfocado en información esencial para la desambiguación
Procesamiento Rápido: Estructuras de datos optimizadas para análisis rápido
Filtrado Inteligente: Opciones de filtrado mejoradas para consultas específicas
Salida Limpia: Respuestas estructuradas optimizadas para el razonamiento de IA

🤖 Integración con Agentes

Múltiples Candidatos: Resultados clasificados para toma de decisiones automatizada
Respuestas Estructuradas: Salida limpia y analizable optimizada para LLMs
Manejo de Errores: Degradación elegante con mensajes informativos
Filtrado Mejorado: Solo revistas, umbrales de citas y filtros temporales

🏛️ Nivel Profesional

Mejores Prácticas MCP: Construido con FastMCP siguiendo las pautas oficiales
Anotaciones de Herramientas: Anotaciones MCP adecuadas para una integración óptima con el cliente
Gestión de Recursos: Gestión y limpieza eficiente del cliente HTTP
Límite de Velocidad: Uso respetuoso de la API con retrasos adecuados

🚀 Inicio Rápido

Requisitos Previos

Python 3.10 o superior
Cliente compatible con MCP (por ejemplo, Claude Desktop)
Dirección de correo electrónico (para la cortesía de la API de OpenAlex)

Instalación

Para instrucciones de instalación detalladas, consulte INSTALL.md.

Clonar el repositorio:

git clone https://github.com/drAbreu/alex-mcp.git
cd alex-mcp

Crear un entorno virtual:

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Instalar el paquete:
```
pip install -e .
```

Configurar el entorno:

export OPENALEX_MAILTO=your-email@domain.com

Ejecutar el servidor:

./run_alex_mcp.sh
# Or, if installed as a CLI tool:
alex-mcp

⚙️ Configuración de MCP

Configuración de Claude Desktop

Agregue a su archivo de configuración de Claude Desktop:

{
  "mcpServers": {
    "alex-mcp": {
      "command": "/path/to/alex-mcp/run_alex_mcp.sh",
      "env": {
        "OPENALEX_MAILTO": "your-email@domain.com"
      }
    }
  }
}

Reemplace /path/to/alex-mcp con la ruta real al repositorio en su sistema.

🤖 Uso con Agentes de IA

Integración con OpenAI Agents

Puede cargar este servidor MCP en su flujo de trabajo de agente de OpenAI utilizando la interfaz agents.mcp.MCPServerStdio:

from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    name="OpenAlex MCP For Author disambiguation and works",
    cache_tools_list=True,
    params={
        "command": "uvx",
        "args": [
            "--from", "git+https://github.com/drAbreu/alex-mcp.git@4.1.0",
            "alex-mcp"
        ],
        "env": {
            "OPENALEX_MAILTO": "your-email@domain.com"
        }
    },
    client_session_timeout_seconds=10
) as alex_mcp:
    await alex_mcp.connect()
    tools = await alex_mcp.list_tools()
    print(f"Available tools: {[tool.name for tool in tools]}")

Integración con Agentes de Investigación Académica

Este servidor MCP está específicamente optimizado para flujos de trabajo de investigación académica:

# Optimized for academic research workflows
from alex_agent import run_author_research

# Enhanced functionality with streamlined data
result = await run_author_research(
    "Find J. Abreu at EMBO with recent publications"
)

# Clean, structured output for AI processing
print(f"Success: {result['workflow_metadata']['success']}")
print(f"Quality: {result['research_result']['metadata']['result_analysis']['quality_score']}/100")

Inicio Directo con uvx

# Standard launch
uvx --from git+https://github.com/drAbreu/alex-mcp.git@4.1.0 alex-mcp

# With environment variables
OPENALEX_MAILTO=your-email@domain.com uvx --from git+https://github.com/drAbreu/alex-mcp.git@4.1.0 alex-mcp

🛠️ Herramientas Disponibles

1. autocomplete_authors ⭐ NUEVO

Obtenga múltiples candidatos de autores utilizando la API de autocompletado de OpenAlex para una desambiguación inteligente.

Parámetros:

name (obligatorio): Nombre del autor a buscar (por ejemplo, "James Briscoe", "M. Ralser")
context (opcional): Contexto para la desambiguación (por ejemplo, "Francis Crick Institute biología del desarrollo")
limit (opcional): Máximo de candidatos (1-10, predeterminado: 5)

Características Clave:

⚡ Rápido: Tiempo de respuesta de ~200 ms
🎯 Inteligente: Múltiples candidatos con pistas institucionales
🧠 Listo para IA: Perfecto para selección basada en contexto
📊 Enriquecido: Recuento de trabajos, citas, información de la institución

Salida Simplificada:

{
  "query": "James Briscoe",
  "context": "Francis Crick Institute",
  "total_candidates": 3,
  "candidates": [
    {
      "openalex_id": "https://openalex.org/A5019391436",
      "display_name": "James Briscoe",
      "institution_hint": "The Francis Crick Institute, UK",
      "works_count": 415,
      "cited_by_count": 24623,
      "external_id": "https://orcid.org/0000-0002-1020-5240"
    }
  ]
}

Patrón de Uso:

# Get multiple candidates for disambiguation
candidates = await autocomplete_authors(
    "James Briscoe", 
    context="Francis Crick Institute developmental biology"
)

# AI selects best match based on institutional context
# Much more accurate than single search result!

2. search_authors

Busque autores con salida simplificada para agentes de IA.

Parámetros:

name (obligatorio): Nombre del autor a buscar
institution (opcional): Filtro por nombre de institución
topic (opcional): Filtro por tema de investigación
country_code (opcional): Filtro por código de país (por ejemplo, "US", "DE")
limit (opcional): Máximo de resultados (1-25, predeterminado: 20)

Salida Simplificada:

{
  "query": "J. Abreu",
  "total_count": 3,
  "results": [
    {
      "id": "https://openalex.org/A123456789",
      "display_name": "Jorge Abreu-Vicente",
      "orcid": "https://orcid.org/0000-0000-0000-0000",
      "display_name_alternatives": ["J. Abreu-Vicente", "Jorge Abreu Vicente"],
      "affiliations": [
        {
          "institution": {
            "display_name": "European Molecular Biology Organization",
            "country_code": "DE"
          },
          "years": [2023, 2024, 2025]
        }
      ],
      "cited_by_count": 316,
      "works_count": 25,
      "summary_stats": {
        "h_index": 9,
        "i10_index": 5
      },
      "x_concepts": [
        {
          "display_name": "Astrophysics",
          "score": 0.8
        },
        {
          "display_name": "Machine Learning", 
          "score": 0.6
        }
      ]
    }
  ]
}

Características: Estructura limpia optimizada para el razonamiento y la desambiguación de IA

2. retrieve_author_works

Recupere trabajos de un autor determinado con capacidades de filtrado mejoradas.

Parámetros:

author_id (obligatorio): ID de autor de OpenAlex
limit (opcional): Máximo de resultados (1-50, predeterminado: 20)
order_by (opcional): "date" o "citations" (predeterminado: "date")
publication_year (opcional): Filtrar por año específico
type (opcional): Filtro por tipo de trabajo (por ejemplo, "journal-article")
authorships_institutions_id (opcional): Filtrar por institución
is_retracted (opcional): Filtrar trabajos retractados
open_access_is_oa (opcional): Filtrar por estado de acceso abierto

Salida Mejorada:

{
  "author_id": "https://openalex.org/A123456789",
  "total_count": 25,
  "results": [
    {
      "id": "https://openalex.org/W123456789",
      "title": "A platform for the biomedical application of large language models",
      "doi": "10.1038/s41587-024-02534-3",
      "publication_year": 2025,
      "type": "journal-article",
      "cited_by_count": 42,
      "authorships": [
        {
          "author": {
            "display_name": "Jorge Abreu-Vicente"
          },
          "institutions": [
            {
              "display_name": "European Molecular Biology Organization"
            }
          ]
        }
      ],
      "locations": [
        {
          "source": {
            "display_name": "Nature Biotechnology",
            "type": "journal"
          }
        }
      ],
      "open_access": {
        "is_oa": true
      },
      "primary_topic": {
        "display_name": "Biomedical Engineering"
      }
    }
  ]
}

Características: Datos completos de trabajos con filtrado flexible para consultas específicas

📊 Optimización de Datos

Arquitectura de Información Enfocada

Este servidor MCP proporciona datos estructurados y enfocados diseñados específicamente para el consumo de agentes de IA:

Características de Datos de Autor

Resolución de Identidad: Nombres, ORCID, alternativas para desambiguación
Seguimiento de Afiliaciones: Conexiones institucionales actuales e históricas
Métricas de Impacto: Recuento de citas, índice h e impacto académico
Contexto de Investigación: Campos, conceptos y experiencia en el dominio
Análisis de Carrera: Cambios y transiciones de afiliación temporales

Características de Datos de Trabajo

Metadatos de Publicación: Título, DOI, medio y detalles de publicación
Evaluación de Impacto: Recuento de citas e influencia académica
Información de Acceso: Estado de acceso abierto y disponibilidad
Detalles de Autoría: Listas completas de autores y afiliaciones institucionales
Clasificación de Investigación: Temas, conceptos y categorización de dominio

Filtrado Mejorado

# Target high-impact journal articles
works = await retrieve_author_works(
    author_id="https://openalex.org/A123456789",
    type="journal-article",      # Focus on journal publications
    open_access_is_oa=True,      # Open access only
    order_by="citations",        # Most cited first
    limit=15
)

# Career transition analysis
authors = await search_authors(
    name="J. Abreu",
    institution="EMBO",          # Current institution
    topic="Machine Learning",    # Research focus
    limit=10
)

🧪 Ejemplo de Uso

Desambiguación de Autores

from alex_mcp.server import search_authors_core

# Comprehensive author search
results = search_authors_core(
    name="J Abreu Vicente",
    institution="EMBO",
    topic="Machine Learning",
    limit=20
)

print(f"Found {results.total_count} candidates")
for author in results.results:
    print(f"- {author.display_name}")
    if author.affiliations:
        current_inst = author.affiliations[0].institution.display_name
        print(f"  Institution: {current_inst}")
    print(f"  Metrics: {author.cited_by_count} citations, h-index {author.summary_stats.h_index}")
    if author.x_concepts:
        fields = [c.display_name for c in author.x_concepts[:3]]
        print(f"  Research: {', '.join(fields)}")

Análisis de Trabajos Académicos

from alex_mcp.server import retrieve_author_works_core

# Comprehensive work retrieval
works = retrieve_author_works_core(
    author_id="https://openalex.org/A5058921480",
    type="journal-article",      # Academic focus
    order_by="citations",        # Impact-based ordering
    limit=20
)

print(f"Found {works.total_count} publications")
for work in works.results:
    print(f"- {work.title}")
    if work.locations:
        journal = work.locations[0].source.display_name
        print(f"  Published in: {journal} ({work.publication_year})")
    print(f"  Impact: {work.cited_by_count} citations")
    if work.open_access and work.open_access.is_oa:
        print("  ✓ Open Access")

Análisis de Instituciones y Campos

# Analyze career transitions
def analyze_career_path(author_result):
    affiliations = author_result.affiliations
    if len(affiliations) > 1:
        print("Career path:")
        for aff in sorted(affiliations, key=lambda x: min(x.years)):
            years = f"{min(aff.years)}-{max(aff.years)}"
            print(f"  {years}: {aff.institution.display_name}")
    
    # Research evolution
    if author_result.x_concepts:
        print("Research areas:")
        for concept in author_result.x_concepts[:5]:
            print(f"  {concept.display_name} (score: {concept.score:.2f})")

# Usage
results = search_authors_core("Jorge Abreu Vicente")
if results.results:
    analyze_career_path(results.results[0])

🔧 Opciones de Configuración

Variables de Entorno

# Required
export OPENALEX_MAILTO=your-email@domain.com

# Optional settings
export OPENALEX_MAX_AUTHORS=100             # Maximum authors per query
export OPENALEX_USER_AGENT=research-agent-v1.0
export ALEX_MCP_VERSION=4.1.0

# Rate limiting (respectful usage)
export OPENALEX_RATE_PER_SEC=10
export OPENALEX_RATE_PER_DAY=100000

Ajuste de Rendimiento

# For comprehensive research applications
config = {
    "max_authors_per_query": 25,     # Detailed author analysis
    "max_works_per_author": 50,      # Complete publication history
    "enable_all_filters": True,      # Full filtering capabilities
    "detailed_affiliations": True,   # Complete institutional data
    "research_concepts": True        # Detailed concept analysis
}

🧑‍💻 Desarrollo y Pruebas

Estructura del Proyecto

alex-mcp/
├── src/alex_mcp/
│   ├── server.py              # Main MCP server
│   ├── data_objects.py        # Data models and structures
│   └── utils.py               # Utility functions
├── examples/
│   ├── basic_usage.py         # Simple examples
│   ├── advanced_queries.py    # Complex query examples
│   └── integration_demo.py    # AI agent integration
├── tests/
│   ├── test_server.py         # Server functionality tests
│   └── test_integration.py    # Integration tests
└── docs/
    └── api_reference.md       # Detailed API documentation

Ejecución de Pruebas

# Install test dependencies
pip install -e ".[test]"

# Run functionality tests
pytest tests/test_server.py -v

# Test with real queries
python examples/basic_usage.py

# Test AI agent integration
python examples/integration_demo.py

Ejemplos de Desarrollo

# Test author disambiguation
python examples/basic_usage.py --query "J. Abreu" --institution "EMBO"

# Test work retrieval
python examples/advanced_queries.py --author-id "A123456789" --type "journal-article"

# Test integration patterns
python examples/integration_demo.py --workflow "career-analysis"

📈 Ejemplos de Integración

Flujos de Trabajo de Investigación Académica

Integración perfecta con análisis de investigación impulsado por IA:

# Enhanced academic research agent
from alex_agent import AcademicResearchAgent

agent = AcademicResearchAgent(
    mcp_servers=[alex_mcp],  # Streamlined data processing
    model="gpt-4.1-2025-04-14"
)

# Complex research queries with structured data
result = await agent.research_author(
    "Find J. Abreu at EMBO with machine learning publications"
)

# Rich, structured output for AI reasoning
print(f"Quality Score: {result.quality_score}/100")
print(f"Author disambiguation: {result.confidence}")
print(f"Research fields: {result.research_domains}")

Sistemas Multi-Agente

# Collaborative research analysis
async def research_collaboration_network(seed_author):
    # Find primary author
    authors = await alex_mcp.search_authors(seed_author)
    primary = authors['results'][0]
    
    # Get their works
    works = await alex_mcp.retrieve_author_works(
        primary['id'], 
        type="journal-article"
    )
    
    # Analyze co-authors and build network
    collaborators = set()
    for work in works['results']:
        for authorship in work.get('authorships', []):
            collaborators.add(authorship['author']['display_name'])
    
    return {
        'primary_author': primary,
        'publication_count': len(works['results']),
        'collaborator_network': list(collaborators),
        'research_impact': sum(w['cited_by_count'] for w in works['results'])
    }

🤝 Contribuciones

Damos la bienvenida a contribuciones para mejorar la funcionalidad y agregar nuevas características:

Hacer un fork del repositorio
Crear una rama de características: git checkout -b feature/enhanced-filtering
Agregar pruebas: Asegúrese de que sus cambios mantengan la calidad y estructura de los datos
Enviar una solicitud de extracción: Incluya ejemplos y documentación

Prioridades de Desarrollo

Capacidades de filtrado mejoradas
Enriquecimiento adicional de datos
Optimizaciones de rendimiento
Ejemplos de integración
Mejoras de documentación

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulte LICENSE para más detalles.

OpenAlex Author Disambiguation

Documentación

Servidor MCP de Desambiguación de Autores de OpenAlex

🎯 Características Clave

🔍 Capacidades Principales

🚀 Optimizado para Agentes de IA

🤖 Integración con Agentes

🏛️ Nivel Profesional

🚀 Inicio Rápido

Requisitos Previos

Instalación

⚙️ Configuración de MCP

Configuración de Claude Desktop

🤖 Uso con Agentes de IA

Integración con OpenAI Agents

Integración con Agentes de Investigación Académica

Inicio Directo con uvx

🛠️ Herramientas Disponibles

1. autocomplete_authors ⭐ NUEVO

2. search_authors

2. retrieve_author_works

📊 Optimización de Datos

Arquitectura de Información Enfocada

Características de Datos de Autor

Características de Datos de Trabajo

Filtrado Mejorado

🧪 Ejemplo de Uso

Desambiguación de Autores

Análisis de Trabajos Académicos

Análisis de Instituciones y Campos

🔧 Opciones de Configuración

Variables de Entorno

Ajuste de Rendimiento

🧑‍💻 Desarrollo y Pruebas

Estructura del Proyecto

Ejecución de Pruebas

Ejemplos de Desarrollo

📈 Ejemplos de Integración

Flujos de Trabajo de Investigación Académica

Sistemas Multi-Agente

🤝 Contribuciones

Prioridades de Desarrollo

📄 Licencia

🌐 Enlaces