Merge branch 'feat/TG-1053-mcp-entity-read' into 'enterprise'

feat(mcp): add entity read tools for projects, connections, table groups, test suites (TG-1053)

See merge request dkinternal/testgen/dataops-testgen!538

Author: ci bot

testgen/common/models/connection.py

@@ -43,6 +43,17 @@ class ConnectionMinimal(EntityMinimal):
     connection_name: str
 
 
+@dataclass
+class ConnectionListItem(EntityMinimal):
+    connection_id: int
+    connection_name: str
+    project_code: str
+    sql_flavor_code: SQLFlavorCode
+    project_host: str | None
+    project_db: str | None
+    table_group_count: int
+
+
 class Connection(Entity):
     __tablename__ = "connections"
 
@@ -93,6 +104,35 @@ def select_minimal_where(
         results = cls._select_columns_where(cls._minimal_columns, *clauses, order_by=order_by)
         return [ConnectionMinimal(**row) for row in results]
 
+    @classmethod
+    def list_for_project(
+        cls, project_code: str, *clauses, page: int = 1, limit: int = 20
+    ) -> tuple[list[ConnectionListItem], int]:
+        """Paginated listing of connections in a project, with their table-group counts."""
+        tg_count_subq = (
+            select(
+                TableGroup.connection_id.label("connection_id"),
+                func.count().label("table_group_count"),
+            )
+            .group_by(TableGroup.connection_id)
+            .subquery()
+        )
+        query = (
+            select(
+                cls.connection_id,
+                cls.connection_name,
+                cls.project_code,
+                cls.sql_flavor_code,
+                cls.project_host,
+                cls.project_db,
+                func.coalesce(tg_count_subq.c.table_group_count, 0).label("table_group_count"),
+            )
+            .outerjoin(tg_count_subq, tg_count_subq.c.connection_id == cls.connection_id)
+            .where(cls.project_code == project_code, *clauses)
+            .order_by(*cls._default_order_by)
+        )
+        return cls._paginate(query, page=page, limit=limit, data_class=ConnectionListItem)
+
     @classmethod
     def is_in_use(cls, ids: list[str]) -> bool:
         table_groups = TableGroup.select_minimal_where(TableGroup.connection_id.in_(ids))

testgen/common/models/project.py

@@ -66,19 +66,23 @@ def get_summary(cls, project_code: str) -> ProjectSummary | None:
                 WHERE table_groups.project_code = :project_code
             ) AS profiling_run_count,
             (
-                SELECT COUNT(*) FROM test_suites WHERE test_suites.project_code = :project_code
+                SELECT COUNT(*) FROM test_suites
+                WHERE test_suites.project_code = :project_code
+                  AND test_suites.is_monitor IS NOT TRUE
             ) AS test_suite_count,
             (
                 SELECT COUNT(*)
                 FROM test_definitions
                     LEFT JOIN test_suites ON test_definitions.test_suite_id = test_suites.id
                 WHERE test_suites.project_code = :project_code
+                  AND test_suites.is_monitor IS NOT TRUE
             ) AS test_definition_count,
             (
                 SELECT COUNT(*)
                 FROM test_runs
                     LEFT JOIN test_suites ON test_runs.test_suite_id = test_suites.id
                 WHERE test_suites.project_code = :project_code
+                  AND test_suites.is_monitor IS NOT TRUE
             ) AS test_run_count,
             (
                 SELECT COALESCE(observability_api_key, '') <> ''

testgen/common/models/table_group.py

@@ -47,6 +47,23 @@ class TableGroupStats(EntityMinimal):
     data_point_ct: int
 
 
+@dataclass
+class TableGroupListItem(EntityMinimal):
+    id: UUID
+    table_groups_name: str
+    table_group_schema: str
+    project_code: str
+    connection_name: str | None
+    table_count: int
+    column_count: int | None
+    row_count: int | None
+    last_profiled_date: datetime | None
+    last_tested_date: datetime | None
+    profiling_score: float | None
+    testing_score: float | None
+    quality_score: float | None
+
+
 @dataclass
 class TableGroupSummary(EntityMinimal):
     id: UUID
@@ -149,6 +166,20 @@ class TableGroup(Entity):
         dq_score_testing,
     )
 
+    @property
+    def quality_score(self) -> float:
+        """Overall quality score per ``utils.score``: profiling * testing when both
+        exist; the non-null one when only one ran; ``0.0`` when neither has run.
+
+        Mirrors what Project Dashboard, data_catalog, and inventory_service display.
+        Render through ``utils.friendly_score`` to get the user-facing percentage form
+        (``"95.0"`` rather than ``"0.95"``). The list-side equivalent is computed in
+        SQL inside ``_list_with_activity`` — keep both in sync if the formula changes.
+        """
+        from testgen.utils import score
+
+        return score(self.dq_score_profiling, self.dq_score_testing)
+
     @classmethod
     def get_minimal(cls, id_: str | UUID) -> TableGroupMinimal | None:
         result = cls._get_columns(id_, cls._minimal_columns)
