recce-nightly 1.15.0.20250806__py3-none-any.whl → 1.26.0.20251124__py3-none-any.whl

recce/cli.py

@@ -8,7 +8,12 @@ import uvicorn
 from click import Abort
 
 from recce import event
-from recce.artifact import download_dbt_artifacts, upload_dbt_artifacts
+from recce.artifact import (
+    delete_dbt_artifacts,
+    download_dbt_artifacts,
+    upload_artifacts_to_session,
+    upload_dbt_artifacts,
+)
 from recce.config import RECCE_CONFIG_FILE, RECCE_ERROR_LOG_FILE, RecceConfig
 from recce.connect_to_cloud import (
     generate_key_pair,
@@ -19,7 +24,12 @@ from recce.exceptions import RecceConfigException
 from recce.git import current_branch, current_default_branch
 from recce.run import check_github_ci_env, cli_run
 from recce.server import RecceServerMode
-from recce.state import RecceCloudStateManager, RecceShareStateManager, RecceStateLoader
+from recce.state import (
+    CloudStateLoader,
+    FileStateLoader,
+    RecceCloudStateManager,
+    RecceShareStateManager,
+)
 from recce.summary import generate_markdown_summary
 from recce.util.api_token import prepare_api_token, show_invalid_api_token_message
 from recce.util.logger import CustomFormatter
@@ -40,9 +50,13 @@ def create_state_loader(review_mode, cloud_mode, state_file, cloud_options):
     console = Console()
 
     try:
-        return RecceStateLoader(
-            review_mode=review_mode, cloud_mode=cloud_mode, state_file=state_file, cloud_options=cloud_options
+        state_loader = (
+            CloudStateLoader(review_mode=review_mode, cloud_options=cloud_options)
+            if cloud_mode
+            else FileStateLoader(review_mode=review_mode, state_file=state_file)
         )
+        state_loader.load()
+        return state_loader
     except RecceCloudException as e:
         console.print("[[red]Error[/red]] Failed to load recce state file")
         console.print(f"Reason: {e.reason}")
@@ -53,6 +67,75 @@ def create_state_loader(review_mode, cloud_mode, state_file, cloud_options):
         exit(1)
 
 
+def patch_derived_args(args):
+    """
+    Patch derived args based on other args.
+    """
+    if args.get("session_id") or args.get("share_url"):
+        args["cloud"] = True
+        args["review"] = True
+
+
+def create_state_loader_by_args(state_file=None, **kwargs):
+    """
+    Create a state loader based on CLI arguments.
+
+    This function handles the cloud options logic that is shared between
+    server and mcp-server commands.
+
+    Args:
+        state_file: Optional path to state file
+        **kwargs: CLI arguments including api_token, cloud, review, session_id, share_url, etc.
+
+    Returns:
+        state_loader: The created state loader instance
+    """
+    from rich.console import Console
+
+    console = Console()
+
+    api_token = kwargs.get("api_token")
+    is_review = kwargs.get("review", False)
+    is_cloud = kwargs.get("cloud", False)
+    cloud_options = None
+
+    # Handle share_url and session_id
+    share_url = kwargs.get("share_url")
+    session_id = kwargs.get("session_id")
+
+    if share_url:
+        share_id = share_url.split("/")[-1]
+        if not share_id:
+            console.print("[[red]Error[/red]] Invalid share URL format.")
+            exit(1)
+
+    if is_cloud:
+        # Cloud mode
+        if share_url:
+            cloud_options = {
+                "host": kwargs.get("state_file_host"),
+                "api_token": api_token,
+                "share_id": share_id,
+            }
+        elif session_id:
+            cloud_options = {
+                "host": kwargs.get("state_file_host"),
+                "api_token": api_token,
+                "session_id": session_id,
+            }
+        else:
+            cloud_options = {
+                "host": kwargs.get("state_file_host"),
+                "github_token": kwargs.get("cloud_token"),
+                "password": kwargs.get("password"),
+            }
+
+    # Create state loader
+    state_loader = create_state_loader(is_review, is_cloud, state_file, cloud_options)
+
+    return state_loader
+
+
 def handle_debug_flag(**kwargs):
     if kwargs.get("debug"):
         import logging
@@ -61,6 +144,14 @@ def handle_debug_flag(**kwargs):
         ch.setFormatter(CustomFormatter())
         logging.basicConfig(handlers=[ch], level=logging.DEBUG)
 
+        # Explicitly set uvicorn logger to DEBUG level
+        uvicorn_logger = logging.getLogger("uvicorn")
+        uvicorn_logger.setLevel(logging.DEBUG)
+
+        # Set all child loggers to DEBUG as well
+        for handler in uvicorn_logger.handlers:
+            handler.setLevel(logging.DEBUG)
+
 
 def add_options(options):
     def _add_options(func):
@@ -130,6 +221,15 @@ recce_cloud_options = [
     ),
 ]
 
+recce_cloud_auth_options = [
+    click.option(
+        "--api-token",
+        help="The personal token generated by Recce Cloud.",
+        type=click.STRING,
+        envvar="RECCE_API_TOKEN",
+    )
+]
+
 recce_dbt_artifact_dir_options = [
     click.option(
         "--target-path",
@@ -159,6 +259,13 @@ recce_hidden_options = [
         envvar="RECCE_SHARE_URL",
         hidden=True,
     ),
+    click.option(
+        "--session-id",
+        help="The session ID triggers this instance.",
+        type=click.STRING,
+        envvar=["RECCE_SESSION_ID", "RECCE_SNAPSHOT_ID"],  # Backward compatibility with RECCE_SNAPSHOT_ID
+        hidden=True,
+    ),
 ]
 
 
@@ -371,18 +478,23 @@ def diff(sql, primary_keys: List[str] = None, keep_shape: bool = False, keep_equ
 @click.option("--host", default="localhost", show_default=True, help="The host to bind to.")
 @click.option("--port", default=8000, show_default=True, help="The port to bind to.", type=int)
 @click.option("--lifetime", default=0, show_default=True, help="The lifetime of the server in seconds.", type=int)
-@click.option("--review", is_flag=True, help="Open the state file in the review mode.")
-@click.option("--single-env", is_flag=True, help="Launch in single environment mode directly.")
 @click.option(
-    "--api-token", help="The personal token generated by Recce Cloud.", type=click.STRING, envvar="RECCE_API_TOKEN"
+    "--idle-timeout",
+    default=0,
+    show_default=True,
+    help="The idle timeout in seconds. If 0, idle timeout is disabled. Maximum value is capped by lifetime.",
+    type=int,
 )
+@click.option("--review", is_flag=True, help="Open the state file in the review mode.")
+@click.option("--single-env", is_flag=True, help="Launch in single environment mode directly.")
 @add_options(dbt_related_options)
 @add_options(sqlmesh_related_options)
 @add_options(recce_options)
 @add_options(recce_dbt_artifact_dir_options)
 @add_options(recce_cloud_options)
+@add_options(recce_cloud_auth_options)
 @add_options(recce_hidden_options)
-def server(host, port, lifetime, state_file=None, **kwargs):
+def server(host, port, lifetime, idle_timeout=0, state_file=None, **kwargs):
     """
     Launch the recce server
 
@@ -408,11 +520,6 @@ def server(host, port, lifetime, state_file=None, **kwargs):
     recce server --cloud
     recce server --review --cloud
 
-    \b
-    # Launch the server using the state from a shared URL. (Requires Recce API token)
-    export RECCE_API_TOKEN=<your-recce-api-token>
-    recce server --cloud --share-url <share-url>
-
     """
 
     from rich.console import Console
@@ -423,15 +530,23 @@ def server(host, port, lifetime, state_file=None, **kwargs):
     RecceConfig(config_file=kwargs.get("config"))
 
     handle_debug_flag(**kwargs)
+    patch_derived_args(kwargs)
+
     server_mode = kwargs.get("mode") if kwargs.get("mode") else RecceServerMode.server
     is_review = kwargs.get("review", False)
     is_cloud = kwargs.get("cloud", False)
-    flag = {}
+    flag = {
+        "single_env_onboarding": False,
+        "show_relaunch_hint": False,
+        "preview": False,
+        "read_only": False,
+    }
     console = Console()
-    cloud_options = None
 
+    # Prepare API token
     try:
         api_token = prepare_api_token(**kwargs)
+        kwargs["api_token"] = api_token
     except RecceConfigException:
         show_invalid_api_token_message()
         exit(1)
@@ -439,102 +554,33 @@ def server(host, port, lifetime, state_file=None, **kwargs):
         "api_token": api_token,
     }
 
-    share_url = kwargs.get("share_url")
-    if share_url:
-        share_id = share_url.split("/")[-1]
-        if not share_id:
-            console.print("[[red]Error[/red]] Invalid share URL format.")
-            exit(1)
-
-    if server_mode == RecceServerMode.server:
-        flag = {"single_env_onboarding": False, "show_relaunch_hint": False}
-        if is_cloud:
-            if share_url:
-                # recce server --cloud --share-url <share-url>
-                # Use state file stored for the share url
-                # Forces use of the review mode.
-                is_review = kwargs["review"] = True
-                cloud_options = {
-                    "host": kwargs.get("state_file_host"),
-                    "api_token": api_token,
-                    "share_id": share_id,
-                }
-            else:
-                # recce server --cloud
-                # recce server --cloud --review
-                # Use state file stored for the PR of the current branch
-                cloud_options = {
-                    "host": kwargs.get("state_file_host"),
-                    "github_token": kwargs.get("cloud_token"),
-                    "password": kwargs.get("password"),
-                }
-
-        # Check Single Environment Onboarding Mode if the review mode is False
+    # Check Single Environment Onboarding Mode if not in cloud mode and not in review mode
+    if not is_cloud and not is_review:
         project_dir_path = Path(kwargs.get("project_dir") or "./")
         target_base_path = project_dir_path.joinpath(Path(kwargs.get("target_base_path", "target-base")))
-        if not target_base_path.is_dir() and not is_review:
+        if not target_base_path.is_dir():
             # Mark as single env onboarding mode if user provides the target-path only
             flag["single_env_onboarding"] = True
             flag["show_relaunch_hint"] = True
             # Use the target path as the base path
             kwargs["target_base_path"] = kwargs.get("target_path")
-    elif server_mode == RecceServerMode.preview:
-        if is_cloud:
-            # recce server --cloud --share-url <share-url> --mode preview
-            # Use state file stored for the share url
-            #
-            # Preview mode disable these features
-            # - run query
-            #
-            # Usage:
-            #    Used in cloud managed instance. For cloud onboarding to preview the uploaded artifacts.
-            cloud_options = {
-                "host": kwargs.get("state_file_host"),
-                "api_token": api_token,
-                "share_id": share_id,
-            }
-        else:
-            # recce server --mode preview recce_state.json
-            if state_file is None:
-                console.print("[[red]Error[/red]] The state_file is required in 'Preview' mode.")
-                console.print("Please provide recce_state json file exported by Recce OSS.")
-                exit(1)
-        is_review = kwargs["review"] = True
-        flag = {
-            "preview": True,
-        }
+
+    # Server mode:
+    #
+    # It's used to determine the features disabled in the Web UI. Only used in the cloud-managed recce instances.
+    #
+    # Read-Only: No run query, no checklist
+    # Preview (Metadata-Only): No run query
+    if server_mode == RecceServerMode.preview:
+        flag["preview"] = True
     elif server_mode == RecceServerMode.read_only:
-        if is_cloud:
-            # recce server --cloud --share-url <share-url> --mode read-only
-            # Use state file stored for the share url
-            #
-            # Read-only mode disable these features
-            # - run query
-            # - use checklist
-            # - share
-            #
-            # Usage:
-            #    Used in cloud managed instance. Launch when user click a share link.
-            cloud_options = {
-                "host": kwargs.get("state_file_host"),
-                "api_token": api_token,
-                "share_id": share_id,
-            }
-        else:
-            # recce server --mode read-only recce_state.json
-            if state_file is None:
-                console.print("[[red]Error[/red]] The state_file is required in 'Read-Only' mode.")
-                console.print("Please provide recce_state json file exported by Recce OSS.")
-                exit(1)
-        is_review = kwargs["review"] = True
-        flag = {
-            "read_only": True,
-        }
+        flag["read_only"] = True
 
     # Onboarding State logic update here
     update_onboarding_state(api_token, flag.get("single_env_onboarding"))
 
-    state_loader = create_state_loader(is_review, is_cloud, state_file, cloud_options)
+    # Create state loader using shared function
+    state_loader = create_state_loader_by_args(state_file, **kwargs)
 
     if not state_loader.verify():
         error, hint = state_loader.error_and_hint
@@ -576,6 +622,22 @@ def server(host, port, lifetime, state_file=None, **kwargs):
     else:
         console.rule("Recce Server")
 
+    # Validate idle_timeout: cap at lifetime if it exceeds lifetime
+    if idle_timeout > 0:
+        # If lifetime is set (> 0) and idle_timeout exceeds it, cap to lifetime
+        if lifetime > 0 and idle_timeout > lifetime:
+            effective_idle_timeout = lifetime
+            console.print(
+                f"[[yellow]Warning[/yellow]] idle_timeout ({idle_timeout}s) exceeds lifetime ({lifetime}s). "
+                f"Capping idle_timeout to {effective_idle_timeout}s."
+            )
+        else:
+            # Use idle_timeout as-is (either lifetime is 0, or idle_timeout <= lifetime)
+            effective_idle_timeout = idle_timeout
+    else:
+        # idle_timeout is 0 or negative, disable idle timeout
+        effective_idle_timeout = 0
+
     state = AppState(
         command=server_mode,
         state_loader=state_loader,
@@ -583,7 +645,10 @@ def server(host, port, lifetime, state_file=None, **kwargs):
         flag=flag,
         auth_options=auth_options,
         lifetime=lifetime,
+        idle_timeout=effective_idle_timeout,
         share_url=kwargs.get("share_url"),
+        organization_name=os.environ.get("RECCE_SESSION_ORGANIZATION_NAME"),
+        web_url=os.environ.get("RECCE_CLOUD_WEB_URL"),
     )
     app.state = state
 
@@ -831,7 +896,7 @@ def purge(**kwargs):
 
     try:
         console.rule("Check Recce State from Cloud")
-        state_loader = RecceStateLoader(
+        state_loader = create_state_loader(
             review_mode=False, cloud_mode=True, state_file=None, cloud_options=cloud_options
         )
     except Exception:
@@ -1187,9 +1252,287 @@ def download_base_artifacts(**kwargs):
     password = kwargs.get("password")
     target_path = kwargs.get("target_path")
     branch = kwargs.get("branch")
+    # If recce can't infer default branch from "GITHUB_BASE_REF" and current_default_branch()
+    if branch is None:
+        console.print(
+            "[[red]Error[/red]] Please provide your base branch name with '--branch' to download the base " "artifacts."
+        )
+        exit(1)
+
     return _download_artifacts(branch, cloud_token, console, kwargs, password, target_path)
 
 
+@cloud.command(cls=TrackCommand)
+@click.option("--cloud-token", help="The GitHub token used by Recce Cloud.", type=click.STRING, envvar="GITHUB_TOKEN")
+@click.option(
+    "--branch",
+    "-b",
+    help="The branch to delete artifacts from.",
+    type=click.STRING,
+    envvar="GITHUB_HEAD_REF",
+    default=current_branch(),
+    show_default=True,
+)
+@click.option("--force", "-f", help="Bypasses the confirmation prompt. Delete the artifacts directly.", is_flag=True)
+@add_options(recce_options)
+def delete_artifacts(**kwargs):
+    """
+    Delete the dbt artifacts from cloud
+
+    Delete the dbt artifacts (metadata.json, catalog.json) from Recce Cloud for the given branch.
+    This will permanently remove the artifacts from the cloud storage.
+
+    By default, the artifacts are deleted from the current branch. You can specify the branch using the --branch option.
+    """
+    from rich.console import Console
+
+    console = Console()
+    cloud_token = kwargs.get("cloud_token")
+    branch = kwargs.get("branch")
+    force = kwargs.get("force", False)
+
+    if not force:
+        if not click.confirm(f'Do you want to delete artifacts from branch "{branch}"?'):
+            console.print("Deletion cancelled.")
+            return 0
+
+    try:
+        delete_dbt_artifacts(branch=branch, token=cloud_token, debug=kwargs.get("debug", False))
+        console.print(f"[[green]Success[/green]] Artifacts deleted from branch: {branch}")
+        return 0
+    except click.exceptions.Abort:
+        pass
+    except RecceCloudException as e:
+        console.print("[[red]Error[/red]] Failed to delete the dbt artifacts from cloud.")
+        console.print(f"Reason: {e.reason}")
+        exit(1)
+    except Exception as e:
+        console.print("[[red]Error[/red]] Failed to delete the dbt artifacts from cloud.")
+        console.print(f"Reason: {e}")
+        exit(1)
+
+
+@cloud.command(cls=TrackCommand, name="list-organizations")
+@click.option("--api-token", help="The Recce Cloud API token.", type=click.STRING, envvar="RECCE_API_TOKEN")
+@add_options(recce_options)
+def list_organizations(**kwargs):
+    """
+    List organizations from Recce Cloud
+
+    Lists all organizations that the authenticated user has access to.
+    """
+    from rich.console import Console
+    from rich.table import Table
+
+    console = Console()
+    handle_debug_flag(**kwargs)
+
+    try:
+        api_token = prepare_api_token(**kwargs)
+    except RecceConfigException:
+        show_invalid_api_token_message()
+        exit(1)
+
+    try:
+        from recce.util.recce_cloud import RecceCloud
+
+        cloud = RecceCloud(api_token)
+        organizations = cloud.list_organizations()
+
+        if not organizations:
+            console.print("No organizations found.")
+            return
+
+        table = Table(title="Organizations")
+        table.add_column("ID", style="cyan")
+        table.add_column("Name", style="green")
+        table.add_column("Display Name", style="yellow")
+
+        for org in organizations:
+            table.add_row(str(org.get("id", "")), org.get("name", ""), org.get("display_name", ""))
+
+        console.print(table)
+
+    except RecceCloudException as e:
+        console.print(f"[[red]Error[/red]] {e}")
+        exit(1)
+    except Exception as e:
+        console.print(f"[[red]Error[/red]] {e}")
+        exit(1)
+
+
+@cloud.command(cls=TrackCommand, name="list-projects")
+@click.option(
+    "--organization",
+    "-o",
+    help="Organization ID (can also be set via RECCE_ORGANIZATION_ID environment variable)",
+    type=click.STRING,
+    envvar="RECCE_ORGANIZATION_ID",
+)
+@click.option("--api-token", help="The Recce Cloud API token.", type=click.STRING, envvar="RECCE_API_TOKEN")
+@add_options(recce_options)
+def list_projects(**kwargs):
+    """
+    List projects from Recce Cloud
+
+    Lists all projects in the specified organization that the authenticated user has access to.
+
+    Examples:
+
+        # Using environment variable
+        export RECCE_ORGANIZATION_ID=8
+        recce cloud list-projects
+
+        # Using command line argument
+        recce cloud list-projects --organization 8
+
+        # Override environment variable
+        export RECCE_ORGANIZATION_ID=8
+        recce cloud list-projects --organization 10
+    """
+    from rich.console import Console
+    from rich.table import Table
+
+    console = Console()
+    handle_debug_flag(**kwargs)
+
+    try:
+        api_token = prepare_api_token(**kwargs)
+    except RecceConfigException:
+        show_invalid_api_token_message()
+        exit(1)
+
+    organization = kwargs.get("organization")
+    if not organization:
+        console.print("[[red]Error[/red]] Organization ID is required. Please provide it via:")
+        console.print("  --organization <id> or set RECCE_ORGANIZATION_ID environment variable")
+        exit(1)
+
+    try:
+        from recce.util.recce_cloud import RecceCloud
+
+        cloud = RecceCloud(api_token)
+        projects = cloud.list_projects(organization)
+
+        if not projects:
+            console.print(f"No projects found in organization {organization}.")
+            return
+
+        table = Table(title=f"Projects in Organization {organization}")
+        table.add_column("ID", style="cyan")
+        table.add_column("Name", style="green")
+        table.add_column("Display Name", style="yellow")
+
+        for project in projects:
+            table.add_row(str(project.get("id", "")), project.get("name", ""), project.get("display_name", ""))
+
+        console.print(table)
+
+    except RecceCloudException as e:
+        console.print(f"[[red]Error[/red]] {e}")
+        exit(1)
+    except Exception as e:
+        console.print(f"[[red]Error[/red]] {e}")
+        exit(1)
+
+
+@cloud.command(cls=TrackCommand, name="list-sessions")
+@click.option(
+    "--organization",
+    "-o",
+    help="Organization ID (can also be set via RECCE_ORGANIZATION_ID environment variable)",
+    type=click.STRING,
+    envvar="RECCE_ORGANIZATION_ID",
+)
+@click.option(
+    "--project",
+    "-p",
+    help="Project ID (can also be set via RECCE_PROJECT_ID environment variable)",
+    type=click.STRING,
+    envvar="RECCE_PROJECT_ID",
+)
+@click.option("--api-token", help="The Recce Cloud API token.", type=click.STRING, envvar="RECCE_API_TOKEN")
+@add_options(recce_options)
+def list_sessions(**kwargs):
+    """
+    List sessions from Recce Cloud
+
+    Lists all sessions in the specified project that the authenticated user has access to.
+
+    Examples:
+
+        # Using environment variables
+        export RECCE_ORGANIZATION_ID=8
+        export RECCE_PROJECT_ID=7
+        recce cloud list-sessions
+
+        # Using command line arguments
+        recce cloud list-sessions --organization 8 --project 7
+
+        # Mixed usage (env + CLI override)
+        export RECCE_ORGANIZATION_ID=8
+        recce cloud list-sessions --project 7
+
+        # Override environment variables
+        export RECCE_ORGANIZATION_ID=8
+        export RECCE_PROJECT_ID=7
+        recce cloud list-sessions --organization 10 --project 9
+    """
+    from rich.console import Console
+    from rich.table import Table
+
+    console = Console()
+    handle_debug_flag(**kwargs)
+
+    try:
+        api_token = prepare_api_token(**kwargs)
+    except RecceConfigException:
+        show_invalid_api_token_message()
+        exit(1)
+
+    organization = kwargs.get("organization")
+    project = kwargs.get("project")
+
+    # Validate required parameters
+    if not organization:
+        console.print("[[red]Error[/red]] Organization ID is required. Please provide it via:")
+        console.print("  --organization <id> or set RECCE_ORGANIZATION_ID environment variable")
+        exit(1)
+
+    if not project:
+        console.print("[[red]Error[/red]] Project ID is required. Please provide it via:")
+        console.print("  --project <id> or set RECCE_PROJECT_ID environment variable")
+        exit(1)
+
+    try:
+        from recce.util.recce_cloud import RecceCloud
+
+        cloud = RecceCloud(api_token)
+        sessions = cloud.list_sessions(organization, project)
+
+        if not sessions:
+            console.print(f"No sessions found in project {project}.")
+            return
+
+        table = Table(title=f"Sessions in Project {project}")
+        table.add_column("ID", style="cyan")
+        table.add_column("Name", style="green")
+        table.add_column("Is Base", style="yellow")
+
+        for session in sessions:
+            is_base = "✓" if session.get("is_base", False) else ""
+            table.add_row(session.get("id", ""), session.get("name", ""), is_base)
+
+        console.print(table)
+
+    except RecceCloudException as e:
+        console.print(f"[[red]Error[/red]] {e}")
+        exit(1)
+    except Exception as e:
+        console.print(f"[[red]Error[/red]] {e}")
+        exit(1)
+
+
 @cli.group("github", short_help="GitHub related commands", hidden=True)
 def github(**kwargs):
     pass
@@ -1219,7 +1562,10 @@ def artifact(**kwargs):
 @cli.command(cls=TrackCommand)
 @click.argument("state_file", type=click.Path(exists=True))
 @click.option(
-    "--api-token", help="The personal token generated by Recce Cloud.", type=click.STRING, envvar="RECCE_API_TOKEN"
+    "--api-token",
+    help="The personal token generated by Recce Cloud.",
+    type=click.STRING,
+    envvar="RECCE_API_TOKEN",
 )
 def share(state_file, **kwargs):
     """
@@ -1277,6 +1623,100 @@ def share(state_file, **kwargs):
         exit(1)
 
 
+snapshot_id_option = click.option(
+    "--snapshot-id",
+    help="The snapshot ID to upload artifacts to cloud.",
+    type=click.STRING,
+    envvar=["RECCE_SNAPSHOT_ID", "RECCE_SESSION_ID"],
+    required=True,
+)
+
+session_id_option = click.option(
+    "--session-id",
+    help="The session ID to upload artifacts to cloud.",
+    type=click.STRING,
+    envvar=["RECCE_SESSION_ID", "RECCE_SNAPSHOT_ID"],
+    required=True,
+)
+
+target_path_option = click.option(
+    "--target-path",
+    help="dbt artifacts directory for your artifacts.",
+    type=click.STRING,
+    default="target",
+    show_default=True,
+)
+
+
+@cli.command(cls=TrackCommand, hidden=True)
+@add_options([session_id_option, target_path_option])
+@add_options(recce_cloud_auth_options)
+@add_options(recce_options)
+def upload_session(**kwargs):
+    """
+    Upload target/manifest.json and target/catalog.json to the specific session ID
+
+    Upload the dbt artifacts (manifest.json, catalog.json) to Recce Cloud for the given session ID.
+    This allows you to associate artifacts with a specific session for later use.
+
+    Examples:\n
+
+    \b
+    # Upload artifacts to a session ID
+    recce upload-session --session-id <session-id>
+
+    \b
+    # Upload artifacts from custom target path to a session ID
+    recce upload-session --session-id <session-id> --target-path my-target
+    """
+    from rich.console import Console
+
+    console = Console()
+    handle_debug_flag(**kwargs)
+
+    # Initialize Recce Config
+    RecceConfig(config_file=kwargs.get("config"))
+
+    try:
+        api_token = prepare_api_token(**kwargs)
+    except RecceConfigException:
+        show_invalid_api_token_message()
+        exit(1)
+
+    session_id = kwargs.get("session_id")
+    target_path = kwargs.get("target_path")
+
+    try:
+        rc = upload_artifacts_to_session(
+            target_path, session_id=session_id, token=api_token, debug=kwargs.get("debug", False)
+        )
+        console.rule("Uploaded Successfully")
+        console.print(
+            f'Uploaded dbt artifacts to Recce Cloud for session ID "{session_id}" from "{os.path.abspath(target_path)}"'
+        )
+    except Exception as e:
+        console.rule("Failed to Upload Session", style="red")
+        console.print(f"[[red]Error[/red]] Failed to upload the dbt artifacts to the session {session_id}.")
+        console.print(f"Reason: {e}")
+        rc = 1
+    return rc
+
+
+# Backward compatibility for `recce snapshot` command
+@cli.command(
+    cls=TrackCommand,
+    hidden=True,
+    deprecated=True,
+    help="Upload target/manifest.json and target/catalog.json to the specific snapshot ID",
+)
+@add_options([snapshot_id_option, target_path_option])
+@add_options(recce_cloud_auth_options)
+@add_options(recce_options)
+def snapshot(**kwargs):
+    kwargs["session_id"] = kwargs.get("snapshot_id")
+    return upload_session(**kwargs)
+
+
 @cli.command(hidden=True, cls=TrackCommand)
 @click.argument("state_file", required=True)
 @click.option("--host", default="localhost", show_default=True, help="The host to bind to.")
@@ -1290,5 +1730,106 @@ def read_only(ctx, state_file=None, **kwargs):
     ctx.invoke(server, state_file=state_file, **kwargs)
 
 
+@cli.command(cls=TrackCommand)
+@click.option("--sse", is_flag=True, default=False, help="Start in HTTP/SSE mode instead of stdio mode")
+@click.option("--host", default="localhost", help="Host to bind to in SSE mode (default: localhost)")
+@click.option("--port", default=8000, type=int, help="Port to bind to in SSE mode (default: 8000)")
+@add_options(dbt_related_options)
+@add_options(sqlmesh_related_options)
+@add_options(recce_options)
+@add_options(recce_dbt_artifact_dir_options)
+@add_options(recce_cloud_options)
+@add_options(recce_cloud_auth_options)
+@add_options(recce_hidden_options)
+def mcp_server(sse, host, port, **kwargs):
+    """
+    [Experiment] Start the Recce MCP (Model Context Protocol) server
+
+    The MCP server provides an interface for AI assistants and tools to interact
+    with Recce's data validation capabilities. By default, it uses stdio for
+    communication. Use --sse to enable HTTP/Server-Sent Events mode instead.
+
+    Available tools:
+    - get_lineage_diff: Get lineage differences between environments
+    - row_count_diff: Compare row counts between environments
+    - query: Execute SQL queries with dbt templating
+    - query_diff: Compare query results between environments
+    - profile_diff: Generate statistical profiles and compare
+
+    Examples:\n
+
+    \b
+    # Start the MCP server in stdio mode (default)
+    recce mcp-server
+
+    \b
+    # Start in HTTP/SSE mode on default port 8000
+    recce mcp-server --sse
+
+    \b
+    # Start in HTTP/SSE mode with custom host and port
+    recce mcp-server --sse --host 0.0.0.0 --port 9000
+
+    \b
+    # Start with custom dbt configuration
+    recce mcp-server --target prod --project-dir ./my_project
+
+    SSE Connection URL (when using --sse): http://<host>:<port>/sse
+    """
+    from rich.console import Console
+
+    console = Console()
+    try:
+        # Import here to avoid import errors if mcp is not installed
+        from recce.mcp_server import run_mcp_server
+    except ImportError as e:
+        console.print(f"[[red]Error[/red]] Failed to import MCP server: {e}")
+        console.print(r"Please install the MCP package: pip install 'recce\[mcp]'")
+        exit(1)
+
+    # Initialize Recce Config
+    RecceConfig(config_file=kwargs.get("config"))
+
+    handle_debug_flag(**kwargs)
+    patch_derived_args(kwargs)
+
+    # Prepare API token
+    try:
+        api_token = prepare_api_token(**kwargs)
+        kwargs["api_token"] = api_token
+    except RecceConfigException:
+        show_invalid_api_token_message()
+        exit(1)
+
+    # Create state loader using shared function (if cloud mode is enabled)
+    is_cloud = kwargs.get("cloud", False)
+    if is_cloud:
+        state_loader = create_state_loader_by_args(None, **kwargs)
+        kwargs["state_loader"] = state_loader
+
+    try:
+        if sse:
+            console.print(f"Starting Recce MCP Server in HTTP/SSE mode on {host}:{port}...")
+            console.print(f"SSE endpoint: http://{host}:{port}/sse")
+            console.print("Available tools: get_lineage_diff, row_count_diff, query, query_diff, profile_diff")
+        else:
+            console.print("Starting Recce MCP Server in stdio mode...")
+            console.print("Available tools: get_lineage_diff, row_count_diff, query, query_diff, profile_diff")
+
+        # Run the server (stdio or SSE based on --sse flag)
+        asyncio.run(run_mcp_server(sse=sse, host=host, port=port, **kwargs))
+    except (asyncio.CancelledError, KeyboardInterrupt):
+        # Graceful shutdown (e.g., Ctrl+C)
+        console.print("[yellow]MCP Server interrupted[/yellow]")
+        exit(0)
+    except Exception as e:
+        console.print(f"[[red]Error[/red]] Failed to start MCP server: {e}")
+        if kwargs.get("debug"):
+            import traceback
+
+            traceback.print_exc()
+        exit(1)
+
+
 if __name__ == "__main__":
     cli()