postgresai 0.15.0-dev.1 → 0.15.0-dev.11

package/lib/mcp-server.ts

@@ -14,6 +14,8 @@ import {
   updateActionItem,
   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
@@ -106,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) }] };
     }
@@ -124,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) }] };
     }
@@ -145,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) }] };
     }
@@ -163,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
@@ -250,6 +325,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);
@@ -300,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: {
@@ -328,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"],
@@ -336,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: {
@@ -349,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"],
@@ -357,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,
           },
         },
@@ -442,6 +608,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

@@ -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
  */
@@ -63,7 +63,7 @@ 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",
@@ -75,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;
 
 /**