🔭 EOSC Data Commons Search server

Ein Server für den EOSC Data Commons project MatchMaker-Dienst, der eine natürlichsprachliche Suche über offen zugängliche Datensätze bereitstellt. Er stellt einen HTTP-POST-Endpunkt bereit und unterstützt das Model Context Protocol (MCP), um Nutzern zu helfen, Datensätze und Werkzeuge über eine durch große Sprachmodelle unterstützte Suche zu entdecken.

🧩 Endpunkte

Die HTTP-API umfasst 2 Hauptendpunkte:

• /mcp: MCP-Server, der mithilfe des EOSC Data Commons OpenSearch-Dienstes nach relevanten Daten sucht, um eine Benutzerfrage zu beantworten

  • Verwendet Streamable-HTTP-Transport

  • Verfügbare Werkzeuge:

    • Datensätze durchsuchen

    • Metadaten für die Dateien in einem Datensatz abrufen (Name, Beschreibung, Dateityp)

    • Werkzeuge durchsuchen

    • Zitationen zu Datensätzen oder Werkzeugen durchsuchen

• /chat: HTTP-POST-Endpunkt (JSON) zum Chatten mit den MCP-Server-Werkzeugen über einen LLM-Anbieter (API-Schlüssel wird zur Bereitstellung über Umgebungsvariable bereitgestellt)

  • Streamt Server-Sent-Events (SSE)-Antworten gemäß dem AG-UI-Protokoll.

[!TIP]

Es kann auch einfach als MCP-Server über das pip-Paket verwendet werden.

Related MCP server: Datos.gob.es-MCP

🔌 Mit dem MCP-Server verbinden

Das System kann direkt als MCP-Server verwendet werden, entweder über STDIO oder Streamable-HTTP-Transport.

[!WARNING]

Sie benötigen Zugriff auf eine vorab indizierte OpenSearch-Instanz, damit der MCP-Server funktioniert.

Befolgen Sie die Anweisungen Ihres Clients und verwenden Sie die /mcp-URL des öffentlichen Servers: https://matchmaker.eosc-data-commons.eu/api/search/mcp

Um einen neuen MCP-Server zu VSCode GitHub Copilot hinzuzufügen:

• Öffnen Sie die Befehlspalette (ctrl+shift+p oder cmd+shift+p)

• Suchen Sie nach MCP: Add Server...

• Wählen Sie HTTP und geben Sie die MCP-Server-URL an: https://matchmaker.eosc-data-commons.eu/api/search/mcp

Ihre VSCode-mcp.json sollte wie folgt aussehen:

{
    "servers": {
        "data-commons-search-http": {
            "url": "https://matchmaker.eosc-data-commons.eu/api/search/mcp",
            "type": "http"
        }
    },
    "inputs": []
}

🛠️ Entwicklung

[!IMPORTANT]

Anforderungen:

• uv, um Skripte und virtuelle Umgebungen einfach zu verwalten

• docker, um die Datenbank und den OpenSearch-Dienst bereitzustellen

• API-Schlüssel für einen LLM-Anbieter: e-infra CZ, Mistral.ai oder OpenRouter

📥 Entwicklungsabhängigkeiten installieren

uv sync --all-extras

Pre-commit-Hooks installieren:

uv run --all-extras pre-commit install

Erstellen Sie eine keys.env-Datei mit Ihrem/n API-Schlüssel(n) des LLM-Anbieters und optional weiteren Konfigurationen:

CESNET_API_KEY=YOUR_API_KEY
MISTRAL_API_KEY=YOUR_API_KEY

OIDC_CLIENT_ID=
OIDC_CLIENT_SECRET=
LANGFUSE_PUBLIC_KEY=
LANGFUSE_SECRET_KEY=
POSTGRES_HOST=localhost
POSTGRES_USER=app
POSTGRES_PASSWORD=app_password

RATE_LIMITING_ENABLED=False
LOG_LEVEL=DEBUG
LOG_JSON=false

