detectkit 0.61.0__tar.gz → 0.62.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectkit
-Version: 0.61.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"
@@ -199,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
@@ -207,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.61.0 → detectkit-0.62.0}/README.md

@@ -120,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
@@ -128,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.61.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.61.0"
+__version__ = "0.62.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.61.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.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.61.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.61.0 → detectkit-0.62.0}/detectkit/config/profile.py

@@ -176,10 +176,19 @@ class ProfileConfig(BaseModel):
         else:
             raise ValueError(f"Unsupported database type: {self.type}")
 
-    def create_manager(self) -> BaseDatabaseManager:
+    def create_manager(self, ensure_locations: bool = True) -> BaseDatabaseManager:
         """
         Create database manager from profile configuration.
 
+        Args:
+            ensure_locations: When False, skip creating the internal/data
+                database(s)/schema(s) as a side effect of connecting — a
+                strict read-only probe. For DuckDB this additionally forces
+                a read-only attach (see :class:`DuckDBDatabaseManager`), so
+                the connect itself can never create a missing state file.
+                Used by the read-only MCP server, which must never run DDL
+                at startup.
+
         Returns:
             Database manager instance
 
@@ -201,6 +210,7 @@ class ProfileConfig(BaseModel):
                 internal_database=self.get_internal_location(),
                 data_database=self.get_data_location(),
                 settings=self.settings,
+                ensure_locations=ensure_locations,
             )
         elif self.type == "postgres":
             from detectkit.database.postgres_manager import PostgresDatabaseManager
@@ -220,6 +230,7 @@ class ProfileConfig(BaseModel):
                 internal_schema=self.get_internal_location(),
                 data_schema=self.get_data_location(),
                 settings=self.settings,
+                ensure_locations=ensure_locations,
             )
         elif self.type in ("mysql", "mariadb"):
             # MariaDB is served by the same manager; it detects the vendor at
@@ -236,6 +247,7 @@ class ProfileConfig(BaseModel):
                 internal_database=self.get_internal_location(),
                 data_database=self.get_data_location(),
                 settings=self.settings,
+                ensure_locations=ensure_locations,
             )
         elif self.type == "duckdb":
             # In-process, file-backed database: host/port/user/password/database
@@ -256,6 +268,7 @@ class ProfileConfig(BaseModel):
                 data_schema=self.get_data_location(),
                 read_only=self.read_only,
                 settings=self.settings,
+                ensure_locations=ensure_locations,
             )
         else:
             raise ValueError(f"Unsupported database type: {self.type}")
@@ -351,18 +364,24 @@ class ProfilesConfig(BaseModel):
 
         return self.profiles[name]
 
-    def create_manager(self, profile_name: str | None = None) -> BaseDatabaseManager:
+    def create_manager(
+        self, profile_name: str | None = None, ensure_locations: bool = True
+    ) -> BaseDatabaseManager:
         """
         Create database manager for a profile.
 
         Args:
             profile_name: Profile name (if None, use default)
+            ensure_locations: Passed through to
+                :meth:`ProfileConfig.create_manager` — False for a strict
+                read-only probe that never runs DDL as a side effect of
+                connecting.
 
         Returns:
             Database manager instance
         """
         profile = self.get_profile(profile_name)
-        return profile.create_manager()
+        return profile.create_manager(ensure_locations=ensure_locations)
 
     def get_alert_channel_config(self, channel_name: str) -> dict[str, Any]:
         """

{detectkit-0.61.0 → detectkit-0.62.0}/detectkit/database/_sql_manager.py

@@ -51,6 +51,11 @@ class SQLDatabaseManager(BaseDatabaseManager):
             database to connect to, inside which the schemas live); optional for
             MySQL (which addresses tables as ``database.table``).
         settings: Extra driver-specific connection options.
