Servidor MCP de Semantic Scholar

Una implementación de servidor FastMCP para la API Semantic Scholar, que proporciona acceso integral a datos de artículos académicos, información de autores y redes de citas.

Estructura del proyecto

El proyecto ha sido refactorizado en una estructura modular para una mejor mantenibilidad:

semantic-scholar-server/
├── semantic_scholar/            # Main package
│   ├── __init__.py             # Package initialization
│   ├── server.py               # Server setup and main functionality
│   ├── mcp.py                  # Centralized FastMCP instance definition
│   ├── config.py               # Configuration classes
│   ├── utils/                  # Utility modules
│   │   ├── __init__.py
│   │   ├── errors.py           # Error handling
│   │   └── http.py             # HTTP client and rate limiting
│   ├── api/                    # API endpoints
│       ├── __init__.py
│       ├── papers.py           # Paper-related endpoints
│       ├── authors.py          # Author-related endpoints
│       └── recommendations.py  # Recommendation endpoints
├── run.py                      # Entry point script

Esta estructura:

Separa las preocupaciones en módulos lógicos
Hace que la base de código sea más fácil de entender y mantener.
Permite mejores pruebas y futuras ampliaciones
Mantiene agrupadas las funcionalidades relacionadas
Centraliza la instancia FastMCP para evitar importaciones circulares

Características

Búsqueda y descubrimiento de documentos
- Búsqueda de texto completo con filtrado avanzado
- Correspondencia de trabajos basados en títulos
- Recomendaciones de artículos (individuales y múltiples)
- Recuperación de detalles de lotes de papel
- Búsqueda avanzada con estrategias de clasificación
Análisis de citas
- Exploración de redes de citas
- Seguimiento de referencias
- Análisis del contexto y la influencia de las citas
Información del autor
- Búsqueda de autor y detalles del perfil
- Historial de publicaciones
- Recuperación de detalles del autor por lotes
Funciones avanzadas
- Búsqueda compleja con múltiples estrategias de clasificación
- Selección de campos personalizables
- Operaciones por lotes eficientes
- Cumplimiento de la limitación de velocidad
- Soporte para acceso autenticado y no autenticado
- Apagado elegante y manejo de errores
- Agrupación de conexiones y gestión de recursos

Requisitos del sistema

Python 3.8+
Marco FastMCP
Variable de entorno para la clave API (opcional)

Instalación

Instalación mediante herrería

Para instalar Semantic Scholar MCP Server para Claude Desktop automáticamente a través de Smithery :

npx -y @smithery/cli install semantic-scholar-fastmcp-mcp-server --client claude

Instalación manual

Clonar el repositorio:

git clone https://github.com/YUZongmin/semantic-scholar-fastmcp-mcp-server.git
cd semantic-scholar-server

Instale FastMCP y otras dependencias siguiendo estos pasos: https://github.com/jlowin/fastmcp
Configurar FastMCP:

Los usuarios de Claude Desktop deben configurar el servidor en el archivo de configuración de FastMCP. Agreguen lo siguiente a su configuración (normalmente en ~/.config/claude-desktop/config.json ):

{
  "mcps": {
    "Semantic Scholar Server": {
      "command": "/path/to/your/venv/bin/fastmcp",
      "args": [
        "run",
        "/path/to/your/semantic-scholar-server/run.py"
      ],
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "your-api-key-here"  # Optional
      }
    }
  }
}

Asegúrese de:

Reemplace /path/to/your/venv/bin/fastmcp con la ruta real a su instalación de FastMCP
Reemplace /path/to/your/semantic-scholar-server/run.py con la ruta real a run.py en su máquina
Si tiene una clave de API de Semantic Scholar, agréguela a la sección env . De lo contrario, puede eliminarla por completo env

Comience a utilizar el servidor:

El servidor ahora estará disponible para su instancia de Claude Desktop. No es necesario ejecutar ningún comando manualmente: Claude iniciará y administrará automáticamente el proceso del servidor cuando sea necesario.

Clave API (opcional)

Para obtener límites de velocidad más altos y un mejor rendimiento:

Obtenga una clave API de la API de Semantic Scholar
Agréguelo a su configuración de FastMCP como se muestra arriba en la sección env

Si no se proporciona una clave API, el servidor utilizará un acceso no autenticado con límites de velocidad más bajos.

Configuración

Variables de entorno

SEMANTIC_SCHOLAR_API_KEY : Su clave de API de Semantic Scholar (opcional)
- Obtenga su clave de la API de Semantic Scholar
- Si no se proporciona, el servidor utilizará acceso no autenticado.

Límites de velocidad

El servidor se ajusta automáticamente a los límites de velocidad adecuados:

Con clave API :

