🔭 EOSC Data Commons Search server

EOSC Data Commons プロジェクトの MatchMaker サービスのためのサーバーで、オープンアクセスデータセットに対する自然言語検索を提供します。HTTP POST エンドポイントを公開し、Model Context Protocol (MCP) をサポートして、大規模言語モデル支援検索を通じてユーザーがデータセットやツールを発見できるようにします。

🧩 Endpoints

HTTP API は主に 2 つのエンドポイントで構成されています:

• /mcp: MCP サーバー。EOSC Data Commons OpenSearch サービスを使用して、ユーザーの質問に答えるための関連データを検索します

  • Streamable HTTP トランスポートを使用します

  • 利用可能なツール:

    • データセットを検索

    • データセット内のファイルのメタデータを取得（名前、説明、ファイルの種類）

    • ツールを検索

    • データセットまたはツールに関連する引用を検索

• /chat: HTTP POST エンドポイント（JSON）。LLM プロバイダーを介して MCP サーバーツールとチャットするためのもの（API キーはデプロイ時に環境変数で提供）

  • AG-UI プロトコル に準拠した Server-Sent Events (SSE) レスポンスをストリーミングします。

[!TIP]

pip パッケージを通じて MCP サーバーとしてのみ使用することもできます。

Related MCP server: Datos.gob.es-MCP

🔌 MCP サーバーに接続する

このシステムは、STDIO または Streamable HTTP トランスポートのいずれかを使用して、MCP サーバーとして直接使用できます。

[!WARNING]

MCP サーバーを機能させるには、事前にインデックスされた OpenSearch インスタンスへのアクセスが必要です。

クライアントの指示に従い、公開サーバーの /mcp URL を使用してください: https://matchmaker.eosc-data-commons.eu/api/search/mcp

VSCode GitHub Copilot に新しい MCP サーバーを追加するには:

• コマンドパレットを開く（ctrl+shift+p または cmd+shift+p）

• MCP: Add Server... を検索

• HTTP を選択し、MCP サーバー URL を指定: https://matchmaker.eosc-data-commons.eu/api/search/mcp

VSCode の mcp.json は次のようになります:

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

🛠️ 開発

[!IMPORTANT]

要件:

• uv、スクリプトと仮想環境を簡単に扱うため

• docker、データベースと OpenSearch サービスをデプロイするため

• LLM プロバイダーの API キー: e-infra CZ、Mistral.ai、または OpenRouter

📥 開発依存関係のインストール

uv sync --all-extras

pre-commit フックをインストール:

uv run --all-extras pre-commit install

LLM プロバイダーの API キーと、必要に応じてその他の設定を記述した keys.env ファイルを作成します:

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

💾 データベース

検索システムは、認証済みユーザーの会話を保存するために PostgreSQL データベースへの接続が必要です。

metadata-warehouse をデプロイして初期化します。これらの手順では、metadata-warehouse フォルダーが data-commons-search と同じフォルダー内に存在することを前提としています。

cd ../metadata-warehouse
docker compose up postgres

データベースを初期化するには、metadata-warehouse リポジトリから実行します:

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

[!IMPORTANT]

公開環境では、app ユーザーのパスワードを更新する必要があります:

ALTER USER app WITH PASSWORD 'newpassword';

データベースをリセット:

docker compose down --volumes --remove-orphans

db.py から metadata-warehouse へスキーマをエクスポートします（data-commons-search リポジトリのルートで実行するコマンド）:

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

⚡️ 開発サーバーを起動

開発サーバーを http://localhost:8000 で起動します。MCP エンドポイントは http://localhost:8000/mcp で、実行中の OpenSearch インスタンスを指します:

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

デフォルト: OPENSEARCH_URL=http://localhost:9200

環境変数でサーバーポートをカスタマイズ:

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]

この開発サーバーを指すように、matchmaker フロントエンドを開発環境で別途デプロイできます:

cd ../matchmaker
npm run dev

[!TIP]

curl リクエストの例:

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"}'

認証済みユーザーのアクセストークンを使用（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"}'

最後の会話を取得:

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"

Cesnet プロバイダーから利用可能なモデルを検索:

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

推奨モデル: cesnet/agentic

🔐 シークレットストア

EGI Secret Store を使用します。aai.egi.eu/token からトークンを取得します（実際のアクセストークンを得るには JWT をデコードします）

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"

🐳 Docker でデプロイ

API キーを記述した keys.env ファイルを作成します（完全な例は上記を参照）:

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 は、LLM にスパムを送信する可能性のあるボットに対する保護層を追加するために使用できます。指定しない場合、API を照会するための API キーは不要です。

プリビルドの Docker イメージ ghcr.io/eosc-data-commons/data-commons-search:main を使用できます。

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}"

サービスをビルドしてデプロイ:

docker compose up

📦 本番用にビルド

dist/ にパッケージをビルド:

uv build

✅ テストを実行

[!CAUTION]

最初にポート 8000 でサーバーを起動し（開発サーバーの起動セクションを参照）、PostgreSQL を起動する必要があります。

uv run pytest

ベンチマークを実行（一連の検索クエリの成功を確認）:

uv run tests/benchmark.py

LLM 脱獄テストを実行 garak を使用:

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

API のストレステストを実行（20 の同時使用）:

uv run tests/stress_api.py -c 20

🧹 コードのフォーマットと型チェック

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

♻️ 環境のリセット

uv をアップグレード:

uv self update

uv キャッシュをクリーンアップ:

uv cache clean

🔧 メンテナンス

データベース内のデータセットの統計を src/data_commons_search/stats.json に事前計算:

POSTGRES_DB=datasetdb uv run scripts/compute_stats.py

pyproject.toml の依存関係を更新:

uvx uv-bump

🏷️ リリースプロセス

バージョンバンプを指定してリリーススクリプトを実行: fix、minor、または major

.github/release.sh fix

または明示的なバージョン（例: フロントエンドのバージョンに合わせる場合）:

.github/release.sh 0.10.0

これにより、git タグの作成、GitHub リリース、Docker イメージの公開が行われます。

🤝 謝辞

LLM プロバイダー cesnet は、e-INFRA CZ によって提供され、CERIT-SC Masaryk University によって運用されているサービスです。

計算リソースは、チェコ共和国教育・青少年・スポーツ省によって支援された e-INFRA CZ プロジェクト（ID:90254）によって提供されました。

認証プロバイダーは EGI Check-in です。