inspirehep-mcp

Servidor MCP de InspireHEP

Un servidor MCP que integra la literatura de física de altas energías de InspireHEP con LLMs. Busca artículos, explora citas, recupera métricas de autores y genera referencias formateadas.

Instalación

# Using pip
pip install inspirehep-mcp

# Or run directly with uvx (no install needed)
uvx inspirehep-mcp

git clone https://github.com/MohamedElashri/inspirehep-mcp.git
cd inspirehep-mcp
uv sync
uv run inspirehep-mcp

Despliegue de endpoint remoto

El comando instalado sigue siendo un servidor stdio por defecto, por lo que las configuraciones de escritorio existentes continúan funcionando. Para ejecutarlo de forma nativa como un endpoint MCP remoto, selecciona el transporte Streamable HTTP:

INSPIREHEP_ALLOWED_HOSTS="mcp.example.org" \
  INSPIREHEP_HTTP_RATE_LIMIT=60 \
  inspirehep-mcp --transport streamable-http --host 0.0.0.0 --port 8000

El endpoint MCP es http://localhost:8000/mcp y la sonda de salud no autenticada es http://localhost:8000/health. PORT también se respeta cuando una plataforma de alojamiento lo inyecta. Coloca el servicio detrás de HTTPS para el despliegue en internet.

Docker

Las etiquetas de lanzamiento publican un contenedor en el Registro de Contenedores de GitHub. La imagen usa Streamable HTTP por defecto:

docker run --rm -p 8000:8000 \
  ghcr.io/mohamedelashri/inspirehep-mcp:latest

Para un nombre de host público, agrégalo a la lista de permitidos del host:

docker run --rm -p 8000:8000 \
  -e INSPIREHEP_ALLOWED_HOSTS="mcp.example.org" \
  -e INSPIREHEP_HTTP_RATE_LIMIT=60 \
  ghcr.io/mohamedelashri/inspirehep-mcp:latest

La imagen se ejecuta como un usuario no root, tiene una verificación de salud integrada y usa respuestas JSON sin estado, por lo que las réplicas no necesitan estado de sesión MCP compartido.

Docker Compose

El docker-compose.yml incluido puede compilar el checkout actual o ejecutar la imagen publicada:

# Local deployment
docker compose up --build -d

# Add the public hostname when deploying behind a domain
INSPIREHEP_ALLOWED_HOSTS="mcp.example.org" docker compose up -d

El servicio de Compose es de solo lectura, elimina las capacidades de Linux, habilita no-new-privileges y conserva la verificación de salud de la imagen.

Limitación de velocidad entrante

Las solicitudes Streamable HTTP se limitan por IP de cliente con un token bucket. El valor predeterminado es 60 solicitudes por minuto con una ráfaga de 20; /health está exento. Establece INSPIREHEP_HTTP_RATE_LIMIT=0 para deshabilitarlo.

Las solicitudes a /mcp están limitadas a 256 KiB. El servidor nativo también acepta como máximo 100 conexiones o tareas concurrentes, cierra las conexiones keep-alive inactivas después de 5 segundos y admite como máximo 32 fallos de caché pendientes de la API de INSPIRE. El trabajo ascendente excesivo falla rápidamente en lugar de acumularse en memoria.

Por defecto, el limitador usa la dirección del par directo e ignora los encabezados reenviados. Solo habilita INSPIREHEP_TRUST_PROXY_HEADERS cuando un proxy inverso de confianza sobrescribe X-Forwarded-For; de lo contrario, los clientes pueden elegir su propia identidad de limitación de velocidad. El limitador está en memoria y por proceso, por lo que los despliegues con múltiples réplicas también deben aplicar un límite compartido en el proxy o gateway.

[!IMPORTANTE] Las herramientas de solo lectura evitan el riesgo de mutación, pero un endpoint público aún puede usarse para consumir tu cómputo y la asignación de API ascendente. Este servidor no agrega autenticación. Usa un proxy inverso con autenticación si el endpoint no debe estar abierto a todos, y conserva un límite de velocidad en el borde para despliegues distribuidos. Mantén habilitada la protección contra el rebinding de DNS y establece INSPIREHEP_ALLOWED_ORIGINS para los clientes que envían un encabezado Origin.

Integración

Claude Desktop / Cursor

Agrega a tu configuración de cliente MCP:

{
  "mcpServers": {
    "inspirehep": {
      "command": "uvx",
      "args": ["inspirehep-mcp"]
    }
  }
}

Claude Code

Opción A: Usando la CLI

# Global scope (available across all projects)
claude mcp add --scope user inspirehep -- uvx inspirehep-mcp

# Project scope (shared via .mcp.json, checked into source control)
claude mcp add --scope project inspirehep -- uvx inspirehep-mcp

Opción B: Configuración manual

Para el ámbito global, agrega a ~/.claude.json:

{
  "mcpServers": {
    "inspirehep": {
      "command": "uvx",
      "args": ["inspirehep-mcp"]
    }
  }
}

Para el ámbito del proyecto, crea .mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "inspirehep": {
      "command": "uvx",
      "args": ["inspirehep-mcp"]
    }
  }
}

CLI de Antigravity

Abre el administrador interactivo de MCP con /mcp, o configura el servidor manualmente. Antigravity lee los servidores MCP globales desde ~/.gemini/config/mcp_config.json y los servidores locales del espacio de trabajo desde .agents/mcp_config.json:

{
  "mcpServers": {
    "inspirehep": {
      "command": "uvx",
      "args": ["inspirehep-mcp"]
    }
  }
}

Herramientas

Configuración

Todos los ajustes mediante variables de entorno (prefijo INSPIREHEP_):

Desarrollo

# Run tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=inspirehep_mcp --cov-report=term-missing

# Unit tests only (no network)
uv run pytest tests/test_utils.py tests/test_cache.py tests/test_errors.py \
  tests/test_config.py tests/test_rate_limit.py tests/test_server.py \
  tests/test_api_client_safety.py tests/test_tools_safety.py

LICENCIA

Este proyecto está licenciado bajo la Licencia AGPL-3.0: consulta el archivo LICENSE para más detalles.