Language: Français | English

Give your coding agent (Claude Code, Cursor) reliable, always-fresh knowledge of your Dataform pipeline — table and column lineage, schemas, impact analysis — instead of letting it read .sqlx files one by one and hallucinate the DAG.

Install with Claude Code

Prerequisites (once per machine): uv (brew install uv) and @dataform/cli ≥ 3.0 (npm i -g @dataform/cli).

At the root of your Dataform repo, create or extend .mcp.json (template: .mcp.json.example):

{
  "mcpServers": {
    "dataform-context": {
      "type": "stdio",
      "command": "/opt/homebrew/bin/uvx",
      "args": ["--from", "dataform-context-mcp@latest", "dataform-context", "serve"]
    }
  }
}

That's it: no clone, no --repo (the server indexes the current directory). Open a Claude Code session in the repo and type /mcp: dataform-context should show as connected. First call takes ~15 s (initial compilation), then ~10 ms.

Verify from the agent: just ask "run check_setup" — the tool diagnoses the whole installation (dataform CLI, compilation, index, lineage coverage, goldens). Or copy integrations/claude-code/commands/dataform-context-verify.md into your repo's .claude/commands/ to get /dataform-context-verify.

Recommended: add the agent-instruction block to the repo's CLAUDE.md (see Getting the agent to adopt the tools).

Pin a version or work offline

@latest makes uvx check PyPI on every server start: fixes reach you with no action on your side, at the cost of a mandatory network access at start-up (1 to 3 s). Offline, the server does not start. To pin a version, or to ride out an outage, replace @latest with an exact version:

"args": ["--from", "dataform-context-mcp@0.5.0", "dataform-context", "serve"]

A pinned version no longer receives fixes: remember to bump it.

Install with Cursor

Same server, standard MCP stdio. Copy integrations/cursor/mcp.json.example to your repo's .cursor/mcp.json, and the rule integrations/cursor/rules/dataform-context.mdc to .cursor/rules/. Commands dataform-context-verify.md and dataform-context-golden-init.md go into .cursor/commands/ for /dataform-context-verify and /dataform-context-golden-init — same protocol as the Claude Code side (Cursor supports custom commands and, since v1.5, MCP elicitation). All integration material is summarized in integrations/README.md (French).

Install with Codex CLI

Prerequisites: uv and @dataform/cli ≥ 3.0.

At the root of your repo, create or extend .codex/config.toml (template: integrations/codex/config.toml.snippet):

[mcp_servers.dataform-context]
command = "/opt/homebrew/bin/uvx"
args = ["--from", "dataform-context-mcp@latest", "dataform-context", "serve"]

.codex/config.toml only loads for a "trusted" project: the first time you launch codex in the repo, answer "yes" to the trust prompt.

Add the block from integrations/codex/AGENTS.md.snippet.md to your AGENTS.md, then copy integrations/codex/skills/ into .codex/skills/ to get the dataform-context-verify and dataform-context-golden-init skills.

Install with Antigravity

Copy integrations/antigravity/mcp_config.json.example to .agents/mcp_config.json, the rule integrations/antigravity/rules/dataform-context.md to .agents/rules/, and the workflows integrations/antigravity/workflows/ to .agents/workflows/ to get /dataform-context-verify and /dataform-context-golden-init.

Install with Windsurf

⚠️ Unlike the other clients, Windsurf's MCP config is global per machine, not project-scoped. Merge integrations/windsurf/mcp_config.json.snippet into ~/.codeium/windsurf/mcp_config.json (once per machine). Rules and workflows stay project-scoped and commit normally: copy integrations/windsurf/rules/dataform-context.md to .windsurf/rules/ and integrations/windsurf/workflows/ to .windsurf/workflows/.

Install with Copilot (VS Code)

Copy integrations/copilot/mcp.json.example to .vscode/mcp.json (⚠️ not a root .mcp.json — schema collision with Claude Code/Cursor), the block from integrations/copilot/copilot-instructions.snippet.md to .github/copilot-instructions.md, and the prompt files integrations/copilot/prompts/ to .github/prompts/ to get /dataform-context-verify and /dataform-context-golden-init.

