@vaultgradient/pipequery-cli 0.3.3 → 0.6.0

package/dist/index.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { Command } from "commander";
-import chalk8 from "chalk";
+import chalk9 from "chalk";
 
 // src/commands/init.ts
 import { writeFile } from "fs/promises";
@@ -83,7 +83,7 @@ async function initCommand() {
 
 // src/commands/serve.ts
 import { writeFile as writeFile3, mkdir, readFile as readFile3, unlink } from "fs/promises";
-import { resolve as resolve4 } from "path";
+import { resolve as resolve5 } from "path";
 import { existsSync as existsSync3 } from "fs";
 import { spawn } from "child_process";
 
@@ -236,11 +236,11 @@ var WebSocketSourceAdapter = class {
   listeners = /* @__PURE__ */ new Set();
   maxBuffer;
   async start() {
-    return new Promise((resolve9, reject) => {
+    return new Promise((resolve10, reject) => {
       this.ws = new WebSocket(this.config.url);
       this.ws.on("open", () => {
         this.error = void 0;
-        resolve9();
+        resolve10();
       });
       this.ws.on("message", (raw) => {
         try {
@@ -394,6 +394,455 @@ var StaticSourceAdapter = class {
   }
 };
 
+// src/server/sources/postgres.ts
+import pg from "pg";
+var DEFAULT_INTERVAL_MS = 3e4;
+var DEFAULT_MAX_ROWS = 1e4;
+function expandEnv(input) {
+  return input.replace(/\$\{([A-Z0-9_]+)\}/gi, (_, name) => {
+    const value = process.env[name];
+    if (value === void 0) {
+      process.stderr.write(
+        `[pipequery] env var "${name}" referenced in postgres source URL is not set
+`
+      );
+      return "";
+    }
+    return value;
+  });
+}
+function resolveSsl(ssl) {
+  if (ssl === false) return false;
+  if (ssl === "no-verify") return { rejectUnauthorized: false };
+  return { rejectUnauthorized: true };
+}
+var PostgresSourceAdapter = class {
+  constructor(config) {
+    this.config = config;
+    this.intervalMs = config.interval ? parseDuration(config.interval) : DEFAULT_INTERVAL_MS;
+    this.maxRows = config.maxRows ?? DEFAULT_MAX_ROWS;
+  }
+  config;
+  pool = null;
+  data = [];
+  timer = null;
+  lastFetch = null;
+  error;
+  listeners = /* @__PURE__ */ new Set();
+  intervalMs;
+  maxRows;
+  async start() {
+    const connectionString = expandEnv(this.config.url);
+    this.pool = new pg.Pool({
+      connectionString,
+      ssl: resolveSsl(this.config.ssl),
+      // Small pool — we're read-only polling, not a transactional app.
+      min: 0,
+      max: 2,
+      idleTimeoutMillis: 1e4
+    });
+    this.pool.on("error", (err) => {
+      this.error = err.message;
+    });
+    await this.fetch();
+    this.timer = setInterval(() => {
+      void this.fetch();
+    }, this.intervalMs);
+  }
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (this.pool) {
+      void this.pool.end();
+      this.pool = null;
+    }
+  }
+  getData() {
+    return this.data;
+  }
+  getStatus() {
+    return {
+      healthy: !this.error,
+      rowCount: this.data.length,
+      lastFetch: this.lastFetch,
+      error: this.error
+    };
+  }
+  onUpdate(callback) {
+    this.listeners.add(callback);
+    return () => this.listeners.delete(callback);
+  }
+  async refresh() {
+    await this.fetch();
+  }
+  async fetch() {
+    if (!this.pool) {
+      this.error = "Postgres pool not initialized";
+      return;
+    }
+    try {
+      const capQuery = `SELECT * FROM (${stripTrailingSemicolon(this.config.query)}) AS pq_src LIMIT ${this.maxRows + 1}`;
+      const res = await this.pool.query(capQuery);
+      if (res.rows.length > this.maxRows) {
+        throw new Error(
+          `Query returned more than maxRows=${this.maxRows}. Add LIMIT/WHERE to bound the result set, or raise maxRows in the source config.`
+        );
+      }
+      this.data = res.rows;
+      this.lastFetch = /* @__PURE__ */ new Date();
+      this.error = void 0;
+      this.notify();
+    } catch (err) {
+      this.error = err instanceof Error ? err.message : String(err);
+    }
+  }
+  notify() {
+    for (const cb of this.listeners) cb(this.data);
+  }
+};
+function stripTrailingSemicolon(sql) {
+  return sql.trim().replace(/;+\s*$/, "");
+}
+
+// src/server/sources/mysql.ts
+import mysql from "mysql2/promise";
+var DEFAULT_INTERVAL_MS2 = 3e4;
+var DEFAULT_MAX_ROWS2 = 1e4;
+function expandEnv2(input) {
+  return input.replace(/\$\{([A-Z0-9_]+)\}/gi, (_, name) => {
+    const value = process.env[name];
+    if (value === void 0) {
+      process.stderr.write(
+        `[pipequery] env var "${name}" referenced in mysql source URL is not set
+`
+      );
+      return "";
+    }
+    return value;
+  });
+}
+function resolveSsl2(ssl) {
+  if (ssl === false) return void 0;
+  if (ssl === "no-verify") return { rejectUnauthorized: false };
+  return { rejectUnauthorized: true };
+}
+var MysqlSourceAdapter = class {
+  constructor(config) {
+    this.config = config;
+    this.intervalMs = config.interval ? parseDuration(config.interval) : DEFAULT_INTERVAL_MS2;
+    this.maxRows = config.maxRows ?? DEFAULT_MAX_ROWS2;
+  }
+  config;
+  pool = null;
+  data = [];
+  timer = null;
+  lastFetch = null;
+  error;
+  listeners = /* @__PURE__ */ new Set();
+  intervalMs;
+  maxRows;
+  async start() {
+    const uri = expandEnv2(this.config.url);
+    this.pool = mysql.createPool({
+      uri,
+      ssl: resolveSsl2(this.config.ssl),
+      connectionLimit: 2,
+      waitForConnections: true,
+      // mysql2 returns BigInt for large integers by default — stringify so the
+      // data serializes cleanly to JSON (which can't encode BigInt).
+      supportBigNumbers: true,
+      bigNumberStrings: true
+    });
+    await this.fetch();
+    this.timer = setInterval(() => {
+      void this.fetch();
+    }, this.intervalMs);
+  }
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (this.pool) {
+      void this.pool.end();
+      this.pool = null;
+    }
+  }
+  getData() {
+    return this.data;
+  }
+  getStatus() {
+    return {
+      healthy: !this.error,
+      rowCount: this.data.length,
+      lastFetch: this.lastFetch,
+      error: this.error
+    };
+  }
+  onUpdate(callback) {
+    this.listeners.add(callback);
+    return () => this.listeners.delete(callback);
+  }
+  async refresh() {
+    await this.fetch();
+  }
+  async fetch() {
+    if (!this.pool) {
+      this.error = "MySQL pool not initialized";
+      return;
+    }
+    try {
+      const capQuery = `SELECT * FROM (${stripTrailingSemicolon2(this.config.query)}) AS pq_src LIMIT ${this.maxRows + 1}`;
+      const [rows] = await this.pool.query(capQuery);
+      const asArray = Array.isArray(rows) ? rows : [];
+      if (asArray.length > this.maxRows) {
+        throw new Error(
+          `Query returned more than maxRows=${this.maxRows}. Add LIMIT/WHERE to bound the result set, or raise maxRows in the source config.`
+        );
+      }
+      this.data = asArray;
+      this.lastFetch = /* @__PURE__ */ new Date();
+      this.error = void 0;
+      this.notify();
+    } catch (err) {
+      this.error = err instanceof Error ? err.message : String(err);
+    }
+  }
+  notify() {
+    for (const cb of this.listeners) cb(this.data);
+  }
+};
+function stripTrailingSemicolon2(sql) {
+  return sql.trim().replace(/;+\s*$/, "");
+}
+
+// src/server/sources/sqlite.ts
+import { resolve as resolve4 } from "path";
+import Database from "better-sqlite3";
+var DEFAULT_INTERVAL_MS3 = 3e4;
+var DEFAULT_MAX_ROWS3 = 1e4;
+var IN_MEMORY = ":memory:";
+var SqliteSourceAdapter = class {
+  constructor(config, cwd) {
+    this.config = config;
+    this.intervalMs = config.interval ? parseDuration(config.interval) : DEFAULT_INTERVAL_MS3;
+    this.maxRows = config.maxRows ?? DEFAULT_MAX_ROWS3;
+    this.readonly = config.readonly ?? true;
+    this.resolvedPath = config.path === IN_MEMORY ? IN_MEMORY : resolve4(cwd, config.path);
+  }
+  config;
+  db = null;
+  data = [];
+  timer = null;
+  lastFetch = null;
+  error;
+  listeners = /* @__PURE__ */ new Set();
+  intervalMs;
+  maxRows;
+  resolvedPath;
+  readonly;
+  async start() {
+    const opts = this.resolvedPath === IN_MEMORY ? {} : { readonly: this.readonly, fileMustExist: this.readonly };
+    this.db = new Database(this.resolvedPath, opts);
+    if (this.resolvedPath !== IN_MEMORY && !this.readonly) {
+      this.db.pragma("journal_mode = WAL");
+    }
+    await this.fetch();
+    this.timer = setInterval(() => {
+      void this.fetch();
+    }, this.intervalMs);
+  }
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (this.db) {
+      this.db.close();
+      this.db = null;
+    }
+  }
+  getData() {
+    return this.data;
+  }
+  getStatus() {
+    return {
+      healthy: !this.error,
+      rowCount: this.data.length,
+      lastFetch: this.lastFetch,
+      error: this.error
+    };
+  }
+  onUpdate(callback) {
+    this.listeners.add(callback);
+    return () => this.listeners.delete(callback);
+  }
+  async refresh() {
+    await this.fetch();
+  }
+  async fetch() {
+    if (!this.db) {
+      this.error = "SQLite database not initialized";
+      return;
+    }
+    try {
+      const capQuery = `SELECT * FROM (${stripTrailingSemicolon3(this.config.query)}) AS pq_src LIMIT ${this.maxRows + 1}`;
+      const rows = this.db.prepare(capQuery).all();
+      if (rows.length > this.maxRows) {
+        throw new Error(
+          `Query returned more than maxRows=${this.maxRows}. Add LIMIT/WHERE to bound the result set, or raise maxRows in the source config.`
+        );
+      }
+      this.data = rows;
+      this.lastFetch = /* @__PURE__ */ new Date();
+      this.error = void 0;
+      this.notify();
+    } catch (err) {
+      this.error = err instanceof Error ? err.message : String(err);
+    }
+  }
+  notify() {
+    for (const cb of this.listeners) cb(this.data);
+  }
+};
+function stripTrailingSemicolon3(sql) {
+  return sql.trim().replace(/;+\s*$/, "");
+}
+
+// src/server/sources/kafka.ts
+import { randomBytes } from "crypto";
+import { Kafka, logLevel } from "kafkajs";
+var DEFAULT_MAX_BUFFER = 1e3;
+function expandEnv3(input) {
+  return input.replace(/\$\{([A-Z0-9_]+)\}/gi, (_, name) => {
+    const value = process.env[name];
+    if (value === void 0) {
+      process.stderr.write(
+        `[pipequery] env var "${name}" referenced in kafka source is not set
+`
+      );
+      return "";
+    }
+    return value;
+  });
+}
+function normalizeBrokers(brokers) {
+  const list = Array.isArray(brokers) ? brokers : brokers.split(",");
+  return list.map((b) => expandEnv3(b.trim())).filter(Boolean);
+}
+var KafkaSourceAdapter = class {
+  constructor(config) {
+    this.config = config;
+    this.maxBuffer = config.maxBuffer ?? DEFAULT_MAX_BUFFER;
+    this.groupId = config.groupId ?? `pipequery-${randomBytes(6).toString("hex")}`;
+  }
+  config;
+  data = [];
+  kafka = null;
+  consumer = null;
+  lastFetch = null;
+  error;
+  connected = false;
+  listeners = /* @__PURE__ */ new Set();
+  maxBuffer;
+  groupId;
+  async start() {
+    const brokers = normalizeBrokers(this.config.brokers);
+    if (brokers.length === 0) {
+      throw new Error("Kafka source has no brokers configured");
+    }
+    this.kafka = new Kafka({
+      clientId: `pipequery-${this.config.topic}`,
+      brokers,
+      ssl: this.config.ssl ?? false,
+      sasl: this.config.sasl ? {
+        mechanism: this.config.sasl.mechanism,
+        username: expandEnv3(this.config.sasl.username),
+        password: expandEnv3(this.config.sasl.password)
+      } : void 0,
+      // Silence kafkajs's own logger — we surface errors via SourceStatus.
+      logLevel: logLevel.ERROR
+    });
+    this.consumer = this.kafka.consumer({ groupId: this.groupId });
+    await this.consumer.connect();
+    await this.consumer.subscribe({
+      topic: this.config.topic,
+      fromBeginning: this.config.fromBeginning ?? false
+    });
+    this.connected = true;
+    this.error = void 0;
+    void this.consumer.run({
+      eachMessage: async ({ message, partition }) => {
+        try {
+          const row = this.decode(message.value, message.key, message.timestamp, partition, message.offset);
+          this.data.push(row);
+          if (this.data.length > this.maxBuffer) {
+            this.data = this.data.slice(-this.maxBuffer);
+          }
+          this.lastFetch = /* @__PURE__ */ new Date();
+          this.error = void 0;
+          this.notify();
+        } catch {
+        }
+      }
+    });
+  }
+  stop() {
+    this.connected = false;
+    if (this.consumer) {
+      const consumer = this.consumer;
+      this.consumer = null;
+      void consumer.disconnect().catch(() => {
+      });
+    }
+    this.kafka = null;
+  }
+  getData() {
+    return this.data;
+  }
+  getStatus() {
+    return {
+      healthy: this.connected && !this.error,
+      rowCount: this.data.length,
+      lastFetch: this.lastFetch,
+      error: this.error
+    };
+  }
+  onUpdate(callback) {
+    this.listeners.add(callback);
+    return () => this.listeners.delete(callback);
+  }
+  decode(value, key, timestamp, partition, offset) {
+    const base = {
+      _kafka_topic: this.config.topic,
+      _kafka_partition: partition,
+      _kafka_offset: offset,
+      _kafka_timestamp: Number.parseInt(timestamp, 10),
+      _kafka_key: key ? key.toString("utf8") : null
+    };
+    if (!value) {
+      return { ...base, value: null };
+    }
+    const format = this.config.valueFormat ?? "json";
+    if (format === "string") {
+      return { ...base, value: value.toString("utf8") };
+    }
+    if (format === "raw") {
+      return { ...base, value: value.toString("base64") };
+    }
+    const decoded = JSON.parse(value.toString("utf8"));
+    if (decoded !== null && typeof decoded === "object" && !Array.isArray(decoded)) {
+      return { ...base, ...decoded };
+    }
+    return { ...base, value: decoded };
+  }
+  notify() {
+    for (const cb of this.listeners) cb(this.data);
+  }
+};
+
 // src/server/sources/manager.ts
 var SourceManager = class {
   constructor(cwd) {
@@ -479,25 +928,22 @@ var SourceManager = class {
         return new FileSourceAdapter(config, this.cwd);
       case "static":
         return new StaticSourceAdapter(config);
+      case "postgres":
+        return new PostgresSourceAdapter(config);
+      case "mysql":
+        return new MysqlSourceAdapter(config);
+      case "sqlite":
+        return new SqliteSourceAdapter(config, this.cwd);
+      case "kafka":
+        return new KafkaSourceAdapter(config);
       default:
         throw new Error(`Unknown source type: ${config.type}`);
     }
   }
 };
 
-// src/server/routes/health.ts
-function registerHealthRoutes(app, sourceManager, startedAt) {
-  app.get("/health", async () => {
-    return { status: "ok", uptime: Date.now() - startedAt.getTime() };
-  });
-  app.get("/status", async () => {
-    return {
-      status: "ok",
-      uptime: Date.now() - startedAt.getTime(),
-      sources: sourceManager.getAllStatuses()
-    };
-  });
-}
+// src/server/watches/manager.ts
+import { createHash } from "crypto";
 
 // ../src/engine/types.ts
 var AGGREGATE_NAMES = /* @__PURE__ */ new Set([
@@ -2325,6 +2771,333 @@ function query(context, expression) {
   return fn(context);
 }
 
+// src/server/activity-log.ts
+var MAX_ENTRIES = 100;
+var entries = [];
+function logActivity(level, message) {
+  entries.push({
+    time: (/* @__PURE__ */ new Date()).toISOString(),
+    level,
+    message
+  });
+  if (entries.length > MAX_ENTRIES) {
+    entries.splice(0, entries.length - MAX_ENTRIES);
+  }
+}
+function getActivityLog(since) {
+  if (!since) return [...entries];
+  return entries.filter((e) => e.time > since);
+}
+function info(msg) {
+  logActivity("info", msg);
+}
+function warn(msg) {
+  logActivity("warn", msg);
+}
+function error(msg) {
+  logActivity("error", msg);
+}
+
+// src/telegram/notifier.ts
+import { Bot } from "grammy";
+
+// src/telegram/format.ts
+var TELEGRAM_TEXT_LIMIT = 4096;
+var FENCE_OVERHEAD = 32;
+var TRUNCATE_BUDGET = TELEGRAM_TEXT_LIMIT - FENCE_OVERHEAD;
+var MAX_ROWS_INLINE = 30;
+var MAX_COL_WIDTH = 24;
+function formatResult(result, opts = {}) {
+  const maxRows = opts.maxRows ?? MAX_ROWS_INLINE;
+  if (Array.isArray(result)) {
+    if (result.length === 0) return "<i>(no rows)</i>";
+    const allObjects = result.every(
+      (r) => r !== null && typeof r === "object" && !Array.isArray(r)
+    );
+    if (allObjects) {
+      return renderTable(result, result.length, maxRows, opts);
+    }
+    return renderJson(result.slice(0, maxRows), result.length, maxRows);
+  }
+  return renderJson(result, 1, 1);
+}
+function formatError(err) {
+  const msg = err instanceof Error ? err.message : String(err);
+  return `\u274C <b>Error</b>
+<pre>${escapeHtml(msg)}</pre>`;
+}
+function renderTable(rows, totalCount, maxRows, opts) {
+  const maxColWidth = opts.maxColWidth ?? MAX_COL_WIDTH;
+  const sample = rows.slice(0, maxRows);
+  const columns = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const r of sample) {
+    for (const k of Object.keys(r)) {
+      if (!seen.has(k)) {
+        seen.add(k);
+        columns.push(k);
+      }
+    }
+  }
+  const widths = columns.map(
+    (c) => Math.min(
+      maxColWidth,
+      Math.max(c.length, ...sample.map((r) => stringifyCell(r[c]).length))
+    )
+  );
+  const headerRow = columns.map((c, i) => padCell(c, widths[i])).join("  ");
+  const sep = widths.map((w) => "\u2500".repeat(w)).join("  ");
+  const dataRows = sample.map(
+    (r) => columns.map((c, i) => padCell(stringifyCell(r[c]), widths[i])).join("  ")
+  );
+  const lines = [headerRow, sep, ...dataRows];
+  let body = lines.join("\n");
+  if (body.length > TRUNCATE_BUDGET) {
+    body = body.slice(0, TRUNCATE_BUDGET - 30) + "\n... (truncated)";
+  }
+  let out = `<pre>${escapeHtml(body)}</pre>`;
+  if (totalCount > maxRows) {
+    out += `
+<i>showing ${maxRows} of ${totalCount} rows \u2014 narrow your query</i>`;
+  } else {
+    out += `
+<i>${totalCount} row${totalCount === 1 ? "" : "s"}</i>`;
+  }
+  return out;
+}
+function stringifyCell(value) {
+  if (value === null || value === void 0) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return JSON.stringify(value);
+}
+function padCell(s, width) {
+  if (s.length > width) return s.slice(0, width - 1) + "\u2026";
+  return s.padEnd(width, " ");
+}
+function renderJson(data, totalCount, maxRows) {
+  const text = JSON.stringify(data, null, 2);
+  let body = text;
+  if (body.length > TRUNCATE_BUDGET) {
+    body = body.slice(0, TRUNCATE_BUDGET - 30) + "\n... (truncated)";
+  }
+  let out = `<pre>${escapeHtml(body)}</pre>`;
+  if (Array.isArray(data) && totalCount > maxRows) {
+    out += `
+<i>showing ${maxRows} of ${totalCount} rows \u2014 narrow your query</i>`;
+  }
+  return out;
+}
+var HTML_ENTITIES = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;"
+};
+function escapeHtml(s) {
+  return s.replace(/[&<>]/g, (c) => HTML_ENTITIES[c] ?? c);
+}
+
+// src/telegram/notifier.ts
+var botCache = /* @__PURE__ */ new Map();
+function expandEnv4(input) {
+  return input.replace(/\$\{([A-Z0-9_]+)\}/gi, (_, name) => process.env[name] ?? "");
+}
+function getBot(token) {
+  let bot = botCache.get(token);
+  if (!bot) {
+    bot = new Bot(token);
+    botCache.set(token, bot);
+  }
+  return bot;
+}
+var TelegramNotifier = class {
+  token;
+  chatId;
+  template;
+  constructor(cfg) {
+    const tokenSource = cfg.botToken ?? process.env.PIPEQUERY_TG_BOT_TOKEN;
+    if (!tokenSource) {
+      throw new Error(
+        "TelegramNotifier: no bot token. Set notify.telegram.botToken or PIPEQUERY_TG_BOT_TOKEN."
+      );
+    }
+    this.token = expandEnv4(tokenSource);
+    this.chatId = cfg.chatId;
+    this.template = cfg.message;
+  }
+  async notify(payload) {
+    const bot = getBot(this.token);
+    const text = this.renderMessage(payload);
+    await bot.api.sendMessage(this.chatId, text, {
+      parse_mode: "HTML",
+      link_preview_options: { is_disabled: true }
+    });
+  }
+  renderMessage(payload) {
+    if (this.template) {
+      return renderTemplate(this.template, payload);
+    }
+    const header = `\u{1F514} <b>Watch fired:</b> <code>${escapeHtml(payload.watchName)}</code>`;
+    const reason = `<i>${escapeHtml(payload.reason)}</i>`;
+    const body = formatResult(payload.result);
+    return [header, reason, body].join("\n");
+  }
+};
+function renderTemplate(tmpl, payload) {
+  const result = payload.result;
+  const rows = Array.isArray(result) ? result : [result];
+  const firstRow = rows[0];
+  const count = rows.length;
+  return tmpl.replace(/\{\{\s*\.([a-zA-Z0-9_]+)\s*\}\}/g, (match, name) => {
+    if (name === "count") return String(count);
+    if (name === "watchName") return payload.watchName;
+    if (name === "reason") return payload.reason;
+    if (firstRow && typeof firstRow === "object" && firstRow !== null) {
+      const value = firstRow[name];
+      if (value === void 0) return match;
+      return String(value);
+    }
+    return match;
+  });
+}
+
+// src/server/watches/manager.ts
+var DEFAULT_INTERVAL_MS4 = 6e4;
+var WatchManager = class {
+  constructor(sourceManager) {
+    this.sourceManager = sourceManager;
+  }
+  sourceManager;
+  watches = /* @__PURE__ */ new Map();
+  disposed = false;
+  start(configs) {
+    for (const [name, cfg] of Object.entries(configs)) {
+      try {
+        this.startOne(name, cfg);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        error(`Watch "${name}" failed to start: ${msg}`);
+        process.stderr.write(`[pipequery-watch] "${name}" failed to start: ${msg}
+`);
+      }
+    }
+  }
+  startOne(name, cfg) {
+    const notifiers = buildNotifiers(cfg.notify);
+    if (notifiers.length === 0) {
+      throw new Error(`watch has no notification channels configured`);
+    }
+    const intervalMs = cfg.interval ? parseDuration(cfg.interval) : DEFAULT_INTERVAL_MS4;
+    const state = {
+      config: cfg,
+      notifiers,
+      intervalMs,
+      timer: null,
+      lastWasEmpty: null,
+      lastHash: null
+    };
+    this.watches.set(name, state);
+    info(`Watch "${name}" registered (every ${cfg.interval ?? "60s"})`);
+    void this.tick(name);
+    state.timer = setInterval(() => void this.tick(name), intervalMs);
+  }
+  async tick(name) {
+    if (this.disposed) return;
+    const state = this.watches.get(name);
+    if (!state) return;
+    let result;
+    try {
+      const ctx = this.sourceManager.getContext();
+      result = query(ctx, state.config.query);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      error(`Watch "${name}" query failed: ${msg}`);
+      return;
+    }
+    const fireWhen = state.config.fireWhen ?? "when_non_empty";
+    const isEmpty = isResultEmpty(result);
+    const hash = hashResult(result);
+    let shouldFire = false;
+    let reason = "";
+    if (fireWhen === "when_non_empty") {
+      if (state.lastWasEmpty !== false && !isEmpty) {
+        shouldFire = true;
+        reason = "result transitioned to non-empty";
+      }
+    } else if (fireWhen === "when_empty") {
+      if (state.lastWasEmpty !== true && isEmpty) {
+        shouldFire = true;
+        reason = "result transitioned to empty";
+      }
+    } else if (fireWhen === "on_change") {
+      if (state.lastHash !== null && state.lastHash !== hash) {
+        shouldFire = true;
+        reason = "result content changed";
+      }
+    }
+    state.lastWasEmpty = isEmpty;
+    state.lastHash = hash;
+    if (!shouldFire) return;
+    info(`Watch "${name}" fired (${reason})`);
+    await Promise.all(
+      state.notifiers.map(
+        (n) => n.notify({ watchName: name, result, reason }).catch((err) => {
+          const msg = err instanceof Error ? err.message : String(err);
+          error(`Watch "${name}" notify failed: ${msg}`);
+          process.stderr.write(`[pipequery-watch] "${name}" notify failed: ${msg}
+`);
+        })
+      )
+    );
+  }
+  stop(name) {
+    const state = this.watches.get(name);
+    if (!state) return false;
+    if (state.timer) clearInterval(state.timer);
+    this.watches.delete(name);
+    return true;
+  }
+  list() {
+    return [...this.watches.keys()];
+  }
+  dispose() {
+    this.disposed = true;
+    for (const state of this.watches.values()) {
+      if (state.timer) clearInterval(state.timer);
+    }
+    this.watches.clear();
+  }
+};
+function buildNotifiers(notify) {
+  const out = [];
+  if (notify.telegram) out.push(new TelegramNotifier(notify.telegram));
+  return out;
+}
+function isResultEmpty(result) {
+  if (result === null || result === void 0) return true;
+  if (Array.isArray(result)) return result.length === 0;
+  if (typeof result === "object") return Object.keys(result).length === 0;
+  return false;
+}
+function hashResult(result) {
+  const json = JSON.stringify(result, (_, v) => v === void 0 ? null : v);
+  return createHash("sha256").update(json).digest("hex");
+}
+
+// src/server/routes/health.ts
+function registerHealthRoutes(app, sourceManager, startedAt) {
+  app.get("/health", async () => {
+    return { status: "ok", uptime: Date.now() - startedAt.getTime() };
+  });
+  app.get("/status", async () => {
+    return {
+      status: "ok",
+      uptime: Date.now() - startedAt.getTime(),
+      sources: sourceManager.getAllStatuses()
+    };
+  });
+}
+
 // src/server/routes/control.ts
 function registerControlRoutes(app, sourceManager, endpointRegistry, configCallbacks) {
   app.get("/api/_control/sources", async () => {
@@ -2512,33 +3285,6 @@ function sendAllPanels(res, queries, sourceManager) {
   }
 }
 
-// src/server/activity-log.ts
-var MAX_ENTRIES = 100;
-var entries = [];
-function logActivity(level, message) {
-  entries.push({
-    time: (/* @__PURE__ */ new Date()).toISOString(),
-    level,
-    message
-  });
-  if (entries.length > MAX_ENTRIES) {
-    entries.splice(0, entries.length - MAX_ENTRIES);
-  }
-}
-function getActivityLog(since) {
-  if (!since) return [...entries];
-  return entries.filter((e) => e.time > since);
-}
-function info(msg) {
-  logActivity("info", msg);
-}
-function warn(msg) {
-  logActivity("warn", msg);
-}
-function error(msg) {
-  logActivity("error", msg);
-}
-
 // src/server/app.ts
 async function createServer(config, configPath, cwd) {
   const app = Fastify({ logger: false });
@@ -2599,8 +3345,12 @@ async function createServer(config, configPath, cwd) {
   registerControlRoutes(app, sourceManager, { endpoints }, configCallbacks);
   registerSSERoutes(app, sourceManager);
   registerDynamicRoutes(app, sourceManager, endpoints);
+  const watchManager = new WatchManager(sourceManager);
+  if (config.watches && Object.keys(config.watches).length > 0) {
+    watchManager.start(config.watches);
+  }
   info("Server ready");
-  return { app, sourceManager, endpoints };
+  return { app, sourceManager, endpoints, watchManager };
 }
 
 // src/utils/banner.ts
@@ -2665,8 +3415,8 @@ function printServerStartup(opts) {
 // src/commands/serve.ts
 async function serveCommand(opts) {
   const cwd = process.cwd();
-  const pqDir = resolve4(cwd, ".pipequery");
-  const serverJsonPath = resolve4(pqDir, "server.json");
+  const pqDir = resolve5(cwd, ".pipequery");
+  const serverJsonPath = resolve5(pqDir, "server.json");
   if (opts.stop) {
     return stopDaemon(serverJsonPath);
   }
@@ -2678,7 +3428,7 @@ async function serveCommand(opts) {
   }
   const { app, sourceManager } = await createServer(config, configPath, cwd);
   await mkdir(pqDir, { recursive: true });
-  const logPath = resolve4(pqDir, "server.log");
+  const logPath = resolve5(pqDir, "server.log");
   await writeFile3(serverJsonPath, JSON.stringify({ url: `http://localhost:${port}`, pid: process.pid, daemon: false, log: logPath }));
   await app.listen({ port, host });
   const sourceCount = sourceManager.getSourceNames().length;
@@ -2700,9 +3450,9 @@ async function serveCommand(opts) {
   process.on("SIGTERM", shutdown);
 }
 async function startDaemon(cwd, port, host) {
-  const pqDir = resolve4(cwd, ".pipequery");
-  const serverJsonPath = resolve4(pqDir, "server.json");
-  const logPath = resolve4(pqDir, "server.log");
+  const pqDir = resolve5(cwd, ".pipequery");
+  const serverJsonPath = resolve5(pqDir, "server.json");
+  const logPath = resolve5(pqDir, "server.log");
   if (existsSync3(serverJsonPath)) {
     try {
       const info2 = JSON.parse(await readFile3(serverJsonPath, "utf-8"));
@@ -2759,11 +3509,11 @@ import chalk4 from "chalk";
 
 // src/utils/server-discovery.ts
 import { readFile as readFile4 } from "fs/promises";
-import { resolve as resolve5 } from "path";
+import { resolve as resolve6 } from "path";
 import { existsSync as existsSync4 } from "fs";
 async function getServerUrl() {
   const cwd = process.cwd();
-  const serverJsonPath = resolve5(cwd, ".pipequery", "server.json");
+  const serverJsonPath = resolve6(cwd, ".pipequery", "server.json");
   if (existsSync4(serverJsonPath)) {
     try {
       const info2 = JSON.parse(await readFile4(serverJsonPath, "utf-8"));
@@ -2805,14 +3555,14 @@ async function queryCommand(expression, opts) {
     return;
   }
   if (Array.isArray(result) && result.length > 0 && typeof result[0] === "object") {
-    renderTable(result);
+    renderTable2(result);
   } else if (typeof result === "object" && result !== null && !Array.isArray(result)) {
-    renderTable([result]);
+    renderTable2([result]);
   } else {
     console.log(result);
   }
 }
-function renderTable(rows) {
+function renderTable2(rows) {
   if (rows.length === 0) {
     log.dim("(empty result)");
     return;
@@ -2906,8 +3656,60 @@ async function sourceAddCommand(name, opts) {
         ...opts.watch ? { watch: true } : {}
       };
       break;
+    case "postgres":
+      if (!opts.url) throw new Error("--url is required for Postgres sources");
+      if (!opts.query) throw new Error("--query is required for Postgres sources");
+      sourceConfig = {
+        type: "postgres",
+        url: opts.url,
+        query: opts.query,
+        interval: opts.interval ?? "30s",
+        ...opts.ssl === "no-verify" ? { ssl: "no-verify" } : {},
+        ...opts.ssl === "false" ? { ssl: false } : {},
+        ...opts.maxRows ? { maxRows: Number.parseInt(opts.maxRows, 10) } : {}
+      };
+      break;
+    case "mysql":
+      if (!opts.url) throw new Error("--url is required for MySQL sources");
+      if (!opts.query) throw new Error("--query is required for MySQL sources");
+      sourceConfig = {
+        type: "mysql",
+        url: opts.url,
+        query: opts.query,
+        interval: opts.interval ?? "30s",
+        ...opts.ssl === "no-verify" ? { ssl: "no-verify" } : {},
+        ...opts.ssl === "false" ? { ssl: false } : {},
+        ...opts.maxRows ? { maxRows: Number.parseInt(opts.maxRows, 10) } : {}
+      };
+      break;
+    case "sqlite":
+      if (!opts.path) throw new Error("--path is required for SQLite sources");
+      if (!opts.query) throw new Error("--query is required for SQLite sources");
+      sourceConfig = {
+        type: "sqlite",
+        path: opts.path,
+        query: opts.query,
+        interval: opts.interval ?? "30s",
+        ...opts.maxRows ? { maxRows: Number.parseInt(opts.maxRows, 10) } : {},
+        ...opts.readonly === false ? { readonly: false } : {}
+      };
+      break;
+    case "kafka":
+      if (!opts.brokers) throw new Error("--brokers is required for Kafka sources (comma-separated)");
+      if (!opts.topic) throw new Error("--topic is required for Kafka sources");
+      sourceConfig = {
+        type: "kafka",
+        brokers: opts.brokers,
+        topic: opts.topic,
+        ...opts.groupId ? { groupId: opts.groupId } : {},
+        ...opts.fromBeginning ? { fromBeginning: true } : {},
+        ...opts.maxBuffer ? { maxBuffer: Number.parseInt(opts.maxBuffer, 10) } : {},
+        ...opts.valueFormat ? { valueFormat: opts.valueFormat } : {},
+        ...opts.ssl === "true" ? { ssl: true } : {}
+      };
+      break;
     default:
-      throw new Error(`Unknown source type: ${opts.type}. Use: rest, websocket, file`);
+      throw new Error(`Unknown source type: ${opts.type}. Use: rest, websocket, file, postgres, mysql, sqlite, kafka`);
   }
   config.sources[name] = sourceConfig;
   await saveConfig(config, configPath);
@@ -3862,7 +4664,7 @@ async function dashboardCommand(opts) {
 import React6 from "react";
 import { render as render2 } from "ink";
 import { existsSync as existsSync5, readFileSync } from "fs";
-import { resolve as resolve6 } from "path";
+import { resolve as resolve7 } from "path";
 
 // src/tui/MonitorApp.tsx
 import { useState as useState5, useEffect as useEffect4 } from "react";
@@ -4046,7 +4848,7 @@ function MonitorApp({ serverUrl }) {
 // src/commands/monitor.ts
 async function monitorCommand() {
   const serverUrl = await getServerUrl();
-  const discoveryPath = resolve6(process.cwd(), ".pipequery", "server.json");
+  const discoveryPath = resolve7(process.cwd(), ".pipequery", "server.json");
   let logPath;
   if (existsSync5(discoveryPath)) {
     try {
@@ -4058,7 +4860,7 @@ async function monitorCommand() {
     }
   }
   if (!logPath) {
-    const fallback = resolve6(process.cwd(), ".pipequery", "server.log");
+    const fallback = resolve7(process.cwd(), ".pipequery", "server.log");
     if (existsSync5(fallback)) {
       logPath = fallback;
     }
@@ -4078,7 +4880,7 @@ async function monitorCommand() {
 
 // src/commands/remote.ts
 import { writeFile as writeFile4 } from "fs/promises";
-import { resolve as resolve7 } from "path";
+import { resolve as resolve8 } from "path";
 
 // src/docker/templates.ts
 function generateDockerfile(port) {
@@ -4128,9 +4930,9 @@ async function remoteDeployCommand() {
   const cwd = process.cwd();
   const { config } = await loadConfig(cwd);
   const port = config.server.port;
-  await writeFile4(resolve7(cwd, "Dockerfile"), generateDockerfile(port));
-  await writeFile4(resolve7(cwd, "docker-compose.yaml"), generateDockerCompose(port));
-  await writeFile4(resolve7(cwd, ".dockerignore"), generateDockerignore());
+  await writeFile4(resolve8(cwd, "Dockerfile"), generateDockerfile(port));
+  await writeFile4(resolve8(cwd, "docker-compose.yaml"), generateDockerCompose(port));
+  await writeFile4(resolve8(cwd, ".dockerignore"), generateDockerignore());
   log.success("Generated Dockerfile, docker-compose.yaml, and .dockerignore");
   log.info(`Run: docker compose up -d --build`);
   log.info(`Then: pq remote connect http://localhost:${port}`);
@@ -4140,7 +4942,7 @@ async function loadOrCreateConfig(cwd) {
   if (existing) {
     return loadConfig(cwd);
   }
-  const configPath = resolve7(cwd, "pipequery.yaml");
+  const configPath = resolve8(cwd, "pipequery.yaml");
   const config = {
     server: { ...DEFAULT_CONFIG.server },
     sources: {},
@@ -4188,6 +4990,1052 @@ async function remoteStatusCommand() {
   }
 }
 
+// src/mcp/provider.ts
+var LocalProvider = class {
+  constructor(config, cwd) {
+    this.config = config;
+    this.sourceManager = new SourceManager(cwd);
+    this.endpoints = new Map(Object.entries(config.endpoints));
+    this.ready = this.bootSources();
+  }
+  config;
+  sourceManager;
+  endpoints;
+  ready;
+  async bootSources() {
+    for (const [name, src] of Object.entries(this.config.sources)) {
+      try {
+        await this.sourceManager.addSource(name, src);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[pipequery-mcp] Source "${name}" failed to start: ${msg}
+`);
+      }
+    }
+  }
+  async listSources() {
+    await this.ready;
+    const statuses = this.sourceManager.getAllStatuses();
+    return Object.entries(statuses).map(([name, status]) => ({ name, status }));
+  }
+  async describeSource(name, sampleSize = 5) {
+    await this.ready;
+    const status = this.sourceManager.getSourceStatus(name);
+    const data = this.sourceManager.getSourceData(name);
+    if (!status || !data) return void 0;
+    const sample = data.slice(0, sampleSize);
+    const fields = inferFields(data);
+    return { name, status, sample, fields };
+  }
+  async listEndpoints() {
+    await this.ready;
+    return [...this.endpoints].map(([path, config]) => ({ path, config }));
+  }
+  async callEndpoint(path) {
+    await this.ready;
+    const endpoint2 = this.endpoints.get(path);
+    if (!endpoint2) {
+      throw new Error(`Endpoint "${path}" not found`);
+    }
+    const context = this.sourceManager.getContext();
+    return query(context, endpoint2.query);
+  }
+  async runQuery(expression) {
+    await this.ready;
+    const context = this.sourceManager.getContext();
+    return query(context, expression);
+  }
+  async dispose() {
+    await this.sourceManager.dispose();
+  }
+  // Exposed for the HTTP plugin that wants to mount the MCP server into an
+  // existing `createServer` instance; the caller passes in their own manager.
+  static withSourceManager(sourceManager, endpoints) {
+    return new AttachedLocalProvider(sourceManager, endpoints);
+  }
+};
+var AttachedLocalProvider = class {
+  constructor(sourceManager, endpoints) {
+    this.sourceManager = sourceManager;
+    this.endpoints = endpoints;
+  }
+  sourceManager;
+  endpoints;
+  async listSources() {
+    const statuses = this.sourceManager.getAllStatuses();
+    return Object.entries(statuses).map(([name, status]) => ({ name, status }));
+  }
+  async describeSource(name, sampleSize = 5) {
+    const status = this.sourceManager.getSourceStatus(name);
+    const data = this.sourceManager.getSourceData(name);
+    if (!status || !data) return void 0;
+    return { name, status, sample: data.slice(0, sampleSize), fields: inferFields(data) };
+  }
+  async listEndpoints() {
+    return [...this.endpoints].map(([path, config]) => ({ path, config }));
+  }
+  async callEndpoint(path) {
+    const endpoint2 = this.endpoints.get(path);
+    if (!endpoint2) throw new Error(`Endpoint "${path}" not found`);
+    return query(this.sourceManager.getContext(), endpoint2.query);
+  }
+  async runQuery(expression) {
+    return query(this.sourceManager.getContext(), expression);
+  }
+  async dispose() {
+  }
+};
+var AttachedProvider = class {
+  constructor(baseUrl) {
+    this.baseUrl = baseUrl;
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+  }
+  baseUrl;
+  async get(path) {
+    const res = await fetch(`${this.baseUrl}${path}`);
+    if (!res.ok) throw new Error(`GET ${path} failed: HTTP ${res.status}`);
+    return res.json();
+  }
+  async post(path, body) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) throw new Error(`POST ${path} failed: HTTP ${res.status}`);
+    return res.json();
+  }
+  async listSources() {
+    const statuses = await this.get("/api/_control/sources");
+    return Object.entries(statuses).map(([name, status]) => ({ name, status }));
+  }
+  async describeSource(name, sampleSize = 5) {
+    const res = await this.post(`/api/_control/sources/${encodeURIComponent(name)}/test`, {});
+    if (!res.ok || !res.status || !res.sample) return void 0;
+    return {
+      name,
+      status: res.status,
+      sample: res.sample.slice(0, sampleSize),
+      fields: inferFields(res.sample)
+    };
+  }
+  async listEndpoints() {
+    const endpoints = await this.get("/api/_control/endpoints");
+    return Object.entries(endpoints).map(([path, config]) => ({ path, config }));
+  }
+  async callEndpoint(path) {
+    const normalized = path.startsWith("/") ? path : `/${path}`;
+    const res = await fetch(`${this.baseUrl}${normalized}`);
+    if (!res.ok) throw new Error(`GET ${normalized} failed: HTTP ${res.status}`);
+    return res.json();
+  }
+  async runQuery(expression) {
+    const res = await this.post(
+      "/api/_control/query",
+      { query: expression }
+    );
+    if (!res.ok) throw new Error(res.error ?? "Query failed");
+    return res.result;
+  }
+  async dispose() {
+  }
+};
+function inferFields(rows) {
+  const fields = /* @__PURE__ */ new Set();
+  for (const row of rows.slice(0, 20)) {
+    if (row && typeof row === "object" && !Array.isArray(row)) {
+      for (const k of Object.keys(row)) fields.add(k);
+    }
+  }
+  return [...fields];
+}
+
+// src/mcp/stdio.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/mcp/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+var DEFAULT_INFO = {
+  name: "pipequery",
+  version: "0.1.0"
+};
+function createMcpServer(provider, info2 = DEFAULT_INFO) {
+  const mcp2 = new McpServer(info2);
+  mcp2.registerTool(
+    "query",
+    {
+      title: "Run a PipeQuery expression",
+      description: "Execute a PipeQuery pipe-based expression (e.g. `crypto | where(price > 100) | sort(price desc) | first(5)`) against all currently configured sources. Returns the computed result as JSON.",
+      inputSchema: {
+        expression: z.string().min(1).describe("The PipeQuery expression. Source names used in the expression must be configured; call `list_sources` to see them.")
+      }
+    },
+    async ({ expression }) => {
+      const result = await provider.runQuery(expression);
+      return toolResult(result);
+    }
+  );
+  mcp2.registerTool(
+    "list_sources",
+    {
+      title: "List configured data sources",
+      description: "List every data source configured in pipequery.yaml along with its current health, row count, and last-fetch timestamp."
+    },
+    async () => {
+      const sources = await provider.listSources();
+      return toolResult({ count: sources.length, sources });
+    }
+  );
+  mcp2.registerTool(
+    "describe_source",
+    {
+      title: "Describe a data source",
+      description: "Return a sample of rows and the inferred field names for a single source. Useful before constructing a query.",
+      inputSchema: {
+        name: z.string().min(1).describe("Source name as returned by list_sources."),
+        sample_size: z.number().int().positive().max(100).optional().describe("Number of rows to include in the sample. Defaults to 5, max 100.")
+      }
+    },
+    async ({ name, sample_size }) => {
+      const description = await provider.describeSource(name, sample_size);
+      if (!description) {
+        return toolError(`Source "${name}" not found`);
+      }
+      return toolResult(description);
+    }
+  );
+  mcp2.registerTool(
+    "list_endpoints",
+    {
+      title: "List pre-configured query endpoints",
+      description: "Return every endpoint declared in pipequery.yaml along with its stored query expression. These endpoints can be invoked via `call_endpoint`."
+    },
+    async () => {
+      const endpoints = await provider.listEndpoints();
+      return toolResult({ count: endpoints.length, endpoints });
+    }
+  );
+  mcp2.registerTool(
+    "call_endpoint",
+    {
+      title: "Invoke a pre-configured endpoint",
+      description: "Execute the stored query for an endpoint path (e.g. `/api/top-coins`) and return its JSON result. Equivalent to the HTTP endpoint on `pq serve`, without needing a live HTTP call.",
+      inputSchema: {
+        path: z.string().min(1).describe("Endpoint path, exactly as declared in pipequery.yaml (typically begins with `/`).")
+      }
+    },
+    async ({ path }) => {
+      try {
+        const result = await provider.callEndpoint(path);
+        return toolResult(result);
+      } catch (err) {
+        return toolError(err instanceof Error ? err.message : String(err));
+      }
+    }
+  );
+  return mcp2;
+}
+function toolResult(data) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+  };
+}
+function toolError(message) {
+  return {
+    content: [{ type: "text", text: message }],
+    isError: true
+  };
+}
+
+// src/mcp/stdio.ts
+async function runStdio(provider, info2) {
+  const mcp2 = createMcpServer(provider, info2);
+  const transport = new StdioServerTransport();
+  await mcp2.connect(transport);
+  const cleanup = async () => {
+    try {
+      await mcp2.close();
+    } finally {
+      await provider.dispose();
+    }
+  };
+  process.stdin.on("close", () => {
+    void cleanup().then(() => process.exit(0));
+  });
+  process.on("SIGINT", () => void cleanup().then(() => process.exit(0)));
+  process.on("SIGTERM", () => void cleanup().then(() => process.exit(0)));
+}
+
+// src/mcp/http.ts
+import { createServer as createHttpServer } from "http";
+import { randomUUID } from "crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+async function runHttp(provider, opts) {
+  const host = opts.host ?? "127.0.0.1";
+  const port = opts.port;
+  const mountPath = opts.path ?? "/mcp";
+  const transports = /* @__PURE__ */ new Map();
+  const authToken = opts.authToken;
+  if (!authToken) {
+    process.stderr.write(
+      "[pipequery-mcp] WARNING: HTTP endpoint is UNAUTHENTICATED. Set --auth-token or PIPEQUERY_MCP_TOKEN for anything beyond localhost.\n"
+    );
+  }
+  const attachTransport = async () => {
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID(),
+      onsessioninitialized: (sessionId) => {
+        transports.set(sessionId, transport);
+      },
+      onsessionclosed: (sessionId) => {
+        transports.delete(sessionId);
+      }
+    });
+    const mcp2 = createMcpServer(provider, opts.info);
+    await mcp2.connect(transport);
+    return transport;
+  };
+  const server = createHttpServer(async (req, res) => {
+    if (!req.url) {
+      res.statusCode = 400;
+      res.end("Bad Request");
+      return;
+    }
+    const requestPath = req.url.split("?")[0];
+    if (requestPath !== mountPath) {
+      res.statusCode = 404;
+      res.end("Not Found");
+      return;
+    }
+    if (authToken && !isAuthorized(req, authToken)) {
+      res.statusCode = 401;
+      res.setHeader("content-type", "application/json");
+      res.setHeader("www-authenticate", 'Bearer realm="pipequery-mcp"');
+      res.end(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          error: { code: -32001, message: "Unauthorized: missing or invalid bearer token" },
+          id: null
+        })
+      );
+      return;
+    }
+    try {
+      const body = await readJsonBody(req);
+      const sessionId = getSessionId(req);
+      let transport = sessionId ? transports.get(sessionId) : void 0;
+      if (!transport) {
+        transport = await attachTransport();
+      }
+      await transport.handleRequest(req, res, body);
+    } catch (err) {
+      process.stderr.write(
+        `[pipequery-mcp] transport error: ${err instanceof Error ? err.stack ?? err.message : String(err)}
+`
+      );
+      if (!res.headersSent) {
+        res.statusCode = 500;
+        res.setHeader("content-type", "application/json");
+        res.end(JSON.stringify({
+          jsonrpc: "2.0",
+          error: {
+            code: -32603,
+            message: err instanceof Error ? err.message : String(err)
+          },
+          id: null
+        }));
+      } else {
+        res.end();
+      }
+    }
+  });
+  await new Promise((resolve10) => server.listen(port, host, resolve10));
+  return {
+    url: `http://${host}:${port}${mountPath}`,
+    async close() {
+      await new Promise((resolve10, reject) => {
+        server.close((err) => err ? reject(err) : resolve10());
+      });
+      for (const t of transports.values()) {
+        await t.close();
+      }
+      transports.clear();
+      await provider.dispose();
+    }
+  };
+}
+function isAuthorized(req, expected) {
+  const header = req.headers["authorization"];
+  const raw = typeof header === "string" ? header : Array.isArray(header) ? header[0] : void 0;
+  if (!raw) return false;
+  const match = raw.match(/^Bearer\s+(.+)$/i);
+  if (!match) return false;
+  const token = match[1].trim();
+  return timingSafeEqual(token, expected);
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+function getSessionId(req) {
+  const header = req.headers["mcp-session-id"];
+  if (typeof header === "string") return header;
+  if (Array.isArray(header)) return header[0];
+  return void 0;
+}
+async function readJsonBody(req) {
+  const method = req.method?.toUpperCase();
+  if (method === "GET" || method === "DELETE") return void 0;
+  const chunks = [];
+  for await (const chunk of req) {
+    chunks.push(chunk);
+  }
+  if (chunks.length === 0) return void 0;
+  const text = Buffer.concat(chunks).toString("utf8");
+  if (!text.trim()) return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error("Invalid JSON body");
+  }
+}
+
+// src/commands/mcp.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+async function mcpServeCommand(opts) {
+  const provider = await buildProvider(opts.attach);
+  const isStdio = !opts.http;
+  if (isStdio) {
+    await runStdio(provider);
+    return;
+  }
+  const port = opts.port ?? 3001;
+  const host = opts.host ?? "127.0.0.1";
+  const authToken = opts.authToken ?? process.env.PIPEQUERY_MCP_TOKEN;
+  const handle = await runHttp(provider, { port, host, authToken });
+  log.success(`PipeQuery MCP server listening on ${handle.url}`);
+  log.info("Connect any MCP client to the URL above (Claude, Cursor, custom agents).");
+  log.info("Press Ctrl+C to stop.");
+  const shutdown = async () => {
+    log.info("Shutting down MCP server...");
+    await handle.close();
+    process.exit(0);
+  };
+  process.on("SIGINT", () => void shutdown());
+  process.on("SIGTERM", () => void shutdown());
+}
+async function mcpInspectCommand(opts) {
+  const provider = await buildProvider(opts.attach);
+  const mcp2 = createMcpServer(provider);
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  await mcp2.connect(serverTransport);
+  const client = new Client({ name: "pq-mcp-inspect", version: "0.1.0" });
+  await client.connect(clientTransport);
+  try {
+    const { tools } = await client.listTools();
+    const summary = {
+      server: "pipequery",
+      toolCount: tools.length,
+      tools: tools.map((t) => ({
+        name: t.name,
+        title: t.title,
+        description: t.description,
+        inputSchema: t.inputSchema
+      }))
+    };
+    process.stdout.write(JSON.stringify(summary, null, 2) + "\n");
+  } finally {
+    await client.close();
+    await mcp2.close();
+    await provider.dispose();
+  }
+}
+async function buildProvider(attachUrl) {
+  if (attachUrl) {
+    return new AttachedProvider(attachUrl);
+  }
+  const cwd = process.cwd();
+  const { config } = await loadConfig(cwd);
+  return new LocalProvider(config, cwd);
+}
+
+// src/telegram/bot.ts
+import { Bot as Bot2, GrammyError, HttpError } from "grammy";
+function buildBot(token, provider, opts = {}) {
+  const bot = new Bot2(token);
+  const allowList = normalizeAllowList(opts.allowUsers ?? []);
+  const nl = opts.nl;
+  bot.use(async (ctx, next) => {
+    if (allowList.size === 0) {
+      const id = ctx.from?.id;
+      if (id) trackUnauthSeen(id, ctx.from?.username);
+      await next();
+      return;
+    }
+    if (!isAllowed(ctx, allowList)) {
+      await ctx.reply("\u{1F512} You are not authorized to use this bot.");
+      return;
+    }
+    await next();
+  });
+  bot.command("start", async (ctx) => {
+    await ctx.reply(
+      [
+        "\u{1F44B} <b>pipequery bot</b>",
+        "",
+        "Run pipequery expressions against your configured data sources from chat.",
+        "",
+        "<b>Commands</b>",
+        "/sources \u2014 list configured sources and their health",
+        "/describe &lt;name&gt; \u2014 sample rows + field names",
+        "/endpoints \u2014 list pre-configured endpoints",
+        "/call &lt;path&gt; \u2014 execute a pre-configured endpoint",
+        "/query &lt;expression&gt; \u2014 run an arbitrary pipequery expression",
+        "/help \u2014 this message"
+      ].join("\n"),
+      { parse_mode: "HTML" }
+    );
+  });
+  bot.command("help", async (ctx) => {
+    const lines = [
+      "<b>Examples</b>",
+      "<code>/sources</code>",
+      "<code>/describe products</code>",
+      "<code>/query products | sort(price desc) | first(5)</code>",
+      "<code>/query crypto | where(price &gt; 100) | rollup(avg(price) as avg)</code>",
+      "<code>/call /api/top-coins</code>"
+    ];
+    if (nl) {
+      lines.push(
+        "",
+        "<b>Natural language</b>",
+        "Send any plain-text message (no leading <code>/</code>) and I'll translate it into a pipequery expression and run it.",
+        'Example: <i>"top 5 most expensive paid orders"</i>'
+      );
+    }
+    lines.push(
+      "",
+      "<b>Tips</b>",
+      "\u2022 Wrap quoted strings carefully \u2014 Telegram's autocorrect can mangle them. Send long expressions as a separate message.",
+      "\u2022 Use <code>/describe &lt;source&gt;</code> to discover field names before constructing a where clause.",
+      "\u2022 Results &gt; 30 rows are truncated with a footer; tighten your query to see all of them."
+    );
+    await ctx.reply(lines.join("\n"), { parse_mode: "HTML" });
+  });
+  bot.command("sources", async (ctx) => {
+    try {
+      const sources = await provider.listSources();
+      if (sources.length === 0) {
+        await ctx.reply("<i>No sources configured.</i>", { parse_mode: "HTML" });
+        return;
+      }
+      const lines = sources.map((s) => {
+        const dot = s.status.healthy ? "\u{1F7E2}" : "\u{1F534}";
+        const rowCount = s.status.rowCount.toLocaleString();
+        const err = s.status.error ? ` <i>(${escapeHtml(s.status.error)})</i>` : "";
+        return `${dot} <b>${escapeHtml(s.name)}</b> \u2014 ${rowCount} rows${err}`;
+      });
+      await ctx.reply(lines.join("\n"), { parse_mode: "HTML" });
+    } catch (err) {
+      await ctx.reply(formatError(err), { parse_mode: "HTML" });
+    }
+  });
+  bot.command("describe", async (ctx) => {
+    const name = ctx.match.trim();
+    if (!name) {
+      await ctx.reply("Usage: <code>/describe &lt;source-name&gt;</code>", { parse_mode: "HTML" });
+      return;
+    }
+    try {
+      const desc = await provider.describeSource(name, 5);
+      if (!desc) {
+        await ctx.reply(`Source <code>${escapeHtml(name)}</code> not found.`, { parse_mode: "HTML" });
+        return;
+      }
+      const fields = desc.fields.length ? desc.fields.map((f) => `<code>${escapeHtml(f)}</code>`).join(", ") : "<i>(none inferred)</i>";
+      const sample = formatResult(desc.sample);
+      await ctx.reply(
+        `<b>${escapeHtml(name)}</b> \u2014 ${desc.status.rowCount.toLocaleString()} rows
+<b>Fields:</b> ${fields}
+
+<b>Sample:</b>
+${sample}`,
+        { parse_mode: "HTML" }
+      );
+    } catch (err) {
+      await ctx.reply(formatError(err), { parse_mode: "HTML" });
+    }
+  });
+  bot.command("endpoints", async (ctx) => {
+    try {
+      const endpoints = await provider.listEndpoints();
+      if (endpoints.length === 0) {
+        await ctx.reply("<i>No endpoints configured.</i>", { parse_mode: "HTML" });
+        return;
+      }
+      const lines = endpoints.map(
+        (e) => `<b>${escapeHtml(e.path)}</b>
+<code>${escapeHtml(e.config.query)}</code>`
+      );
+      await ctx.reply(lines.join("\n\n"), { parse_mode: "HTML" });
+    } catch (err) {
+      await ctx.reply(formatError(err), { parse_mode: "HTML" });
+    }
+  });
+  bot.command("call", async (ctx) => {
+    const path = ctx.match.trim();
+    if (!path) {
+      await ctx.reply("Usage: <code>/call &lt;endpoint-path&gt;</code>", { parse_mode: "HTML" });
+      return;
+    }
+    try {
+      const result = await provider.callEndpoint(path);
+      await ctx.reply(formatResult(result), { parse_mode: "HTML" });
+    } catch (err) {
+      await ctx.reply(formatError(err), { parse_mode: "HTML" });
+    }
+  });
+  bot.command("query", async (ctx) => {
+    const expr = ctx.match.trim();
+    if (!expr) {
+      await ctx.reply("Usage: <code>/query &lt;pipequery expression&gt;</code>", { parse_mode: "HTML" });
+      return;
+    }
+    try {
+      const result = await provider.runQuery(expr);
+      await ctx.reply(formatResult(result), { parse_mode: "HTML" });
+    } catch (err) {
+      await ctx.reply(formatError(err), { parse_mode: "HTML" });
+    }
+  });
+  bot.on("message:text", async (ctx) => {
+    const text = ctx.message.text.trim();
+    if (!text || text.startsWith("/")) return;
+    if (!nl) {
+      await ctx.reply(
+        "I don't recognise that. Use <code>/help</code> to see the available commands. Natural-language queries are disabled \u2014 start the bot with <code>--anthropic-key</code> to enable them.",
+        { parse_mode: "HTML" }
+      );
+      return;
+    }
+    try {
+      await ctx.replyWithChatAction("typing");
+      const { expression, explanation } = await nl.translate(text);
+      if (!expression) {
+        const reason = explanation || "I couldn't translate that into a pipequery expression.";
+        await ctx.reply(`\u{1F914} ${escapeHtml(reason)}`, { parse_mode: "HTML" });
+        return;
+      }
+      const result = await provider.runQuery(expression);
+      const header = `<i>${escapeHtml(explanation || "Translated query")}</i>
+<code>${escapeHtml(expression)}</code>
+
+`;
+      await ctx.reply(header + formatResult(result), { parse_mode: "HTML" });
+    } catch (err) {
+      await ctx.reply(formatError(err), { parse_mode: "HTML" });
+    }
+  });
+  bot.catch((err) => {
+    if (err.error instanceof GrammyError) {
+      process.stderr.write(`[pipequery-telegram] grammy error: ${err.error.description}
+`);
+    } else if (err.error instanceof HttpError) {
+      process.stderr.write(`[pipequery-telegram] http error: ${err.error.message}
+`);
+    } else {
+      process.stderr.write(`[pipequery-telegram] unhandled: ${err.error}
+`);
+    }
+  });
+  return bot;
+}
+function normalizeAllowList(entries2) {
+  const set = /* @__PURE__ */ new Set();
+  for (const raw of entries2) {
+    const trimmed = raw.trim().replace(/^@/, "").toLowerCase();
+    if (trimmed) set.add(trimmed);
+  }
+  return set;
+}
+function isAllowed(ctx, allowList) {
+  const from = ctx.from;
+  if (!from) return false;
+  if (allowList.has(String(from.id))) return true;
+  if (from.username && allowList.has(from.username.toLowerCase())) return true;
+  return false;
+}
+var seenUnauth = /* @__PURE__ */ new Set();
+function trackUnauthSeen(id, username) {
+  if (seenUnauth.has(id)) return;
+  seenUnauth.add(id);
+  process.stderr.write(
+    `[pipequery-telegram] WARNING: bot has no allowlist; user "${username ?? id}" can query freely. Restart with --allow-user @yourname to lock it down.
+`
+  );
+}
+
+// src/telegram/nl.ts
+import Anthropic from "@anthropic-ai/sdk";
+var MODEL = "claude-haiku-4-5";
+var MAX_TOKENS = 1024;
+var SCHEMA_TTL_MS = 6e4;
+function createNLTranslator(provider, opts) {
+  const client = opts.client ?? new Anthropic({ apiKey: opts.apiKey });
+  const model = opts.model ?? MODEL;
+  let cachedSchema = null;
+  async function getSchemaPreamble() {
+    const now = Date.now();
+    if (cachedSchema && now - cachedSchema.builtAt < SCHEMA_TTL_MS) {
+      return cachedSchema.text;
+    }
+    const text = await buildSchemaPreamble(provider);
+    cachedSchema = { text, builtAt: now };
+    return text;
+  }
+  async function translate(question) {
+    const schema = await getSchemaPreamble();
+    const response = await client.messages.create({
+      model,
+      max_tokens: MAX_TOKENS,
+      system: [
+        // Cache breakpoint #1 — the always-stable DSL grammar + instructions.
+        // This is the largest block and the one that benefits most from being
+        // cached across every translation request the bot ever serves.
+        {
+          type: "text",
+          text: SYSTEM_PROMPT,
+          cache_control: { type: "ephemeral" }
+        },
+        // Cache breakpoint #2 — the per-tenant source schema. Stable until
+        // the yaml changes (or SCHEMA_TTL_MS elapses).
+        {
+          type: "text",
+          text: schema,
+          cache_control: { type: "ephemeral" }
+        }
+      ],
+      messages: [
+        {
+          role: "user",
+          content: question
+        }
+      ]
+    });
+    const text = extractText(response);
+    return parseTranslation(text);
+  }
+  return {
+    translate,
+    invalidateSchema: () => {
+      cachedSchema = null;
+    }
+  };
+}
+async function buildSchemaPreamble(provider) {
+  const sources = await provider.listSources();
+  const endpoints = await provider.listEndpoints();
+  const sourceLines = [];
+  for (const s of sources) {
+    let fields = [];
+    try {
+      const desc = await provider.describeSource(s.name, 3);
+      if (desc) fields = desc.fields;
+    } catch {
+    }
+    const fieldStr = fields.length ? ` \u2014 fields: ${fields.join(", ")}` : "";
+    sourceLines.push(`- ${s.name} (${s.status.rowCount} rows)${fieldStr}`);
+  }
+  const endpointLines = endpoints.map((e) => `- ${e.path} \u2192 ${e.config.query}`);
+  return [
+    "## Available data sources",
+    sourceLines.length ? sourceLines.join("\n") : "(no sources configured)",
+    "",
+    "## Pre-defined endpoints",
+    endpointLines.length ? endpointLines.join("\n") : "(no endpoints configured)"
+  ].join("\n");
+}
+function extractText(response) {
+  const parts = [];
+  for (const block of response.content) {
+    if (block.type === "text") parts.push(block.text);
+  }
+  return parts.join("").trim();
+}
+function parseTranslation(raw) {
+  const cleaned = raw.replace(/^```json\s*/i, "").replace(/^```\s*/i, "").replace(/```\s*$/i, "").trim();
+  const start = cleaned.indexOf("{");
+  const end = cleaned.lastIndexOf("}");
+  if (start === -1 || end === -1 || end < start) {
+    throw new Error(`Translator returned non-JSON: ${truncate(raw, 200)}`);
+  }
+  const slice = cleaned.slice(start, end + 1);
+  let parsed;
+  try {
+    parsed = JSON.parse(slice);
+  } catch (err) {
+    throw new Error(`Translator returned invalid JSON: ${truncate(raw, 200)}`);
+  }
+  if (typeof parsed !== "object" || parsed === null || typeof parsed.expression !== "string") {
+    throw new Error(`Translator response missing "expression" field: ${truncate(raw, 200)}`);
+  }
+  const obj = parsed;
+  return {
+    expression: obj.expression.trim(),
+    explanation: typeof obj.explanation === "string" ? obj.explanation.trim() : ""
+  };
+}
+function truncate(s, n) {
+  return s.length > n ? `${s.slice(0, n)}\u2026` : s;
+}
+var SYSTEM_PROMPT = `You are a translator that converts natural-language questions into PipeQuery expressions.
+
+PipeQuery is a small, pipe-style query DSL. Every expression starts with a source name (or a literal array) and pipes into one or more operations using \`|\`. PipeQuery is read-only by construction \u2014 there is no DDL, DML, INSERT, UPDATE, DELETE, or DROP. You will never produce SQL.
+
+# Output contract
+
+You MUST respond with a SINGLE JSON object and nothing else. No prose, no markdown, no code fences.
+
+The object has exactly two fields:
+  - "expression": a string containing the PipeQuery expression to execute.
+  - "explanation": a one-sentence plain-English description of what the expression does.
+
+Example:
+{"expression": "orders | where(status == \\"paid\\") | sort(total desc) | first(5)", "explanation": "Top 5 paid orders by total."}
+
+If the user's question cannot be answered with the available sources, return:
+{"expression": "", "explanation": "<brief reason why no expression was produced>"}
+
+# Grammar
+
+Pipeline:
+  <source_name> | <operation> | <operation> | ...
+
+Sources are referenced by their bare name (no quotes). The available source names are listed in the schema preamble that follows this prompt.
+
+# Operations
+
+## where(<expression>)
+Filter rows. The expression is evaluated per row and must return a boolean.
+  - Comparison operators: ==  !=  >  >=  <  <=
+  - Logical operators: &&  ||  !
+  - Arithmetic: +  -  *  /  %
+  - Field reference: bare identifier (e.g., \`price\`, \`status\`)
+  - Strings: double-quoted ("paid")
+  - Numbers: 1, 1.5, -42
+  - Booleans: true, false
+  - Null: null
+
+Examples:
+  events | where(severity == "high")
+  trades | where(price > 100 && symbol == "BTC")
+  users | where(!banned)
+
+## sort(<field> asc|desc, ...)
+Sort by one or more fields. Direction is optional, defaults to asc.
+  orders | sort(total desc)
+  orders | sort(country asc, total desc)
+
+## first(N) / last(N)
+Take the first / last N rows. N must be a positive integer literal.
+  trades | sort(ts desc) | first(10)
+
+## distinct / distinct(field, ...)
+Deduplicate rows. With no args, dedupes on the full row; with args, dedupes on the listed fields.
+  users | distinct(email)
+
+## select(<expression>, ...)
+Project fields. Each expression can be a bare field, a computed expression, or an alias (\`expr as name\`).
+  orders | select(id, total, total * 0.1 as tax)
+
+## groupBy(<field>, ...) and rollup
+Aggregate. \`groupBy\` keeps groups; \`rollup\` collapses each group to one row with computed aggregates.
+
+  orders | rollup(country, sum(total) as revenue, count() as n)
+  trades | groupBy(symbol) | rollup(avg(price) as avg)
+
+Aggregate functions: sum, avg, min, max, count, median, stddev, var, percentile, distinct_count, first_value, last_value, vwap, wavg, pct, sharpe, calmar, sortino, info_ratio, drawdown, sum_abs, abs_sum.
+
+\`count()\` takes no field. \`percentile(field, p)\` and \`vwap(value, weight)\` take two args.
+
+## flatten / flatten(field)
+Unnest array values. With \`flatten(orders)\` each element of \`row.orders\` becomes its own row.
+
+## map(<expression>, ...)
+Transform each row into a new shape (similar to \`select\` but always emits a new object).
+
+## reduce(initial, accumulator)
+Fold rows into a single value. Rare; prefer rollup.
+
+## join(<source>, <condition>)
+Inner join with another source on a boolean condition. Use \`left\` and \`right\` to refer to fields.
+  orders | join(customers, left.customer_id == right.id)
+
+## pivot(<field>, <agg>, ...)
+Pivot rows into columns by a key field.
+
+# Conventions and best practices
+
+1. Prefer \`rollup\` over \`groupBy\` unless the caller wants the per-group rows kept.
+2. Always cap result size with \`first(N)\` for "top N" or "show me" questions; default to 10 if the user doesn't specify.
+3. Use the EXACT field names from the schema preamble. Do not invent fields.
+4. If two sources need to be joined and there's no obvious join key in the schema, prefer to ask for clarification by emitting the empty-expression form rather than guessing.
+5. Quote string literals with double quotes; escape internal double quotes with \\".
+6. Do not produce SQL, JavaScript, or English in the expression field \u2014 only PipeQuery.
+7. Numbers are bare; no thousands separators, no quotes.
+8. Comparisons against null use \`== null\` / \`!= null\`.
+
+# Worked examples
+
+Question: "What are the top 5 most expensive orders that were paid?"
+{"expression": "orders | where(status == \\"paid\\") | sort(total desc) | first(5)", "explanation": "Top 5 paid orders by total."}
+
+Question: "Average BTC price right now"
+{"expression": "trades | where(symbol == \\"BTC\\") | rollup(avg(price) as avg_price)", "explanation": "Average price across all BTC rows."}
+
+Question: "Revenue by country"
+{"expression": "orders | rollup(country, sum(total) as revenue) | sort(revenue desc)", "explanation": "Sum of order totals grouped by country, highest first."}
+
+Question: "How many distinct users placed an order?"
+{"expression": "orders | rollup(distinct_count(user_id) as users)", "explanation": "Count of unique user IDs in orders."}
+
+Question: "Show high-severity events from the last hour"
+(only answerable if the schema has a timestamp field; otherwise return empty.)
+{"expression": "events | where(severity == \\"high\\") | sort(ts desc) | first(50)", "explanation": "Most recent high-severity events, capped at 50."}
+
+Question: "Drop the orders table"
+{"expression": "", "explanation": "PipeQuery is read-only and cannot drop tables."}
+
+Question: "How many rows in foo?"
+(only answerable if a source named \`foo\` exists; otherwise return empty.)
+{"expression": "foo | rollup(count() as n)", "explanation": "Row count of foo."}
+
+# Reminder
+
+- Output exactly ONE JSON object.
+- The "expression" field must be valid PipeQuery referencing only sources from the schema preamble.
+- Use double quotes for strings, escape inner quotes as \\".
+- Default result cap is first(10) for unbounded "show me" questions unless an aggregation makes the result naturally small.
+- Never produce SQL or destructive operations.
+`;
+
+// src/commands/telegram.ts
+async function telegramServeCommand(opts) {
+  const token = opts.botToken ?? process.env.PIPEQUERY_TG_BOT_TOKEN;
+  if (!token) {
+    log.error(
+      "Bot token required. Pass --bot-token <token> or set PIPEQUERY_TG_BOT_TOKEN."
+    );
+    process.exit(1);
+  }
+  const anthropicKey = opts.anthropicKey ?? process.env.ANTHROPIC_API_KEY;
+  const provider = await buildProvider2(opts.attach);
+  const nl = anthropicKey ? createNLTranslator(provider, { apiKey: anthropicKey }) : void 0;
+  const bot = buildBot(token, provider, {
+    allowUsers: opts.allowUser ?? [],
+    nl
+  });
+  const me = await bot.api.getMe();
+  log.success(`Telegram bot listening as @${me.username} (id ${me.id})`);
+  if (nl) {
+    log.info("Natural-language translation enabled (claude-haiku-4-5).");
+  } else {
+    log.dim("Natural-language translation disabled. Pass --anthropic-key or set ANTHROPIC_API_KEY to enable.");
+  }
+  if (!opts.allowUser || opts.allowUser.length === 0) {
+    log.warn("No --allow-user set: anyone with the bot username can query. Add allowlist for production.");
+  }
+  log.info("Press Ctrl+C to stop.");
+  const shutdown = async () => {
+    log.info("Stopping bot...");
+    await bot.stop();
+    await provider.dispose();
+    process.exit(0);
+  };
+  process.on("SIGINT", () => void shutdown());
+  process.on("SIGTERM", () => void shutdown());
+  await bot.start();
+}
+async function buildProvider2(attachUrl) {
+  if (attachUrl) {
+    return new AttachedProvider(attachUrl);
+  }
+  const cwd = process.cwd();
+  const { config } = await loadConfig(cwd);
+  return new LocalProvider(config, cwd);
+}
+
+// src/commands/watch.ts
+import chalk7 from "chalk";
+async function watchListCommand() {
+  const cwd = process.cwd();
+  const { config } = await loadConfig(cwd);
+  const watches = config.watches ?? {};
+  const entries2 = Object.entries(watches);
+  if (entries2.length === 0) {
+    log.dim("No watches configured. Add one with: pq watch add <name>");
+    return;
+  }
+  console.log(chalk7.bold("Watches:\n"));
+  for (const [name, w] of entries2) {
+    const interval = w.interval ?? "60s";
+    const fireWhen = w.fireWhen ?? "when_non_empty";
+    const channels = Object.keys(w.notify).join(", ") || "<none>";
+    console.log(`  ${chalk7.bold(name)}  ${chalk7.dim(`every ${interval} \u2022 ${fireWhen}`)}`);
+    console.log(`    ${chalk7.dim("query:  ")}${w.query}`);
+    console.log(`    ${chalk7.dim("notify: ")}${channels}`);
+  }
+}
+async function watchAddCommand(name, opts) {
+  const cwd = process.cwd();
+  const { config, path: configPath } = await loadConfig(cwd);
+  if (!opts.telegramChatId) {
+    throw new Error("--telegram-chat-id is required (only Telegram notifier supported in v1)");
+  }
+  const fireWhen = opts.fireWhen ?? "when_non_empty";
+  if (!["when_non_empty", "when_empty", "on_change"].includes(fireWhen)) {
+    throw new Error(`--fire-when must be one of: when_non_empty, when_empty, on_change`);
+  }
+  const watch3 = {
+    query: opts.query,
+    ...opts.interval ? { interval: opts.interval } : {},
+    fireWhen,
+    notify: {
+      telegram: {
+        chatId: parseChatId(opts.telegramChatId),
+        ...opts.telegramBotToken ? { botToken: opts.telegramBotToken } : {},
+        ...opts.telegramMessage ? { message: opts.telegramMessage } : {}
+      }
+    }
+  };
+  config.watches = config.watches ?? {};
+  config.watches[name] = watch3;
+  await saveConfig(config, configPath);
+  log.success(`Watch "${name}" added. Restart \`pq serve\` to activate.`);
+}
+async function watchRemoveCommand(name) {
+  const cwd = process.cwd();
+  const { config, path: configPath } = await loadConfig(cwd);
+  if (!config.watches?.[name]) {
+    log.error(`Watch "${name}" not found`);
+    return;
+  }
+  delete config.watches[name];
+  await saveConfig(config, configPath);
+  log.success(`Watch "${name}" removed. Restart \`pq serve\` to apply.`);
+}
+function parseChatId(input) {
+  if (/^-?\d+$/.test(input)) {
+    const n = Number(input);
+    if (Number.isFinite(n) && Number.isSafeInteger(n)) return n;
+  }
+  return input;
+}
+
 // src/commands/completion.ts
 var BASH_COMPLETION = `###-begin-pq-completions-###
 _pq_completions() {
@@ -4352,11 +6200,11 @@ function detectShell() {
 
 // src/commands/stop.ts
 import { readFile as readFile5, unlink as unlink2 } from "fs/promises";
-import { resolve as resolve8 } from "path";
+import { resolve as resolve9 } from "path";
 import { existsSync as existsSync6 } from "fs";
 async function stopCommand(opts) {
   const cwd = process.cwd();
-  const serverJsonPath = resolve8(cwd, ".pipequery", "server.json");
+  const serverJsonPath = resolve9(cwd, ".pipequery", "server.json");
   if (!existsSync6(serverJsonPath)) {
     log.error("No running server found.");
     log.dim("Start one with: pq serve  or  pq serve -d");
@@ -4403,7 +6251,7 @@ async function stopCommand(opts) {
 // src/commands/repl.ts
 import { createInterface } from "readline";
 import { spawnSync } from "child_process";
-import chalk7 from "chalk";
+import chalk8 from "chalk";
 var COMMANDS = {
   help: "Show available commands",
   serve: "Start the server (serve -d for daemon, serve --stop to stop)",
@@ -4421,15 +6269,15 @@ async function startRepl() {
   let serverUrl = null;
   try {
     serverUrl = await getServerUrl();
-    log.success(`Connected to server at ${chalk7.white.bold(serverUrl)}`);
+    log.success(`Connected to server at ${chalk8.white.bold(serverUrl)}`);
   } catch {
     log.warn("No running server found. Start one with: pq serve");
   }
-  console.log(chalk7.dim('  Type "help" for available commands, "exit" to quit.\n'));
+  console.log(chalk8.dim('  Type "help" for available commands, "exit" to quit.\n'));
   const rl = createInterface({
     input: process.stdin,
     output: process.stdout,
-    prompt: chalk7.hex("#06b6d4").bold("  pq > "),
+    prompt: chalk8.hex("#06b6d4").bold("  pq > "),
     terminal: true
   });
   rl.prompt();
@@ -4446,7 +6294,7 @@ async function startRepl() {
         case "help":
           console.log();
           for (const [name, desc] of Object.entries(COMMANDS)) {
-            console.log(`  ${chalk7.hex("#06b6d4")(name.padEnd(12))} ${chalk7.dim(desc)}`);
+            console.log(`  ${chalk8.hex("#06b6d4")(name.padEnd(12))} ${chalk8.dim(desc)}`);
           }
           console.log();
           break;
@@ -4493,7 +6341,7 @@ async function startRepl() {
           });
           try {
             serverUrl = await getServerUrl();
-            log.success(`Connected to server at ${chalk7.white.bold(serverUrl)}`);
+            log.success(`Connected to server at ${chalk8.white.bold(serverUrl)}`);
           } catch {
           }
           rl.resume();
@@ -4521,7 +6369,7 @@ async function startRepl() {
           break;
         case "exit":
         case "quit":
-          console.log(chalk7.dim("  Goodbye.\n"));
+          console.log(chalk8.dim("  Goodbye.\n"));
           rl.close();
           process.exit(0);
           break;
@@ -4565,20 +6413,20 @@ function printTable(rows) {
     const maxData = rows.reduce((max, row) => Math.max(max, formatCell3(row[col]).length), 0);
     return Math.max(col.length, maxData);
   });
-  const header = columns.map((col, i) => chalk7.hex("#06b6d4").bold(col.padEnd(widths[i]))).join("  ");
-  const separator = widths.map((w) => chalk7.dim("\u2500".repeat(w))).join(chalk7.dim("\u2500\u2500"));
+  const header = columns.map((col, i) => chalk8.hex("#06b6d4").bold(col.padEnd(widths[i]))).join("  ");
+  const separator = widths.map((w) => chalk8.dim("\u2500".repeat(w))).join(chalk8.dim("\u2500\u2500"));
   console.log();
   console.log(`  ${header}`);
   console.log(`  ${separator}`);
   for (const row of rows) {
     const line = columns.map((col, i) => {
       const val = formatCell3(row[col]);
-      return typeof row[col] === "number" ? chalk7.hex("#f59e0b")(val.padStart(widths[i])) : val.padEnd(widths[i]);
+      return typeof row[col] === "number" ? chalk8.hex("#f59e0b")(val.padStart(widths[i])) : val.padEnd(widths[i]);
     }).join("  ");
     console.log(`  ${line}`);
   }
   console.log();
-  console.log(chalk7.dim(`  ${rows.length} row(s)`));
+  console.log(chalk8.dim(`  ${rows.length} row(s)`));
   console.log();
 }
 function formatCell3(value) {
@@ -4596,19 +6444,20 @@ async function fetchAndPrint(serverUrl, path, key) {
 }
 
 // src/index.ts
+var collectRepeated = (value, acc) => [...acc, value];
 var program = new Command();
 program.name("pq").description("PipeQuery CLI \u2014 data sources, aggregations, APIs, and terminal dashboards").version("0.1.0").addHelpText("beforeAll", () => {
   printBanner();
   return "";
 }).configureHelp({
-  subcommandTerm: (cmd) => chalk8.hex("#06b6d4")(cmd.name()) + (cmd.usage() ? " " + chalk8.dim(cmd.usage()) : "")
+  subcommandTerm: (cmd) => chalk9.hex("#06b6d4")(cmd.name()) + (cmd.usage() ? " " + chalk9.dim(cmd.usage()) : "")
 });
 program.command("init").description("Create a pipequery.yaml config file").action(initCommand);
 program.command("serve").description("Start the PipeQuery server").option("-p, --port <port>", "Server port", parseInt).option("-H, --host <host>", "Server host").option("-d, --daemon", "Run as a background daemon").option("--stop", "Stop a running daemon").action(serveCommand);
 program.command("query <expression>").description("Run an ad-hoc PipeQuery expression").option("-f, --format <format>", "Output format: table, json", "table").action(queryCommand);
 var source = program.command("source").description("Manage data sources");
 source.command("list").description("List configured data sources").action(sourceListCommand);
-source.command("add <name>").description("Add a data source").requiredOption("-t, --type <type>", "Source type: rest, websocket, file").option("-u, --url <url>", "URL for REST or WebSocket sources").option("-i, --interval <interval>", "Poll interval for REST (e.g., 30s, 5m)", "30s").option("-d, --data-path <path>", "Dot-path to extract data from response").option("-p, --path <path>", "File path for file sources").option("-w, --watch", "Watch file for changes").action(sourceAddCommand);
+source.command("add <name>").description("Add a data source").requiredOption("-t, --type <type>", "Source type: rest, websocket, file, postgres, mysql, sqlite, kafka").option("-u, --url <url>", "Connection URL for REST / WebSocket / Postgres / MySQL sources").option("-i, --interval <interval>", "Poll interval (e.g., 30s, 5m)", "30s").option("-d, --data-path <path>", "Dot-path to extract data from REST response").option("-p, --path <path>", "File path for file or sqlite sources").option("-w, --watch", "Watch file for changes (file sources)").option("-q, --query <sql>", "SELECT query for Postgres / MySQL / SQLite sources").option("--ssl <mode>", "Postgres / MySQL SSL: require (default), no-verify, false; Kafka: true / false").option("--max-rows <n>", "DB sources: safety cap on rows per fetch (default 10000)").option("--no-readonly", "SQLite: open the database read-write instead of read-only").option("-b, --brokers <list>", "Kafka: comma-separated bootstrap brokers (supports ${ENV_VAR})").option("--topic <topic>", "Kafka topic to subscribe to").option("--group-id <id>", "Kafka consumer group (default: ephemeral per-process)").option("--from-beginning", "Kafka: read topic from the start instead of latest").option("--value-format <fmt>", "Kafka value decoding: json (default), string, raw").option("--max-buffer <n>", "Kafka / WebSocket: ring buffer size (default 1000)").action(sourceAddCommand);
 source.command("remove <name>").description("Remove a data source").action(sourceRemoveCommand);
 source.command("test <name>").description("Test a data source and show sample data").action(sourceTestCommand);
 var endpoint = program.command("endpoint").description("Manage API endpoints");
@@ -4621,6 +6470,15 @@ var remote = program.command("remote").description("Manage remote deployment");
 remote.command("deploy").description("Generate Dockerfile and docker-compose.yaml").action(remoteDeployCommand);
 remote.command("connect <url>").description("Connect CLI to a remote PipeQuery server").action(remoteConnectCommand);
 remote.command("status").description("Check remote server health").action(remoteStatusCommand);
+var mcp = program.command("mcp").description("Model Context Protocol server for AI clients");
+mcp.command("serve").description("Start an MCP server exposing pipequery as tools (for Claude, Cursor, Copilot, etc.)").option("--http", "Serve over HTTP/SSE instead of stdio").option("-p, --port <port>", "HTTP port (when --http is set)", parseInt).option("-H, --host <host>", "HTTP host (when --http is set)").option("--attach <url>", "Attach to a running `pq serve` instance at the given URL instead of loading pipequery.yaml locally").option("--auth-token <token>", "Require Authorization: Bearer <token> on HTTP requests. Falls back to $PIPEQUERY_MCP_TOKEN. Without either, the endpoint is unauthenticated.").action(mcpServeCommand);
+mcp.command("inspect").description("Print the MCP tool schemas as JSON (useful for directory submission / debugging)").option("--attach <url>", "Attach to a running `pq serve` instance at the given URL instead of loading pipequery.yaml locally").action(mcpInspectCommand);
+var telegram = program.command("telegram").description("Telegram bot transport for pipequery");
+telegram.command("serve").description("Run a Telegram bot that exposes pipequery commands (/query, /sources, /describe, /endpoints, /call) plus natural-language queries when --anthropic-key is set").option("-t, --bot-token <token>", "Telegram bot token (or set $PIPEQUERY_TG_BOT_TOKEN)").option("--attach <url>", "Attach to a running `pq serve` instance instead of loading pipequery.yaml locally").option("--allow-user <handle>", "Allowlist a user (numeric id or @username); repeatable. With no allowlist, anyone with the bot username can query.", collectRepeated, []).option("--anthropic-key <key>", "Anthropic API key (or set $ANTHROPIC_API_KEY) \u2014 enables natural-language \u2192 pipequery translation on plain-text messages via claude-haiku-4-5.").action(telegramServeCommand);
+var watch2 = program.command("watch").description("Manage alert watches (query \u2192 notification when condition fires)");
+watch2.command("list").description("List configured watches").action(watchListCommand);
+watch2.command("add <name>").description("Add a watch that fires a notification when its query result triggers the configured condition").requiredOption("-q, --query <expression>", "PipeQuery expression to evaluate on each tick").option("-i, --interval <duration>", "Poll interval (e.g., 30s, 5m). Default 60s.").option("-f, --fire-when <mode>", "Fire condition: when_non_empty (default), when_empty, on_change").option("--telegram-chat-id <id>", "Telegram chat / channel / group ID to notify").option("--telegram-bot-token <token>", "Bot token override (defaults to $PIPEQUERY_TG_BOT_TOKEN)").option("--telegram-message <template>", "Optional message template; supports {{ .field }} from the first row, plus {{ .count }}, {{ .watchName }}, {{ .reason }}").action(watchAddCommand);
+watch2.command("remove <name>").description("Remove a watch").action(watchRemoveCommand);
 program.command("stop").description("Stop the running PipeQuery server (daemon or foreground)").option("-f, --force", "Force kill (SIGKILL instead of SIGTERM)").action(stopCommand);
 program.command("completion").description("Generate shell completion script").option("-s, --shell <shell>", "Shell type: bash, zsh, fish").action(completionCommand);
 if (process.argv.length <= 2) {