jDataMunch MCP

Index a local data file (CSV, Excel, Parquet, or JSONL). Profiles all columns, detects types, computes statistics, and loads rows into SQLite for fast filtered retrieval. Set incremental=true (default) to skip re-indexing if file is unchanged. CSV, Excel, Parquet and JSONL only; any other format is rejected.

Index data files from a GitHub repository. Discovers CSV, Excel, Parquet, and JSONL files, downloads them, and indexes each via the same pipeline as index_local. Datasets are named {owner}--{repo}--{filename}. Max 50 MB per file, 20 files per repo. Set GITHUB_TOKEN env var for private repos or to avoid rate limits.

List every indexed dataset with its row count, column count, and source file. Call it first to find the dataset name every other tool needs, and to confirm a file was actually indexed. Lists only datasets under the active storage_path.

Takes no parameters.

List GitHub repositories indexed via index_repo. Shows repo name, HEAD SHA, dataset count, total rows, and dataset names for each repo. Covers repos indexed with index_repo only; a dataset added by index_local is not listed here.

Takes no parameters.

Primary orientation tool. Default detail='compact' returns one row per column: name, type, null%, distinct count, and the min/max (numbers, dates) or most frequent values (text; every value when 10 or fewer), plus date formats and unique columns. detail='full' adds samples, top values with counts, mean, median and summaries. Statistics come from the index, not a re-read of the source. On wide tables (60+ columns), results are auto-paginated — use columns=[] to select specific ones, or columns_offset to page through remaining columns.

Deep profile of a single column. Full value distribution for low-cardinality columns, histogram bins for numeric, temporal range for datetime. Default detail='compact' gives counts, range or stats, and top values as [value, count] pairs; detail='full' adds samples, percentages and a summary. top_n capped at 200; histogram_bins capped at 50.

Search across column names and values. Returns column-level results with IDs — tells you where to look, not the data itself. Use before get_rows or describe_column. max_results capped at 50. Set semantic=true for embedding-based search (requires an embedding provider: JDATAMUNCH_EMBED_MODEL, GOOGLE_API_KEY, or OPENAI_API_KEY).

Filtered row retrieval via structured filters. All filters are SQL-parameterized (no injection). Operators: eq, neq, gt, gte, lt, lte, contains, in, is_null, between. Use columns=[] to project — reduces tokens significantly on wide tables. Prefer aggregate() for summaries over paginating through rows. Rows come back as arrays under a 'fields' header (row_format='objects' for dicts). Returns at most limit rows (default 50); page with offset instead of raising it.

Server-side aggregations (GROUP BY). Saves orders of magnitude in tokens vs returning rows for the LLM to aggregate. Functions: count, sum, avg, min, max, count_distinct, median. limit capped at 1000.

Return a sample of rows. Useful for understanding data shape without prior knowledge. Method: 'head', 'tail', or 'random'. Use columns=[] on wide tables to reduce response size. Pass seed (int) with method='random' for deterministic, reproducible sampling. A sample shows shape, not distribution; use get_distribution when you need the spread.

Compare schema (columns, types, nullability) between two indexed datasets. Detects added/removed columns, type changes, and null-rate shifts. Pure in-memory comparison — no re-reading source files. Useful for detecting schema changes between dataset versions. Assessment: 'identical' | 'additive' (only additions) | 'breaking' (removals or type changes).

Return the highest-risk columns in a dataset ranked by a composite score combining: null rate, cardinality anomalies, numeric outlier spread, and (v1.10.0) runtime traffic from runtime_query_calls when traces exist. When include_runtime is true but no traces are ingested, the response carries an honest-hint caveat in _meta.runtime_caveat rather than silently scoring on static signals alone. top_n capped at 50.

Compute pairwise Pearson correlations between numeric columns. Returns pairs sorted by |r| descending, filtered to significant correlations. Use this to discover relationships in the data without manual exploration. top_n capped at 200.

Join two indexed datasets via SQL JOIN. Uses ATTACH DATABASE to combine two SQLite stores into one query. Supports inner, left, right, and cross joins. Use columns_a/columns_b to project — reduces tokens on wide tables. Row limit capped at 500. Prefer aggregate() on join results for summaries.

