detectkit 0.60.0__tar.gz → 0.62.0__tar.gz

{detectkit-0.60.0/detectkit.egg-info → detectkit-0.62.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectkit
-Version: 0.60.0
+Version: 0.62.0
 Summary: Metric monitoring with automatic anomaly detection
 Author: detectkit team
 License: MIT
@@ -54,6 +54,8 @@ Requires-Dist: prophet>=1.1.0; extra == "advanced-detectors"
 Requires-Dist: timesfm>=0.1.0; extra == "advanced-detectors"
 Provides-Extra: osi
 Requires-Dist: sqlglot>=20.0; extra == "osi"
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.27; extra == "mcp"
 Provides-Extra: all
 Requires-Dist: clickhouse-driver>=0.2.0; extra == "all"
 Requires-Dist: psycopg2-binary>=2.9.0; extra == "all"
@@ -62,6 +64,7 @@ Requires-Dist: duckdb>=1.1; extra == "all"
 Requires-Dist: prophet>=1.1.0; extra == "all"
 Requires-Dist: timesfm>=0.1.0; extra == "all"
 Requires-Dist: sqlglot>=20.0; extra == "all"
+Requires-Dist: mcp<2,>=1.27; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
@@ -104,6 +107,7 @@ Dynamic: license-file
 - **Alert lifecycle** — consecutive anomalies, fraction-of-window rule (`anomaly_window` + `min_anomaly_share`), cooldown, recovery notifications, no-data alerts
 - **Project-level error alerts** — catch DB outages and pipeline crashes once per run
 - **Database agnostic** — ClickHouse, PostgreSQL, MySQL/MariaDB, DuckDB (no server needed)
+- **Hybrid mode** — read metric SQL from a billed-per-query warehouse while all pipeline state lives in a cheap local database
 - **Idempotent** — resume from interruptions, no duplicate processing
 - **CLI** — `dtk init`, `dtk run --select`, `dtk unlock`, `dtk clean`, tag-based selectors
 - **AI-native onboarding** — `dtk init-claude` sets up Claude Code context (CLAUDE.md + rules + three skills) so an assistant can scaffold metrics, configure databases, and file feedback upstream
@@ -198,6 +202,18 @@ for r in results:
         print(f"Anomaly at {r.timestamp}: {r.value}")
 ```
 
+## AI & automation
+
+- **[MCP server](docs/guides/mcp.md)** (`dtk mcp`) — a read-only [Model Context
+  Protocol](https://modelcontextprotocol.io) server so an AI assistant (Claude
+  Code, Claude Desktop, any MCP client) can query a project's metric configs,
+  loaded data, detector results, replayed alert history and autotune runs
+  directly — no write access to the pipeline.
+- **[GitHub Action](docs/guides/github-action.md)** — a composite action that
+  runs `dtk run`/`autotune`/`clean` as a CI check or scheduled job and gates
+  on detectkit's own exit-code contract, with the `--json` run summary wired
+  to step outputs.
+
 ## Documentation
 
 - **[dtk.pipelab.dev](https://dtk.pipelab.dev)** — full docs site, guides, reference, and a live in-browser playground
@@ -206,6 +222,8 @@ for r in results:
 - [Detectors Guide](docs/guides/detectors.md) — choosing the right detector
 - [Alerting Guide](docs/guides/alerting.md) — channels, mentions, cooldown, recovery
 - [Reading Alerts](docs/guides/reading-alerts.md) — what a received alert means (for stakeholders)
+- [MCP Guide](docs/guides/mcp.md) — read-only AI-assistant access with `dtk mcp`
+- [GitHub Action Guide](docs/guides/github-action.md) — run the pipeline in CI
 - [CLI Reference](docs/reference/cli.md) — command-line documentation
 - [Examples](docs/examples/) — real-world monitoring scenarios
 - [Changelog](CHANGELOG.md) — version history

{detectkit-0.60.0 → detectkit-0.62.0}/README.md

@@ -25,6 +25,7 @@
 - **Alert lifecycle** — consecutive anomalies, fraction-of-window rule (`anomaly_window` + `min_anomaly_share`), cooldown, recovery notifications, no-data alerts
 - **Project-level error alerts** — catch DB outages and pipeline crashes once per run
 - **Database agnostic** — ClickHouse, PostgreSQL, MySQL/MariaDB, DuckDB (no server needed)
+- **Hybrid mode** — read metric SQL from a billed-per-query warehouse while all pipeline state lives in a cheap local database
 - **Idempotent** — resume from interruptions, no duplicate processing
 - **CLI** — `dtk init`, `dtk run --select`, `dtk unlock`, `dtk clean`, tag-based selectors
 - **AI-native onboarding** — `dtk init-claude` sets up Claude Code context (CLAUDE.md + rules + three skills) so an assistant can scaffold metrics, configure databases, and file feedback upstream
@@ -119,6 +120,18 @@ for r in results:
         print(f"Anomaly at {r.timestamp}: {r.value}")
 ```
 
+## AI & automation
+
+- **[MCP server](docs/guides/mcp.md)** (`dtk mcp`) — a read-only [Model Context
+  Protocol](https://modelcontextprotocol.io) server so an AI assistant (Claude
+  Code, Claude Desktop, any MCP client) can query a project's metric configs,
+  loaded data, detector results, replayed alert history and autotune runs
+  directly — no write access to the pipeline.
+- **[GitHub Action](docs/guides/github-action.md)** — a composite action that
+  runs `dtk run`/`autotune`/`clean` as a CI check or scheduled job and gates
+  on detectkit's own exit-code contract, with the `--json` run summary wired
+  to step outputs.
+
 ## Documentation
 
 - **[dtk.pipelab.dev](https://dtk.pipelab.dev)** — full docs site, guides, reference, and a live in-browser playground
@@ -127,6 +140,8 @@ for r in results:
 - [Detectors Guide](docs/guides/detectors.md) — choosing the right detector
 - [Alerting Guide](docs/guides/alerting.md) — channels, mentions, cooldown, recovery
 - [Reading Alerts](docs/guides/reading-alerts.md) — what a received alert means (for stakeholders)
+- [MCP Guide](docs/guides/mcp.md) — read-only AI-assistant access with `dtk mcp`
+- [GitHub Action Guide](docs/guides/github-action.md) — run the pipeline in CI
 - [CLI Reference](docs/reference/cli.md) — command-line documentation
 - [Examples](docs/examples/) — real-world monitoring scenarios
 - [Changelog](CHANGELOG.md) — version history

{detectkit-0.60.0 → detectkit-0.62.0}/detectkit/__init__.py

@@ -4,7 +4,7 @@ detectk - Anomaly Detection for Time-Series Metrics
 A Python library for data analysts and engineers to monitor metrics with automatic anomaly detection.
 """
 
-__version__ = "0.60.0"
+__version__ = "0.62.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.60.0 → detectkit-0.62.0}/detectkit/cli/assets/claude/rules/cli.md

@@ -18,6 +18,7 @@ Run all commands from a project directory (the one containing
 | `dtk clean --select <sel>` | Prune internal data that no longer matches the config |
 | `dtk osi import <model>` | Scaffold a native metric from an OSI semantic-model metric (see "OSI interop") |
 | `dtk osi export` | Publish metrics into an OSI fragment (config in `custom_extensions[detectkit]`) |
+| `dtk mcp` | Serve a **read-only** MCP server for an AI assistant (metrics, data, alerts, autotune history — no writes) |
 | `dtk --version` | Show installed detectkit version |
 
 ## Selectors (`--select` / `-s`)
@@ -376,6 +377,40 @@ The `dtk ui` metric Builder's **From OSI** sub-tab does the import
 interactively (paste a model, pick a metric/target, Compile) through the
 same code path — see "Managing metrics from the UI" above.
 
+## `dtk mcp`
+
+A **read-only** [Model Context Protocol](https://modelcontextprotocol.io)
+server, exposing a project to *another* AI assistant (an MCP client — Claude
+Code, Claude Desktop, an IDE extension) rather than being one itself. It is a
+separate, additive command (needs `pip install 'detectkit[mcp]'`) that
+contains **zero write paths**: no config edits, no label writes, no pipeline
+runs, no schema creation. Ten tools: `list_metrics`, `get_metric`,
+`get_metric_status`, `get_project_status`, `query_datapoints`,
+`query_detections`, `replay_alerts` (reconstructs the alert timeline the same
+way `dtk run --report` does — never reads `_dtk_alert_states`, never
+dispatches), `get_autotune_history`, `get_incidents`, `get_server_info`.
+Channel connection details/secrets in `profiles.yml` are never exposed —
+`get_metric` lists alerting channels by name only.
+
+```bash
+dtk mcp --project-dir /abs/path/to/project [--select <sel>] [--profile NAME]
+```
+
+- `--project-dir` — resolved before `$DETECTKIT_PROJECT_DIR` before the
+  current directory (an MCP client passes no cwd, so at least one must
+  resolve; each mechanism searches upward for `detectkit_project.yml`).
+- `--select` — scopes the whole session: every tool that names a metric
+  refuses one outside this set (an access-control boundary, not just a
+  default).
+
+This is a **different thing** from the generic database MCP CLAUDE.md
+recommends you (the assistant working in this repo) optionally connect to for
+your own read access to the project's DB — `dtk mcp` answers in detectkit's
+own terms (replayed alert decisions, detector identity, labeled incidents),
+not raw SQL, and it's for exposing *this* project to a *separate* assistant
+session/client (e.g. Claude Desktop), not something you need to launch or
+connect to yourself. `dtk mcp --help` has the full flag reference.
+
 ## Common workflows
 
 ```bash

{detectkit-0.60.0 → detectkit-0.62.0}/detectkit/cli/assets/claude/rules/metrics.md

@@ -11,6 +11,7 @@ keep them in sync. Detectors are covered in `detectors.md`, alerting in
 name: api_response_time        # required, unique across the project
 description: API p95 latency   # optional, shown in alerts
 profile: prod                  # optional, overrides project default_profile
+source_profile: warehouse      # optional — hybrid mode: source-DB profile for THIS metric's SQL (see below)
 enabled: true                  # optional, false → skipped by `dtk run`
 tags: [critical, api]          # optional, used by `--select tag:<t>`
 ai_context:                    # optional — OSI-compatible grounding (descriptive only)
@@ -67,6 +68,19 @@ false_alert_budget: 0.3        # optional — `dtk tune` target false-alert rate
 project-wide default; unset → project, then a built-in `0.5`. Tuning-only — it never
 affects the load/detect/alert pipeline.
 
+`source_profile` is **hybrid mode** for this one metric: the `profiles.yml`
+profile whose database runs *this metric's* SQL query, while `_dtk_*` state
+(datapoints, detections, task locks, alert state) stays in the active
+**state** profile — the one `dtk run` is already connected to for everything
+else. Overrides the project-wide `source_profile` (`project.md`); resolves
+**metric → project → unset** (unset on both = today's behavior — one profile
+for everything). Not the same field as `profile` above (`profile` is dead —
+not applied at runtime by `dtk run`; `source_profile` is live). Only the
+metric's **load** step ever connects to it — detect/alert and every other
+command don't — though every `dtk run` fail-fast validates the resolved name
+up front regardless of `--steps` (a typo exits 1 before any pipeline work).
+See the [Hybrid Mode guide](https://dtk.pipelab.dev/guides/hybrid-mode/).
+
 `ai_context` is **OSI-compatible grounding** you can add to any metric with **no
 OSI model needed** — the metric's business meaning (`instructions`), alternative
 names (`synonyms`) and example values (`examples`), mirroring the

{detectkit-0.60.0 → detectkit-0.62.0}/detectkit/cli/assets/claude/rules/project.md

@@ -33,6 +33,7 @@ timeouts:                      # per-step, seconds
 alert_help_url: null           # optional, see below — "How to read this alert" link
 false_alert_budget: null       # optional — `dtk tune` target FDR (0,1]; per-metric override wins
 loading_delay: null            # optional — default data-maturity delay; per-metric override wins
+source_profile: null           # optional — hybrid mode: default source-DB profile; per-metric override wins
 
 error_alerting:                # optional, see below
   enabled: false
@@ -50,6 +51,26 @@ overrides it (`0` opts that metric out); see `metrics.md` for the full
 load/no-data behavior and the detection-latency trade-off. Only set this
 project-wide when your metrics genuinely share the same upstream schedule.
 
+`source_profile` is **hybrid mode**: a project-wide default `profiles.yml`
+profile whose database runs metric SQL, while *every* `_dtk_*` table
+(datapoints, detections, task locks, alert state) stays in the active
+**state** profile — the one `dtk run` is already connected to for everything
+else. A per-metric `source_profile` overrides it (`metrics.md`); resolves
+**metric → project → unset**, same precedence as `loading_delay`. Unset on
+both = today's behavior (one profile does everything). Only the LOAD step's
+metric-SQL query is affected — detect/alert and every other command
+(`dtk autotune`/`tune`/`ui`/`clean`/`unlock`) only ever touch the state
+profile. A source-side failure raises `SourceDatabaseError` (message leads
+with `source database (profile '<name>'): ...`), distinct from a plain
+exception for a state-side failure — useful for telling a warehouse outage
+apart from a state-DB outage in `error_alerting`'s `{error_type}` /
+`{error_message}`. `dtk run` validates every resolved `source_profile` name
+against `profiles.yml` before opening any connection (unknown name → exit
+`1`, no partial run). Full config example + operational caveats (connecting a
+profile always runs `CREATE DATABASE`/`SCHEMA IF NOT EXISTS` for its own
+`internal_*` location too, even a source-only one) in the [Hybrid Mode
+guide](https://dtk.pipelab.dev/guides/hybrid-mode/).
+
 ### `alert_help_url` — "How to read this alert" link
 
 Every default-rendered alert on every channel carries a `How to read this alert`

detectkit-0.62.0/detectkit/cli/commands/mcp.py

@@ -0,0 +1,31 @@
+"""Implementation of 'dtk mcp' — the read-only Model Context Protocol server.
+
+Isolated from the load/detect/alert pipeline: this module imports only
+``click`` at load time. Everything else — :mod:`detectkit.mcp.server` and the
+optional ``mcp`` SDK it lazily guards — is imported inside :func:`run_mcp`'s
+body, so `import detectkit.cli.commands.mcp` never pulls in the SDK either.
+"""
+
+from __future__ import annotations
+
+import click
+
+
+def run_mcp(*, project_dir: str | None, select: str, profile: str | None) -> None:
+    """Resolve the project and serve the read-only MCP server over stdio.
+
+    Args:
+        project_dir: Explicit project directory (searched upward for
+            ``detectkit_project.yml``). Falls back to ``$DETECTKIT_PROJECT_DIR``,
+            then to searching upward from the current directory.
+        select: Selector scoping which metrics the server exposes.
+        profile: Profile name to use (defaults to the project's
+            ``default_profile``).
+    """
+    from detectkit.mcp.errors import McpError
+    from detectkit.mcp.server import run_server
+
+    try:
+        run_server(project_dir=project_dir, selector=select, profile=profile)
+    except McpError as exc:
+        raise click.ClickException(str(exc)) from exc

{detectkit-0.60.0 → detectkit-0.62.0}/detectkit/cli/commands/run.py

@@ -13,7 +13,7 @@ from typing import Any
 
 import click
 
-from detectkit.config.metric_config import MetricConfig
+from detectkit.config.metric_config import MetricConfig, resolve_source_profile
 from detectkit.config.profile import ProfilesConfig
 from detectkit.config.project_config import ProjectConfig
 from detectkit.config.validator import (
@@ -326,6 +326,21 @@ def _run_impl(
         summary["error"] = f"Error loading profiles.yml: {e}"
         return 1
 
+    # Fail-fast: every selected metric's RESOLVED source_profile (hybrid
+    # mode) must name a real profile. This is a cheap name check — no
+    # connections opened — so a typo'd source_profile fails the whole run
+    # up front instead of surfacing deep inside whichever metric's LOAD step
+    # happens to hit it first.
+    source_profile_error = _validate_source_profiles(metrics, project_config, profiles_config)
+    if source_profile_error:
+        # A config typo, not an outage: exit 1 without paging error_alerting,
+        # consistent with the sibling config-error paths (bad selector,
+        # unparseable profiles.yml). The error alert channel is reserved for
+        # DB-down / DDL / runtime failures.
+        click.echo(click.style(f"Error: {source_profile_error}", fg="red", bold=True))
+        summary["error"] = f"Error: {source_profile_error}"
+        return 1
+
     # Create database manager
     try:
         db_manager = profiles_config.create_manager(profile)
@@ -372,84 +387,136 @@ def _run_impl(
         summary["error"] = f"Error initializing internal tables: {e}"
         return 1
 
+    # The active STATE profile's actual name (mirrors ProfilesConfig.get_profile's
+    # own None -> default_profile resolution) — lets the task manager recognize
+    # a metric's source_profile that happens to name the state profile itself,
+    # and reuse db_manager instead of opening a duplicate connection.
+    state_profile_name: str | None
+    if profile is not None:
+        state_profile_name = profile
+    else:
+        state_profile_name = getattr(profiles_config, "default_profile", None)
+
     # Create task manager
     task_manager = TaskManager(
         internal_manager=internal_manager,
         db_manager=db_manager,
         profiles_config=profiles_config,
         project_config=project_config,
+        state_profile_name=state_profile_name,
     )
 
-    # Process each metric
-    for index, (metric_path, config) in enumerate(metrics):
-        result = process_metric(
-            metric_path=metric_path,
-            config=config,
-            project_root=project_root,
-            task_manager=task_manager,
-            steps=step_list,
-            from_date=from_dt,
-            to_date=to_dt,
-            full_refresh=full_refresh,
-            force=force,
-        )
-        summary["metrics"].append(
-            {
-                "name": config.name,
-                "status": _status_str(result["status"]),
-                "steps_completed": [s.value for s in result["steps_completed"]],
-                "datapoints_loaded": result["datapoints_loaded"],
-                "anomalies_detected": result["anomalies_detected"],
-                "alerts_sent": result["alerts_sent"],
-                "error": result["error"],
-            }
-        )
-
-        # Project-level error alert was dispatched — stop processing the
-        # rest of the metrics. The DB / source is presumed unreachable;
-        # subsequent metrics would all fail with the same error.
-        if result.get("abort_run"):
-            click.echo(
-                click.style(
-                    "✗ Aborting run after project error alert. " "Remaining metrics skipped.",
-                    fg="red",
-                    bold=True,
-                )
+    try:
+        # Process each metric
+        for index, (metric_path, config) in enumerate(metrics):
+            result = process_metric(
+                metric_path=metric_path,
+                config=config,
+                project_root=project_root,
+                task_manager=task_manager,
+                steps=step_list,
+                from_date=from_dt,
+                to_date=to_dt,
+                full_refresh=full_refresh,
+                force=force,
+            )
+            summary["metrics"].append(
+                {
+                    "name": config.name,
+                    "status": _status_str(result["status"]),
+                    "steps_completed": [s.value for s in result["steps_completed"]],
+                    "datapoints_loaded": result["datapoints_loaded"],
+                    "anomalies_detected": result["anomalies_detected"],
+                    "alerts_sent": result["alerts_sent"],
+                    "error": result["error"],
+                }
             )
-            summary["aborted"] = True
-            for _, skipped_config in metrics[index + 1 :]:
-                summary["metrics"].append(
-                    {
-                        "name": skipped_config.name,
-                        "status": "skipped",
-                        "steps_completed": [],
-                        "datapoints_loaded": 0,
-                        "anomalies_detected": 0,
-                        "alerts_sent": 0,
-                        "error": None,
-                    }
-                )
-            break
 
-        # Optional: emit a self-contained HTML report from the freshly-persisted
-        # internal tables (values + bands + anomalies + replayed alerts).
-        if report_path is not None:
-            try:
-                emit_metric_report(
-                    config=config,
-                    project_root=project_root,
-                    internal_manager=internal_manager,
-                    report_path=report_path,
-                    project_name=getattr(project_config, "name", None),
-                    project_loading_delay=getattr(project_config, "loading_delay", None),
-                    from_dt=from_dt,
-                    to_dt=to_dt,
+            # Project-level error alert was dispatched — stop processing the
+            # rest of the metrics. The DB / source is presumed unreachable;
+            # subsequent metrics would all fail with the same error.
+            if result.get("abort_run"):
+                click.echo(
+                    click.style(
+                        "✗ Aborting run after project error alert. " "Remaining metrics skipped.",
+                        fg="red",
+                        bold=True,
+                    )
                 )
-            except Exception as report_error:  # never fail the run on a report
-                click.echo(click.style(f"  │ Report skipped: {report_error}", fg="yellow"))
-
-    failed = any(m["status"] == "failed" for m in summary["metrics"])
-    return 1 if (failed or summary["aborted"]) else 0
+                summary["aborted"] = True
+                for _, skipped_config in metrics[index + 1 :]:
+                    summary["metrics"].append(
+                        {
+                            "name": skipped_config.name,
+                            "status": "skipped",
+                            "steps_completed": [],
+                            "datapoints_loaded": 0,
+                            "anomalies_detected": 0,
+                            "alerts_sent": 0,
+                            "error": None,
+                        }
+                    )
+                break
+
+            # Optional: emit a self-contained HTML report from the freshly-persisted
+            # internal tables (values + bands + anomalies + replayed alerts).
+            if report_path is not None:
+                try:
+                    emit_metric_report(
+                        config=config,
+                        project_root=project_root,
+                        internal_manager=internal_manager,
+                        report_path=report_path,
+                        project_name=getattr(project_config, "name", None),
+                        project_loading_delay=getattr(project_config, "loading_delay", None),
+                        from_dt=from_dt,
+                        to_dt=to_dt,
+                    )
+                except Exception as report_error:  # never fail the run on a report
+                    click.echo(click.style(f"  │ Report skipped: {report_error}", fg="yellow"))
+
+        failed = any(m["status"] == "failed" for m in summary["metrics"])
+        return 1 if (failed or summary["aborted"]) else 0
+    finally:
+        # Close every pooled hybrid-mode SOURCE manager (never db_manager
+        # itself — this function owns that connection's lifecycle, and it
+        # was never explicitly closed here either, before or after hybrid
+        # mode existed). Duck-typed lookup: a test double standing in for
+        # TaskManager need not implement it.
+        close_sources = getattr(task_manager, "close_sources", None)
+        if close_sources is not None:
+            close_sources()
+
+
+def _validate_source_profiles(
+    metrics: list[tuple[Path, MetricConfig]],
+    project_config: ProjectConfig,
+    profiles_config: ProfilesConfig,
+) -> str | None:
+    """Cheap, connection-free check that every metric's RESOLVED
+    ``source_profile`` (hybrid mode) names a real profile.
+
+    Returns an error message naming every offending metric, or ``None`` when
+    every resolved name is either unset (no hybrid override) or a known
+    profile. Runs before any database manager is built.
+    """
+    project_source_profile = getattr(project_config, "source_profile", None)
+    known_profiles = getattr(profiles_config, "profiles", {}) or {}
+    unknown: dict[str, str] = {}
+    for _, config in metrics:
+        name = resolve_source_profile(
+            getattr(config, "source_profile", None), project_source_profile
+        )
+        if name is not None and name not in known_profiles:
+            unknown[config.name] = name
+    if not unknown:
+        return None
+    details = ", ".join(f"{m} -> '{p}'" for m, p in sorted(unknown.items()))
+    available = ", ".join(sorted(known_profiles.keys()))
+    return (
+        f"Unknown source_profile referenced by metric(s): {details}. "
+        f"Available profiles: {available}"
+    )
 
 
 def _resolve_report_path(report_path: str, project_root: Path, metric_name: str) -> Path:

{detectkit-0.60.0 → detectkit-0.62.0}/detectkit/cli/main.py

@@ -592,5 +592,61 @@ from detectkit.cli.commands.osi import osi as _osi_group  # noqa: E402
 cli.add_command(_osi_group)
 
 
+# MCP (Model Context Protocol) server — a self-contained, READ-ONLY command
+# (`dtk mcp`), unlike `dtk osi` a single command rather than a group. Isolated
+# from the load/detect/alert pipeline: nothing in load/detect/alert imports
+# detectkit.mcp, and this module only imports click at load time — the mcp SDK
+# (the optional `[mcp]` extra) and detectkit.mcp.server are imported lazily,
+# inside the command body.
+@cli.command()
+@click.option(
+    "--project-dir",
+    default=None,
+    help=(
+        "Project directory (searched upward for detectkit_project.yml). "
+        "Default: $DETECTKIT_PROJECT_DIR, else search upward from the current "
+        "directory. An MCP client passes no cwd, so at least one of these must "
+        "resolve."
+    ),
+)
+@click.option(
+    "--select",
+    "-s",
+    default="*",
+    show_default=True,
+    help="Selector scoping which metrics the server exposes (metric name, path, or tag)",
+)
+@click.option(
+    "--profile",
+    help="Profile to use (default: from project config)",
+)
+def mcp(project_dir: str | None, select: str, profile: str | None) -> None:
+    """
+    Serve a read-only Model Context Protocol (MCP) server over stdio.
+
+    Exposes a detectkit project to an MCP client (an IDE assistant, a desktop
+    app, a cloud agent): metric configs, loaded datapoints, detector results,
+    replayed alert history, autotune runs, and labeled incidents. Nothing in
+    this server writes to the database or the filesystem — no config edits,
+    no label writes, no pipeline runs, no schema creation. It never calls
+    `ensure_tables()`; a project with no data yet answers tool calls with a
+    clear "run `dtk run` first" error instead of creating tables.
+
+    `--select` scopes the whole session: every tool that names a metric
+    refuses one outside this set, and list/status tools intersect their own
+    selector with it. Needs the `[mcp]` extra: pip install 'detectkit[mcp]'.
+
+    Examples:
+        # Expose every metric in the project the current directory is inside
+        dtk mcp
+
+        # Scope to one tag, from a project the client doesn't cd into
+        dtk mcp --project-dir /opt/monitoring --select "tag:critical"
+    """
+    from detectkit.cli.commands.mcp import run_mcp
+
+    run_mcp(project_dir=project_dir, select=select, profile=profile)
+
+
 if __name__ == "__main__":
     cli()

{detectkit-0.60.0 → detectkit-0.62.0}/detectkit/config/metric_config.py

@@ -627,6 +627,8 @@ class MetricConfig(BaseModel):
         description: Optional metric description (supports multi-line text)
         tags: Optional list of tags for metric selection (e.g., ["critical", "api"])
         profile: Profile name to use (overrides default_profile from project config)
+        source_profile: Hybrid mode — profile whose database runs this metric's
+            SQL, while _dtk_* state stays in the active (state) profile
         query: Inline SQL query (mutually exclusive with query_file)
         query_file: Path to SQL file (mutually exclusive with query)
         query_columns: Column name mapping for query results
@@ -684,6 +686,22 @@ class MetricConfig(BaseModel):
     profile: str | None = Field(
         default=None, description="Profile name to use (overrides default_profile)"
     )
+    # Hybrid mode: run this metric's SQL against a different database than the
+    # one holding _dtk_* state. Unlike `profile` above (which is dead — only
+    # round-tripped by autotune's config emitter), this is live: the load step
+    # resolves it to a pooled `ProfilesConfig.create_manager(...)` and executes
+    # the metric's query through it, while every other step (detect/alert) and
+    # save_datapoints itself keep using the active state profile. Falls back to
+    # ProjectConfig.source_profile, then None (= use the state profile).
+    source_profile: str | None = Field(
+        default=None,
+        description=(
+            "profiles.yml profile whose database runs this metric's SQL; "
+            "_dtk_* state stays in the active (state) profile. Falls back to "
+            "the project-level source_profile, then to the state profile "
+            "itself."
+        ),
+    )
     query: str | None = Field(default=None, description="Inline SQL query")
     query_file: Path | None = Field(default=None, description="Path to SQL file")
     query_columns: QueryColumnsConfig | None = Field(
@@ -1054,6 +1072,24 @@ def resolve_loading_delay_seconds(
     return 0
 
 
+def resolve_source_profile(
+    metric_source_profile: str | None, project_source_profile: str | None
+) -> str | None:
+    """Resolve the profiles.yml profile that should run a metric's SQL:
+    metric -> project -> ``None``.
+
+    ``None`` means "run the SQL through the same connection detectkit is
+    already using for ``_dtk_*`` state" — i.e. hybrid mode is off for this
+    metric and the meaning of ``dtk run --profile`` / ``default_profile`` is
+    unchanged. The first configured value wins, mirroring
+    :func:`resolve_loading_delay_seconds`'s metric -> project precedence.
+    """
+    for value in (metric_source_profile, project_source_profile):
+        if value is not None:
+            return value
+    return None
+
+
 def resolve_grid_phase_seconds(loading_start_time: str | None, interval_seconds: int) -> int:
     """Phase of the metric's interval grid on the epoch clock, in ``[0, interval)``.