🔭 Servidor de búsqueda de EOSC Data Commons

Un servidor para el servicio MatchMaker del proyecto EOSC Data Commons, que proporciona búsqueda en lenguaje natural sobre conjuntos de datos de acceso abierto. Expone un endpoint HTTP POST y soporta el Model Context Protocol (MCP) para ayudar a los usuarios a descubrir conjuntos de datos y herramientas mediante una búsqueda asistida por un modelo de lenguaje grande.

🧩 Endpoints

La API HTTP consta de 2 endpoints principales:

• /mcp: Servidor MCP que busca datos relevantes para responder a una pregunta del usuario utilizando el servicio OpenSearch de EOSC Data Commons

  • Utiliza transporte HTTP Streamable

  • Herramientas disponibles:

    • Buscar conjuntos de datos

    • Obtener metadatos de los archivos de un conjunto de datos (nombre, descripción, tipo de archivos)

    • Buscar herramientas

    • Buscar citas relacionadas con conjuntos de datos o herramientas

• /chat: Endpoint HTTP POST (JSON) para chatear con las herramientas del servidor MCP a través de un proveedor de LLM (clave API proporcionada mediante variable de entorno en el despliegue)

  • Transmite respuestas Server-Sent Events (SSE) que cumplen con el protocolo AG-UI.

[!TIP]

También se puede usar simplemente como un servidor MCP a través del paquete pip.

Related MCP server: Datos.gob.es-MCP

🔌 Conectar al servidor MCP

El sistema se puede usar directamente como un servidor MCP utilizando ya sea STDIO o transporte HTTP Streamable.

[!WARNING]

Necesitarás acceso a una instancia de OpenSearch preindexada para que el servidor MCP funcione.

Sigue las instrucciones de tu cliente y usa la URL /mcp del servidor público: https://matchmaker.eosc-data-commons.eu/api/search/mcp

Para añadir un nuevo servidor MCP a VSCode GitHub Copilot:

• Abre la Paleta de Comandos (ctrl+shift+p o cmd+shift+p)

• Busca MCP: Add Server...

• Elige HTTP y proporciona la URL del servidor MCP: https://matchmaker.eosc-data-commons.eu/api/search/mcp

Tu mcp.json de VSCode debería verse así:

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

🛠️ Desarrollo

[!IMPORTANT]

Requisitos:

• uv, para manejar fácilmente scripts y entornos virtuales

• docker, para desplegar la base de datos y el servicio OpenSearch

• Clave API para un proveedor de LLM: e-infra CZ, Mistral.ai o OpenRouter

📥 Instalar dependencias de desarrollo

uv sync --all-extras

Instalar hooks de pre-commit:

uv run --all-extras pre-commit install

Crea un archivo keys.env con las claves API de tu proveedor de LLM y, opcionalmente, otras configuraciones:

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

💾 Base de datos

El sistema de búsqueda necesita conectarse a una base de datos PostgreSQL para almacenar las conversaciones de los usuarios autenticados.

Despliega e inicializa el metadata-warehouse; en estas instrucciones esperamos que la carpeta metadata-warehouse esté junto a data-commons-search, en la misma carpeta.

cd ../metadata-warehouse
docker compose up postgres

Para inicializar la base de datos, ejecuta desde el repositorio metadata-warehouse:

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

[!IMPORTANT]

Para entornos disponibles públicamente, querrás actualizar la contraseña del usuario app:

ALTER USER app WITH PASSWORD 'newpassword';

Restablecer la base de datos:

docker compose down --volumes --remove-orphans

Exporta el esquema desde db.py al metadata-warehouse (comando para ejecutar en la raíz del repositorio data-commons-search):

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

⚡️ Iniciar servidor de desarrollo

Inicia el servidor en modo desarrollo en http://localhost:8000, con el endpoint MCP en http://localhost:8000/mcp apuntando a una instancia de OpenSearch en ejecución:

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

Por defecto OPENSEARCH_URL=http://localhost:9200

Personaliza el puerto del servidor mediante la variable de entorno:

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]

Puedes desplegar el frontend matchmaker en modo desarrollo al lado, apuntando a este servidor de desarrollo:

cd ../matchmaker
npm run dev

[!TIP]

Ejemplo de solicitud 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"}'

Con token de acceso de usuario autenticado desde 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"}'

Obtener la última conversación:

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"

Encontrar modelo disponible del proveedor Cesnet:

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

Modelo recomendado: cesnet/agentic

🔐 Almacén de secretos

EGI Secret Store, obtén el token de aai.egi.eu/token (decodifica el JWT para obtener el token de acceso real)

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"

🐳 Desplegar con Docker

Crea un archivo keys.env con las claves API (consulta arriba para ver el ejemplo completo):

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 se puede usar para añadir una capa de protección contra bots que podrían hacer spam al LLM; si no se proporciona, no se necesitará ninguna clave API para consultar la API.

Puedes usar la imagen docker preconstruida ghcr.io/eosc-data-commons/data-commons-search:main

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

Construye y despliega el servicio:

docker compose up

📦 Construir para producción

Construye el paquete en dist/:

uv build

✅ Ejecutar pruebas

[!CAUTION]

Primero necesitas iniciar el servidor en el puerto 8000 (consulta la sección de inicio del servidor de desarrollo) y PostgreSQL.

uv run pytest

Ejecutar benchmark (comprobar el éxito de un conjunto de consultas de búsqueda):

uv run tests/benchmark.py

Ejecutar pruebas de jailbreak de LLM con garak:

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

Ejecutar pruebas de estrés (20 usos concurrentes) de la API:

uv run tests/stress_api.py -c 20

🧹 Formatear código y verificación de tipos

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

♻️ Restablecer el entorno

Actualizar uv:

uv self update

Limpiar la caché de uv:

uv cache clean

🔧 Mantenimiento

Precalcular estadísticas para los conjuntos de datos en la base de datos en src/data_commons_search/stats.json:

POSTGRES_DB=datasetdb uv run scripts/compute_stats.py

Actualizar dependencias en pyproject.toml:

uvx uv-bump

🏷️ Proceso de lanzamiento

Ejecuta el script de lanzamiento proporcionando el incremento de versión: fix, minor o major

.github/release.sh fix

O una versión explícita, por ejemplo, para alinearla con la versión del frontend:

.github/release.sh 0.10.0

Esto creará una etiqueta git, un lanzamiento de GitHub y publicará una imagen docker

🤝 Agradecimientos

El proveedor de LLM cesnet es un servicio proporcionado por e-INFRA CZ y operado por CERIT-SC de la Universidad Masaryk

Los recursos computacionales fueron proporcionados por el proyecto e-INFRA CZ (ID:90254), apoyado por el Ministerio de Educación, Juventud y Deportes de la República Checa.

El proveedor de autenticación es EGI Check-in.