Puntos finales de búsqueda, lote y recomendación: 1 solicitud por segundo
Otros puntos finales: 10 solicitudes por segundo

Sin clave API :

Todos los puntos finales: 100 solicitudes cada 5 minutos
Tiempos de espera más largos para las solicitudes

Herramientas MCP disponibles

Nota: Todas las herramientas cumplen con la documentación oficial de la API de Semantic Scholar . Consulte la documentación oficial para obtener información detallada sobre las especificaciones de los campos y las últimas actualizaciones.

Herramientas de búsqueda de documentos

paper_relevance_search : busca artículos mediante clasificación de relevancia
- Admite parámetros de consulta completos que incluyen filtros de rango de años y recuento de citas
- Devuelve resultados paginados con campos personalizables
paper_bulk_search : Búsqueda masiva de artículos con opciones de clasificación
- Similar a la búsqueda por relevancia, pero optimizada para conjuntos de resultados más grandes
- Admite la clasificación por número de citas, fecha de publicación, etc.
paper_title_search : Encuentra artículos por coincidencia exacta del título
- Útil para encontrar artículos específicos cuando conoce el título.
- Devuelve información detallada del papel con campos personalizables
paper_details : Obtenga detalles completos sobre un artículo específico
- Acepta varios formatos de identificación de papel (S2 ID, DOI, ArXiv, etc.)
- Devuelve metadatos detallados del artículo con soporte para campos anidados
paper_batch_details : recupera de forma eficiente los detalles de varios documentos
- Acepta hasta 1000 identificaciones en papel por solicitud
- Admite los mismos formatos de identificación y campos que los detalles de un solo papel.

Herramientas de citación

paper_citations : Obtener artículos que citan un artículo específico
- Devuelve una lista paginada de artículos citados
- Incluye el contexto de la cita cuando esté disponible
- Admite personalización y clasificación de campos.
paper_references : Obtener artículos referenciados por un artículo específico
- Devuelve una lista paginada de los artículos referenciados
- Incluye contexto de referencia cuando esté disponible
- Admite personalización y clasificación de campos.

Herramientas de autor

author_search : Buscar autores por nombre
- Devuelve resultados paginados con campos personalizables
- Incluye afiliaciones y recuentos de publicaciones.
author_details : Obtenga información detallada sobre un autor
- Devuelve metadatos completos del autor
- Incluye métricas como el índice h y el número de citas.
author_papers : Obtenga artículos escritos por un autor
- Devuelve una lista paginada de las publicaciones del autor.
- Admite personalización y clasificación de campos.
author_batch_details : Obtener detalles de varios autores
- Recupere eficientemente información de hasta 1000 autores
- Devuelve los mismos campos que los detalles de un solo autor.

Herramientas de recomendación

paper_recommendations_single : Obtenga recomendaciones basadas en un solo artículo
- Devuelve artículos similares según el contenido y los patrones de citas.
- Admite la personalización de campos para los artículos recomendados
paper_recommendations_multi : Obtenga recomendaciones basadas en múltiples artículos
- Acepta ejemplos de trabajos positivos y negativos.
- Devuelve artículos similares a los ejemplos positivos y diferentes a los negativos.

Ejemplos de uso

Búsqueda básica de artículos

results = await paper_relevance_search(
    context,
    query="machine learning",
    year="2020-2024",
    min_citation_count=50,
    fields=["title", "abstract", "authors"]
)

Recomendaciones de artículos

# Single paper recommendation
recommendations = await paper_recommendations_single(
    context,
    paper_id="649def34f8be52c8b66281af98ae884c09aef38b",
    fields="title,authors,year"
)

# Multi-paper recommendation
recommendations = await paper_recommendations_multi(
    context,
    positive_paper_ids=["649def34f8be52c8b66281af98ae884c09aef38b", "ARXIV:2106.15928"],
    negative_paper_ids=["ArXiv:1805.02262"],
    fields="title,abstract,authors"
)

Operaciones por lotes

# Get details for multiple papers
papers = await paper_batch_details(
    context,
    paper_ids=["649def34f8be52c8b66281af98ae884c09aef38b", "ARXIV:2106.15928"],
    fields="title,authors,year,citations"
)

# Get details for multiple authors
authors = await author_batch_details(
    context,
    author_ids=["1741101", "1780531"],
    fields="name,hIndex,citationCount,paperCount"
)

Manejo de errores

El servidor proporciona respuestas de error estandarizadas:

{
    "error": {
        "type": "error_type",  # rate_limit, api_error, validation, timeout
        "message": "Error description",
        "details": {
            # Additional context
            "authenticated": true/false  # Indicates if request was authenticated
        }
    }
}

Semantic Scholar MCP Server

Integrations