Generate natural-language summaries for a dataset and all its columns. Works on already-indexed datasets — reads profiles from index.json, generates summaries, and writes them back. No re-parsing of source files. Summaries are also auto-generated during index_local.

Delete an indexed dataset and its SQLite store. Frees disk space. Irreversible — the dataset must be re-indexed to use again.

Precompute column embeddings for semantic search. Optional warm-up — search_data with semantic=true lazily embeds on first use. Running embed_dataset upfront eliminates that latency. Requires an embedding provider (JDATAMUNCH_EMBED_MODEL, GOOGLE_API_KEY, or OPENAI_API_KEY).

Return cumulative token savings and cost avoided across all tool calls. Savings are modelled estimates, not per-call measurements.

Takes no parameters.

Verify an indexed dataset's on-disk integrity. Runs SQLite PRAGMA integrity_check, cross-checks row count and column list against index.json, and verifies index.json content hash. Reports stale-lock state from interrupted index_local runs. Returns overall_status: 'ok' | 'warning' | 'error'. Checks the integrity of the index, never the correctness of the underlying data.

Return the last N profile snapshots for a dataset. Snapshots are appended on every successful index_local — use this to detect schema/content drift over multiple ingests of the same dataset. n capped at 50.

Composite quality grade (A–F) for a dataset (B4). Combines null severity, type-confidence, constant-column count, primary-key presence, semantic-typing coverage, and drift history into a single score with a structured breakdown. Grades structure and completeness, not whether the values are right.

Rank primary-key candidates for a dataset (B5). Each entry carries a confidence score plus the reasons that raised it (integer column, UUID format, no nulls, exact-count unique). Candidates are ranked from profile statistics, so confirm against the source system before treating one as the key.

Discover FK candidates between this dataset and other indexed datasets (B5). For each non-PK column in the source, scans up to 20 other datasets' PK candidates and proposes joins where containment ≥ 95%. Sample-based (500 distinct values per source column).

Unified bin-counts for any column type (B8). Numeric → equal-width bins between min/max; datetime → time-bucket bins; categorical / string → top-n + 'other' bucket. Token-cheap way to ask 'what does this column look like?'. Bin counts only (default 20 bins); it never returns the underlying rows.

Map a natural-language intent into a ranked tool-call sequence for the given dataset (B3). Pure routing — no LLM call. Built-in intents: summarize, anomalies, compare, join, filter, trend, correlate.

Read-only sandboxed SQL escape hatch (B1). Accepts a single SELECT (or WITH … SELECT) statement. The first dataset is the main connection; additional datasets are ATTACHed under schema names (e.g. `<dataset>.rows`). Statement runs under PRAGMA query_only=1 with a 10-second budget and 500-row cap. Use this for HAVING / window functions / CTEs / multi-way joins that the structured tools don't cover.

Transitive impact of a column-level schema change (drop_column, rename_column, retype_column). Walks the inferred FK graph to max_depth, surfaces direct + transitive hits across datasets, and normalises blast_score to [0, 1]. For retype_column, also flags type_mismatch entries at FK edges whose partner type wouldn't survive the retype. Read-only.

Composite preflight: is this column safe to drop? Fuses four signals — primary-key status, foreign-key participation, cross-dataset name match, and runtime traffic — into a single verdict plus ranked blockers and a recommended_action. Verdict tiers: pk_blocking, fk_blocking, runtime_observed, cross_dataset_blocking, safe_to_drop. Read-only. The killer feature of the Phase-1 sibling-parity batch.

Surface columns with zero or stale runtime traffic. Reads runtime_query_calls (populated by ingest_sql_log) and surfaces columns that haven't been queried within `window_days`. Excludes primary-key candidates and audit fields (created_at / updated_at / dbt_*) by default. Refuses to run with explicit error when no runtime data has been ingested — would otherwise trivially flag every column.

Ingest a SQL log file (pg_stat_statements CSV or generic JSONL, .gz transparently) into the per-dataset runtime tables. Each query is parsed for table + column refs, redacted at the chokepoint (string + numeric literals + cell-PII registry), and rolled up into runtime_query_calls keyed by (fingerprint, table, column). Tables in the log that don't match any indexed dataset count as unmapped. Foundational primitive for find_unused_columns, check_column_drop_safe, and data_health_radar (v1.6.0 sibling-parity Phase 1).

