@vaultgradient/pipequery-cli 0.3.3 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaultgradient/pipequery-cli",
-  "version": "0.3.3",
+  "version": "0.6.0",
   "description": "CLI for PipeQuery — data sources, aggregations, APIs, and terminal dashboards",
   "type": "module",
   "bin": {
@@ -13,20 +13,30 @@
     "test:watch": "vitest"
   },
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.91.1",
     "@fastify/cors": "^11.2.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^12.9.0",
     "chalk": "^5.6.2",
     "chokidar": "^5.0.0",
     "commander": "^14.0.3",
     "csv-parse": "^6.2.1",
     "fastify": "^5.8.5",
+    "grammy": "^1.42.0",
     "ink": "^7.0.1",
+    "kafkajs": "^2.2.4",
+    "mysql2": "^3.22.2",
     "ora": "^9.3.0",
+    "pg": "^8.20.0",
     "react": "^19.2.5",
     "ws": "^8.20.0",
-    "yaml": "^2.8.3"
+    "yaml": "^2.8.3",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^25.6.0",
+    "@types/pg": "^8.20.0",
     "@types/react": "^19.2.14",
     "@types/ws": "^8.18.1",
     "tsup": "^8.5.1",

package/src/commands/mcp.ts

@@ -0,0 +1,87 @@
+import { loadConfig } from '../config/loader.js';
+import { log } from '../utils/logger.js';
+import { AttachedProvider, LocalProvider, type Provider } from '../mcp/provider.js';
+import { runStdio } from '../mcp/stdio.js';
+import { runHttp } from '../mcp/http.js';
+import { createMcpServer } from '../mcp/server.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+
+interface McpServeOptions {
+  http?: boolean;
+  port?: number;
+  host?: string;
+  attach?: string;
+  authToken?: string;
+}
+
+export async function mcpServeCommand(opts: McpServeOptions): Promise<void> {
+  const provider = await buildProvider(opts.attach);
+  const isStdio = !opts.http;
+
+  if (isStdio) {
+    // In stdio mode, stdout is reserved for JSON-RPC. All logs go to stderr.
+    await runStdio(provider);
+    return;
+  }
+
+  const port = opts.port ?? 3001;
+  const host = opts.host ?? '127.0.0.1';
+  // CLI flag takes precedence over env var. No token => unauthenticated
+  // (runHttp warns loudly at startup).
+  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());
+}
+
+export async function mcpInspectCommand(opts: { attach?: string }): Promise<void> {
+  const provider = await buildProvider(opts.attach);
+  const mcp = createMcpServer(provider);
+
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  await mcp.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 mcp.close();
+    await provider.dispose();
+  }
+}
+
+async function buildProvider(attachUrl?: string): Promise<Provider> {
+  if (attachUrl) {
+    return new AttachedProvider(attachUrl);
+  }
+
+  const cwd = process.cwd();
+  const { config } = await loadConfig(cwd);
+  return new LocalProvider(config, cwd);
+}

package/src/commands/source.ts

