hal-mcp

Un servidor MCP (Model Context Protocol) para HAL, el archivo abierto nacional francés (Hyper Articles en Ligne). Permite a un asistente de IA — Claude, o cualquier cliente compatible con MCP — consultar HAL: buscar publicaciones, calcular estadísticas, exportar citas y seguir la producción de un investigador.

No se requiere clave API. Va más allá de la simple búsqueda con facetas (estadísticas agregadas), seguimiento de autores por IdHAL y exportación bibliográfica nativa.

Características (6 herramientas)

Related MCP server: Crossref Academic MCP Server

Requisitos

• Python 3.10 o superior

• El SDK mcp, versión 1.x (consulta la nota importante a continuación)

⚠️ Importante — versión del SDK mcp Este servidor utiliza FastMCP, que fue eliminado en mcp v2.0.0. Por lo tanto, el proyecto fija mcp>=1.2.0,<2.0.0. Si ves un error de importación de FastMCP al inicio, se instaló v2 por error: reinstala con pip install "mcp<2.0.0".

Instalación

git clone https://github.com/Arpany-Tech/hal-mcp
cd hal-mcp
pip install -e .

Comprobar que funciona

1. Comprueba que el servidor arranca

python -m hal_mcp.server

El cursor se queda bloqueado sin salida: esto es lo esperado. El servidor está en ejecución y esperando mensajes MCP en la entrada estándar. Pulsa Ctrl+C para detenerlo. (Si en su lugar obtienes un error, consulta la nota sobre el SDK mcp más arriba).

2. Pruebas interactivas con MCP Inspector

La herramienta oficial para explorar un servidor MCP sin un cliente completo:

npx @modelcontextprotocol/inspector python -m hal_mcp.server

Abre la URL impresa, haz clic en Conectar y luego en Listar herramientas: aparecen las 6 herramientas. Puedes llamar a cada una manualmente e inspeccionar las respuestas.

3. Prueba la capa de API directamente (sin MCP)

python3 - << 'PY'
import asyncio
from hal_mcp import client

async def main():
    res = await client.search_publications(
        "artificial intelligence", year_from=2023,
        open_access_only=True, rows=3,
    )
    print("Total:", res["total"])
    for d in res["documents"]:
        print("-", d.get("label_s"))

asyncio.run(main())
PY

Conectar con Claude Desktop

En claude_desktop_config.json (Configuración → Desarrollador → Editar configuración):

{
  "mcpServers": {
    "hal": {
      "command": "python",
      "args": ["-m", "hal_mcp.server"]
    }
  }
}

Reinicia por completo Claude Desktop. Las herramientas de HAL aparecen en el indicador de herramientas del cuadro de mensaje.

Consejo: si Claude Desktop no encuentra python, usa la ruta completa a tu intérprete (p. ej. C:\\Python313\\python.exe en Windows) en lugar de "python" en command.

Preguntas de ejemplo

• "Busca artículos de acceso abierto sobre aprendizaje federado desde 2023."

• "Dame la producción del investigador con IdHAL dominique-lesselier, con coautores."

• "¿Cuál es el desglose año a año de las publicaciones sobre deep learning?"

• "Exporta las 10 publicaciones más recientes sobre transformers a BibTeX."

• "¿Qué laboratorios trabajan en física cuántica?"

Cómo funciona

HAL expone una API de búsqueda basada en Apache Solr, consultable por HTTP sin autenticación. Este servidor traduce parámetros intuitivos (year_from, doc_type, open_access_only...) a sintaxis de Solr (fq, facet, wt...), de modo que el agente obtiene una interfaz sencilla sin dejar de beneficiarse de la potencia de Solr (filtros, facetas, exportaciones).

• Documentación de la API de HAL: https://api.archives-ouvertes.fr/docs/search

• Referencia de estructuras: https://api.archives-ouvertes.fr/docs/ref/resource/structure

Arquitectura

src/hal_mcp/
├── server.py    # declares the 6 MCP tools (FastMCP)
├── client.py    # calls to HAL's Solr API (httpx)
└── fields.py    # constants: Solr fields, document types

La capa client.py no tiene dependencia de MCP: se puede probar de forma aislada.

Desarrollo

Ejecuta las pruebas:

pip install pytest pytest-asyncio
pytest                    # all tests
pytest -m "not network"   # unit tests only (offline, fast)
pytest -m network         # integration tests that call HAL

Hoja de ruta

• get_structure_output — producción de un laboratorio determinado.

• Facetas pivotadas (cruce tipo × texto completo, año × tipo).

• Facetas de rango (facet.range) para gráficos de series temporales/evolución.

• Filtrado por colección / portal expuesto como parámetro.

• Transporte HTTP para Claude.ai (conector) y ChatGPT (modo desarrollador).

Licencia

MIT — consulta el archivo LICENSE.

Aviso legal

Proyecto independiente, no afiliado al CCSD (que opera HAL). Los metadatos provienen de la API pública de HAL. Por favor, respeta los términos de uso de HAL y la licencia de cada publicación individual.