feat(mcp): single-env onboarding, --help prerequisites, and error classification

[iamcxa]

Summary

• DRC-2794: Fix MCP server crash when target-base/ is missing — no longer throws raw FileNotFoundError
• DRC-2795: Single-env onboarding mode — when target-base/ is missing, uses target/ for both environments with _warning in diff responses and description hints
• DRC-2796: --help prerequisites section documenting required dbt artifacts
• DRC-2754: Error classification for MCP server — shared indicator constants, classified errors → logger.warning() + Sentry metrics, unclassified → logger.error() + traceback

Reviewer Guide

Quick mapping from issue → code area. Start here if you're reviewing file-by-file.

Issue	What	Key files / functions
DRC-2794	Don't crash on missing target-base/	recce/cli.py → mcp_server() detects missing dir, sets single_env=True
DRC-2795	Diff tools add _warning in single-env mode	recce/mcp_server.py → _maybe_add_warning(), diff tool descriptions
DRC-2796	--help shows prerequisites	recce/cli.py → mcp_server() epilog text
DRC-2754	Central error classification	recce/mcp_server.py → _classify_db_error() in call_tool; recce/tasks/rowcount.py → shared indicator constants

Design notes for reviewers:

• _maybe_add_warning() only applies to 3 diff tools (row_count_diff, query_diff, profile_diff) — lineage_diff and schema_diff work without base env, so no warning needed
• Error classification priority: permission_denied > table_not_found > syntax_error (first match wins) — this matches severity order
• Central handler re-raises after logging — MCP SDK requires raised exceptions to set isError=True
• run.py:schema_diff_should_be_approved() try/except is intentional — ensures check creation even on error

Changes

Single-env onboarding (DRC-2794 + DRC-2795)

• CLI detects missing target-base/ and sets single_env=True (fixes DRC-2794 crash)
• _maybe_add_warning() adds _warning field to diff tool results
• Diff tool descriptions include conditional single-env note
• All tools remain available (no tool restriction in single-env mode)

Help text prerequisites (DRC-2796)

• recce mcp-server --help shows prerequisites section before examples
• Documents required dbt artifact directories and generation commands

Error classification (DRC-2754)

• Shared error indicator constants in recce/tasks/rowcount.py
• _classify_db_error() in MCP central handler: permission_denied > table_not_found > syntax_error
• Classified errors → logger.warning() + sentry_metrics.count(); unclassified → logger.error()
• Applied to run.py schema_diff_should_be_approved() and sqlmesh path

Test coverage

• 25 E2E tests (real DuckDB via DbtTestHelper) — Layer 1 (direct) + Layer 2 (anyio MCP protocol)
• Unit tests for error classification, call_tool handler, single-env mode
• Coverage for edge cases: missing base env, removed/modified columns, run_check error paths
• _query_row_count dbt path permission_denied and table_not_found branches

Docs

• Project-level MCP developer skill (.claude/skills/recce-mcp-dev/)
• MCP E2E verification skill (.claude/skills/recce-mcp-e2e/)
• AGENTS.md: add coverage command and skills directory

Demo

https://www.loom.com/share/91c92e56501d460d95b421e6a2ce1649

DRC-2795 single-env onboarding + MCP E2E auto test

Test plan

• python -m pytest tests/test_mcp_server.py tests/test_mcp_e2e.py -v — 71 tests pass
• python -m pytest tests/test_run.py tests/test_summary.py tests/test_rowcount_sqlmesh.py — 40 tests pass
• make flake8 — clean
• Codecov patch coverage gaps resolved (12 → 0 missing patch lines)

Closes DRC-2794, DRC-2795, DRC-2796, DRC-2754

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines	Coverage Δ
recce/cli.py	52.09% <100.00%> (+2.32%)	⬆️
recce/mcp_server.py	77.27% <100.00%> (+24.86%)	⬆️
recce/run.py	28.69% <100.00%> (+3.15%)	⬆️
recce/summary.py	66.05% <100.00%> (+0.72%)	⬆️
recce/tasks/rowcount.py	90.04% <100.00%> (+16.28%)	⬆️
tests/test_cli.py	100.00% <100.00%> (ø)
tests/test_mcp_e2e.py	100.00% <100.00%> (ø)
tests/test_mcp_server.py	100.00% <100.00%> (ø)
tests/test_rowcount_sqlmesh.py	100.00% <100.00%> (ø)
tests/test_run.py	100.00% <100.00%> (ø)
... and 1 more

