Merge remote-tracking branch 'origin/enterprise' into feat/TG-1029-mcp-hygiene-issues

Author: rboni-dk

deploy/build_mcp_docs.py

@@ -0,0 +1,151 @@
+"""Export the TestGen MCP server as a Markdown reference page.
+
+Usage:
+    python deploy/build_mcp_docs.py [--output PATH]
+
+Introspects the FastMCP instance built by ``build_mcp_server()`` and emits
+a single Markdown page listing prompts, tools, and resources. Tools are
+grouped by the ``_DOC_GROUP`` constant defined on each tool module — when
+adding a new tool module, declare ``_DOC_GROUP = "..."`` so the new tools
+land under the right heading automatically.
+"""
+
+import argparse
+import re
+import sys
+import textwrap
+from pathlib import Path
+from typing import Any
+
+from testgen.mcp.server import build_mcp_server
+from testgen.mcp.tools.common import DocGroup
+
+_DEFAULT_OUTPUT = Path("docs/mcp/supported-tools.md")
+_ARGS_HEADER_RE = re.compile(r"^\s*Args:\s*$", re.MULTILINE)
+
+# Order in which tool groups appear on the page. Each entry is a ``DocGroup``
+# member; tools whose module declares a ``_DOC_GROUP`` not in this list are
+# appended after these in the order they are first seen.
+_GROUP_ORDER: list[DocGroup] = [
+    DocGroup.DISCOVER,
+    DocGroup.INVESTIGATE,
+    DocGroup.BROWSE_PROFILING,
+    DocGroup.TRIGGER,
+]
+_FALLBACK_GROUP = "Other tools"
+
+
+def _short_description(docstring: str) -> str:
+    """Return the first prose paragraph of a docstring, stripped of Args/Returns sections."""
+    if not docstring:
+        return ""
+    text = textwrap.dedent(docstring).strip()
+    match = _ARGS_HEADER_RE.search(text)
+    if match:
+        text = text[: match.start()].rstrip()
+    first_paragraph = text.split("\n\n", 1)[0]
+    return " ".join(line.strip() for line in first_paragraph.splitlines())
+
+
+def _entry_name(item: Any) -> str:
+    """Display name for a tool, resource, or prompt."""
+    return str(getattr(item, "uri", None) or item.name)
+
+
+def _render_entry(item: Any) -> str:
+    description = _short_description(item.description or "")
+    return f"- **`{_entry_name(item)}`** — {description}"
+
+
+def _group_for_tool(tool: Any) -> str:
+    """Resolve a tool's display group via its module's ``_DOC_GROUP`` constant."""
+    module = sys.modules.get(tool.fn.__module__)
+    group = getattr(module, "_DOC_GROUP", None)
+    return str(group) if group is not None else _FALLBACK_GROUP
+
+
+def _group_tools(tools: list[Any]) -> list[tuple[str, list[Any]]]:
+    """Bucket tools by their module's ``_DOC_GROUP``, ordered by ``_GROUP_ORDER``."""
+    buckets: dict[str, list[Any]] = {}
+    for tool in tools:
+        buckets.setdefault(_group_for_tool(tool), []).append(tool)
+
+    ordered: list[tuple[str, list[Any]]] = []
+    for group in _GROUP_ORDER:
+        title = str(group)
+        if title in buckets:
+            ordered.append((title, sorted(buckets.pop(title), key=lambda t: t.name)))
+    for title, bucket in buckets.items():
+        ordered.append((title, sorted(bucket, key=lambda t: t.name)))
+    return ordered
+
+
+def _build_markdown(mcp: Any) -> str:
+    tools = mcp._tool_manager.list_tools()
+    resources = sorted(mcp._resource_manager.list_resources(), key=lambda r: str(r.uri))
+    prompts = sorted(mcp._prompt_manager.list_prompts(), key=lambda p: p.name)
+    grouped_tools = _group_tools(list(tools))
+
+    parts: list[str] = [
+        "# Supported Tools",
+        "",
+        "The TestGen MCP server exposes the prompts, tools, and resources listed below.",
+        "",
+        "For setup instructions, see [Set up the MCP Server](setup.md).",
+        "For example questions to ask an assistant, see [MCP Server](index.md#what-you-can-ask).",
+        "",
+        "## Prompts",
+        "",
+        (
+            "Prompts are pre-built workflows you can invoke directly through your AI client — typically "
+            "as a slash command (for example, `/testgen:table_health` in Claude Code) or "
+            "from a quick-action menu. They orchestrate several tool calls behind the scenes for common "
+            "investigations. Exact UX varies by client."
+        ),
+        "",
+    ]
+    parts.extend(_render_entry(prompt) for prompt in prompts)
+    parts.append("")
+
+    parts.extend(["## Tools", "", "Tools are operations the assistant calls during a conversation, picked based on what you ask.", ""])
+    for heading, bucket in grouped_tools:
+        parts.append(f"### {heading}")
+        parts.append("")
+        parts.extend(_render_entry(tool) for tool in bucket)
+        parts.append("")
+
+    parts.extend(
+        [
+            "## Resources",
+            "",
+            "Resources are static reference documents that AI clients can fetch by URI.",
+            "",
+        ]
+    )
+    parts.extend(_render_entry(resource) for resource in resources)
+
+    return "\n".join(parts).rstrip() + "\n"
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Export the TestGen MCP server as a Markdown reference.")
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=_DEFAULT_OUTPUT,
+        help=f"Output Markdown file path (default: {_DEFAULT_OUTPUT}, relative to cwd)",
+    )
+    args = parser.parse_args()
+
+    mcp = build_mcp_server(api_base_url="https://testgen.example.com")
+    markdown = _build_markdown(mcp)
+
+    output: Path = args.output
+    output.parent.mkdir(parents=True, exist_ok=True)
+    frontmatter = "---\nsearch:\n  boost: 0.5\n---\n"
+    output.write_text(frontmatter + markdown, encoding="utf-8")
+    print(f"Exported MCP supported tools -> {output}")
+
+
+if __name__ == "__main__":
+    main()

