postgresai 0.14.0 → 0.15.0-dev.10

package/lib/init.ts

@@ -127,8 +127,10 @@ export async function connectWithSslFallback(
   verbose?: boolean
 ): Promise<{ client: PgClient; usedSsl: boolean }> {
   const tryConnect = async (config: PgClientConfig): Promise<PgClient> => {
-    const client = new ClientClass(config);
+    const client = new ClientClass({ ...config, connectionTimeoutMillis: 10_000 } as any);
     await client.connect();
+    // Set a default statement timeout to prevent runaway queries
+    await client.query("SET statement_timeout = '30s'");
     return client;
   };
 
@@ -149,7 +151,7 @@ export async function connectWithSslFallback(
     }
 
     if (verbose) {
-      console.log("SSL connection failed, retrying without SSL...");
+      console.error("SSL connection failed, retrying without SSL...");
     }
 
     // Retry without SSL
@@ -454,8 +456,18 @@ export function resolveAdminConnection(opts: {
   return { clientConfig: cfg, display: describePgConfig(cfg), sslFallbackEnabled: true };
 }
 
+/**
+ * Generate a cryptographically secure random password for the monitoring role.
+ *
+ * Encoding note — bytes vs output length:
+ *   - hex:      N bytes → 2N characters  (24 bytes → 48 hex chars)
+ *   - base64:   N bytes → ⌈4N/3⌉ chars   (24 bytes → 32 base64url chars, no padding)
+ *
+ * We use base64url (RFC 4648 §5) because it is shorter than hex and safe in URLs,
+ * connection strings, and shell variables without quoting.
+ */
 function generateMonitoringPassword(): string {
-  // URL-safe and easy to copy/paste; 24 bytes => 32 base64url chars (no padding).
+  // 24 random bytes → 32 base64url characters (no padding).
   // Note: randomBytes() throws on failure; we add a tiny sanity check for unexpected output.
   const password = randomBytes(24).toString("base64url");
   if (password.length < 30) {
@@ -659,6 +671,36 @@ export type VerifyInitResult = {
   missingOptional: string[];
 };
 
+/** A single permission check result from the preflight query. */
+export type PermissionCheckRow = {
+  permission_name: string;
+  status: "required" | "optional";
+  /**
+   * Whether the permission is granted.
+   * - `true`  — permission is granted
+   * - `false` — permission is explicitly denied
+   * - `null`  — check was skipped (e.g., object does not exist, so the privilege
+   *             check is inapplicable — such as SELECT on a view that hasn't been created)
+   */
+  granted: boolean | null;
+  fix_command: string | null;
+};
+
+/**
+ * Result of the preflight permission check for the current DB user.
+ *
+ * - `ok` is `true` when `missingRequired` is empty.
+ * - `rows` contains every check (for inspection / logging).
+ * - `missingRequired` / `missingOptional` are filtered subsets of `rows`
+ *   where the permission is not granted (`granted !== true`).
+ */
+export type PreflightPermissionResult = {
+  ok: boolean;
+  rows: PermissionCheckRow[];
+  missingRequired: PermissionCheckRow[];
+  missingOptional: PermissionCheckRow[];
+};
+
 export type UninitPlan = {
   monitoringUser: string;
   database: string;
@@ -813,7 +855,12 @@ export async function verifyInitSetup(params: {
       missingRequired.push("USAGE on schema postgres_ai");
     }
 
-    const viewExistsRes = await params.client.query("select to_regclass('postgres_ai.pg_statistic') is not null as ok");
+    const viewExistsRes = await params.client.query(`
+      select case
+        when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then null
+        else to_regclass('postgres_ai.pg_statistic') is not null
+      end as ok
+    `);
     if (!viewExistsRes.rows?.[0]?.ok) {
       missingRequired.push("view postgres_ai.pg_statistic exists");
     } else {
@@ -936,4 +983,149 @@ export async function verifyInitSetup(params: {
   }
 }
 
+/**
+ * Check that the currently connected DB user has sufficient permissions for
+ * monitoring operations. Returns structured results with fix commands.
+ *
+ * Required permissions cause startup to fail; optional ones produce warnings.
+ *
+ * @param client  An already-connected PostgreSQL client.
+ * @returns       A {@link PreflightPermissionResult} with per-check rows and
+ *                filtered `missingRequired` / `missingOptional` arrays.
+ * @throws        Propagates database errors (network, permission denied on catalog
+ *                tables, timeout) to the caller.
+ */
+export async function checkCurrentUserPermissions(
+  client: PgClient
+): Promise<PreflightPermissionResult> {
+  const sql = `
+    with permission_checks as (
+      select
+        format('connect on database %I', current_database()) as permission_name,
+        'required' as status,
+        has_database_privilege(current_user, current_database(), 'connect') as granted
+
+      union all
+
+      select
+        'pg_monitor role membership' as permission_name,
+        'required' as status,
+        -- CASE guarantees evaluation order: pg_has_role() is only called if the
+        -- pg_monitor role exists, avoiding ERROR on PostgreSQL < 10 or when dropped.
+        case
+          when not exists (select from pg_roles where rolname = 'pg_monitor')
+          then false
+          else pg_has_role(current_user, 'pg_monitor', 'member')
+        end as granted
+
+      union all
+
+      select
+        'select on pg_catalog.pg_index' as permission_name,
+        'required' as status,
+        has_table_privilege(current_user, 'pg_catalog.pg_index', 'select') as granted
+
+      union all
+
+      select
+        'postgres_ai.pg_statistic view exists' as permission_name,
+        'optional' as status,
+        case
+          when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then null
+          else to_regclass('postgres_ai.pg_statistic') is not null
+        end as granted
+
+      union all
+
+      select
+        'select on postgres_ai.pg_statistic' as permission_name,
+        'optional' as status,
+        case
+          when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then null
+          when to_regclass('postgres_ai.pg_statistic') is null then null
+          else has_table_privilege(current_user, 'postgres_ai.pg_statistic', 'select')
+        end as granted
+    )
+    select
+      permission_name,
+      status,
+      granted,
+      case
+        when status = 'required' and not coalesce(granted, false) then
+          case
+            when permission_name like 'connect%' then
+              format('grant connect on database %I to %I;', current_database(), current_user)
+            when permission_name = 'pg_monitor role membership' then
+              format('grant pg_monitor to %I;', current_user)
+            when permission_name like 'select on pg_catalog.pg_index' then
+              format('grant select on pg_catalog.pg_index to %I;', current_user)
+          end
+        when permission_name = 'postgres_ai.pg_statistic view exists' and granted = false then
+          '-- create postgres_ai.pg_statistic view (see setup script)'
+        when permission_name = 'select on postgres_ai.pg_statistic' and granted = false then
+          format('grant select on postgres_ai.pg_statistic to %I;', current_user)
+        else null
+      end as fix_command
+    from permission_checks
+    order by
+      case status when 'required' then 1 else 2 end,
+      permission_name;
+  `;
+
+  const res = await client.query(sql);
+  const rows: PermissionCheckRow[] = res.rows;
+
+  // Required: treat null (skipped) as not-granted — fail safe.
+  // Optional: only explicit false counts as missing; null means the check was
+  //           skipped (e.g., view doesn't exist) and is not actionable.
+  const missingRequired = rows.filter((r) => r.status === "required" && r.granted !== true);
+  const missingOptional = rows.filter((r) => r.status === "optional" && r.granted === false);
+
+  return {
+    ok: missingRequired.length === 0,
+    rows,
+    missingRequired,
+    missingOptional,
+  };
+}
+
+/**
+ * Format permission check results into user-facing error/warning lines.
+ *
+ * @returns An object with `warnings` (for optional misses), `errors` (for
+ *          required misses including fix SQL), and `failed` (whether required
+ *          permissions are missing).
+ */
+export function formatPermissionCheckMessages(result: PreflightPermissionResult): {
+  failed: boolean;
+  warnings: string[];
+  errors: string[];
+} {
+  const warnings: string[] = [];
+  const errors: string[] = [];
+
+  for (const row of result.missingOptional) {
+    const fix = row.fix_command ? ` Fix: ${row.fix_command}` : "";
+    warnings.push(`Warning: optional permission missing — ${row.permission_name}.${fix}`);
+  }
 
+  if (!result.ok) {
+    errors.push("Error: the database user is missing required permissions.\n");
+    errors.push("Missing permissions:");
+    for (const row of result.missingRequired) {
+      errors.push(`  - ${row.permission_name}`);
+    }
+    const fixes = result.missingRequired
+      .map((r) => r.fix_command)
+      .filter(Boolean);
+    if (fixes.length > 0) {
+      errors.push("\nTo fix, run the following as a superuser:\n");
+      for (const fix of fixes) {
+        errors.push(`  ${fix}`);
+      }
+    }
+    errors.push("\nAlternatively, run 'postgresai prepare-db' to set up permissions automatically.");
+  }
+
+  return { failed: !result.ok, warnings, errors };
+}

package/lib/issues.ts

@@ -130,10 +130,10 @@ export async function fetchIssues(params: FetchIssuesParams): Promise<IssueListI
 
   if (debug) {
     const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
-    console.log(`Debug: Resolved API base URL: ${base}`);
-    console.log(`Debug: GET URL: ${url.toString()}`);
-    console.log(`Debug: Auth scheme: access-token`);
-    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.error(`Debug: Resolved API base URL: ${base}`);
+    console.error(`Debug: GET URL: ${url.toString()}`);
+    console.error(`Debug: Auth scheme: access-token`);
+    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
   }
 
   const response = await fetch(url.toString(), {
@@ -142,8 +142,8 @@ export async function fetchIssues(params: FetchIssuesParams): Promise<IssueListI
   });
 
   if (debug) {
-    console.log(`Debug: Response status: ${response.status}`);
-    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+    console.error(`Debug: Response status: ${response.status}`);
+    console.error(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
   }
 
   const data = await response.text();
@@ -188,10 +188,10 @@ export async function fetchIssueComments(params: FetchIssueCommentsParams): Prom
 
   if (debug) {
     const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
-    console.log(`Debug: Resolved API base URL: ${base}`);
-    console.log(`Debug: GET URL: ${url.toString()}`);
-    console.log(`Debug: Auth scheme: access-token`);
-    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.error(`Debug: Resolved API base URL: ${base}`);
+    console.error(`Debug: GET URL: ${url.toString()}`);
+    console.error(`Debug: Auth scheme: access-token`);
+    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
   }
 
   const response = await fetch(url.toString(), {
@@ -200,8 +200,8 @@ export async function fetchIssueComments(params: FetchIssueCommentsParams): Prom
   });
 
   if (debug) {
-    console.log(`Debug: Response status: ${response.status}`);
-    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+    console.error(`Debug: Response status: ${response.status}`);
+    console.error(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
   }
 
   const data = await response.text();
@@ -248,10 +248,10 @@ export async function fetchIssue(params: FetchIssueParams): Promise<IssueDetail
 
   if (debug) {
     const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
-    console.log(`Debug: Resolved API base URL: ${base}`);
-    console.log(`Debug: GET URL: ${url.toString()}`);
-    console.log(`Debug: Auth scheme: access-token`);
-    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.error(`Debug: Resolved API base URL: ${base}`);
+    console.error(`Debug: GET URL: ${url.toString()}`);
+    console.error(`Debug: Auth scheme: access-token`);
+    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
   }
 
   const response = await fetch(url.toString(), {
@@ -260,8 +260,8 @@ export async function fetchIssue(params: FetchIssueParams): Promise<IssueDetail
   });
 
   if (debug) {
-    console.log(`Debug: Response status: ${response.status}`);
-    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+    console.error(`Debug: Response status: ${response.status}`);
+    console.error(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
   }
 
   const data = await response.text();
@@ -369,11 +369,11 @@ export async function createIssue(params: CreateIssueParams): Promise<CreatedIss
 
   if (debug) {
     const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
-    console.log(`Debug: Resolved API base URL: ${base}`);
-    console.log(`Debug: POST URL: ${url.toString()}`);
-    console.log(`Debug: Auth scheme: access-token`);
-    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
-    console.log(`Debug: Request body: ${body}`);
+    console.error(`Debug: Resolved API base URL: ${base}`);
+    console.error(`Debug: POST URL: ${url.toString()}`);
+    console.error(`Debug: Auth scheme: access-token`);
+    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.error(`Debug: Request body: ${body}`);
   }
 
   const response = await fetch(url.toString(), {
@@ -383,8 +383,8 @@ export async function createIssue(params: CreateIssueParams): Promise<CreatedIss
   });
 
   if (debug) {
-    console.log(`Debug: Response status: ${response.status}`);
-    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+    console.error(`Debug: Response status: ${response.status}`);
+    console.error(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
   }
 
   const data = await response.text();
@@ -442,11 +442,11 @@ export async function createIssueComment(params: CreateIssueCommentParams): Prom
 
   if (debug) {
     const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
-    console.log(`Debug: Resolved API base URL: ${base}`);
-    console.log(`Debug: POST URL: ${url.toString()}`);
-    console.log(`Debug: Auth scheme: access-token`);
-    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
-    console.log(`Debug: Request body: ${body}`);
+    console.error(`Debug: Resolved API base URL: ${base}`);
+    console.error(`Debug: POST URL: ${url.toString()}`);
+    console.error(`Debug: Auth scheme: access-token`);
+    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.error(`Debug: Request body: ${body}`);
   }
 
   const response = await fetch(url.toString(), {
@@ -456,8 +456,8 @@ export async function createIssueComment(params: CreateIssueCommentParams): Prom
   });
 
   if (debug) {
-    console.log(`Debug: Response status: ${response.status}`);
-    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+    console.error(`Debug: Response status: ${response.status}`);
+    console.error(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
   }
 
   const data = await response.text();
@@ -550,11 +550,11 @@ export async function updateIssue(params: UpdateIssueParams): Promise<UpdatedIss
 
   if (debug) {
     const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
-    console.log(`Debug: Resolved API base URL: ${base}`);
-    console.log(`Debug: POST URL: ${url.toString()}`);
-    console.log(`Debug: Auth scheme: access-token`);
-    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
-    console.log(`Debug: Request body: ${body}`);
+    console.error(`Debug: Resolved API base URL: ${base}`);
+    console.error(`Debug: POST URL: ${url.toString()}`);
+    console.error(`Debug: Auth scheme: access-token`);
+    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.error(`Debug: Request body: ${body}`);
   }
 
   const response = await fetch(url.toString(), {
@@ -564,8 +564,8 @@ export async function updateIssue(params: UpdateIssueParams): Promise<UpdatedIss
   });
 
   if (debug) {
-    console.log(`Debug: Response status: ${response.status}`);
-    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+    console.error(`Debug: Response status: ${response.status}`);
+    console.error(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
   }
 
   const data = await response.text();
@@ -639,11 +639,11 @@ export async function updateIssueComment(params: UpdateIssueCommentParams): Prom
 
   if (debug) {
     const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
-    console.log(`Debug: Resolved API base URL: ${base}`);
-    console.log(`Debug: POST URL: ${url.toString()}`);
-    console.log(`Debug: Auth scheme: access-token`);
-    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
-    console.log(`Debug: Request body: ${body}`);
+    console.error(`Debug: Resolved API base URL: ${base}`);
+    console.error(`Debug: POST URL: ${url.toString()}`);
+    console.error(`Debug: Auth scheme: access-token`);
+    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.error(`Debug: Request body: ${body}`);
   }
 
   const response = await fetch(url.toString(), {
@@ -653,8 +653,8 @@ export async function updateIssueComment(params: UpdateIssueCommentParams): Prom
   });
 
   if (debug) {
-    console.log(`Debug: Response status: ${response.status}`);
-    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+    console.error(`Debug: Response status: ${response.status}`);
+    console.error(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
   }
 
   const data = await response.text();
@@ -736,10 +736,10 @@ export async function fetchActionItem(params: FetchActionItemParams): Promise<Is
 
   if (debug) {
     const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
-    console.log(`Debug: Resolved API base URL: ${base}`);
-    console.log(`Debug: GET URL: ${url.toString()}`);
-    console.log(`Debug: Auth scheme: access-token`);
-    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.error(`Debug: Resolved API base URL: ${base}`);
+    console.error(`Debug: GET URL: ${url.toString()}`);
+    console.error(`Debug: Auth scheme: access-token`);
+    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
   }
 
   const response = await fetch(url.toString(), {
@@ -748,8 +748,8 @@ export async function fetchActionItem(params: FetchActionItemParams): Promise<Is
   });
 
   if (debug) {
-    console.log(`Debug: Response status: ${response.status}`);
-    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+    console.error(`Debug: Response status: ${response.status}`);
+    console.error(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
   }
 
   const data = await response.text();
@@ -814,10 +814,10 @@ export async function fetchActionItems(params: FetchActionItemsParams): Promise<
 
   if (debug) {
     const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
-    console.log(`Debug: Resolved API base URL: ${base}`);
-    console.log(`Debug: GET URL: ${url.toString()}`);
-    console.log(`Debug: Auth scheme: access-token`);
-    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.error(`Debug: Resolved API base URL: ${base}`);
+    console.error(`Debug: GET URL: ${url.toString()}`);
+    console.error(`Debug: Auth scheme: access-token`);
+    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
   }
 
   const response = await fetch(url.toString(), {
@@ -826,8 +826,8 @@ export async function fetchActionItems(params: FetchActionItemsParams): Promise<
   });
 
   if (debug) {
-    console.log(`Debug: Response status: ${response.status}`);
-    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+    console.error(`Debug: Response status: ${response.status}`);
+    console.error(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
   }
 
   const data = await response.text();
@@ -913,11 +913,11 @@ export async function createActionItem(params: CreateActionItemParams): Promise<
 
   if (debug) {
     const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
-    console.log(`Debug: Resolved API base URL: ${base}`);
-    console.log(`Debug: POST URL: ${url.toString()}`);
-    console.log(`Debug: Auth scheme: access-token`);
-    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
-    console.log(`Debug: Request body: ${body}`);
+    console.error(`Debug: Resolved API base URL: ${base}`);
+    console.error(`Debug: POST URL: ${url.toString()}`);
+    console.error(`Debug: Auth scheme: access-token`);
+    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.error(`Debug: Request body: ${body}`);
   }
 
   const response = await fetch(url.toString(), {
@@ -927,8 +927,8 @@ export async function createActionItem(params: CreateActionItemParams): Promise<
   });
 
   if (debug) {
-    console.log(`Debug: Response status: ${response.status}`);
-    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+    console.error(`Debug: Response status: ${response.status}`);
+    console.error(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
   }
 
   const data = await response.text();
@@ -1035,11 +1035,11 @@ export async function updateActionItem(params: UpdateActionItemParams): Promise<
 
   if (debug) {
     const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
-    console.log(`Debug: Resolved API base URL: ${base}`);
-    console.log(`Debug: POST URL: ${url.toString()}`);
-    console.log(`Debug: Auth scheme: access-token`);
-    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
-    console.log(`Debug: Request body: ${body}`);
+    console.error(`Debug: Resolved API base URL: ${base}`);
+    console.error(`Debug: POST URL: ${url.toString()}`);
+    console.error(`Debug: Auth scheme: access-token`);
+    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.error(`Debug: Request body: ${body}`);
   }
 
   const response = await fetch(url.toString(), {
@@ -1049,8 +1049,8 @@ export async function updateActionItem(params: UpdateActionItemParams): Promise<
   });
 
   if (debug) {
-    console.log(`Debug: Response status: ${response.status}`);
-    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+    console.error(`Debug: Response status: ${response.status}`);
+    console.error(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
   }
 
   if (!response.ok) {

package/lib/mcp-server.ts

@@ -14,6 +14,7 @@ import {
   updateActionItem,
   type ConfigChange,
 } from "./issues";
+import { fetchReports, fetchAllReports, fetchReportFiles, fetchReportFileData, parseFlexibleDate } from "./reports";
 import { resolveBaseUrls } from "./util";
 
 // MCP SDK imports - Bun handles these directly
@@ -250,6 +251,50 @@ export async function handleToolCall(
       return { content: [{ type: "text", text: JSON.stringify({ success: true }, null, 2) }] };
     }
 
+    // Reports Tools
+    if (toolName === "list_reports") {
+      const projectId = args.project_id !== undefined ? Number(args.project_id) : undefined;
+      const status = args.status ? String(args.status) : undefined;
+      const limit = args.limit !== undefined ? Number(args.limit) : undefined;
+      const beforeDate = args.before_date ? parseFlexibleDate(String(args.before_date)) : undefined;
+      const all = args.all === true;
+      let reports;
+      if (all) {
+        reports = await fetchAllReports({ apiKey, apiBaseUrl, projectId, status, limit, debug });
+      } else {
+        reports = await fetchReports({ apiKey, apiBaseUrl, projectId, status, limit, beforeDate, debug });
+      }
+      return { content: [{ type: "text", text: JSON.stringify(reports, null, 2) }] };
+    }
+
+    if (toolName === "list_report_files") {
+      const reportId = args.report_id !== undefined ? Number(args.report_id) : undefined;
+      if (reportId !== undefined && isNaN(reportId)) {
+        return { content: [{ type: "text", text: "report_id must be a number" }], isError: true };
+      }
+      const type = args.type ? String(args.type) as "json" | "md" : undefined;
+      const checkId = args.check_id ? String(args.check_id) : undefined;
+      if (reportId === undefined && !checkId) {
+        return { content: [{ type: "text", text: "Either report_id or check_id is required" }], isError: true };
+      }
+      const files = await fetchReportFiles({ apiKey, apiBaseUrl, reportId, type, checkId, debug });
+      return { content: [{ type: "text", text: JSON.stringify(files, null, 2) }] };
+    }
+
+    if (toolName === "get_report_data") {
+      const reportId = args.report_id !== undefined ? Number(args.report_id) : undefined;
+      if (reportId !== undefined && isNaN(reportId)) {
+        return { content: [{ type: "text", text: "report_id must be a number" }], isError: true };
+      }
+      const type = args.type ? String(args.type) as "json" | "md" : undefined;
+      const checkId = args.check_id ? String(args.check_id) : undefined;
+      if (reportId === undefined && !checkId) {
+        return { content: [{ type: "text", text: "Either report_id or check_id is required" }], isError: true };
+      }
+      const files = await fetchReportFileData({ apiKey, apiBaseUrl, reportId, type, checkId, debug });
+      return { content: [{ type: "text", text: JSON.stringify(files, null, 2) }] };
+    }
+
     throw new Error(`Unknown tool: ${toolName}`);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -442,6 +487,51 @@ export async function startMcpServer(rootOpts?: RootOptsLike, extra?: { debug?:
             additionalProperties: false,
           },
         },
+        // Reports Tools
+        {
+          name: "list_reports",
+          description: "List checkup reports. Returns report metadata: id, project, status, timestamps. Use get_report_data to fetch actual report content. Supports date-based filtering with before_date.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              project_id: { type: "number", description: "Filter by project ID" },
+              status: { type: "string", description: "Filter by status (e.g., 'completed')" },
+              limit: { type: "number", description: "Max number of reports to return (default: 20)" },
+              before_date: { type: "string", description: "Show reports created before this date (YYYY-MM-DD, DD.MM.YYYY, YYYY-MM-DD HH:mm, etc.)" },
+              all: { type: "boolean", description: "Fetch all reports (paginated automatically)" },
+              debug: { type: "boolean", description: "Enable verbose debug logs" },
+            },
+            additionalProperties: false,
+          },
+        },
+        {
+          name: "list_report_files",
+          description: "List files in a checkup report (metadata only, no content). Each report contains json (raw data) and md (markdown analysis) files per check. Either report_id or check_id must be provided.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              report_id: { type: "number", description: "Checkup report ID (optional if check_id is provided)" },
+              type: { type: "string", description: "Filter by file type: 'json' or 'md'" },
+              check_id: { type: "string", description: "Filter by check ID (e.g., 'H002', 'F004')" },
+              debug: { type: "boolean", description: "Enable verbose debug logs" },
+            },
+            additionalProperties: false,
+          },
+        },
+        {
+          name: "get_report_data",
+          description: "Get checkup report file content. Returns files with a 'data' field containing the actual content: markdown analysis or JSON raw data. Use type='md' for human-readable analysis with recommendations, type='json' for raw check data. Either report_id or check_id must be provided.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              report_id: { type: "number", description: "Checkup report ID (optional if check_id is provided)" },
+              type: { type: "string", description: "Filter by file type: 'json' for raw data, 'md' for markdown analysis" },
+              check_id: { type: "string", description: "Filter by check ID (e.g., 'H002', 'F004')" },
+              debug: { type: "boolean", description: "Enable verbose debug logs" },
+            },
+            additionalProperties: false,
+          },
+        },
       ],
     };
   });

package/lib/metrics-loader.ts

@@ -63,8 +63,11 @@ export function listMetricNames(): string[] {
 export const METRIC_NAMES = {
   // Index health checks
   H001: "pg_invalid_indexes",
-  H002: "unused_indexes", 
+  H002: "unused_indexes",
   H004: "redundant_indexes",
+  // Bloat estimation
+  F004: "pg_table_bloat",
+  F005: "pg_btree_bloat",
   // Settings and version info (A002, A003, A007, A013)
   settings: "settings",
   // Database statistics (A004)
@@ -72,6 +75,8 @@ export const METRIC_NAMES = {
   dbSize: "db_size",
   // Stats reset info (H002)
   statsReset: "stats_reset",
+  // I/O statistics (I001) - PostgreSQL 16+
+  I001: "pg_stat_io",
 } as const;
 
 /**