feat(mcp): add CRUD write tools for projects and test suites (TG-1070)

Three new MCP write tools in core and one in the enterprise project-management
plugin, so an LLM can manage projects and test suites without falling back to
the UI:

- update_project (core, administer permission): updates the full per-project
  settings surface exposed in the UI — display name, weighted DQ scoring
  toggle, DataOps Observability URL + key, data retention enable/days, and
  retention schedule cron + timezone. Side effects mirror the UI: weights
  flip triggers a background score recalc, retention toggles upsert/delete
  the scheduled cleanup job. observability_api_key is consumed but never
  echoed back (mcp-patterns secrets rule).

- create_test_suite (core, edit permission): under a table group. Accepts
  the full UI-editable surface in one call — name, description, default
  severity, observability export toggle, DataOps Observability component
  fields, and scoring exclusion — so the LLM doesn't need a follow-up
  update_test_suite to finish configuring a new suite. Always non-monitor.

- update_test_suite (core, edit permission): same surface, partial updates.
  Resolves through the existing monitor-filtered resolve_test_suite so a
  monitor-suite ID surfaces the unified "not found or not accessible"
  wording. Empty-string args on NullIfEmptyString columns normalize to
  None on the way in so the diff never reports a phantom change.

create_project (enterprise plugin, global_admin) registers through the
TG-1124 plugin MCP-tools hook in testgen_project_management. Mirrors the
UI's "Add Project" handler: persists the row and schedules the data-retention
cleanup job at the project's defaults so MCP-created projects behave the
same as UI-created ones. Project creation is enterprise-only because it
belongs to the project-management feature.

global_admin is a User flag, not a per-project role, so the core
mcp_permission decorator was extended to special-case it. Every other call
site stays unchanged.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: 2 people

testgen/mcp/permissions.py

@@ -138,17 +138,29 @@ def mcp_permission(permission: str) -> Callable:
     Raises ``MCPPermissionDenied`` if the user has no projects with the required
     permission. Other ``MCPPermissionDenied`` exceptions from tool code propagate
     through — the ``safe_tool`` error boundary handles conversion to text.
