Data Commons Search

You run an MCP-enabled server that lets you search EOSC Data Commons datasets and retrieve dataset metadata using natural language queries. It exposes an HTTP MCP endpoint for tool discovery and a chat endpoint for interactive conversations with an LLM provider, helping you locate data and related resources quickly.

How to use

You can connect an MCP client to the server to perform two main actions: search datasets and obtain metadata about the files within a dataset. The MCP endpoint is available at the /mcp path, and you can interact with the chat endpoint at /chat to drive LLM-assisted searches.

How to install

Prerequisites you need before starting:
- Python environment and the uvx helper
- Docker if you plan to run the OpenSearch service in a container
- API keys for an LLM provider (example env vars shown below)

Step-by-step setup with STDIO or HTTP transport is shown below. Choose one transport method based on your environment.

HTTP MCP URL example (for use with an MCP client or VSCode Copilot): use the MCP URL of your deployed server. A typical configuration in a client would point to the /mcp endpoint.

If you prefer STDIO transport for local development, use a command akin to running the server with uvx/uv and exposing the required environment variables.

{
  "type": "http",
  "name": "data-commons-search-http",
  "url": "http://localhost:8000/mcp",
  "args": []
}

Additional deployment notes

The server can be started in development mode at http://localhost:8000 with the MCP endpoint at http://localhost:8000/mcp. You can customize the OpenSearch URL via environment variables when starting the server.

If you want to run a local STDIO transport, you can use a command like uvx or uv with appropriate arguments and environment variables to point to the OpenSearch instance.

Example for starting in dev mode with a local OpenSearch instance (default OPENSEARCH_URL is http://localhost:9200):

uv run uvicorn src.data_commons_search.main:app --log-config logging.yml --reload

Connecting via Docker (optional)

You can deploy the server with Docker using a prebuilt image. Provide API keys via environment variables and expose the MCP endpoint.

services:
  mcp:
    image: ghcr.io/eosc-data-commons/data-commons-search:main
    ports:
      - "http://localhost:8000:8000"
    environment:
      OPENSEARCH_URL: "http://opensearch:9200"
      EINFRACZ_API_KEY: "YOUR_API_KEY"

Available tools

search_datasets

Query the EOSC Data Commons OpenSearch service to find datasets relevant to your natural language input.

get_dataset_metadata

Retrieve metadata for the files in a dataset, including name, description, and file types.