OPENSEARCH_URL=http://localhost:9200

💾 Datenbank

Das Suchsystem muss sich mit einer PostgreSQL-Datenbank verbinden, um die Konversationen authentifizierter Benutzer zu speichern.

Stellen Sie das metadata-warehouse bereit und initialisieren Sie es. In diesen Anweisungen erwarten wir, dass sich der Ordner metadata-warehouse neben data-commons-search im selben Ordner befindet.

cd ../metadata-warehouse
docker compose up postgres

Um die Datenbank zu initialisieren, führen Sie im metadata-warehouse-Repository aus:

uv run --directory scripts/postgres_data create_db.py --db appdb --reset

[!IMPORTANT]

Für öffentlich zugängliche Umgebungen sollten Sie das Passwort des app-Benutzers aktualisieren:

ALTER USER app WITH PASSWORD 'newpassword';

Datenbank zurücksetzen:

docker compose down --volumes --remove-orphans

Exportieren Sie das Schema aus db.py in das metadata-warehouse (Befehl, der im Stammverzeichnis des data-commons-search-Repositorys ausgeführt werden muss):

uv run scripts/export_db_schema.py ../metadata-warehouse/scripts/postgres_data/create_sql/appdb/tables.sql

⚡️ Entwicklungsserver starten

Starten Sie den Server in der Entwicklung unter http://localhost:8000, mit MCP-Endpunkt unter http://localhost:8000/mcp, der auf eine laufende OpenSearch-Instanz zeigt:

uv run --all-extras uvicorn src.data_commons_search.main:app --reload

Standard OPENSEARCH_URL=http://localhost:9200

Serverport über Umgebungsvariable anpassen:

OPENSEARCH_URL=http://localhost:9200 SERVER_PORT=8001 uv run --all-extras uvicorn src.data_commons_search.main:app --host 0.0.0.0 --port 8001 --reload

[!NOTE]

Sie können das matchmaker-Frontend in der Entwicklung parallel bereitstellen, das auf diesen Entwicklungsserver zeigt:

cd ../matchmaker
npm run dev

[!TIP]

Beispiel-curl-Anfrage:

curl -X POST http://localhost:8000/chat -H "Content-Type: application/json" \
	-d '{"items": [{"type": "message", "role": "user", "content": [{"text": "Educational datasets from Switzerland covering student assessments, language competencies, and learning outcomes, including experimental or longitudinal studies on pupils or students."}]}], "model": "cesnet/agentic"}'

Mit authentifiziertem Benutzerzugriffstoken von http://127.0.0.1:8000/auth/login:

curl -X POST http://localhost:8000/chat -H "Content-Type: application/json" \
-H "Cookie: access_token=$ACCESS_TOKEN" \
-d '{"items": [{"type": "message", "role": "user", "content": [{"text": "Educational datasets from Switzerland covering student assessments, language competencies, and learning outcomes, including experimental or longitudinal studies on pupils or students."}]}], "model": "cesnet/agentic"}'

Letzte Konversation abrufen:

curl -X GET "http://localhost:8000/conversation/$(curl -s http://localhost:8000/conversations -H "Content-Type: application/json" -H "Cookie: access_token=$ACCESS_TOKEN" | jq -r '.[-1].thread_id')" -H "Content-Type: application/json" -H "Cookie: access_token=$ACCESS_TOKEN"

Verfügbares Modell vom Cesnet-Anbieter finden:

curl -H "Authorization: Bearer $CESNET_API_KEY" https://llm.ai.e-infra.cz/v1/models | jq ".data[].id"

Empfohlenes Modell: cesnet/agentic

🔐 Geheimnisspeicher

EGI Secret Store, holen Sie das Token von aai.egi.eu/token (dekodieren Sie das JWT, um das tatsächliche Zugriffstoken zu erhalten)