+        ensure_locations: When False, skip the ``_ensure_locations()`` call
+            that otherwise runs DDL (``CREATE SCHEMA``/``CREATE DATABASE``)
+            as a side effect of connecting — a strict read-only probe (used
+            by the read-only MCP server, which must never run DDL at
+            startup).
     """
 
     #: Maps the canonical column kind to a native SQL type. Subclasses override.
@@ -69,6 +74,7 @@ class SQLDatabaseManager(BaseDatabaseManager):
         data_location: str = "public",
         database: str | None = None,
         settings: dict[str, Any] | None = None,
+        ensure_locations: bool = True,
     ) -> None:
         self._host = host
         self._port = port
@@ -83,7 +89,8 @@ class SQLDatabaseManager(BaseDatabaseManager):
         self._table_meta: dict[str, tuple[list[str], str | None]] = {}
 
         self._conn: Any = self._connect()
-        self._ensure_locations()
+        if ensure_locations:
+            self._ensure_locations()
 
     # ── dialect hooks (subclasses override) ─────────────────────────────────
 
@@ -153,7 +160,7 @@ class SQLDatabaseManager(BaseDatabaseManager):
         if col.default is None:
             return ""
         d = col.default
-        if isinstance(d, (int, float)):
+        if isinstance(d, int | float):
             return f" DEFAULT {d}"
         if isinstance(d, str) and d.lstrip("-").isdigit():
             return f" DEFAULT {d}"

{detectkit-0.61.0 → detectkit-0.62.0}/detectkit/database/clickhouse_manager.py

@@ -36,6 +36,10 @@ class ClickHouseDatabaseManager(BaseDatabaseManager):
         internal_database: Database for internal tables (_dtk_*)
         data_database: Database for user data tables
         settings: Optional ClickHouse settings
+        ensure_locations: When False, skip creating the internal/data
+            databases as a side effect of connecting — a strict read-only
+            probe (used by the read-only MCP server, which must never run
+            DDL at startup).
     """
 
     def __init__(
@@ -47,6 +51,7 @@ class ClickHouseDatabaseManager(BaseDatabaseManager):
         internal_database: str = "detectk_internal",
         data_database: str = "default",
         settings: dict[str, Any] | None = None,
+        ensure_locations: bool = True,
     ):
         """Initialize ClickHouse manager."""
         if not CLICKHOUSE_AVAILABLE:
@@ -67,8 +72,9 @@ class ClickHouseDatabaseManager(BaseDatabaseManager):
             settings=settings or {},
         )
 
-        # Ensure databases exist
-        self._ensure_databases()
+        # Ensure databases exist (skipped for a strict read-only probe).
+        if ensure_locations:
+            self._ensure_databases()
 
     def _ensure_databases(self) -> None:
         """Create internal and data databases if they don't exist."""
@@ -154,7 +160,7 @@ class ClickHouseDatabaseManager(BaseDatabaseManager):
         """Format default value for SQL."""
         if isinstance(value, str):
             return f"'{value}'"
-        elif isinstance(value, (int, float)):
+        elif isinstance(value, int | float):
             return str(value)
         elif value is None:
             return "NULL"
@@ -228,12 +234,12 @@ class ClickHouseDatabaseManager(BaseDatabaseManager):
                 value = data[col_name][i]
 
                 # Convert numpy types to Python types
-                if isinstance(value, (np.datetime64, np.timedelta64)):
+                if isinstance(value, np.datetime64 | np.timedelta64):
                     # Convert numpy datetime64 to Python datetime
                     value = self._convert_numpy_datetime(value)
                 elif isinstance(value, np.ndarray):
                     value = value.tolist()
-                elif isinstance(value, (np.integer, np.floating)):
+                elif isinstance(value, np.integer | np.floating):
                     value = value.item()
                 elif value is None or (isinstance(value, float) and np.isnan(value)):
                     value = None

{detectkit-0.61.0 → detectkit-0.62.0}/detectkit/database/duckdb_manager.py

@@ -203,6 +203,18 @@ class DuckDBDatabaseManager(SQLDatabaseManager):
             internal/data schemas already exist.
         settings: Extra ``duckdb.connect`` ``config`` options (e.g.
             ``{"memory_limit": "512MB"}``).
