hal-mcp

Ein MCP-Server (Model Context Protocol) für HAL, das französische nationale Open-Access-Archiv (Hyper Articles en Ligne). Er ermöglicht es einem KI-Assistenten – Claude oder einem beliebigen MCP-kompatiblen Client – HAL abzufragen: Publikationen suchen, Statistiken berechnen, Zitate exportieren und die Veröffentlichungen eines Forschers verfolgen.

Kein API-Schlüssel erforderlich. Er geht über die einfache Suche hinaus mit Facetten (aggregierte Statistiken), Autorenverfolgung per IdHAL und nativem bibliografischem Export.

Funktionen (6 Tools)

Related MCP server: Crossref Academic MCP Server

Voraussetzungen

• Python 3.10 oder neuer

• Das mcp SDK, Version 1.x (siehe wichtiger Hinweis unten)

⚠️ Wichtig — mcp SDK-Version Dieser Server verwendet FastMCP, das in mcp v2.0.0 entfernt wurde. Das Projekt pinnt daher mcp>=1.2.0,<2.0.0. Wenn Sie beim Start einen FastMCP-Importfehler sehen, wurde v2 versehentlich installiert: Installieren Sie es neu mit pip install "mcp<2.0.0".

Installation

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

Überprüfen, dass es funktioniert

1. Prüfen, ob der Server startet

python -m hal_mcp.server

Der Cursor hängt ohne Ausgabe: das ist erwartet. Der Server läuft und wartet auf MCP-Nachrichten auf der Standardeingabe. Drücken Sie Ctrl+C, um ihn zu stoppen. (Wenn Sie stattdessen einen Fehler erhalten, siehe den mcp SDK-Hinweis oben.)

2. Interaktives Testen mit MCP Inspector

Das offizielle Werkzeug, um einen MCP-Server ohne vollständigen Client zu erkunden:

npx @modelcontextprotocol/inspector python -m hal_mcp.server

Öffnen Sie die gedruckte URL, klicken Sie auf Connect, dann auf List Tools: Die 6 Tools erscheinen. Sie können jedes einzeln aufrufen und die Antworten inspizieren.

3. Testen Sie die API-Ebene direkt (ohne 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

Verbinden mit Claude Desktop

In claude_desktop_config.json (Einstellungen → Entwickler → Konfiguration bearbeiten):

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

Starten Sie Claude Desktop vollständig neu. Die HAL-Tools erscheinen im Tools-Indikator des Nachrichtenfelds.

Tipp: Wenn Claude Desktop python nicht finden kann, verwenden Sie den vollständigen Pfad zu Ihrem Interpreter (z. B. C:\\Python313\\python.exe unter Windows) anstelle von "python" in command.

Beispielfragen

• Finden Sie Open-Access-Artikel zu föderiertem Lernen seit 2023.

• Geben Sie mir die Veröffentlichungen des Forschers mit IdHAL dominique-lesselier, mit Koautoren.

• Wie ist die jährliche Aufschlüsselung der Deep-Learning-Publikationen?

• Exportieren Sie die 10 neuesten Publikationen zu Transformatoren nach BibTeX.

• Welche Labore arbeiten an Quantenphysik?

So funktioniert es

HAL stellt eine Such-API bereit, die auf Apache Solr basiert und über HTTP ohne Authentifizierung abfragbar ist. Dieser Server übersetzt benutzerfreundliche Parameter (year_from, doc_type, open_access_only...) in Solr-Syntax (fq, facet, wt...), sodass der Agent eine einfache Schnittstelle erhält und dennoch von Solrs Leistungsfähigkeit profitiert (Filter, Facetten, Exporte).

• HAL-API-Dokumentation: https://api.archives-ouvertes.fr/docs/search

• Strukturreferenz: https://api.archives-ouvertes.fr/docs/ref/resource/structure

Architektur

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

Die client.py-Schicht hat keine MCP-Abhängigkeit: Sie kann isoliert getestet werden.

Entwicklung

Führen Sie die Tests aus:

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

Roadmap

• get_structure_output — Veröffentlichungen eines bestimmten Labors.

• Pivot-Facetten (Kreuztyp × Volltext, Jahr × Typ).

• Bereichs-Facetten (facet.range) für Zeitreihen-/Entwicklungsdiagramme.

• Sammlungs-/Portal-Filterung als Parameter verfügbar.

• HTTP-Transport für Claude.ai (Connector) und ChatGPT (Entwicklermodus).

Lizenz

MIT — siehe die Datei LICENSE.

Haftungsausschluss

Unabhängiges Projekt, nicht mit dem CCSD verbunden (das HAL betreibt). Metadaten stammen aus der öffentlichen HAL-API. Bitte respektieren Sie die Nutzungsbedingungen von HAL und die Lizenz jeder einzelnen Publikation.