docs/MCP_USAGE.md

MCP Server Usage Guide

Overview

The HF EDA MCP Server provides three main tools for exploratory data analysis of HuggingFace datasets via the Model Context Protocol (MCP).

Available MCP Tools

The following 3 tools are automatically exposed by Gradio when mcp_server=True:

1. get_dataset_metadata

Retrieve comprehensive metadata for a HuggingFace dataset.

Parameters:

• dataset_id (string): HuggingFace dataset identifier (e.g., 'imdb', 'squad')
• config_name (string, optional): Configuration name for multi-config datasets

Returns: JSON object with dataset metadata including size, features, splits, and configuration details.

2. get_dataset_sample

Retrieve a sample of rows from a HuggingFace dataset.

Parameters:

• dataset_id (string): HuggingFace dataset identifier
• split (string, default: 'train'): Dataset split to sample from
• num_samples (number, default: 10): Number of samples to retrieve (max: 10000)
• config_name (string, optional): Configuration name for multi-config datasets

Returns: JSON object with sampled data and metadata.

3. analyze_dataset_features

Perform basic exploratory analysis on dataset features.

Parameters:

• dataset_id (string): HuggingFace dataset identifier
• split (string, default: 'train'): Dataset split to analyze
• sample_size (number, default: 1000): Number of samples for analysis (max: 50000)
• config_name (string, optional): Configuration name for multi-config datasets

Returns: JSON object with feature analysis results including statistics, missing values, and data quality assessment.

MCP Client Configuration

Using with Claude Desktop

Add this configuration to your MCP settings:

{
  "mcpServers": {
    "hf-eda-mcp-server": {
      "command": "pdm",
      "args": ["run", "hf-eda-mcp"],
      "env": {
        "HF_TOKEN": "your_huggingface_token_here"
      }
    }
  }
}

Using with Hosted Server

If the server is running on a remote host:

{
  "mcpServers": {
    "hf-eda-mcp-server": {
      "url": "https://your-server.com/gradio_api/mcp/sse"
    }
  }
}

Starting the Server

Local Development

# Start with MCP server enabled (default)
pdm run hf-eda-mcp

# Start on custom port
pdm run hf-eda-mcp --port 8080

# Start with verbose logging
pdm run hf-eda-mcp --verbose

# Start without MCP server functionality
pdm run hf-eda-mcp --no-mcp

# Start with custom host (listen on all interfaces)
pdm run hf-eda-mcp --host 0.0.0.0

# Start with public sharing enabled
pdm run hf-eda-mcp --share

# Start with custom cache directory
pdm run hf-eda-mcp --cache-dir /path/to/cache

# Start with custom maximum sample size
pdm run hf-eda-mcp --max-sample-size 100000

Server Modes

The server provides both a web interface and MCP server functionality in a single application. When MCP is enabled, Gradio automatically exposes the 3 EDA functions as MCP tools while still providing the web interface for direct interaction.

Environment Variables

The server supports comprehensive configuration via environment variables:

Authentication

• HF_TOKEN: HuggingFace access token for private datasets (optional)

Server Configuration

• HF_EDA_PORT: Server port (default: 7860)
• HF_EDA_HOST: Server host (default: 127.0.0.1)
• HF_EDA_MCP_ENABLED: Enable MCP server functionality (default: true)
• HF_EDA_SHARE: Enable public sharing via Gradio (default: false)

Logging Configuration

• HF_EDA_LOG_LEVEL: Logging level - DEBUG, INFO, WARNING, ERROR (default: INFO)

Performance and Caching

• HF_EDA_CACHE_DIR: Directory for caching datasets (optional)
• HF_EDA_MAX_CACHE_SIZE: Maximum cache size in MB (default: 1000)
• HF_EDA_MAX_SAMPLE_SIZE: Maximum sample size for analysis (default: 50000)
• HF_EDA_MAX_CONCURRENT: Maximum concurrent requests (default: 10)
• HF_EDA_REQUEST_TIMEOUT: Request timeout in seconds (default: 300)

Configuration Examples

Production Configuration

export HF_TOKEN="your_token_here"
export HF_EDA_HOST="0.0.0.0"
export HF_EDA_PORT="8080"
export HF_EDA_LOG_LEVEL="WARNING"
export HF_EDA_CACHE_DIR="/var/cache/hf-eda"
export HF_EDA_MAX_CONCURRENT="20"
pdm run hf-eda-mcp

Development Configuration

export HF_TOKEN="your_token_here"
export HF_EDA_LOG_LEVEL="DEBUG"
export HF_EDA_CACHE_DIR="./cache"
pdm run hf-eda-mcp --verbose

Example Usage

Once connected to an MCP client, you can use the tools like this:

# Get metadata for the IMDB dataset
Use the get_dataset_metadata tool with dataset_id="imdb"

# Sample 5 rows from the training split
Use the get_dataset_sample tool with dataset_id="imdb", split="train", num_samples=5

# Analyze features of the GLUE dataset (CoLA configuration)
Use the analyze_dataset_features tool with dataset_id="glue", config_name="cola", sample_size=500

API Endpoints

When the server is running, you can also access the tools via HTTP API:

• MCP Schema: http://localhost:7860/gradio_api/mcp/schema
• API Documentation: http://localhost:7860/?view=api
• Web Interface: http://localhost:7860

Troubleshooting

Authentication Issues

• Ensure HF_TOKEN environment variable is set for private datasets
• Check that your HuggingFace token has appropriate permissions

Dataset Not Found

• Verify the dataset ID is correct and exists on HuggingFace Hub
• Check if the dataset requires authentication

Performance Issues

• Reduce sample_size for large datasets
• Use streaming mode (enabled by default) for better memory efficiency