+        ensure_locations: When False, skip creating the internal/data
+            schemas as a side effect of connecting (a strict read-only
+            probe — see
+            :class:`~detectkit.database._sql_manager.SQLDatabaseManager`)
+            **and** force a read-only attach regardless of ``read_only``,
+            for a real file path. Skipping schema creation alone is not
+            enough for DuckDB: a plain read-write ``duckdb.connect`` against
+            a *missing* file path creates that file as a side effect of
+            connecting, before any DDL runs — forcing ``read_only=True``
+            is what actually prevents that. ``":memory:"`` is exempted from
+            the forced read-only attach (it has no file to create, and
+            DuckDB rejects a read-only in-memory connection outright).
 
     Raises:
         ImportError: If the ``duckdb`` package is not installed.
@@ -224,6 +236,7 @@ class DuckDBDatabaseManager(SQLDatabaseManager):
         data_schema: str = "main",
         read_only: bool = False,
         settings: dict[str, Any] | None = None,
+        ensure_locations: bool = True,
     ) -> None:
         if not DUCKDB_AVAILABLE:
             raise ImportError(
@@ -235,7 +248,17 @@ class DuckDBDatabaseManager(SQLDatabaseManager):
                 "path, or ':memory:' for a transient, tests/preview-only in-process "
                 "database whose state is lost between runs)."
             )
-        self._read_only = read_only
+        # `ensure_locations=False` is a strict read-only PROBE (see
+        # `SQLDatabaseManager.__init__`): skipping `_ensure_locations()` is
+        # not enough on its own for DuckDB, because a plain read-write
+        # `duckdb.connect` against a MISSING file creates that file as a
+        # side effect of connecting, before any DDL runs. Force a read-only
+        # attach so the connect itself can never create the file/schemas.
+        # ":memory:" is exempted — it has no file to create in the first
+        # place, and DuckDB rejects a read-only in-memory connection outright
+        # (`CatalogException: Cannot launch in-memory database in read-only
+        # mode!`), so forcing it there would break rather than protect.
+        self._read_only = True if (not ensure_locations and path != ":memory:") else read_only
         # Kept separately (and typed `str`, not `str | None`) from the base
         # class's `self._database` so `_connect()` doesn't need to narrow an
         # Optional it knows — by the ValueError check above — can't be None.
@@ -248,6 +271,7 @@ class DuckDBDatabaseManager(SQLDatabaseManager):
             data_location=data_schema,
             database=path,
             settings=settings,
+            ensure_locations=ensure_locations,
         )
 
     def _connect(self) -> Any:

{detectkit-0.61.0 → detectkit-0.62.0}/detectkit/database/mysql_manager.py

@@ -44,6 +44,9 @@ class MySQLDatabaseManager(SQLDatabaseManager):
         data_database: Database for user data tables.
         database: Optional default database for the connection.
         settings: Extra ``pymysql.connect`` keyword arguments.
+        ensure_locations: When False, skip creating the internal/data
+            databases as a side effect of connecting — a strict read-only
+            probe (see :class:`~detectkit.database._sql_manager.SQLDatabaseManager`).
     """
 
     _TYPE_MAP = {
@@ -72,6 +75,7 @@ class MySQLDatabaseManager(SQLDatabaseManager):
         data_database: str = "analytics",
         database: str | None = None,
         settings: dict[str, Any] | None = None,
+        ensure_locations: bool = True,
     ) -> None:
         if not PYMYSQL_AVAILABLE:
             raise ImportError(
@@ -86,6 +90,7 @@ class MySQLDatabaseManager(SQLDatabaseManager):
             data_location=data_database,
             database=database,
             settings=settings,
+            ensure_locations=ensure_locations,
         )
 
     def _connect(self) -> Any:

{detectkit-0.61.0 → detectkit-0.62.0}/detectkit/database/postgres_manager.py

@@ -34,6 +34,9 @@ class PostgresDatabaseManager(SQLDatabaseManager):
         internal_schema: Schema for internal ``_dtk_*`` tables.
         data_schema: Schema for user data tables.
         settings: Extra ``psycopg2.connect`` keyword arguments.
+        ensure_locations: When False, skip creating the internal/data
+            schemas as a side effect of connecting — a strict read-only
+            probe (see :class:`~detectkit.database._sql_manager.SQLDatabaseManager`).
     """
 
     _TYPE_MAP = {
@@ -54,6 +57,7 @@ class PostgresDatabaseManager(SQLDatabaseManager):
         internal_schema: str = "detectkit",
         data_schema: str = "public",
         settings: dict[str, Any] | None = None,
+        ensure_locations: bool = True,
     ) -> None:
         if not PSYCOPG2_AVAILABLE:
             raise ImportError(
@@ -68,6 +72,7 @@ class PostgresDatabaseManager(SQLDatabaseManager):
             data_location=data_schema,
             database=database,
             settings=settings,
+            ensure_locations=ensure_locations,
         )
 
     def _connect(self) -> Any:

