diff --git a/docs/5-data-diffing/mcp-server.md b/docs/5-data-diffing/mcp-server.md index d92ad1c..57037b0 100644 --- a/docs/5-data-diffing/mcp-server.md +++ b/docs/5-data-diffing/mcp-server.md @@ -35,7 +35,7 @@ Recce compares your current branch's dbt models against a baseline from your mai ## Prerequisites -Before starting the MCP server, generate both artifact sets. +Before starting the MCP server, generate your development artifacts. Base artifacts are recommended for full diffing but not required. ### Generate development artifacts @@ -61,8 +61,8 @@ git stash pop # restore changes This creates `target-base/manifest.json` and `target-base/catalog.json`. The MCP server compares these two artifact sets to produce diffs. -!!! warning - The MCP server will not start if either `target/manifest.json` or `target-base/manifest.json` is missing. +!!! note + If `target-base/` is missing, the MCP server starts in **single-environment mode** — all tools remain available, but diff results show no changes because both sides reference the same data. Generate base artifacts to enable real comparisons. ## Installation @@ -207,27 +207,41 @@ When connected, the MCP server exposes these tools to your AI agent: | `schema_diff` | Detect schema changes (added, removed, or modified columns and type changes) | | `row_count_diff` | Compare row counts between branches | | `profile_diff` | Statistical profiling comparison (min, max, avg, nulls, and more) | -| `value_diff` | Compare actual data values between branches | -| `top_k_diff` | Compare top-K value distributions | -| `histogram_diff` | Compare value distributions as histograms | | `query` | Run arbitrary SQL against your warehouse | | `query_diff` | Run the same SQL against both branches and compare results | +| `list_checks` | List all validation checks in the current session with their status | +| `run_check` | Run a specific validation check by ID | + +### Check types available through `run_check` + +These check types are accessible as preset checks configured in `recce.yml` or created in the Recce instance. Your AI agent runs them with the `run_check` tool: + +| Check type | Description | +|------------|-------------| +| `value_diff` | Compare actual data values row by row between branches | +| `top_k_diff` | Compare top-K value distributions | +| `histogram_diff` | Compare value distributions as histograms | + +See [Preset checks](../7-cicd/preset-checks.md) for how to configure these check types. + +!!! note + If base artifacts (`target-base/`) are not present, the server starts in **single-environment mode** — all tools remain available, but diff results show no changes. Generate base artifacts to enable real comparisons. ## Troubleshooting ### MCP server fails to start -The most common cause is missing dbt artifacts. Check that both artifact directories exist: +The most common cause is missing dbt artifacts. Check that your dbt artifacts exist: ```shell -ls target/manifest.json target-base/manifest.json +ls target/manifest.json ``` -If either file is missing, follow the [Prerequisites](#prerequisites) section above. +If missing, run `dbt docs generate` in your current branch. See [Prerequisites](#prerequisites). -### "No such file or directory: target-base/manifest.json" +### Diff results show no changes -You need to generate base artifacts. See [Prerequisites](#prerequisites). +If the server starts but all diffs return empty results, you are likely in single-environment mode (missing base artifacts). Follow the [Generate base artifacts](#generate-base-artifacts) steps to enable real comparisons. ### Port already in use (SSE mode)