@@ -51,6 +51,16 @@ export async function sourceAddCommand(name: string, opts: {
   dataPath?: string;
   path?: string;
   watch?: boolean;
+  query?: string;
+  ssl?: string;
+  maxRows?: string;
+  readonly?: boolean;
+  brokers?: string;
+  topic?: string;
+  groupId?: string;
+  fromBeginning?: boolean;
+  valueFormat?: string;
+  maxBuffer?: string;
 }) {
   const cwd = process.cwd();
   const { config, path: configPath } = await loadConfig(cwd);
@@ -79,8 +89,60 @@ export async function sourceAddCommand(name: string, 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' as const } : {}),
+        ...(opts.ssl === 'false' ? { ssl: false as const } : {}),
+        ...(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' as const } : {}),
+        ...(opts.ssl === 'false' ? { ssl: false as const } : {}),
+        ...(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 as 'json' | 'string' | 'raw' } : {}),
+        ...(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`);
   }
 
   // Save to config

package/src/commands/telegram.ts

@@ -0,0 +1,65 @@
+import { loadConfig } from '../config/loader.js';
+import { log } from '../utils/logger.js';
+import { LocalProvider, AttachedProvider, type Provider } from '../mcp/provider.js';
+import { buildBot } from '../telegram/bot.js';
+import { createNLTranslator } from '../telegram/nl.js';
+
+interface TelegramServeOptions {
+  botToken?: string;
+  attach?: string;
+  allowUser?: string[];
+  anthropicKey?: string;
+}
+
+export async function telegramServeCommand(opts: TelegramServeOptions): Promise<void> {
+  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 buildProvider(opts.attach);
+  const nl = anthropicKey
+    ? createNLTranslator(provider, { apiKey: anthropicKey })
+    : undefined;
+
+  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 buildProvider(attachUrl?: string): Promise<Provider> {
+  if (attachUrl) {
+    return new AttachedProvider(attachUrl);
+  }
+  const cwd = process.cwd();
+  const { config } = await loadConfig(cwd);
+  return new LocalProvider(config, cwd);
+}

package/src/commands/watch.ts

@@ -0,0 +1,84 @@
+import chalk from 'chalk';
+import { loadConfig, saveConfig } from '../config/loader.js';
+import { log } from '../utils/logger.js';
+import type { WatchConfig } from '../config/schema.js';
+
+export async function watchListCommand(): Promise<void> {
+  const cwd = process.cwd();
+  const { config } = await loadConfig(cwd);
+  const watches = config.watches ?? {};
+  const entries = Object.entries(watches);
+  if (entries.length === 0) {
+    log.dim('No watches configured. Add one with: pq watch add <name>');
+    return;
+  }
+  console.log(chalk.bold('Watches:\n'));
+  for (const [name, w] of entries) {
+    const interval = w.interval ?? '60s';
+    const fireWhen = w.fireWhen ?? 'when_non_empty';
+    const channels = Object.keys(w.notify).join(', ') || '<none>';
+    console.log(`  ${chalk.bold(name)}  ${chalk.dim(`every ${interval} • ${fireWhen}`)}`);
+    console.log(`    ${chalk.dim('query:  ')}${w.query}`);
+    console.log(`    ${chalk.dim('notify: ')}${channels}`);
+  }
+}
+
+export async function watchAddCommand(name: string, opts: {
+  query: string;
+  interval?: string;
+  fireWhen?: string;
+  telegramChatId?: string;
+  telegramMessage?: string;
+  telegramBotToken?: string;
+}): Promise<void> {
+  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 watch: WatchConfig = {
+    query: opts.query,
+    ...(opts.interval ? { interval: opts.interval } : {}),
+    fireWhen: fireWhen as WatchConfig['fireWhen'],
+    notify: {
+      telegram: {
+        chatId: parseChatId(opts.telegramChatId),
+        ...(opts.telegramBotToken ? { botToken: opts.telegramBotToken } : {}),
+        ...(opts.telegramMessage ? { message: opts.telegramMessage } : {}),
+      },
+    },
+  };
+
+  config.watches = config.watches ?? {};
+  config.watches[name] = watch;
+  await saveConfig(config, configPath);
+  log.success(`Watch "${name}" added. Restart \`pq serve\` to activate.`);
+}
+
+export async function watchRemoveCommand(name: string): Promise<void> {
+  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: string): string | number {
+  // Numeric Telegram chat IDs (e.g. -1001234567890) are large negative
+  // integers that fit in safe-integer range. Keep negatives as numbers.
+  if (/^-?\d+$/.test(input)) {
+    const n = Number(input);
+    if (Number.isFinite(n) && Number.isSafeInteger(n)) return n;
+  }
+  return input;
+}

package/src/config/schema.ts

@@ -4,6 +4,7 @@ export interface PipeQueryConfig {
   sources: Record<string, SourceConfig>;
   endpoints: Record<string, EndpointConfig>;
   dashboards: Record<string, DashboardConfig>;
+  watches?: Record<string, WatchConfig>;
 }
 
 export interface ServerConfig {
@@ -21,7 +22,11 @@ export type SourceConfig =
   | RestSourceConfig
   | WebSocketSourceConfig
   | FileSourceConfig
-  | StaticSourceConfig;
+  | StaticSourceConfig
+  | PostgresSourceConfig
+  | MysqlSourceConfig
+  | SqliteSourceConfig
+  | KafkaSourceConfig;
 
 export interface RestSourceConfig {
   type: 'rest';
@@ -50,6 +55,109 @@ export interface StaticSourceConfig {
   data: unknown[];
 }
 
+export interface PostgresSourceConfig {
+  type: 'postgres';
+  /**
+   * Postgres connection URL. Supports `${ENV_VAR}` interpolation so
+   * credentials can live in the environment instead of the yaml.
+   * Example: `postgres://${DB_USER}:${DB_PASS}@db.internal:5432/app`.
+   */
+  url: string;
+  /**
+   * The SELECT query to run on each poll. Must be a single statement.
+   * It's the caller's responsibility to add LIMIT/WHERE clauses that
+   * bound the result set; `maxRows` below is a hard safety cap.
+   */
+  query: string;
+  /** Poll interval, e.g. "30s", "5m". Defaults to "30s". */
+  interval?: string;
+  /**
+   * SSL policy. `"require"` verifies the cert (production default for
+   * most hosted Postgres). `"no-verify"` skips verification (useful for
+   * self-signed dev setups). `false` disables TLS entirely.
+   */
+  ssl?: 'require' | 'no-verify' | false;
+  /** Safety cap. If the query returns more rows, the fetch errors. Default 10000. */
+  maxRows?: number;
+}
+
+export interface MysqlSourceConfig {
+  type: 'mysql';
+  /**
+   * MySQL connection URL. Supports `${ENV_VAR}` interpolation so
+   * credentials can live in the environment instead of the yaml.
+   * Example: `mysql://${DB_USER}:${DB_PASS}@db.internal:3306/app`.
+   */
+  url: string;
+  /** The SELECT query to run on each poll. */
+  query: string;
+  /** Poll interval, e.g. "30s", "5m". Defaults to "30s". */
+  interval?: string;
+  /**
+   * SSL policy. `"require"` verifies the cert (production default).
+   * `"no-verify"` skips verification. `false` disables TLS.
+   */
+  ssl?: 'require' | 'no-verify' | false;
+  /** Safety cap. Default 10000. */
+  maxRows?: number;
+}
+
+export interface KafkaSourceConfig {
+  type: 'kafka';
+  /**
+   * Comma-separated list of Kafka bootstrap brokers, or an array. Supports
+   * `${ENV_VAR}` interpolation. Example: `"broker1:9092,broker2:9092"`.
+   */
+  brokers: string | string[];
+  /** Topic to subscribe to. Only one topic per source; use multiple sources for multiple topics. */
+  topic: string;
+  /**
+   * Consumer group ID. If omitted, an ephemeral per-process group is generated
+   * so this pipequery instance sees the full firehose. Set explicitly to share
+   * a partitioned subscription across pipequery replicas.
+   */
+  groupId?: string;
+  /** Start reading from the topic's beginning on first connect. Default false (latest). */
+  fromBeginning?: boolean;
+  /** Ring buffer size. Oldest messages are evicted. Default 1000. */
+  maxBuffer?: number;
+  /**
+   * How to decode the message value.
+   *   - `"json"` (default): `JSON.parse(buffer.toString())`; non-JSON messages are skipped.
+   *   - `"string"`: UTF-8 string, stored as `{ value }`.
+   *   - `"raw"`: base64-encoded bytes, stored as `{ value }`.
+   */
+  valueFormat?: 'json' | 'string' | 'raw';
+  /** SSL / TLS toggle. Default false (plaintext). */
+  ssl?: boolean;
+  /**
+   * SASL authentication. Supports `${ENV_VAR}` interpolation in username/password.
+   */
+  sasl?: {
+    mechanism: 'plain' | 'scram-sha-256' | 'scram-sha-512';
+    username: string;
+    password: string;
+  };
+}
+
+export interface SqliteSourceConfig {
+  type: 'sqlite';
+  /**
+   * Path to the SQLite database file, relative to the directory
+   * containing pipequery.yaml. Use `:memory:` for an in-memory database
+   * (useful for tests; data will not persist across restarts).
+   */
+  path: string;
+  /** The SELECT query to run on each poll. */
+  query: string;
+  /** Poll interval, e.g. "30s", "5m". Defaults to "30s". */
+  interval?: string;
+  /** Open the database read-only. Recommended for query-only sources. Default true. */
+  readonly?: boolean;
+  /** Safety cap. Default 10000. */
+  maxRows?: number;
+}
+
 // ─── Endpoint config ─────────────────────────────────────────────────────────
 
 export interface EndpointConfig {
@@ -71,3 +179,47 @@ export interface PanelConfig {
   viz: 'table' | 'bar' | 'sparkline' | 'stat' | 'orderbook' | 'heatmap' | 'candle' | 'auto';
   size?: 'full' | 'half' | 'stat';
 }
+
+// ─── Watches (alerts triggered by a query result) ────────────────────────────
+
+export interface WatchConfig {
+  /** PipeQuery expression to evaluate on each tick. */
+  query: string;
+  /** Poll interval, e.g. "30s", "5m". Defaults to "60s". */
+  interval?: string;
+  /**
+   * When to fire a notification:
+   *   - `when_non_empty` (default): fires on the transition from empty/null
+   *     to non-empty. Doesn't re-fire while still non-empty; re-fires after
+   *     going empty and then non-empty again. Standard alerting shape.
+   *   - `when_empty`: inverse — fires when transitioning to empty (e.g., a
+   *     liveness check that fails when no rows match).
+   *   - `on_change`: fires on any change in the result content. Useful for
+   *     "tell me when this number moves" but can be chatty.
+   */
+  fireWhen?: 'when_non_empty' | 'when_empty' | 'on_change';
+  /** Notification channels. At least one must be configured. */
+  notify: WatchNotify;
+}
+
+export interface WatchNotify {
+  telegram?: TelegramNotifyConfig;
+}
+
+export interface TelegramNotifyConfig {
+  /**
+   * Bot token; supports `${ENV_VAR}` interpolation. If omitted, defaults
+   * to the `PIPEQUERY_TG_BOT_TOKEN` environment variable.
+   */
+  botToken?: string;
+  /** Chat / channel / group ID to post to. */
+  chatId: string | number;
+  /**
+   * Optional message template. `{{ .field }}` expands to the named field
+   * of the FIRST row of the result (most alerts care about a single
+   * triggering row). `{{ .count }}` is special and yields the total row
+   * count. If omitted, the bot posts a default summary line plus the
+   * full result rendered as a Markdown table.
+   */
+  message?: string;
+}

package/src/index.ts

@@ -8,11 +8,17 @@ import { endpointListCommand, endpointAddCommand, endpointRemoveCommand } from '
 import { dashboardCommand } from './commands/dashboard.js';
 import { monitorCommand } from './commands/monitor.js';
 import { remoteDeployCommand, remoteConnectCommand, remoteStatusCommand } from './commands/remote.js';
+import { mcpServeCommand, mcpInspectCommand } from './commands/mcp.js';
+import { telegramServeCommand } from './commands/telegram.js';
+import { watchListCommand, watchAddCommand, watchRemoveCommand } from './commands/watch.js';
 import { completionCommand } from './commands/completion.js';
 import { stopCommand } from './commands/stop.js';
 import { startRepl } from './commands/repl.js';
 import { printBanner } from './utils/banner.js';
 
+// Commander helper: accumulate `--allow-user @a --allow-user @b` into an array.
+const collectRepeated = (value: string, acc: string[]): string[] => [...acc, value];
+
 const program = new Command();
 
 program
@@ -65,12 +71,22 @@ source
 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')
+  .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
@@ -138,6 +154,64 @@ remote
   .description('Check remote server health')
   .action(remoteStatusCommand);
 
+// ─── pq mcp ──────────────────────────────────────────────────────────────────
+
+const 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);
+
+// ─── pq telegram ─────────────────────────────────────────────────────────────
+
+const 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) — enables natural-language → pipequery translation on plain-text messages via claude-haiku-4-5.')
+  .action(telegramServeCommand);
+
+// ─── pq watch ────────────────────────────────────────────────────────────────
+
+const watch = program.command('watch').description('Manage alert watches (query → notification when condition fires)');
+
+watch
+  .command('list')
+  .description('List configured watches')
+  .action(watchListCommand);
+
+watch
+  .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);
+
+watch
+  .command('remove <name>')
+  .description('Remove a watch')
+  .action(watchRemoveCommand);
+
 // ─── pq stop ────────────────────────────────────────────────────────────────
 
 program