export BASE="https://matchmaker.eosc-data-commons.eu"
curl -s "$BASE/auth/user" --cookie "access_token=$TOKEN"

curl -s -X PUT "$BASE/auth/keys/vip" --cookie "access_token=$TOKEN" \
  -H "Content-Type: application/json" -d '{"key_value":"sk-123"}'

curl -s "$BASE/auth/keys" --cookie "access_token=$TOKEN"
curl -s "$BASE/auth/keys/all" --cookie "access_token=$TOKEN"
curl -s "$BASE/auth/keys/vip" --cookie "access_token=$TOKEN"
curl -s -X DELETE "$BASE/auth/keys/vip" --cookie "access_token=$TOKEN"

🐳 Mit Docker bereitstellen

Erstellen Sie eine keys.env-Datei mit den API-Schlüsseln (siehe oben für ein vollständiges Beispiel):

CESNET_API_KEY=YOUR_API_KEY
MISTRAL_API_KEY=YOUR_API_KEY
SEARCH_API_KEY=SECRET_KEY_YOU_CAN_USE_IN_FRONTEND_TO_AVOID_SPAM

[!TIP]

SEARCH_API_KEY kann verwendet werden, um eine Schutzschicht gegen Bots hinzuzufügen, die das LLM möglicherweise spammern. Wenn nicht angegeben, ist für die Abfrage der API kein API-Schlüssel erforderlich.

Sie können das vorgefertigte Docker-Image ghcr.io/eosc-data-commons/data-commons-search:main verwenden

Beispiel-compose.yml:

services:
  mcp:
    image: ghcr.io/eosc-data-commons/data-commons-search:main
    ports:
      - "127.0.0.1:8000:8000"
    environment:
      OPENSEARCH_URL: "http://opensearch:9200"
      CESNET_API_KEY: "${CESNET_API_KEY}"

Dienst erstellen und bereitstellen:

docker compose up

📦 Für die Produktion erstellen

Paket in dist/ erstellen:

uv build

✅ Tests ausführen

[!CAUTION]

Sie müssen zuerst den Server auf Port 8000 starten (siehe Abschnitt „Entwicklungsserver starten“) und PostgreSQL.

uv run pytest

Benchmark ausführen (Erfolg einer Reihe von Suchabfragen prüfen):

uv run tests/benchmark.py

LLM-Jailbreak-Tests ausführen mit garak:

PYTHONPATH=tests/security uv run garak --config tests/security/garak.yaml

Stresstests ausführen (20 gleichzeitige Nutzungen) der API:

uv run tests/stress_api.py -c 20

🧹 Code formatieren und Typprüfung

uvx ruff format && uvx ruff check --fix && uvx ty check

♻️ Umgebung zurücksetzen

uv aktualisieren:

uv self update

uv-Cache bereinigen:

uv cache clean

🔧 Wartung

Statistiken für die Datensätze in der Datenbank vorab berechnen und in src/data_commons_search/stats.json speichern:

POSTGRES_DB=datasetdb uv run scripts/compute_stats.py

Abhängigkeiten in pyproject.toml aktualisieren:

uvx uv-bump

🏷️ Release-Prozess

Führen Sie das Release-Skript aus und geben Sie den Versionssprung an: fix, minor oder major

.github/release.sh fix

Oder eine explizite Version, z. B. um sie an die Frontend-Version anzugleichen:

.github/release.sh 0.10.0

Dadurch werden ein Git-Tag, ein GitHub-Release erstellt und ein Docker-Image veröffentlicht.

🤝 Danksagungen

Der LLM-Anbieter cesnet ist ein Dienst von e-INFRA CZ und wird von CERIT-SC Masaryk University betrieben.

Die Rechenressourcen wurden vom Projekt e-INFRA CZ (ID:90254) bereitgestellt, das vom Ministerium für Bildung, Jugend und Sport der Tschechischen Republik unterstützt wird.

Der Authentifizierungsanbieter ist EGI Check-in.