Skip to main content
Glama

soup-mcp: Model Context Protocol Server for Soup

A lightweight, secure, and production-ready Model Context Protocol (MCP) server that exposes Soup's dataset intelligence and processing engine directly to AI developer tools—including Cursor, Claude Code, Antigravity, Cline, and Continue.


Why soup-mcp?

When AI engineers fine-tune local models in modern AI IDEs, data preparation is the single largest bottleneck:

  • Inspecting schemas and field distributions

  • Stripping invisible control characters, AI preambles ("As an AI language model..."), and fixing broken markdown code fences

  • Performing deterministic train/val/test splits with reproducible seeds

  • Removing duplicates and near-duplicate records

  • Deterministic sampling for fast testing

  • Merging multiple disparate data sources into a single file

  • Converting between Alpaca, ShareGPT, and ChatML formats

  • Scoring datasets for PII, toxic keywords, and educational value

soup-mcp connects these operations directly into the LLM's tool-calling loop, allowing AI assistants to prepare datasets autonomously, safely, and reproducibly.


Related MCP server: DataClinic MCP

Available MCP Tools (9 Core Tools)

Tool

Type

Description

soup_inspect_dataset

Read-only

Analyzes format validity, row counts, token length distributions, empty fields, duplicates, and issues.

soup_detect_format

Read-only

Detects schema format (alpaca, sharegpt, chatml, dpo, etc.) and column structure.

soup_score_dataset

Read-only

Evaluates dataset for PII (emails/phones), toxic keywords, language distribution, and educational value.

soup_clean_dataset

Safe Mutating

Sanitizes control characters, strips AI disclaimers, repairs unclosed markdown fences, and fixes JSON syntax.

soup_dedup_dataset

Safe Mutating

Drops exact and field-level duplicates with preserved row order.

soup_sample_dataset

Safe Mutating

Deterministic random subset sampling by count or percentage with seed.

soup_split_dataset

Safe Mutating

Deterministic train/validation/test partitioning with reproducible pseudorandom seeds.

soup_convert_format

Safe Mutating

Lossless format conversion between Alpaca, ShareGPT, and ChatML.

soup_merge_datasets

Safe Mutating

Merges multiple JSONL dataset files into a single unified file.


MCP Prompts (Built-in Workflow Recipes)

soup-mcp includes interactive prompts that AI assistants can load:

  • audit_dataset: Guides the AI to run inspection, format detection, and scoring tools to generate an exhaustive dataset health report.

  • prepare_dataset: Guides the AI through the complete preparation recipe: inspection -> cleaning -> deduplication -> format conversion -> train/val splitting.


Security Invariants

soup-mcp adheres strictly to Soup's core security architecture:

  1. Working Directory Containment: All read and write operations are strictly bound to the operator's Current Working Directory (CWD). Any relative traversal (../) or absolute path escaping CWD is refused immediately.

  2. Symlink Boundary Checks: Symlinks pointing outside the workspace boundary are rejected.

  3. Atomic File Writes: Output datasets are written to temporary files and atomically renamed (os.replace). File generation is all-or-nothing; an interrupted operation will never corrupt an existing dataset.

  4. No In-Place Overwrites: Input datasets are never modified in place. Cleaned or converted files default to distinct filenames (e.g. data_cleaned.jsonl).


Quickstart & Client Setup

1. Installation

git clone https://github.com/Shubham-dev-stack/soup-mcp.git
cd soup-mcp
pip install -e .

2. Configuration for AI Clients

Cursor (.cursor/mcp.json or Global MCP Settings)

{
  "mcpServers": {
    "soup": {
      "command": "python",
      "args": ["-m", "soup_mcp.server"]
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "soup": {
      "command": "python",
      "args": ["-m", "soup_mcp.server"]
    }
  }
}

Antigravity / Cline / Continue (.mcp.json)

{
  "mcpServers": {
    "soup": {
      "command": "python",
      "args": ["-m", "soup_mcp.server"]
    }
  }
}

Testing & Verification

The test suite enforces 100% test pass rates and multi-item positive control verification:

pytest -v

All 71 tests pass covering:

  • Format auto-detection & inspection across multi-row datasets

  • Cleaning rules (invisible control characters, zero-width spaces, AI disclaimers)

  • De-duplication and preserved item order

  • Sample partitioning with deterministic seeds

  • Multi-dataset file merging

  • Split boundary checks (percentage & absolute modes with seed reproducibility)

  • 1-to-1 message preservation during format conversion

  • Negative security controls (path traversal, parent symlinks, in-place overwrite prevention)

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      Not graded
      maintenance
      Provides AI agents with data validation, transformation, and normalization capabilities, including JSON schema validation, CSV processing, data normalization, text cleaning, and dataset merging.
      5
      66 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI coding assistants to audit datasets against DAMA-DMBOK quality dimensions, sanitize PII, generate differential-privacy synthetic twins, compress prompt context, and export dbt schema tests and interactive HTML reports. It supports development against sensitive data with zero real records exposed to external LLMs.
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to deterministically profile, clean, normalize, and validate tabular data, including locale-aware numbers, dates, text encoding, IDs, and CSV/XLSX/JSON inputs, while flagging ambiguous values instead of guessing.
      6
      176 PyPI
      Business Source 1.1