postgresai 0.15.0-dev.10 → 0.15.0-dev.11

package/lib/checkup-dictionary.ts

@@ -57,17 +57,6 @@ export function getCheckupEntry(code: string): CheckupDictionaryEntry | null {
   return dictionaryByCode.get(code.toUpperCase()) ?? null;
 }
 
-/**
- * Get the title for a checkup code.
- *
- * @param code - The check code (e.g., "A001", "H002")
- * @returns The title or the code itself if not found
- */
-export function getCheckupTitle(code: string): string {
-  const entry = getCheckupEntry(code);
-  return entry?.title ?? code;
-}
-
 /**
  * Check if a code exists in the dictionary.
  *

package/lib/checkup.ts

@@ -2,41 +2,41 @@
  * Express Checkup Module
  * ======================
  * Generates JSON health check reports directly from PostgreSQL without Prometheus.
- * 
+ *
  * ARCHITECTURAL DECISIONS
  * -----------------------
- * 
+ *
  * 1. SINGLE SOURCE OF TRUTH FOR SQL QUERIES
- *    Complex metrics (index health, settings, db_stats) are loaded from 
+ *    Complex metrics (index health, settings, db_stats) are loaded from
  *    config/pgwatch-prometheus/metrics.yml via getMetricSql() from metrics-loader.ts.
- *    
+ *
  *    Simple queries (version, database list, connection states, uptime) use
  *    inline SQL as they're trivial and CLI-specific.
- * 
+ *
  * 2. JSON SCHEMA COMPLIANCE
  *    All generated reports MUST comply with JSON schemas in reporter/schemas/.
  *    These schemas define the expected format for both:
  *    - Full-fledged monitoring reporter output
  *    - Express checkup output
- * 
+ *
  *    Before adding or modifying a report, verify the corresponding schema exists
  *    and ensure the output matches. Run schema validation tests to confirm.
- * 
+ *
  * 3. ERROR HANDLING STRATEGY
  *    Functions follow two patterns based on criticality:
- * 
+ *
  *    PROPAGATING (throws on error):
  *    - Core data functions: getPostgresVersion, getSettings, getAlteredSettings,
  *      getDatabaseSizes, getInvalidIndexes, getUnusedIndexes, getRedundantIndexes
  *    - If these fail, the entire report should fail (data is required)
  *    - Callers should handle errors at the report generation level
- * 
+ *
  *    GRACEFUL DEGRADATION (catches errors, includes error in output):
  *    - Optional/supplementary queries: pg_stat_statements, pg_stat_kcache checks,
  *      memory calculations, postmaster startup time
  *    - These are nice-to-have; missing data shouldn't fail the whole report
  *    - Errors are logged and included in report output for visibility
- * 
+ *
  * ADDING NEW REPORTS
  * ------------------
  * 1. Add/verify the metric exists in config/pgwatch-prometheus/metrics.yml
@@ -51,7 +51,7 @@ import * as fs from "fs";
 import * as path from "path";
 import * as pkg from "../package.json";
 import { getMetricSql, transformMetricRow, METRIC_NAMES } from "./metrics-loader";
-import { getCheckupTitle, buildCheckInfoMap } from "./checkup-dictionary";
+import { buildCheckInfoMap } from "./checkup-dictionary";
 
 // Time constants
 const SECONDS_PER_DAY = 86400;
@@ -336,7 +336,7 @@ export function parseVersionNum(versionNum: string): { major: string; minor: str
 /**
  * Format bytes to human readable string using binary units (1024-based).
  * Uses IEC standard: KiB, MiB, GiB, etc.
- * 
+ *
  * Note: PostgreSQL's pg_size_pretty() uses kB/MB/GB with 1024 base (technically
  * incorrect SI usage), but we follow IEC binary units per project style guide.
  */