+
+    ``global_admin`` is a user-level flag, not a per-project role: the check
+    consults ``User.is_global_admin`` and the resulting ``ProjectPermissions``
+    has empty ``memberships``. Tools gated on ``global_admin`` operate above
+    project scope and should not call ``get_project_permissions()``.
     """
 
     def decorator(fn: Callable) -> Callable:
         @functools.wraps(fn)
         def wrapper(*args, **kwargs):
             user = get_authorized_mcp_user()
-            perms = _compute_project_permissions(user, permission)
-            if not perms.allowed_codes:
-                raise MCPPermissionDenied(
-                    "Your role does not include the necessary permission for this operation on any project."
-                )
+            if permission == "global_admin":
+                if not user.is_global_admin:
+                    raise MCPPermissionDenied(
+                        "Your role does not include the necessary permission for this operation."
+                    )
+                perms = ProjectPermissions(memberships={}, permission=permission, username=user.username)
+            else:
+                perms = _compute_project_permissions(user, permission)
+                if not perms.allowed_codes:
+                    raise MCPPermissionDenied(
+                        "Your role does not include the necessary permission for this operation on any project."
+                    )
             tok = _mcp_project_permissions.set(perms)
             try:
                 return fn(*args, **kwargs)

testgen/mcp/server.py

@@ -204,6 +204,7 @@ def build_mcp_server(
         list_profiling_summaries,
         search_columns,
     )
+    from testgen.mcp.tools.projects import update_project
     from testgen.mcp.tools.quality_scores import (
         create_scorecard,
         delete_scorecard,
@@ -263,6 +264,7 @@ def build_mcp_server(
         update_test_result,
     )
     from testgen.mcp.tools.test_runs import get_test_run, list_test_runs
+    from testgen.mcp.tools.test_suites import create_test_suite, update_test_suite
 
     if server_url is None:
         server_url = f"{api_base_url}/mcp"
@@ -375,6 +377,9 @@ def safe_prompt(fn):
     safe_tool(create_table_group)
     safe_tool(update_table_group)
     safe_tool(preview_table_group)
+    safe_tool(update_project)
+    safe_tool(create_test_suite)
+    safe_tool(update_test_suite)
     safe_tool(update_catalog_metadata)
 
     # Resources

testgen/mcp/tools/common.py

@@ -38,7 +38,7 @@
 from testgen.common.models.scheduler import SCHEDULABLE_JOB_KEYS, JobSchedule
 from testgen.common.models.scores import ScoreCategory, ScoreDefinition
 from testgen.common.models.table_group import TableGroup
-from testgen.common.models.test_definition import TestDefinition, TestDefinitionNote, TestType
+from testgen.common.models.test_definition import Severity, TestDefinition, TestDefinitionNote, TestType
 from testgen.common.models.test_result import TestResult, TestResultStatus
 from testgen.common.models.test_suite import TestSuite
 from testgen.mcp.exceptions import MCPResourceNotAccessible, MCPUserError
@@ -132,6 +132,15 @@ def parse_quality_dimension(value: str) -> QualityDimension:
         raise MCPUserError(f"Invalid quality_dimension `{value}`. Valid values: {valid}") from err
 
 
+def parse_severity(value: str) -> Severity:
+    """Validate a test-suite default severity. Accepts ``Fail`` or ``Warning``."""
+    try:
+        return Severity(value)
+    except ValueError as err:
+        valid = ", ".join(s.value for s in Severity)
+        raise MCPUserError(f"Invalid severity `{value}`. Valid values: {valid}") from err
+
+
 class ScoreGroupBy(StrEnum):
     """User-facing values accepted for the ``group_by`` argument on quality-score rollups."""
 

testgen/mcp/tools/projects.py

@@ -0,0 +1,262 @@
+"""MCP write tools for projects.
+
+Project creation and deletion live in the enterprise project-management plugin
+(gated on ``global_admin``); editing a project's own settings is a per-project
+``administer`` operation that ships in core. This module holds the latter.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from testgen.common.enums import JobKey, JobSource
+from testgen.common.models import with_database_session
+from testgen.common.models.job_execution import JobExecution
+from testgen.common.models.project import Project
+from testgen.common.models.scheduler import (
+    DEFAULT_DATA_CLEANUP_CRON,
+    DEFAULT_RETENTION_CRON_TZ,
+    JobSchedule,
+)
+from testgen.mcp.exceptions import MCPResourceNotAccessible, MCPUserError
+from testgen.mcp.permissions import get_project_permissions, mcp_permission
+from testgen.mcp.tools.common import DocGroup, raise_validation_error
+from testgen.mcp.tools.markdown import MdDoc
+
+_DOC_GROUP = DocGroup.MANAGE
+
+DEFAULT_RETENTION_DAYS = 180
+
+
+def _empty_to_none(value: str | None) -> str | None:
+    return value if value else None
+
+
+@with_database_session
+@mcp_permission("administer")
+def update_project(
+    project_code: str,
+    *,
+    project_name: str | None = None,
+    use_dq_score_weights: bool | None = None,
+    observability_api_url: str | None = None,
+    observability_api_key: str | None = None,
+    data_retention_enabled: bool | None = None,
+    data_retention_days: int | None = None,
+    retention_cron_expr: str | None = None,
+    retention_cron_tz: str | None = None,
+) -> str:
+    """Update a project's settings.
+
+    Args:
+        project_code: The project code, e.g. from `list_projects`.
+        project_name: New display name.
+        use_dq_score_weights: Whether quality scoring uses the configured weights.
+            Changing this re-runs project-wide score recalculation in the background.
+        observability_api_url: DataOps Observability API URL. Pass an empty string to clear.
+        observability_api_key: DataOps Observability API key. Pass an empty string to clear.
+            Never echoed back in tool output.
+        data_retention_enabled: Whether old profiling and test history is automatically deleted.
+        data_retention_days: How many days of history to keep (only when retention is enabled).
+            Defaults to 180 when retention is being enabled without specifying days.
+        retention_cron_expr: Cron expression for the retention cleanup job
+            (only when retention is enabled). Defaults to daily at 01:00.
+        retention_cron_tz: Timezone for the retention cleanup cron
+            (only when retention is enabled). Defaults to UTC.
+    """
+    supplied = {
+        "project_name": project_name,
+        "use_dq_score_weights": use_dq_score_weights,
+        "observability_api_url": observability_api_url,
+        "observability_api_key": observability_api_key,
+        "data_retention_enabled": data_retention_enabled,
+        "data_retention_days": data_retention_days,
+        "retention_cron_expr": retention_cron_expr,
+        "retention_cron_tz": retention_cron_tz,
+    }
+    if all(value is None for value in supplied.values()):
+        raise MCPUserError("No fields supplied to update.")
+
+    perms = get_project_permissions()
+    perms.verify_access(project_code, not_found=MCPResourceNotAccessible("Project", project_code))
+
+    project = Project.get(project_code)
+    if project is None:
+        raise MCPResourceNotAccessible("Project", project_code)
+
+    schedule = JobSchedule.get(
+        JobSchedule.project_code == project_code,
+        JobSchedule.key == JobKey.run_data_cleanup,
+    )
+
+    # Compute effective retention state from supplied args + current state. Errors below.
+    effective_enabled = (
+        data_retention_enabled if data_retention_enabled is not None else project.data_retention_enabled
+    )
+    effective_days = (
+        data_retention_days if data_retention_days is not None else project.data_retention_days
+    )
+    # When retention is being newly enabled without explicit days, fall back to the system default.
+    if effective_enabled and effective_days is None:
+        effective_days = DEFAULT_RETENTION_DAYS
+
+    # Validate field-by-field; surface all errors at once.
+    errors: list[str] = []
+    cleaned_name: str | None = None
+    if project_name is not None:
+        cleaned_name = project_name.strip()
+        if not cleaned_name:
+            errors.append("project_name: must not be empty.")
+
+    if data_retention_days is not None and data_retention_days < 1:
+        errors.append("data_retention_days: must be a positive integer.")
+
+    # Setting retention schedule args only makes sense when retention will be enabled.
+    if not effective_enabled:
+        if data_retention_days is not None:
+            errors.append("data_retention_days: cannot be set when data_retention_enabled is False.")
+        if retention_cron_expr is not None:
+            errors.append("retention_cron_expr: cannot be set when data_retention_enabled is False.")
+        if retention_cron_tz is not None:
+            errors.append("retention_cron_tz: cannot be set when data_retention_enabled is False.")
+
+    if errors:
+        raise_validation_error(errors, "Update rejected. No changes saved.")
+
+    weights_were = project.use_dq_score_weights
+
+    # Snapshot the editable surface (including schedule cron + tz, which live on JobSchedule).
+    before = _snapshot(project, schedule)
+
+    # Apply project changes.
+    if cleaned_name is not None:
+        project.project_name = cleaned_name
+    if use_dq_score_weights is not None:
+        project.use_dq_score_weights = use_dq_score_weights
+    if observability_api_url is not None:
+        project.observability_api_url = _empty_to_none(observability_api_url)
+    if observability_api_key is not None:
+        project.observability_api_key = _empty_to_none(observability_api_key)
+    project.data_retention_enabled = effective_enabled
+    project.data_retention_days = effective_days if effective_enabled else None
+
+    # Compute the effective cron values now so the snapshot reflects what the schedule will be.
+    schedule_supplied = any(
+        v is not None
+        for v in (data_retention_enabled, data_retention_days, retention_cron_expr, retention_cron_tz)
+    )
+    effective_cron_expr: str | None
+    effective_cron_tz: str | None
+    if effective_enabled:
+        effective_cron_expr = (
+            retention_cron_expr or (schedule.cron_expr if schedule else None) or DEFAULT_DATA_CLEANUP_CRON
+        )
+        effective_cron_tz = (
+            retention_cron_tz or (schedule.cron_tz if schedule else None) or DEFAULT_RETENTION_CRON_TZ
+        )
+    else:
+        effective_cron_expr = None
+        effective_cron_tz = None
+
+    after = _snapshot(
+        project,
+        _ScheduleSnapshot(cron_expr=effective_cron_expr, cron_tz=effective_cron_tz)
+        if effective_enabled
+        else None,
+    )
+    changed = {attr for attr in before if before[attr] != after[attr]}
+
+    doc = MdDoc()
+    doc.heading(1, f"Project `{project_code}` updated")
+
+    if not changed:
+        doc.text("No fields changed — supplied values matched the current state.")
+        return doc.render()
+
+    project.save()
+
+    # Schedule side effects: only touch JobSchedule when a retention-related arg was supplied.
+    if schedule_supplied:
+        if effective_enabled:
+            JobSchedule.upsert_for_retention(
+                project_code=project_code,
+                retention_days=effective_days,  # type: ignore[arg-type]
+                cron_expr=effective_cron_expr,  # type: ignore[arg-type]
+                cron_tz=effective_cron_tz,  # type: ignore[arg-type]
+            )
+        else:
+            JobSchedule.delete_for_retention(project_code)
+
+    # Weights side effect: submit a background recalculation job, same as the UI.
+    if use_dq_score_weights is not None and use_dq_score_weights != weights_were:
+        JobExecution.submit(
+            job_key=JobKey.recalculate_project_scores,
+            kwargs={"project_code": project_code},
+            source=JobSource.mcp,
+            project_code=project_code,
+        )
+
+    rows: list[list[object]] = []
+    for attr in _DIFF_ORDER:
+        if attr not in changed:
+            continue
+        rows.append([_DIFF_LABELS[attr], _render_field_value(attr, before[attr]), _render_field_value(attr, after[attr])])
+    doc.table(["Field", "Before", "After"], rows, code=[0])
+    return doc.render()
+
+
+class _ScheduleSnapshot:
+    """Stand-in for a JobSchedule row, used while computing the post-update snapshot
+    before any DB write has happened."""
+
+    def __init__(self, cron_expr: str | None, cron_tz: str | None) -> None:
+        self.cron_expr = cron_expr
+        self.cron_tz = cron_tz
+
+
+def _snapshot(project: Project, schedule: Any) -> dict[str, Any]:
+    return {
+        "project_name": project.project_name,
+        "use_dq_score_weights": project.use_dq_score_weights,
+        "observability_api_url": project.observability_api_url,
+        "observability_api_key": project.observability_api_key,
+        "data_retention_enabled": project.data_retention_enabled,
+        "data_retention_days": project.data_retention_days,
+        "retention_cron_expr": schedule.cron_expr if schedule is not None else None,
+        "retention_cron_tz": schedule.cron_tz if schedule is not None else None,
+    }
+
+
+_DIFF_ORDER: tuple[str, ...] = (
+    "project_name",
+    "use_dq_score_weights",
+    "observability_api_url",
+    "observability_api_key",
+    "data_retention_enabled",
+    "data_retention_days",
+    "retention_cron_expr",
+    "retention_cron_tz",
+)
+
+_DIFF_LABELS: dict[str, str] = {
+    "project_name": "Name",
+    "use_dq_score_weights": "Weighted quality scoring",
+    "observability_api_url": "DataOps Observability API URL",
+    "observability_api_key": "DataOps Observability API key",
+    "data_retention_enabled": "Data retention",
+    "data_retention_days": "Retention days",
+    "retention_cron_expr": "Retention cron expression",
+    "retention_cron_tz": "Retention timezone",
+}
+
+
+def _render_field_value(attr: str, value: Any) -> str | None:
+    # Redact the API key — mcp-patterns "Secrets in inputs" rule. The diff still tells the LLM
+    # the field changed; it just never echoes the value (cleartext OR masked).
+    if attr == "observability_api_key" and value:
+        return "[secret]"
+    if isinstance(value, bool):
+        return "Yes" if value else "No"
+    if value is None or value == "":
+        return None
+    return str(value)