From 681c1e2abf1c822b65ca635c51032b2dafcd55c1 Mon Sep 17 00:00:00 2001 From: Kent Date: Wed, 4 Mar 2026 15:27:16 +0800 Subject: [PATCH 1/5] docs(mcp): update available tools table with accurate tool list Add list_checks and run_check to the tools table. Move value_diff, top_k_diff, and histogram_diff to a separate section noting they are accessible via run_check. Add server modes note explaining tool availability in preview/read-only modes. Closes DRC-2735 Co-Authored-By: Claude Opus 4.6 Signed-off-by: Kent --- docs/5-data-diffing/mcp-server.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/docs/5-data-diffing/mcp-server.md b/docs/5-data-diffing/mcp-server.md index d92ad1c..97a4938 100644 --- a/docs/5-data-diffing/mcp-server.md +++ b/docs/5-data-diffing/mcp-server.md @@ -207,11 +207,25 @@ 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` | Execute a specific validation check by ID | + +### Additional check types via `run_check` + +These check types work through preset checks configured in `recce.yml` or created in the Recce instance. Your AI agent executes 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 "Server modes" + The MCP server supports three modes: **server** (default), **preview**, and **read-only**. In preview and read-only modes, only `lineage_diff` and `schema_diff` are available — tools that query your warehouse are disabled. ## Troubleshooting From 36dfd618764b9ae7069930e599d5ba3885edb387 Mon Sep 17 00:00:00 2001 From: Kent Date: Wed, 4 Mar 2026 21:22:49 +0800 Subject: [PATCH 2/5] docs(mcp): apply terminology guide fixes to tools table Use "Run" instead of "Execute", clarify "MCP server modes" to avoid confusion with database servers, and improve section heading and description phrasing per project writing principles. Co-Authored-By: Claude Opus 4.6 --- docs/5-data-diffing/mcp-server.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/5-data-diffing/mcp-server.md b/docs/5-data-diffing/mcp-server.md index 97a4938..ca98c54 100644 --- a/docs/5-data-diffing/mcp-server.md +++ b/docs/5-data-diffing/mcp-server.md @@ -210,11 +210,11 @@ When connected, the MCP server exposes these tools to your AI agent: | `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` | Execute a specific validation check by ID | +| `run_check` | Run a specific validation check by ID | -### Additional check types via `run_check` +### Check types available through `run_check` -These check types work through preset checks configured in `recce.yml` or created in the Recce instance. Your AI agent executes them with the `run_check` tool: +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 | |------------|-------------| @@ -224,7 +224,7 @@ These check types work through preset checks configured in `recce.yml` or create See [Preset checks](../7-cicd/preset-checks.md) for how to configure these check types. -!!! note "Server modes" +!!! note "MCP server modes" The MCP server supports three modes: **server** (default), **preview**, and **read-only**. In preview and read-only modes, only `lineage_diff` and `schema_diff` are available — tools that query your warehouse are disabled. ## Troubleshooting From d77d231fc0151869d248c06de55dfc2e3e0dc2df Mon Sep 17 00:00:00 2001 From: Kent Date: Wed, 4 Mar 2026 21:39:02 +0800 Subject: [PATCH 3/5] docs(mcp): clarify server mode tool availability in admonition Explicitly state that server mode exposes all tools, making the relationship between the tools table and the modes note unambiguous. Co-Authored-By: Claude Opus 4.6 --- docs/5-data-diffing/mcp-server.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/5-data-diffing/mcp-server.md b/docs/5-data-diffing/mcp-server.md index ca98c54..6a2756e 100644 --- a/docs/5-data-diffing/mcp-server.md +++ b/docs/5-data-diffing/mcp-server.md @@ -225,7 +225,7 @@ These check types are accessible as preset checks configured in `recce.yml` or c See [Preset checks](../7-cicd/preset-checks.md) for how to configure these check types. !!! note "MCP server modes" - The MCP server supports three modes: **server** (default), **preview**, and **read-only**. In preview and read-only modes, only `lineage_diff` and `schema_diff` are available — tools that query your warehouse are disabled. + The MCP server supports three modes: **server** (default), **preview**, and **read-only**. In **server** mode, all of the tools listed above are available. In **preview** and **read-only** modes, only `lineage_diff` and `schema_diff` are available — tools that query your warehouse are disabled. ## Troubleshooting From 581d0d76dc003a116064f3c14f0c655dd8677c11 Mon Sep 17 00:00:00 2001 From: Kent Date: Thu, 5 Mar 2026 01:49:27 +0800 Subject: [PATCH 4/5] docs(mcp): document single-environment mode for missing base artifacts Update prerequisites, server modes, and troubleshooting to reflect the new single-env onboarding mode where the MCP server starts without target-base/ artifacts. Depends on DataRecce/recce#1175 (DRC-2795). Co-Authored-By: Claude Opus 4.6 --- docs/5-data-diffing/mcp-server.md | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/docs/5-data-diffing/mcp-server.md b/docs/5-data-diffing/mcp-server.md index 6a2756e..5964132 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 @@ -227,21 +227,29 @@ See [Preset checks](../7-cicd/preset-checks.md) for how to configure these check !!! note "MCP server modes" The MCP server supports three modes: **server** (default), **preview**, and **read-only**. In **server** mode, all of the tools listed above are available. In **preview** and **read-only** modes, only `lineage_diff` and `schema_diff` are available — tools that query your warehouse are disabled. + If base artifacts (`target-base/`) are not present, the server starts in **single-environment mode** where all tools work but diffs show no changes. Diff responses include a `_warning` field reminding you to generate base artifacts. + ## 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 development artifacts. Check that your development 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). + +### Diff results show no changes -### "No such file or directory: target-base/manifest.json" +If the server starts but all diffs return empty results, you are likely in single-environment mode (missing base artifacts). Generate base artifacts to enable real comparisons: -You need to generate base artifacts. See [Prerequisites](#prerequisites). +```shell +git stash && git checkout main +dbt docs generate --target-path target-base +git checkout && git stash pop +``` ### Port already in use (SSE mode) From 84f27427555efccf813b5d21e20389c21ee93b19 Mon Sep 17 00:00:00 2001 From: Kent Date: Fri, 6 Mar 2026 10:02:22 +0800 Subject: [PATCH 5/5] docs(mcp): address review - simplify modes, keep dbt wording, remove git stash - Remove server modes admonition per reviewer feedback (focus on server mode) - Keep "dbt artifacts" instead of generic "development artifacts" - Replace git stash troubleshooting steps with link to prerequisites Co-Authored-By: Claude Opus 4.6 --- docs/5-data-diffing/mcp-server.md | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) diff --git a/docs/5-data-diffing/mcp-server.md b/docs/5-data-diffing/mcp-server.md index 5964132..57037b0 100644 --- a/docs/5-data-diffing/mcp-server.md +++ b/docs/5-data-diffing/mcp-server.md @@ -224,16 +224,14 @@ These check types are accessible as preset checks configured in `recce.yml` or c See [Preset checks](../7-cicd/preset-checks.md) for how to configure these check types. -!!! note "MCP server modes" - The MCP server supports three modes: **server** (default), **preview**, and **read-only**. In **server** mode, all of the tools listed above are available. In **preview** and **read-only** modes, only `lineage_diff` and `schema_diff` are available — tools that query your warehouse are disabled. - - If base artifacts (`target-base/`) are not present, the server starts in **single-environment mode** where all tools work but diffs show no changes. Diff responses include a `_warning` field reminding you to generate base artifacts. +!!! 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 development artifacts. Check that your development artifacts exist: +The most common cause is missing dbt artifacts. Check that your dbt artifacts exist: ```shell ls target/manifest.json @@ -243,13 +241,7 @@ If missing, run `dbt docs generate` in your current branch. See [Prerequisites]( ### Diff results show no changes -If the server starts but all diffs return empty results, you are likely in single-environment mode (missing base artifacts). Generate base artifacts to enable real comparisons: - -```shell -git stash && git checkout main -dbt docs generate --target-path target-base -git checkout && git stash pop -``` +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)