@@ -387,7 +387,7 @@ function formatSettingPrettyValue(
 /**
  * Get PostgreSQL version information.
  * Uses simple inline SQL (trivial query, CLI-specific).
- * 
+ *
  * @throws {Error} If database query fails (propagating - critical data)
  */
 export async function getPostgresVersion(client: Client): Promise<PostgresVersion> {
@@ -1084,7 +1084,7 @@ export const generateH004 = (client: Client, nodeName = "node-01") =>
 
 /**
  * Generate D004 report - pg_stat_statements and pg_stat_kcache settings.
- * 
+ *
  * Uses graceful degradation: extension queries are wrapped in try-catch
  * because extensions may not be installed. Errors are included in the
  * report output rather than failing the entire report.

package/lib/init.ts

@@ -87,7 +87,7 @@ export type AdminConnection = {
 /**
  * Check if an error indicates SSL negotiation failed and fallback to non-SSL should be attempted.
  * This mimics libpq's sslmode=prefer behavior.
- * 
+ *
  * IMPORTANT: This should NOT match certificate errors (expired, invalid, self-signed)
  * as those are real errors the user needs to fix, not negotiation failures.
  */

package/lib/instances.ts

@@ -0,0 +1,245 @@
+/**
+ * Helpers for managing instances.yml (the pgwatch monitoring target list)
+ * and for opening pg connections that honor libpq sslmode semantics.
+ *
+ * These helpers exist as a single source of truth so that `mon targets
+ * add/remove/test` and `mon local-install` (which has its own inline copies
+ * of the same logic) stay consistent — and so unit tests exercise the same
+ * code path the CLI actually runs.
+ */
+
+import * as fs from "fs";
+import * as yaml from "js-yaml";
+import { parse as parseConnString } from "pg-connection-string";
+import type { ClientConfig } from "pg";
+
+export interface Instance {
+  name: string;
+  conn_str?: string;
+  preset_metrics?: string;
+  custom_metrics?: any;
+  is_enabled?: boolean;
+  group?: string;
+  custom_tags?: Record<string, any>;
+}
+
+export class InstancesParseError extends Error {
+  constructor(file: string, cause: unknown) {
+    const causeMsg = cause instanceof Error ? cause.message : String(cause);
+    super(`Failed to parse ${file}: ${causeMsg}`);
+    this.name = "InstancesParseError";
+  }
+}
+
+/**
+ * Read instances.yml as an array of Instance.
+ *
+ * Returns `[]` for a missing/empty file (this is normal — fresh installs and
+ * just-after-`remove` states). Throws InstancesParseError on a corrupted file
+ * so callers can surface the corruption to the user instead of silently
+ * overwriting it (the previous append-text behavior could erase several
+ * targets — including their conn_strs with credentials — if the file had a
+ * partial write or hand-edit problem).
+ */
+export function loadInstances(file: string): Instance[] {
+  if (!fs.existsSync(file)) return [];
+  if (fs.lstatSync(file).isDirectory()) return [];
+  const text = fs.readFileSync(file, "utf8");
+  if (text.trim() === "") return [];
+  let parsed: unknown;
+  try {
+    parsed = yaml.load(text);
+  } catch (err) {
+    throw new InstancesParseError(file, err);
+  }
+  if (parsed === null || parsed === undefined) return [];
+  if (!Array.isArray(parsed)) {
+    throw new InstancesParseError(file, "expected a YAML list at the document root");
+  }
+  return parsed as Instance[];
+}
+
+export function buildInstance(name: string, connStr: string): Instance {
+  return {
+    name,
+    conn_str: connStr,
+    preset_metrics: "full",
+    custom_metrics: null,
+    is_enabled: true,
+    group: "default",
+    custom_tags: {
+      env: "production",
+      cluster: "default",
+      node_name: name,
+      // Sed-substituted placeholder by config/scripts/generate-pgwatch-sources.sh.
+      // js-yaml emits this unquoted on dump (~ is only special at the start of a
+      // scalar in the right context); sed s/~sink_type~/.../g still hits it as
+      // raw text regardless.
+      sink_type: "~sink_type~",
+    },
+  };
+}
+
+/**
+ * Parse → mutate → serialize: load existing list, append, dump back.
+ *
+ * Replaces the previous text-append code path which corrupted instances.yml
+ * after `remove` had left the empty marker `[]` in the file (the append
+ * produced two YAML documents in one file → parse error on every subsequent
+ * read).
+ *
+ * Replaces files where the previous code path treated the directory created
+ * by Docker's bind-mount-into-missing-path as a target.
+ */
+export function addInstanceToFile(file: string, instance: Instance): void {
+  if (fs.existsSync(file) && fs.lstatSync(file).isDirectory()) {
+    fs.rmSync(file, { recursive: true, force: true });
+  }
+  const existing = loadInstances(file);
+  if (existing.some((i) => i.name === instance.name)) {
+    throw new Error(`Monitoring target '${instance.name}' already exists`);
+  }
+  existing.push(instance);
+  fs.writeFileSync(file, yaml.dump(existing), "utf8");
+}
+
+/**
+ * Remove a named instance from the file. Returns true if removed.
+ */
+export function removeInstanceFromFile(file: string, name: string): boolean {
+  const instances = loadInstances(file);
+  const filtered = instances.filter((i) => i.name !== name);
+  if (filtered.length === instances.length) return false;
+  fs.writeFileSync(file, yaml.dump(filtered), "utf8");
+  return true;
+}
+
+/**
+ * Extract `sslmode` (lowercased) from a postgresql:// URL. Returns `""` for
+ * unset or unparseable.
+ */
+export function extractSslmode(connStr: string): string {
+  try {
+    return (new URL(connStr).searchParams.get("sslmode") || "").toLowerCase();
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Map libpq sslmode values to node-postgres' `ssl` option.
+ *
+ * libpq:                     node-postgres ssl:
+ *   disable                    false
+ *   allow / prefer / require   { rejectUnauthorized: false }   (encrypt, no chain check)
+ *   verify-ca                  { rejectUnauthorized: true, checkServerIdentity: () => undefined }
+ *   verify-full                { rejectUnauthorized: true }
+ *   no-verify (pg extension)   { rejectUnauthorized: false }
+ *
+ * Default for unset: prefer-like → no chain verification, matches what
+ * pgwatch (Go pgx) does and what users pass to psql every day.
+ */
+export type SslOption = false | { rejectUnauthorized: boolean; checkServerIdentity?: () => undefined };
+
+export function sslOptionFromConnString(connStr: string): SslOption {
+  return sslOptionFromSslmode(extractSslmode(connStr));
+}
+
+function sslOptionFromSslmode(sslmode: string): SslOption {
+  switch (sslmode) {
+    case "disable":
+      return false;
+    case "verify-ca":
+      return { rejectUnauthorized: true, checkServerIdentity: () => undefined };
+    case "verify-full":
+      return { rejectUnauthorized: true };
+    case "allow":
+    case "prefer":
+    case "require":
+    case "no-verify":
+    case "":
+    default:
+      return { rejectUnauthorized: false };
+  }
+}
+
+/**
+ * The set of sslmode values for which we DO NOT verify the certificate chain.
+ * Exposed so callers can warn users about the lax security posture.
+ */
+export const LAX_SSLMODES = new Set(["", "allow", "prefer", "require"]);
+
+export function isLaxSslmode(sslmode: string): boolean {
+  return LAX_SSLMODES.has(sslmode);
+}
+
+/**
+ * Print a stderr warning when the connection string uses an sslmode that
+ * skips certificate-chain verification. Centralises the message so the
+ * three Client-construction sites stay consistent.
+ */
+export function warnIfLaxSslmode(connStr: string): void {
+  const sslmode = extractSslmode(connStr);
+  if (!isLaxSslmode(sslmode)) return;
+  const shown = sslmode || "(unset)";
+  console.error(
+    `⚠ sslmode=${shown}: TLS chain is NOT verified (matches libpq/psql semantics). ` +
+      `Use sslmode=verify-full for full chain+hostname verification.`,
+  );
+}
+
+/**
+ * Build a `pg.Client` config from a connection string that ACTUALLY honors
+ * libpq sslmode semantics.
+ *
+ * This is non-trivial because node-postgres' `Client` constructor, given a
+ * `connectionString`, runs `Object.assign({}, config, parse(connectionString))`
+ * — meaning the parsed sslmode-derived `ssl` value REPLACES any explicit
+ * `ssl` you passed alongside `connectionString`. So setting
+ * `{ connectionString, ssl: { rejectUnauthorized: false } }` does not work
+ * when the URL contains `sslmode=require` (the parsed value `{}` wins, and
+ * `{}` defaults to chain verification → "self-signed certificate in
+ * certificate chain" against managed Postgres).
+ *
+ * The fix: parse the URL ourselves, pass discrete host/port/user/etc., and
+ * include our explicit `ssl` — never pass `connectionString` so nothing
+ * overrides us.
+ *
+ * We strip `sslmode` from the URL before handing it to `pg-connection-string`'s
+ * `parse()` so that:
+ *   1. its `process.emitWarning("SECURITY WARNING: SSL modes 'prefer'/'require'/
+ *      'verify-ca' are treated as aliases for 'verify-full'…")` doesn't fire
+ *      on every CLI invocation against a Supabase-shaped URL, and
+ *   2. its `verify-ca` compatibility branch doesn't *throw* on us (requires
+ *      sslrootcert which we don't have).
+ *
+ * We don't use the parser's `ssl` output anyway — we compute our own from
+ * `sslOptionFromSslmode(extractSslmode(originalConnStr))` — so removing the
+ * sslmode parameter before parsing is a no-op for the fields we actually use.
+ */
+export function buildClientConfig(
+  connStr: string,
+  extra: { connectionTimeoutMillis?: number } = {},
+): ClientConfig {
+  const sslmode = extractSslmode(connStr);
+  const parsed = parseConnString(withoutSslmode(connStr));
+  return {
+    host: parsed.host || undefined,
+    port: parsed.port ? Number(parsed.port) : undefined,
+    user: parsed.user,
+    password: parsed.password,
+    database: parsed.database || undefined,
+    ssl: sslOptionFromSslmode(sslmode),
+    ...extra,
+  };
+}
+
+function withoutSslmode(connStr: string): string {
+  try {
+    const u = new URL(connStr);
+    u.searchParams.delete("sslmode");
+    return u.toString();
+  } catch {
+    return connStr;
+  }
+}

package/lib/mcp-server.ts

@@ -15,6 +15,7 @@ import {
   type ConfigChange,
 } from "./issues";
 import { fetchReports, fetchAllReports, fetchReportFiles, fetchReportFileData, parseFlexibleDate } from "./reports";
+import { uploadFile, downloadFile, buildMarkdownLink, uploadAttachments, appendAttachmentsToContent } from "./storage";
 import { resolveBaseUrls } from "./util";
 
 // MCP SDK imports - Bun handles these directly
@@ -107,13 +108,19 @@ export async function handleToolCall(
       const issueId = String(args.issue_id || "").trim();
       const rawContent = String(args.content || "");
       const parentCommentId = args.parent_comment_id ? String(args.parent_comment_id) : undefined;
+      const attachments = Array.isArray(args.attachments) ? args.attachments.map(String).filter((p) => p.length > 0) : [];
       if (!issueId) {
         return { content: [{ type: "text", text: "issue_id is required" }], isError: true };
       }
-      if (!rawContent) {
-        return { content: [{ type: "text", text: "content is required" }], isError: true };
+      if (!rawContent && attachments.length === 0) {
+        return { content: [{ type: "text", text: "content or attachments is required" }], isError: true };
+      }
+      let content = interpretEscapes(rawContent);
+      if (attachments.length > 0) {
+        const { storageBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+        const uploaded = await uploadAttachments({ apiKey, storageBaseUrl, attachmentPaths: attachments, debug });
+        content = appendAttachmentsToContent(content, uploaded);
       }
-      const content = interpretEscapes(rawContent);
       const result = await createIssueComment({ apiKey, apiBaseUrl, issueId, content, parentCommentId, debug });
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }
@@ -125,15 +132,21 @@ export async function handleToolCall(
       }
       const title = interpretEscapes(rawTitle);
       const rawDescription = args.description ? String(args.description) : undefined;
-      const description = rawDescription ? interpretEscapes(rawDescription) : undefined;
+      let description = rawDescription ? interpretEscapes(rawDescription) : undefined;
       const projectId = args.project_id !== undefined ? Number(args.project_id) : undefined;
       const labels = Array.isArray(args.labels) ? args.labels.map(String) : undefined;
+      const attachments = Array.isArray(args.attachments) ? args.attachments.map(String).filter((p) => p.length > 0) : [];
       // Get orgId from args or fall back to config
       const orgId = args.org_id !== undefined ? Number(args.org_id) : cfg.orgId;
       // Note: orgId=0 is technically valid (though unlikely), so don't use falsy check
       if (orgId === undefined || orgId === null || Number.isNaN(orgId)) {
         return { content: [{ type: "text", text: "org_id is required. Either provide it as a parameter or run 'pgai auth' to set it in config." }], isError: true };
       }
+      if (attachments.length > 0) {
+        const { storageBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+        const uploaded = await uploadAttachments({ apiKey, storageBaseUrl, attachmentPaths: attachments, debug });
+        description = appendAttachmentsToContent(description ?? "", uploaded);
+      }
       const result = await createIssue({ apiKey, apiBaseUrl, title, orgId, description, projectId, labels, debug });
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }
@@ -146,17 +159,33 @@ export async function handleToolCall(
       const rawTitle = args.title !== undefined ? String(args.title) : undefined;
       const title = rawTitle !== undefined ? interpretEscapes(rawTitle) : undefined;
       const rawDescription = args.description !== undefined ? String(args.description) : undefined;
-      const description = rawDescription !== undefined ? interpretEscapes(rawDescription) : undefined;
+      let description = rawDescription !== undefined ? interpretEscapes(rawDescription) : undefined;
       const status = args.status !== undefined ? Number(args.status) : undefined;
       const labels = Array.isArray(args.labels) ? args.labels.map(String) : undefined;
-      // Validate that at least one update field is provided
-      if (title === undefined && description === undefined && status === undefined && labels === undefined) {
-        return { content: [{ type: "text", text: "At least one field to update is required (title, description, status, or labels)" }], isError: true };
+      const attachments = Array.isArray(args.attachments) ? args.attachments.map(String).filter((p) => p.length > 0) : [];
+      // Validate that at least one update field is provided (attachments alone counts)
+      if (title === undefined && description === undefined && status === undefined && labels === undefined && attachments.length === 0) {
+        return { content: [{ type: "text", text: "At least one field to update is required (title, description, status, labels, or attachments)" }], isError: true };
       }
       // Validate status value if provided (check for NaN and valid values)
       if (status !== undefined && (Number.isNaN(status) || (status !== 0 && status !== 1))) {
         return { content: [{ type: "text", text: "status must be 0 (open) or 1 (closed)" }], isError: true };
       }
+      if (attachments.length > 0) {
+        // If the caller did not supply a new description, fetch the existing one
+        // and append to it so "add a screenshot to issue X" is one round-trip
+        // for the agent. Same race-window tradeoff as the CLI flag.
+        if (description === undefined) {
+          const existing = await fetchIssue({ apiKey, apiBaseUrl, issueId, debug });
+          if (!existing) {
+            return { content: [{ type: "text", text: `Issue not found: ${issueId}` }], isError: true };
+          }
+          description = (existing as { description?: string | null }).description ?? "";
+        }
+        const { storageBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+        const uploaded = await uploadAttachments({ apiKey, storageBaseUrl, attachmentPaths: attachments, debug });
+        description = appendAttachmentsToContent(description, uploaded);
+      }
       const result = await updateIssue({ apiKey, apiBaseUrl, issueId, title, description, status, labels, debug });
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }
@@ -164,17 +193,62 @@ export async function handleToolCall(
     if (toolName === "update_issue_comment") {
       const commentId = String(args.comment_id || "").trim();
       const rawContent = String(args.content || "");
+      const attachments = Array.isArray(args.attachments) ? args.attachments.map(String).filter((p) => p.length > 0) : [];
       if (!commentId) {
         return { content: [{ type: "text", text: "comment_id is required" }], isError: true };
       }
-      if (!rawContent.trim()) {
-        return { content: [{ type: "text", text: "content is required" }], isError: true };
+      if (!rawContent.trim() && attachments.length === 0) {
+        return { content: [{ type: "text", text: "content or attachments is required" }], isError: true };
+      }
+      let content = interpretEscapes(rawContent);
+      if (attachments.length > 0) {
+        const { storageBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+        const uploaded = await uploadAttachments({ apiKey, storageBaseUrl, attachmentPaths: attachments, debug });
+        content = appendAttachmentsToContent(content, uploaded);
       }
-      const content = interpretEscapes(rawContent);
       const result = await updateIssueComment({ apiKey, apiBaseUrl, commentId, content, debug });
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }
 
+    if (toolName === "upload_file") {
+      const filePath = String(args.path || "").trim();
+      if (!filePath) {
+        return { content: [{ type: "text", text: "path is required" }], isError: true };
+      }
+      const { storageBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+      const result = await uploadFile({ apiKey, storageBaseUrl, filePath, debug });
+      const markdown = buildMarkdownLink(result.url, storageBaseUrl, result.metadata.originalName);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                success: result.success,
+                url: result.url,
+                markdown,
+                metadata: result.metadata,
+                requestId: result.requestId,
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+
+    if (toolName === "download_file") {
+      const fileUrl = String(args.url || "").trim();
+      const outputPath = args.output_path !== undefined ? String(args.output_path) : undefined;
+      if (!fileUrl) {
+        return { content: [{ type: "text", text: "url is required" }], isError: true };
+      }
+      const { storageBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+      const result = await downloadFile({ apiKey, storageBaseUrl, fileUrl, outputPath, debug });
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+
     // Action Items Tools
     if (toolName === "view_action_item") {
       // Support both single ID and array of IDs
@@ -345,22 +419,27 @@ export async function startMcpServer(rootOpts?: RootOptsLike, extra?: { debug?:
         },
         {
           name: "post_issue_comment",
-          description: "Post a new comment to an issue (optionally as a reply)",
+          description: "Post a new comment to an issue (optionally as a reply). Local files passed via 'attachments' are uploaded to PostgresAI storage and the resulting markdown links are appended to the comment body (image extensions render inline).",
           inputSchema: {
             type: "object",
             properties: {
               issue_id: { type: "string", description: "Issue ID (UUID)" },
               content: { type: "string", description: "Comment text (supports \\n as newline)" },
               parent_comment_id: { type: "string", description: "Parent comment ID (UUID) for replies" },
+              attachments: {
+                type: "array",
+                items: { type: "string" },
+                description: "Local file paths to upload and append as markdown links (images render inline). Either 'content' or 'attachments' must be non-empty.",
+              },
               debug: { type: "boolean", description: "Enable verbose debug logs" },
             },
-            required: ["issue_id", "content"],
+            required: ["issue_id"],
             additionalProperties: false,
           },
         },
         {
           name: "create_issue",
-          description: "Create a new issue in PostgresAI",
+          description: "Create a new issue in PostgresAI. Local files passed via 'attachments' are uploaded to PostgresAI storage and the resulting markdown links are appended to the issue description.",
           inputSchema: {
             type: "object",
             properties: {
@@ -373,6 +452,11 @@ export async function startMcpServer(rootOpts?: RootOptsLike, extra?: { debug?:
                 items: { type: "string" },
                 description: "Labels to apply to the issue",
               },
+              attachments: {
+                type: "array",
+                items: { type: "string" },
+                description: "Local file paths to upload and append as markdown links to the description (images render inline)",
+              },
               debug: { type: "boolean", description: "Enable verbose debug logs" },
             },
             required: ["title"],
@@ -381,7 +465,7 @@ export async function startMcpServer(rootOpts?: RootOptsLike, extra?: { debug?:
         },
         {
           name: "update_issue",
-          description: "Update an existing issue (title, description, status, labels). Use status=1 to close, status=0 to reopen.",
+          description: "Update an existing issue (title, description, status, labels). Use status=1 to close, status=0 to reopen. Local files passed via 'attachments' are uploaded and appended to 'description'; if 'description' is omitted, the existing description is fetched first and appended to.",
           inputSchema: {
             type: "object",
             properties: {
@@ -394,6 +478,11 @@ export async function startMcpServer(rootOpts?: RootOptsLike, extra?: { debug?:
                 items: { type: "string" },
                 description: "Labels to set on the issue",
               },
+              attachments: {
+                type: "array",
+                items: { type: "string" },
+                description: "Local file paths to upload and append as markdown links (images render inline). When provided without 'description', the existing description is fetched and appended to.",
+              },
               debug: { type: "boolean", description: "Enable verbose debug logs" },
             },
             required: ["issue_id"],
@@ -402,15 +491,47 @@ export async function startMcpServer(rootOpts?: RootOptsLike, extra?: { debug?:
         },
         {
           name: "update_issue_comment",
-          description: "Update an existing issue comment",
+          description: "Update an existing issue comment. Local files passed via 'attachments' are uploaded and appended to 'content' as markdown links.",
           inputSchema: {
             type: "object",
             properties: {
               comment_id: { type: "string", description: "Comment ID (UUID)" },
-              content: { type: "string", description: "New comment text (supports \\n as newline)" },
+              content: { type: "string", description: "New comment text (supports \\n as newline). Either 'content' or 'attachments' must be non-empty." },
+              attachments: {
+                type: "array",
+                items: { type: "string" },
+                description: "Local file paths to upload and append as markdown links (images render inline)",
+              },
+              debug: { type: "boolean", description: "Enable verbose debug logs" },
+            },
+            required: ["comment_id"],
+            additionalProperties: false,
+          },
+        },
+        {
+          name: "upload_file",
+          description: "Upload a local file to PostgresAI storage. Returns the storage URL and a ready-to-paste markdown link (image extensions get the inline `![](url)` form, others get `[](url)`). For posting attachments alongside an issue or comment, prefer the 'attachments' parameter on the issue/comment tools — this tool is for ad-hoc uploads or when you need the URL out of band.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              path: { type: "string", description: "Local file path to upload (absolute or relative to CWD)" },
+              debug: { type: "boolean", description: "Enable verbose debug logs" },
+            },
+            required: ["path"],
+            additionalProperties: false,
+          },
+        },
+        {
+          name: "download_file",
+          description: "Download a file from PostgresAI storage by URL (full URL under the storage base, or a relative path like /files/123/foo.png).",
+          inputSchema: {
+            type: "object",
+            properties: {
+              url: { type: "string", description: "Full URL (must be under the configured storage base) or relative storage path (e.g. /files/123/foo.png)" },
+              output_path: { type: "string", description: "Local destination path (default: derive filename from URL, save in CWD). When omitted, the path-traversal guard restricts the destination to CWD." },
               debug: { type: "boolean", description: "Enable verbose debug logs" },
             },
-            required: ["comment_id", "content"],
+            required: ["url"],
             additionalProperties: false,
           },
         },

package/lib/metrics-loader.ts

@@ -1,6 +1,6 @@
 /**
  * Metrics loader for express checkup reports
- * 
+ *
  * Loads SQL queries from embedded metrics data (generated from metrics.yml at build time).
  * Provides version-aware query selection and row transformation utilities.
  */
@@ -9,7 +9,7 @@ import { METRICS, MetricDefinition } from "./metrics-embedded";
 
 /**
  * Get SQL query for a specific metric, selecting the appropriate version.
- * 
+ *
  * @param metricName - Name of the metric (e.g., "settings", "db_stats")
  * @param pgMajorVersion - PostgreSQL major version (default: 16)
  * @returns SQL query string
@@ -41,7 +41,7 @@ export function getMetricSql(metricName: string, pgMajorVersion: number = 16): s
 
 /**
  * Get metric definition including all metadata.
- * 
+ *
  * @param metricName - Name of the metric
  * @returns MetricDefinition or undefined if not found
  */