... and 7 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

Adds “single-environment onboarding mode” to the Recce MCP server to allow starting when target-base/ artifacts are missing, and expands test coverage around MCP tools and DB error classification.

Changes:

• Add single_env mode to MCP server, including _warning injection into diff tool responses and tool description hints.
• Centralize DB error classification indicators and extend rowcount/sqlmesh error handling + summary rendering (N/A).
• Add new MCP E2E test suite (direct tool calls + full protocol) and CLI tests for single-env auto-detection.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
recce/mcp_server.py	Adds single_env flag, warning injection, and centralized error classification/logging.
recce/cli.py	Documents prerequisites in --help and auto-enables single-env mode when target-base/ missing.
recce/tasks/rowcount.py	Extracts shared DB error indicator lists; improves sqlmesh error classification behavior.
recce/summary.py	Returns "N/A" when row count is unavailable due to known statuses (table missing/permission/etc.).
recce/run.py	Improves logging/handling for schema-diff auto-approval when expected DB errors occur.
tests/test_mcp_e2e.py	Adds E2E tests for MCP tools (DuckDB) and protocol wiring.
tests/test_mcp_server.py	Adds unit tests for single-env warnings, tool descriptions, and DB error classification.
tests/test_cli.py	Adds CLI tests ensuring single-env auto-detection + messaging.
tests/test_summary.py	Adds coverage for new "N/A" behavior under specific meta statuses.
tests/test_rowcount_sqlmesh.py	Adds sqlmesh rowcount error classification tests.
pyproject.toml	Pins sentry-sdk minimum version.
Makefile	Adds an mcp target (currently with a hard-coded local path).

Comments suppressed due to low confidence (3)

recce/mcp_server.py:41

• sentry_sdk is imported but never used in this module (only sentry_metrics is referenced). This will fail flake8 with an unused import (F401); remove the unused import or use it explicitly.

try:
    import sentry_sdk
    from sentry_sdk import metrics as sentry_metrics
except ImportError:
    sentry_sdk = None
    sentry_metrics = None

recce/tasks/rowcount.py:337

• _classify_sqlmesh_error re-raises unknown exceptions via raise error, which discards the original traceback and makes debugging harder. Prefer re-raising with raise from the original except block (or preserve the traceback with raise error.with_traceback(...)).

        # Unknown error — re-raise
        raise error

Makefile:155

• The mcp make target hard-codes a developer-specific absolute path (/Users/kent/...). This will break for other contributors and in CI, and it also leaks a local filesystem path into the repo. Please remove this target or refactor it to use a configurable env var (with a safe default) and document it outside the tracked Makefile if it’s only for local use.

JAFFLE_SHOP_DIR := /Users/kent/Project/recce/jaffle_shop_golden

mcp:
	@dotenv -f $(JAFFLE_SHOP_DIR)/.env run python -m recce.cli mcp-server --sse \
	--project-dir $(JAFFLE_SHOP_DIR) \
	--profiles-dir $(JAFFLE_SHOP_DIR) \
	--target-path $(JAFFLE_SHOP_DIR)/target \
	--target-base-path $(JAFFLE_SHOP_DIR)/target-base \
	--config $(JAFFLE_SHOP_DIR)/recce.yml \
	--port 8000

[iamcxa]

Self-review: inline comments explaining design rationale for each DRC issue area.

[wcchang1115]

Hi KC,
I feel that the recce-mcp-dev skill is a bit overfit for the row count development case.
And there are some minor comments for your further check, thanks!

[iamcxa]

All review feedback addressed — please see individual thread replies for details.

@wcchang1115 @claude

[wcchang1115]

LGTM, thanks!