@@ -385,6 +416,103 @@ def select_summary(
         total = items[0].total_count if items else 0
         return items, total
 
+    @classmethod
+    def list_for_project(
+        cls, project_code: str, *, page: int = 1, limit: int = 20
+    ) -> tuple[list[TableGroupListItem], int]:
+        """Config-focused paginated listing for a project, with table count and activity timestamps."""
+        return cls._list_with_activity(
+            scope_sql="groups.project_code = :project_code",
+            scope_params={"project_code": project_code},
+            page=page,
+            limit=limit,
+        )
+
+    @classmethod
+    def list_for_connection(
+        cls, connection_id: int, *, page: int = 1, limit: int = 20
+    ) -> tuple[list[TableGroupListItem], int]:
+        """Config-focused paginated listing for a connection, with table count and activity timestamps."""
+        return cls._list_with_activity(
+            scope_sql="groups.connection_id = :connection_id",
+            scope_params={"connection_id": connection_id},
+            page=page,
+            limit=limit,
+        )
+
+    @classmethod
+    def _list_with_activity(
+        cls,
+        *,
+        scope_sql: str,
+        scope_params: dict,
+        page: int,
+        limit: int,
+    ) -> tuple[list[TableGroupListItem], int]:
+        session = get_current_session()
+
+        # Separate COUNT(*) query — keeps `total` correct on out-of-range pages where
+        # the page rows are empty (a window function over zero rows would return 0).
+        total_query = f"SELECT COUNT(*) FROM table_groups AS groups WHERE {scope_sql};"
+        total = session.execute(text(total_query), scope_params).scalar() or 0
+        if total == 0:
+            return [], 0
+
+        params: dict = {**scope_params, "limit": limit, "offset": (page - 1) * limit}
+        rows_query = f"""
+        WITH stats AS (
+            SELECT table_groups_id,
+                COUNT(*) AS table_count,
+                SUM(column_ct) AS column_count,
+                SUM(COALESCE(record_ct, approx_record_ct)) AS row_count
+            FROM data_table_chars
+            GROUP BY table_groups_id
+        ),
+        latest_profile AS (
+            SELECT pr.table_groups_id, MAX(je.started_at) AS started_at
+            FROM profiling_runs pr
+                LEFT JOIN job_executions je ON je.id = pr.job_execution_id
+            GROUP BY pr.table_groups_id
+        ),
+        latest_test AS (
+            SELECT ts.table_groups_id, MAX(tr.test_starttime) AS test_starttime
+            FROM test_runs tr
+                JOIN test_suites ts ON ts.id = tr.test_suite_id
+            WHERE ts.is_monitor IS NOT TRUE
+            GROUP BY ts.table_groups_id
+        )
+        SELECT
+            groups.id,
+            groups.table_groups_name,
+            groups.table_group_schema,
+            groups.project_code,
+            connections.connection_name,
+            COALESCE(stats.table_count, 0) AS table_count,
+            stats.column_count,
+            stats.row_count,
+            latest_profile.started_at AS last_profiled_date,
+            latest_test.test_starttime AS last_tested_date,
+            groups.dq_score_profiling AS profiling_score,
+            groups.dq_score_testing AS testing_score,
+            -- Mirrors utils.score: product when both exist, else the non-null one, else NULL.
+            CASE
+                WHEN groups.dq_score_profiling IS NOT NULL AND groups.dq_score_testing IS NOT NULL
+                    THEN groups.dq_score_profiling * groups.dq_score_testing
+                ELSE COALESCE(groups.dq_score_profiling, groups.dq_score_testing)
+            END AS quality_score
+        FROM table_groups AS groups
+            LEFT JOIN connections ON connections.connection_id = groups.connection_id
+            LEFT JOIN stats ON stats.table_groups_id = groups.id
+            LEFT JOIN latest_profile ON latest_profile.table_groups_id = groups.id
+            LEFT JOIN latest_test ON latest_test.table_groups_id = groups.id
+        WHERE {scope_sql}
+        ORDER BY LOWER(groups.table_groups_name)
+        LIMIT :limit OFFSET :offset;
+        """
+        rows = session.execute(text(rows_query), params).mappings().all()
+        items = [TableGroupListItem(**row) for row in rows]
+        return items, total
+
     @classmethod
     def is_in_use(cls, ids: list[str]) -> bool:
         test_suites = TestSuite.select_minimal_where(TestSuite.table_groups_id.in_(ids))

testgen/common/models/test_suite.py

@@ -29,6 +29,15 @@ class TestSuiteMinimal(EntityMinimal):
     export_to_observability: str
 
 
+@dataclass(frozen=True)
+class TestDefinitionStats:
+    """Aggregate test-definition counts for a test suite."""
+
+    total: int
+    locked: int
+    counts_by_type: dict[str, int]
+
+
 @dataclass
 class TestSuiteSummary(EntityMinimal):
     id: UUID
@@ -213,6 +222,36 @@ def select_summary(cls, project_code: str, table_group_id: str | UUID | None = N
         results = db_session.execute(text(query), params).mappings().all()
         return [TestSuiteSummary(**row) for row in results]
 
+    @classmethod
+    def test_definition_stats(cls, test_suite_id: str | UUID) -> "TestDefinitionStats":
+        """Aggregate test-definition counts for a suite: total, locked, and per-test-type.
+
+        The per-type bucket uses the user-facing ``test_name_short`` label from
+        ``test_types``, falling back to the raw ``test_type`` code when the lookup
+        row is missing (defensive — every shipping test type has a short name).
+        """
+        query = """
+        SELECT
+            COALESCE(tt.test_name_short, td.test_type) AS type_label,
+            COUNT(*) AS total,
+            SUM(CASE WHEN COALESCE(td.lock_refresh, 'N') = 'Y' THEN 1 ELSE 0 END) AS locked
+        FROM test_definitions td
+            LEFT JOIN test_types tt ON tt.test_type = td.test_type
+        WHERE td.test_suite_id = :test_suite_id
+        GROUP BY type_label
+        ORDER BY type_label;
+        """
+        rows = (
+            get_current_session()
+            .execute(text(query), {"test_suite_id": str(test_suite_id)})
+            .mappings()
+            .all()
+        )
+        counts_by_type = {row["type_label"]: int(row["total"]) for row in rows}
+        total = sum(counts_by_type.values())
+        locked = sum(int(row["locked"]) for row in rows)
+        return TestDefinitionStats(total=total, locked=locked, counts_by_type=counts_by_type)
+
     @classmethod
     def is_in_use(cls, ids: list[str]) -> bool:
         query = """
@@ -248,4 +287,3 @@ def cascade_delete(cls, ids: list[str]) -> None:
         db_session = get_current_session()
         db_session.execute(text(query), {"test_suite_ids": tuple(ids)})
         cls.delete_where(cls.id.in_(ids))
-

testgen/mcp/server.py

@@ -140,9 +140,20 @@ def build_mcp_server(
         profiling_overview,
         table_health,
     )
-    from testgen.mcp.tools.connections import test_connection
+    from testgen.mcp.tools.connections import (
+            get_connection,
+        list_connections,
+        test_connection,
+        )
     from testgen.mcp.tools.data_catalog import update_catalog_metadata
-    from testgen.mcp.tools.discovery import get_data_inventory, list_projects, list_tables, list_test_suites
+    from testgen.mcp.tools.discovery import (
+        get_data_inventory,
+        get_project,
+        get_test_suite,
+        list_projects,
+        list_tables,
+        list_test_suites,
+    )
     from testgen.mcp.tools.execution import (
         cancel_profiling_run,
         cancel_test_run,
@@ -208,6 +219,8 @@ def build_mcp_server(
     from testgen.mcp.tools.source_data import get_source_data, get_source_data_query, get_table_sample
     from testgen.mcp.tools.table_groups import (
         create_table_group,
+        get_table_group,
+        list_table_groups,
         preview_table_group,
         update_table_group,
     )
@@ -263,8 +276,10 @@ def safe_prompt(fn):
     # Tools
     safe_tool(get_data_inventory)
     safe_tool(list_projects)
+    safe_tool(get_project)
     safe_tool(list_tables)
     safe_tool(list_test_suites)
+    safe_tool(get_test_suite)
     safe_tool(list_test_runs)
     safe_tool(get_test_run)
     safe_tool(list_test_results)
@@ -329,7 +344,11 @@ def safe_prompt(fn):
     safe_tool(create_notification)
     safe_tool(update_notification)
     safe_tool(delete_notification)
+    safe_tool(list_connections)
+    safe_tool(get_connection)
     safe_tool(test_connection)
+    safe_tool(list_table_groups)
+    safe_tool(get_table_group)
     safe_tool(create_table_group)
     safe_tool(update_table_group)
     safe_tool(preview_table_group)

testgen/mcp/tools/common.py

@@ -874,6 +874,18 @@ def parse_sql_flavor(value: str) -> tuple[SqlFlavorLabel, str, str]:
     return label, code, SQL_FLAVOR_CODE_TO_FAMILY[code]
 
 
+def format_flavor_label(sql_flavor_code: str | None) -> str:
+    """Map a stored ``sql_flavor_code`` to its user-facing display label.
+
+    Returns the raw code as a fallback when the code is not in the registry — defensive
+    against a never-shipping-but-still-stored value rather than letting an LLM see ``None``.
+    """
+    if sql_flavor_code is None:
+        return ""
+    label = SQL_FLAVOR_CODE_TO_LABEL.get(sql_flavor_code)
+    return label.value if label else sql_flavor_code
+
+
 # ===========================================================================
 # Connection-parameter contract (MCP input vocabulary)
 #