Multi-signal cross-dataset column consolidation. Fuses name (token Jaccard), type, top-value overlap, cardinality similarity, and (when present) embedding cosine into a composite score. Clusters via union-find and classifies each cluster: near_duplicate, naming_drift, parallel_definition, or overlapping_topic. Use to find duplicate columns across datasets, surface naming drift (`email` vs `email_address`), or detect the same conceptual column spread across multiple datasets. Mirrors jcm's find_similar_symbols. Every signal is heuristic, so a high score means investigate, not merge.

Six-axis health radar for a dataset: null_health, type_confidence, cardinality_health, pk_presence, semantic_coverage, schema_stability (omitted when <2 history snapshots). Optional 7th axis runtime_coverage when traces ingested. Returns 0-100 score per axis + composite + A-F grade. Pairs with diff_data_health_radar for snapshot deltas. Mirrors jcm's six-axis health radar.

Diff two data_health_radar payloads. Pure function — pass the `radar` sub-field from two data_health_radar responses (e.g. yesterday vs today). Returns per-axis deltas, composite delta, grade change, regression and improvement lists (threshold: 3 points), one-line verdict.

Forensic accounting of PII redactions for a dataset. Returns per-pattern counts from runtime_redaction_log (populated by ingest_sql_log with redact=True), so operators can verify the chokepoint is firing on production traffic. Filter by source and lookback window. Empty result with no traces ingested is not an error — it just means no scrubbing has happened yet.

Inspect, set, or reset the weight vector search_data uses to rank columns (name/value/type match weights plus the BM25 and semantic blend scales). Omit all args to inspect the effective weights and their source. Pass set_weights (a {weight: number} object) to override, or reset=true to clear. Scope with dataset (per-dataset overrides win over the global default, which wins over built-ins). Honored by search_data at query time. Unlike jcodemunch/jdocmunch, weights are tuned explicitly here (no ranking ledger). Tunable: name_exact, name_substr, name_word, ai_summary_word, value_exact, value_substr, type_boost, bm25_scale, semantic_scale, default_semantic_weight. Affects search_data ranking only; no other tool reads these weights.

Detect whether the embedding provider has drifted since it was pinned. Column embeddings power semantic search_data and find_similar_columns; if the provider model changes underneath a stored index, saved vectors stop matching the live encoder and semantic ranking quietly degrades. Pins a 16-string canary in <index_path>/embed_canary.json and recomputes it on demand, reporting cosine drift. Call with force=true once to set the baseline, then again after a suspected provider change. Sibling of jcodemunch / jdocmunch check_embedding_drift.

Per-tool latency and cache-hit telemetry. Returns p50/p95/max latency and error rate per tool, the slowest tools by p95, and result-cache hit rates (aggregate / get_correlations / get_data_hotspots are the cached tools). window=session reads the always-on in-memory ring; window=1h/24h/7d/all reads the persistent SQLite sink (requires JDATAMUNCH_PERF_TELEMETRY=1). Sibling of jcodemunch / jdocmunch analyze_perf.

Finalize one canonical Markdown handoff for a completed data audit/analysis (jdatamunch.handoff/v1; suite parity with jCodeMunch). The server assembles YOUR sections deterministically, validates every evidence_refs entry against what this session actually retrieved (column ids like '<dataset>::<column>#column' or dataset names served by search_data / describe_dataset / describe_column — unknown refs fail closed), persists the result session-scoped, and returns a compact receipt {handoff_id, resource_uri, sha256, length, canonical:true}. Read the immutable body via the munch://handoff/<id> resource; repeated reads are byte-identical. Appendices are included exactly once; no character limit; never writes to your data.

Return the version-current CLAUDE.md / AGENT.md policy snippet for jdatamunch-mcp. Lets an agent keep a one-line CLAUDE.md (e.g. "Call jdatamunch_guide and strictly follow its instructions.") instead of pasting a static snippet that drifts from the installed version. Idempotent, no dataset context required. Sibling of jcodemunch_guide and jdocmunch_guide.

Takes no parameters.