invocations/dev.py

@@ -1,4 +1,4 @@
-__all__ = ["build_api_docs", "build_public_image", "clean", "install", "lint"]
+__all__ = ["build_api_docs", "build_mcp_docs", "build_public_image", "clean", "install", "lint"]
 
 import re
 from os.path import exists, join
@@ -83,6 +83,15 @@ def build_api_docs(ctx: Context, version: str = "", output: str = "") -> None:
     ctx.run(f"python deploy/build_api_docs.py {' '.join(args)}")
 
 
+@task(name="build-mcp-docs", pre=(install,))
+def build_mcp_docs(ctx: Context, output: str = "") -> None:
+    """Exports the MCP supported-tools page from the FastMCP server."""
+    args = []
+    if output:
+        args.append(f"--output {output}")
+    ctx.run(f"python deploy/build_mcp_docs.py {' '.join(args)}")
+
+
 @task(
     pre=(required_tools, prep_dk_builer),
     iterable=["label"],

pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dataops-testgen"
-version = "5.9.5"
+version = "5.32.2"
 description = "DataKitchen's Data Quality DataOps TestGen"
 authors = [
     { "name" = "DataKitchen, Inc.", "email" = "info@datakitchen.io" },

testgen/__main__.py

@@ -1,7 +1,45 @@
+# Silence streamlit's "missing ScriptRunContext" / "No runtime found" /
+# "Session state does not function" warnings, which fire whenever streamlit-
+# decorated code runs outside an active script run (our CLI, scheduler, server,
+# and any import that touches @st.cache_data). Must run before the first
+# streamlit-using import, so it sits at the top of the module.
+#
+# We replace ``set_log_level`` itself, after seeding it to "error". Streamlit's
+# own ``_update_logger`` callback fires on config parse and would otherwise
+# downgrade us back to "info"; the cap floors any later call at ERROR.
+def _silence_streamlit_logs() -> None:
+    import logging as _logging
+
+    try:
+        from streamlit import logger as _st_logger
+    except ImportError:
+        return
+
+    _original = _st_logger.set_log_level
+    _original("error")
+
+    def _capped(level):
+        if isinstance(level, str):
+            try:
+                level_num = getattr(_logging, level.upper())
+            except AttributeError:
+                _original(level)
+                return
+        else:
+            level_num = level
+        _original(max(level_num, _logging.ERROR))
+
+    _st_logger.set_log_level = _capped
+
+
+_silence_streamlit_logs()
+
+
 import base64
 import importlib
 import logging
 import os
+import pathlib
 import platform
 import secrets
 import signal
@@ -77,6 +115,16 @@
 VERSION_DATA = version_service.get_version()
 CHILDREN_POLL_INTERVAL = 10
 
+
+def _forward_signal_to_child(child: subprocess.Popen, signum: int) -> None:
+    # On POSIX, forward the signal verbatim. On Windows, subprocess.send_signal
+    # rejects everything except SIGTERM / CTRL_C_EVENT / CTRL_BREAK_EVENT, so
+    # fall back to terminate() — equivalent to TerminateProcess().
+    if sys.platform == "win32":
+        child.terminate()
+    else:
+        child.send_signal(signum)
+
 @dataclass
 class Configuration:
     verbose: bool = field(default=False)
@@ -94,6 +142,7 @@ def invoke(self, ctx: Context):
             raise
         except Exception:
             LOG.exception("There was an unexpected error")
+            sys.exit(1)
 
     def format_epilog(self, _ctx: Context, formatter: click.HelpFormatter) -> None:
         # Schema revision is a DB round-trip; defer until `--help` is actually
@@ -551,9 +600,24 @@ def generate_secret(length: int = 12) -> str:
         "TG_TARGET_DB_TRUST_SERVER_CERTIFICATE=yes",
         "TG_EXPORT_TO_OBSERVABILITY_VERIFY_SSL=no",
     ]
+
+    # Persist caller-supplied runtime overrides (ports, TLS) so they apply to
+    # subsequent `testgen run-app` invocations.
+    persisted_env_vars = ("TG_UI_PORT", "TG_API_PORT", "TESTGEN_LOG_FILE_PATH", "SSL_CERT_FILE", "SSL_KEY_FILE")
+    persisted_lines = [f"{name}={os.environ[name]}" for name in persisted_env_vars if os.environ.get(name)]
+    if persisted_lines:
+        config_lines.extend(["", "# Runtime overrides from installer", *persisted_lines])
+
     config_path.write_text("\n".join(config_lines) + "\n")
     click.echo(f"Config written to {config_path}")
 
+    # `getenv` resolves env vars before config.env, so a pre-existing
+    # TESTGEN_USERNAME / TESTGEN_PASSWORD in the shell would override the
+    # CLI-supplied values and get seeded into the DB. Force the CLI args
+    # to win for the rest of this process.
+    os.environ["TESTGEN_USERNAME"] = username
+    os.environ["TESTGEN_PASSWORD"] = password
+
     # Reload settings — the module was already evaluated at import time
     # before the config file existed.  Reloading re-reads the new file
     # and re-evaluates all module-level variables.
@@ -564,6 +628,14 @@ def generate_secret(length: int = 12) -> str:
     from testgen.ui.scripts.patch_streamlit import patch as patch_streamlit
     patch_streamlit(dev=True)
 
+    # Seed Streamlit's first-run credentials file so `run-app` doesn't block
+    # on the interactive email prompt. We don't care about the value — just
+    # that the file exists so Streamlit skips the prompt.
+    streamlit_creds = pathlib.Path.home() / ".streamlit" / "credentials.toml"
+    if not streamlit_creds.exists():
+        streamlit_creds.parent.mkdir(parents=True, exist_ok=True)
+        streamlit_creds.write_text('[general]\nemail = ""\n')
+
     # Start embedded PostgreSQL (standalone mode is now active via config)
     start_standalone_postgres()
 
@@ -860,14 +932,18 @@ def init_ui():
             child_env = {**os.environ, "TG_JOB_SOURCE": "UI", STANDALONE_URI_ENV_VAR: server_uri}
 
     process= subprocess.Popen(
-        [  # noqa: S607
+        [
+            sys.executable,
+            "-m",
             "streamlit",
             "run",
             app_file,
             "--browser.gatherUsageStats=false",
+            f"--logger.level={'debug' if settings.IS_DEBUG else 'error'}",
             "--client.showErrorDetails=none",
             "--client.toolbarMode=minimal",
             "--server.enableStaticServing=true",
+            f"--server.port={settings.UI_PORT}",
             f"--server.sslCertFile={settings.SSL_CERT_FILE}" if use_ssl else "",
             f"--server.sslKeyFile={settings.SSL_KEY_FILE}" if use_ssl else "",
             "--",
@@ -877,7 +953,7 @@ def init_ui():
     )
     def term_ui(signum, _):
         LOG.info(f"Sending termination signal {signum} to Testgen UI")
-        process.send_signal(signum)
+        _forward_signal_to_child(process, signum)
     signal.signal(signal.SIGINT, term_ui)
     signal.signal(signal.SIGTERM, term_ui)
     status_code = process.wait()
@@ -905,13 +981,13 @@ def run_app(module):
 
         case "all":
             children = [
-                subprocess.Popen([sys.executable, sys.argv[0], "run-app", m], start_new_session=True)
+                subprocess.Popen([sys.executable, "-m", "testgen", "run-app", m], start_new_session=True)
                 for m in APP_MODULES
             ]
 
             def term_children(signum, _):
                 for child in children:
-                    child.send_signal(signum)
+                    _forward_signal_to_child(child, signum)
 
             signal.signal(signal.SIGINT, term_children)
             signal.signal(signal.SIGTERM, term_children)

testgen/api/oauth/metadata.py

@@ -1,4 +1,4 @@
-"""RFC 8414 — OAuth 2.0 Authorization Server Metadata."""
+"""RFC 8414 — OAuth 2.1 Authorization Server Metadata."""
 
 from fastapi import APIRouter
 from fastapi.responses import JSONResponse
@@ -10,7 +10,7 @@
 
 @router.get("/.well-known/oauth-authorization-server")
 def authorization_server_metadata():
-    """Return OAuth 2.0 Authorization Server Metadata per RFC 8414.
+    """Return OAuth 2.1 Authorization Server Metadata per RFC 8414.
 
     MCP clients use this for server discovery.
     """

testgen/commands/run_launch_db_config.py

@@ -9,7 +9,7 @@
 from testgen.common.models import with_database_session
 from testgen.common.read_file import get_template_files
 from testgen.common.read_yaml_metadata_records import import_metadata_records_from_yaml
-from testgen.common.standalone_postgres import get_home_dir, is_standalone_mode
+from testgen.common.standalone_postgres import get_target_host_port, is_standalone_mode
 
 LOG = logging.getLogger("testgen")
 
@@ -24,10 +24,13 @@ def _get_params_mapping() -> dict:
     ui_user_encrypted_password = encrypt_ui_password(settings.PASSWORD)
 
     project_host = settings.PROJECT_DATABASE_HOST
+    project_port = settings.PROJECT_DATABASE_PORT
     project_user = settings.PROJECT_DATABASE_USER
     project_password = settings.PROJECT_DATABASE_PASSWORD
     if is_standalone_mode():
-        project_host = str(get_home_dir() / "pgdata")
+        project_host, server_port = get_target_host_port()
+        if server_port:
+            project_port = server_port
         project_user = "postgres"
         project_password = ""
 
@@ -43,7 +46,7 @@ def _get_params_mapping() -> dict:
         "PROJECT_NAME": settings.PROJECT_NAME,
         "PROJECT_DB": settings.PROJECT_DATABASE_NAME,
         "PROJECT_USER": project_user,
-        "PROJECT_PORT": settings.PROJECT_DATABASE_PORT,
+        "PROJECT_PORT": project_port,
         "PROJECT_HOST": project_host,
         "PROJECT_PW_ENCRYPTED": EncryptText(project_password),
         "PROJECT_HTTP_PATH": "",