🔭 EOSC Data Commons Search 服务器

一个用于 EOSC Data Commons 项目 MatchMaker 服务的服务器，提供对开放访问数据集的自然语言搜索。它暴露了一个 HTTP POST 端点，并支持 Model Context Protocol (MCP)，以帮助用户通过大型语言模型辅助搜索来发现数据集和工具。

🧩 端点

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 服务器

该系统可以直接用作 MCP 服务器，使用 STDIO 或 Streamable HTTP 传输。

[!WARNING]

你需要访问一个预先索引的 OpenSearch 实例，MCP 服务器才能正常工作。

按照你的客户端的说明，使用公共服务器的 /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

创建一个 keys.env 文件，包含你的 LLM 提供商 API 密钥，以及可选的其他配置：

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 中的 schema 导出到 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 部署

创建一个 keys.env 文件，包含 API 密钥（完整示例见上文）：

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

使用 garak 运行 LLM 越狱测试：

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 马萨里克大学运营。

计算资源由 e-INFRA CZ 项目（ID:90254）提供，该项目由捷克共和国教育、青年和体育部支持。

认证提供商是 EGI Check-in。