Fairspec MCP Server

Fairspec MCP Server connects AI assistants to the Fairspec data management framework, enabling automated data validation, schema inference, and querying. It can be installed in any assistant or IDE that supports the Model Context Protocol (MCP).

Installation

Run the MCP server:

npx fairspec@latest mcp

Configure your editor or AI assistant to use the Fairspec MCP server:

claude mcp add fairspec -- npx fairspec@latest mcp

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "fairspec": {
      "command": "npx",
      "args": ["fairspec@latest", "mcp"]
    }
  }
}

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "fairspec": {
      "command": "npx",
      "args": ["fairspec@latest", "mcp"]
    }
  }
}

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "fairspec": {
      "command": "npx",
      "args": ["fairspec@latest", "mcp"]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "fairspec": {
      "command": "npx",
      "args": ["fairspec@latest", "mcp"]
    }
  }
}

Usage

Once configured, you can ask your AI assistant to use Fairspec tools directly in natural language. The MCP server translates your requests into the appropriate tool calls and returns the results. Here are some examples of prompts you can try:

Validate my dataset in the current directory

Infer the schema for data.csv

Check if my data schema is valid

Detect the dialect of measurements.tsv

Query users.csv for all records where age > 30

Infer a dataset descriptor from all files in the data folder

Validate the table schema in schema.json

Show me the first 10 rows of results.csv sorted by date

Tools

The Fairspec MCP Server exposes 10 tools organized around core Fairspec concepts: data, data schemas, datasets, file dialects, tables, and table schemas. Each tool can be invoked by your AI assistant to perform a specific operation such as validation, inference, or querying. Below is a detailed description of each tool.

Validate Data

Validates data against a provided data schema, checking that every value conforms to the declared types and constraints. Returns detailed error reports pinpointing exactly which values failed validation and why.

Infer Data Schema

Analyzes a data sample and infers a data schema descriptor describing its structure, types, and constraints. Examines patterns across values to determine the most appropriate type for each field.

Validate Data Schema

Checks that a data schema descriptor is well-formed and conforms to the Fairspec specification. Ensures that all field definitions use valid types and that constraints are properly structured.

Infer Dataset

Scans a directory of files and produces a dataset descriptor capturing the structure, resources, and metadata. Automatically discovers tabular files, infers their schemas and dialects.

Validate Dataset

Checks that a dataset descriptor is well-formed and that all referenced resources are consistent. Verifies that resource paths resolve correctly and that schemas match the actual data.

Infer File Dialect

Detects the dialect of a tabular file, including delimiter, quote character, and header row presence. Samples the file content to reliably determine formatting details such as line terminators and encoding.

Query Table

Runs a SQL query against a tabular data file and returns the matching rows. Supports standard SQL syntax for filtering, sorting, aggregating, and joining data.

Validate Table

Checks that a table descriptor is well-formed and that the referenced data matches the declared schema. Reports mismatches between expected and observed field types, missing values, and constraint violations.

Infer Table Schema

Reads a tabular data file and infers a table schema descriptor with field names, types, and constraints. Analyzes column values to determine appropriate data types and identifies common patterns.

Validate Table Schema

Checks that a table schema descriptor is well-formed and conforms to the Fairspec specification. Ensures that all field definitions, types, and constraints are valid and properly structured.