{detectkit-0.61.0 → detectkit-0.62.0}/detectkit/loaders/metric_loader.py

@@ -172,7 +172,13 @@ class MetricLoader:
             # Filter by timestamp
             row_ts = row[timestamp_col]
             if isinstance(row_ts, datetime):
-                # Already datetime - compare directly
+                # Naive-UTC convention: a tz-aware timestamp from the source
+                # (DuckDB now()/TIMESTAMPTZ, PostgreSQL timestamptz) is
+                # converted — not rejected — so it compares cleanly with the
+                # naive-UTC window bounds and stores consistently downstream.
+                if row_ts.tzinfo is not None:
+                    row_ts = to_naive_utc(row_ts)
+                    row[timestamp_col] = row_ts
                 if row_ts >= to_date:
                     continue
             else:

detectkit-0.62.0/detectkit/mcp/__init__.py

@@ -0,0 +1,47 @@
+"""Read-only Model Context Protocol (MCP) server for detectkit.
+
+An **isolated, additive** layer — mirroring ``detectkit/semantic/``'s design:
+nothing in the load/detect/alert pipeline imports it, so it can never affect
+a running project. It powers only the ``dtk mcp`` command
+(:mod:`detectkit.cli.commands.mcp`), which exposes a project's metrics,
+loaded data, detector results, replayed alert history, autotune runs and
+labeled incidents to an MCP client (an IDE assistant, a desktop app, a cloud
+agent) over stdio.
+
+The ``mcp`` SDK (the ``[mcp]`` extra, ``pip install 'detectkit[mcp]'``) is a
+guarded, lazy import — see :mod:`detectkit.mcp.server` — so this package (and
+every module in it) imports cleanly even when the extra isn't installed;
+only building/running the actual server needs it.
+
+Module map:
+
+- ``errors.py`` — :class:`McpError` / :class:`McpProjectError` /
+  :class:`McpDependencyMissing`.
+- ``context.py`` — project resolution (``--project-dir`` ->
+  ``$DETECTKIT_PROJECT_DIR`` -> cwd search) and the long-lived
+  :class:`McpContext` (mirrors ``dtk run``'s build order, minus
+  ``ensure_tables()`` — read-only never runs DDL).
+- ``serialize.py`` — ISO-8601 / numpy-free JSON conversion helpers shared by
+  every tool.
+- ``tools.py`` — the 10 read-only tool implementations, as plain functions
+  (no SDK dependency; directly unit-testable).
+- ``server.py`` — the guarded ``FastMCP`` wiring + ``dtk mcp``'s entry point
+  (:func:`~detectkit.mcp.server.run_server`).
+
+See :mod:`detectkit.mcp.tools` for the full tool list and the read-only
+exclusion contract (no config/label writes, no pipeline runs, no DDL).
+"""
+
+from __future__ import annotations
+
+from detectkit.mcp.context import McpContext, build_context, resolve_project_dir
+from detectkit.mcp.errors import McpDependencyMissing, McpError, McpProjectError
+
+__all__ = [
+    "McpContext",
+    "McpDependencyMissing",
+    "McpError",
+    "McpProjectError",
+    "build_context",
+    "resolve_project_dir",
+]