Why

A coding agent working on a Dataform repo reads .sqlx files one by one. Observed consequences in real conditions: invented columns or tables, upstream dependencies missed during refactors, underestimated downstream impact — the staging → intermediate → marts → assertions cascade is never seen as a whole.

Deterministic and self-hosted: no LLM, no network calls from the server, no warehouse access at runtime. Same files → same index → same answers.

.sqlx + includes/ ──▶ dataform compile --json ──▶ CompiledGraph parsing
                                                        │
        Local SQLite (~/.cache/dataform-context-mcp/)  ◀┘
        • actions, layers, documented columns
        • table-level edges (source: compiler dependencyTargets)
        • column-level edges (sqlglot, explicit statuses)
                                                        │
        MCP stdio server (7 tools) ◀────────────────────┘

The 8 tools

• Tolerant name resolution: my_table, dataset.my_table, full canonical name or .sqlx file path — with suggestions on errors.
• Layers discovered dynamically from file paths (definitions/transforms/<NN_name>/, definitions/sources/…) — no hardcoded convention.
• Every response embeds index_meta: freshness, source hash, counts, last compilation status.

Getting the agent to adopt the tools

Block to add to the Dataform repo's CLAUDE.md (or Cursor rules):

Pipeline context: dataform-context MCP

Before reading .sqlx files or modifying a table: get_table_context (schema + neighbors), get_upstream/get_downstream (DAG), impact_analysis (mandatory before any table or column refactor), find_tables_by_layer (layer scope), get_column_lineage (column origin). These tools are generated from dataform compile: they are authoritative for the DAG, unlike a partial file read. complete: false = unknown lineage, not "no dependency". After editing .sqlx files, the index refreshes itself (content hash).

Reading column lineage responses — the "never a false empty" contract

Static extraction has known limits (MERGE, SELECT * over an undocumented source, multi-statement scripts). The absolute rule: an empty lineage is only presented as "no dependency" when it is certain. Otherwise, it says so:

• Every table carries an extraction status (ok, partial, failed, not_attempted, source), always with a reason.
• get_column_lineage returns complete: false + warnings (opaque tables encountered) when the lineage is unknown beyond some point — distinct from complete: true + edges: [] (true absence, e.g. CURRENT_DATE()).
• impact_analysis(column=…) returns possibly_affected: downstream tables whose column impact is unknown. Never exclude them from a refactor.

Category details and surfacing: docs/lineage-limits.md (French).

dataform-context index            # compile + (re)build the current repo's index
dataform-context report           # summary: layers, edges, lineage coverage
dataform-context report --table my_table    # JSON context of one table
dataform-context serve            # MCP server (stdio) — used by .mcp.json
dataform-context validate-golden --golden goldens.json   # manual oracle

[
  {
    "table": "my_dataset.my_table",
    "column": "my_column",
    "direction": "upstream",
    "depth": 1,
    "expected_edges": ["upstream_ds.upstream_table.col -> my_dataset.my_table.my_column"],
    "expect_complete": true
  }
]

src/dataform_context_mcp/
├── compile.py     # subprocess dataform compile --json; structured errors
├── model.py       # CompiledGraph dataclasses (Target, Action, ...)
├── layers.py      # layer inference from file paths
├── staleness.py   # content hash of source files
├── db.py          # SQLite: DDL, rebuild, name resolution, recursive traversals
├── lineage.py     # sqlglot column extraction, explicit statuses, topological order
├── indexer.py     # ensure_fresh: lazy reindex + last-good fallback
├── server.py      # the 7 MCP tools (stdio)
└── cli.py         # index | report | serve | validate-golden

git clone git@github.com:vgossiaux/dataform-context-mcp.git
cd dataform-context-mcp
uv sync && uv run pytest        # 74 tests

Roadmap

• License (prerequisite for going open source).
• Batch, offline, self-hosted LLM semantic enrichment of undocumented columns — never at MCP runtime.
• Mermaid/graphviz graph export; PreToolUse hook suggesting impact_analysis before .sqlx edits.