postgresai 0.15.0-rc.1 → 0.15.0-rc.2

package/README.md

@@ -249,22 +249,93 @@ Cursor configuration example (Settings → MCP):
 ```
 
 Tools exposed:
-- list_issues: returns the same JSON as `postgresai issues list`.
-- view_issue: view a single issue with its comments (args: { issue_id, debug? })
-- post_issue_comment: post a comment (args: { issue_id, content, parent_comment_id?, debug? })
+- `list_issues`: returns the same JSON as `postgresai issues list`.
+- `view_issue`: view a single issue with its comments (args: `{ issue_id, debug? }`).
+- `create_issue`: create a new issue (args: `{ title, description?, org_id, attachments?, debug? }`).
+- `update_issue`: update title/description/status/labels (args: `{ issue_id, title?, description?, status?, labels?, attachments?, debug? }`).
+- `post_issue_comment`: post a comment (args: `{ issue_id, content?, parent_comment_id?, attachments?, debug? }`).
+- `update_issue_comment`: update an existing comment (args: `{ comment_id, content?, attachments?, debug? }`).
+- `upload_file`: upload a local file and return the storage URL plus a ready-to-paste markdown link (args: `{ path, debug? }`).
+- `download_file`: download a file from storage (args: `{ url, output_path?, debug? }`).
+
+#### `attachments` parameter (issue/comment tools)
+
+`create_issue`, `update_issue`, `post_issue_comment`, and `update_issue_comment` accept an
+optional `attachments: string[]` of local file paths. Each file is uploaded to PostgresAI
+storage and the resulting markdown link is appended to the comment body or issue
+description (image extensions — `.png .jpg .jpeg .gif .webp .svg .bmp .ico` — render
+inline as `![](url)`; everything else as `[](url)`).
+
+For `post_issue_comment` and `update_issue_comment`, either `content` or `attachments`
+must be non-empty (attachments alone are allowed). For `update_issue` with `attachments`
+but no `description`, the existing description is fetched first and the new links are
+appended to it.
+
+#### Threat model
+
+The MCP server runs in your local user account with your PostgresAI API key. It
+treats the connected MCP client (the LLM agent) as **trusted** — the same way the
+CLI treats you when you type a command. In particular:
+
+- `upload_file` and the `attachments: string[]` parameter on the issue/comment tools
+  read **any local file the CLI process can read**, including secrets like
+  `~/.ssh/id_rsa`, `~/.aws/credentials`, or `~/.config/postgresai/config.json` (which
+  contains your own API key). The file's bytes are uploaded to PostgresAI storage
+  and the resulting URL becomes visible to anyone with read access to the issue or
+  comment it ends up in.
+- `download_file` writes to **any path the CLI process can write to** when
+  `output_path` is supplied (`~/.ssh/authorized_keys`, `~/.bashrc`, etc. are all
+  fair game). When `output_path` is omitted, downloads are restricted to the
+  current working directory.
+
+This is fine when the agent and the upstream context the agent is reading are
+trusted. It is **not** safe to run this MCP server against an agent that is
+processing untrusted text (issue bodies, comments, web pages, third-party docs)
+without additional sandboxing — a prompt-injection in any input the agent reads
+could be used to exfiltrate local secrets or write arbitrary files. If you need
+to expose this MCP server to such an agent, run the agent (and this server) in a
+container or restricted user account that doesn't have access to anything
+sensitive.
 
 ### Issues management (`issues` group)
 
 ```bash
-postgresai issues list                                  # List issues (shows: id, title, status, created_at)
-postgresai issues view <issueId>                        # View issue details and comments
-postgresai issues post_comment <issueId> <content>      # Post a comment to an issue
-# Options:
-#   --parent <uuid>  Parent comment ID (for replies)
+postgresai issues list                                       # List issues (shows: id, title, status, created_at)
+postgresai issues view <issueId>                             # View issue details and comments
+postgresai issues create --org-id <id> --title <t>           # Create a new issue
+postgresai issues update <issueId> [--title ... --status ...]# Update an existing issue
+postgresai issues post-comment <issueId> <content>           # Post a comment to an issue
+postgresai issues update-comment <commentId> <content>       # Update an existing comment
+postgresai issues files upload <path>                        # Upload a file, print URL + markdown
+postgresai issues files download <url> [-o <path>]           # Download a file
+# Common options:
+#   --parent <uuid>  Parent comment ID (for replies on post-comment)
 #   --debug          Enable debug output
 #   --json           Output raw JSON (overrides default YAML)
 ```
 
+#### Attaching files to issues and comments (`--attach`)
+
+`create`, `update`, `post-comment`, and `update-comment` accept a repeatable
+`--attach <path>` flag. Each file is uploaded to PostgresAI storage and a
+markdown link is appended to the comment body (or issue description). Image
+extensions — `.png .jpg .jpeg .gif .webp .svg .bmp .ico` — render inline as
+`![](url)`; everything else as `[](url)`. Multiple `--attach` flags preserve
+order; each link goes on its own line.
+
+```bash
+# Attach a screenshot to a new comment
+postgresai issues post-comment <issueId> "Saw this in prod" --attach screenshot.png
+
+# Attach multiple files to a new issue
+postgresai issues create --org-id 4 --title "Slow query" \
+  --description "Plan attached" --attach plan.txt --attach flame.svg
+
+# Attach a file to an existing issue without changing the description.
+# The current description is fetched and the link is appended to it.
+postgresai issues update <issueId> --attach trace.log
+```
+
 #### Output format for issues commands
 
 By default, issues commands print human-friendly YAML when writing to a terminal. For scripting, you can:

package/bin/postgres-ai.ts

@@ -14,7 +14,7 @@ import { startMcpServer } from "../lib/mcp-server";
 import { fetchIssues, fetchIssueComments, createIssueComment, fetchIssue, createIssue, updateIssue, updateIssueComment, fetchActionItem, fetchActionItems, createActionItem, updateActionItem, type ConfigChange } from "../lib/issues";
 import { fetchReports, fetchAllReports, fetchReportFiles, fetchReportFileData, renderMarkdownForTerminal, parseFlexibleDate } from "../lib/reports";
 import { resolveBaseUrls } from "../lib/util";
-import { uploadFile, downloadFile, buildMarkdownLink } from "../lib/storage";
+import { uploadFile, downloadFile, buildMarkdownLink, uploadAttachments, appendAttachmentsToContent } from "../lib/storage";
 import { applyInitPlan, applyUninitPlan, buildInitPlan, buildUninitPlan, checkCurrentUserPermissions, connectWithSslFallback, DEFAULT_MONITORING_USER, formatPermissionCheckMessages, KNOWN_PROVIDERS, redactPasswordsInSql, resolveAdminConnection, resolveMonitoringPassword, validateProvider, verifyInitSetup } from "../lib/init";
 import { SupabaseClient, resolveSupabaseConfig, extractProjectRefFromUrl, applyInitPlanViaSupabase, verifyInitSetupViaSupabase, fetchPoolerDatabaseUrl, type PgCompatibleError } from "../lib/supabase";
 import * as pkce from "../lib/pkce";
@@ -3915,9 +3915,18 @@ issues
   .command("post-comment <issueId> <content>")
   .description("post a new comment to an issue")
   .option("--parent <uuid>", "parent comment id")
+  .option(
+    "--attach <path>",
+    "attach a file (uploads to storage and appends a markdown link; repeatable)",
+    (value: string, previous: string[]) => {
+      previous.push(value);
+      return previous;
+    },
+    [] as string[]
+  )
   .option("--debug", "enable debug output")
   .option("--json", "output raw JSON")
-  .action(async (issueId: string, content: string, opts: { parent?: string; debug?: boolean; json?: boolean }) => {
+  .action(async (issueId: string, content: string, opts: { parent?: string; attach?: string[]; debug?: boolean; json?: boolean }) => {
     // Interpret escape sequences in content (e.g., \n -> newline)
     if (opts.debug) {
       // eslint-disable-next-line no-console
@@ -3929,7 +3938,11 @@ issues
       console.error(`Debug: Interpreted content: ${JSON.stringify(content)}`);
     }
 
-    const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Posting comment...");
+    const attachPaths = Array.isArray(opts.attach) ? opts.attach : [];
+    const spinner = createTtySpinner(
+      process.stdout.isTTY ?? false,
+      attachPaths.length > 0 ? "Uploading attachments..." : "Posting comment..."
+    );
     try {
       const rootOpts = program.opts<CliOptions>();
       const cfg = config.readConfig();
@@ -3941,13 +3954,25 @@ issues
         return;
       }
 
-      const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+      const { apiBaseUrl, storageBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+
+      let augmentedContent = content;
+      if (attachPaths.length > 0) {
+        const uploaded = await uploadAttachments({
+          apiKey,
+          storageBaseUrl,
+          attachmentPaths: attachPaths,
+          debug: !!opts.debug,
+        });
+        augmentedContent = appendAttachmentsToContent(content, uploaded);
+        spinner.update("Posting comment...");
+      }
 
       const result = await createIssueComment({
         apiKey,
         apiBaseUrl,
         issueId,
-        content,
+        content: augmentedContent,
         parentCommentId: opts.parent,
         debug: !!opts.debug,
       });
@@ -3976,9 +4001,18 @@ issues
     },
     [] as string[]
   )
+  .option(
+    "--attach <path>",
+    "attach a file (uploads to storage and appends a markdown link to the description; repeatable)",
+    (value: string, previous: string[]) => {
+      previous.push(value);
+      return previous;
+    },
+    [] as string[]
+  )
   .option("--debug", "enable debug output")
   .option("--json", "output raw JSON")
-  .action(async (rawTitle: string, opts: { orgId?: number; projectId?: number; description?: string; label?: string[]; debug?: boolean; json?: boolean }) => {
+  .action(async (rawTitle: string, opts: { orgId?: number; projectId?: number; description?: string; label?: string[]; attach?: string[]; debug?: boolean; json?: boolean }) => {
     const rootOpts = program.opts<CliOptions>();
     const cfg = config.readConfig();
     const { apiKey } = getConfig(rootOpts);
@@ -4005,16 +4039,33 @@ issues
     const description = opts.description !== undefined ? interpretEscapes(String(opts.description)) : undefined;
     const labels = Array.isArray(opts.label) && opts.label.length > 0 ? opts.label.map(String) : undefined;
     const projectId = typeof opts.projectId === "number" && !Number.isNaN(opts.projectId) ? opts.projectId : undefined;
+    const attachPaths = Array.isArray(opts.attach) ? opts.attach : [];
 
-    const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Creating issue...");
+    const spinner = createTtySpinner(
+      process.stdout.isTTY ?? false,
+      attachPaths.length > 0 ? "Uploading attachments..." : "Creating issue..."
+    );
     try {
-      const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+      const { apiBaseUrl, storageBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+
+      let augmentedDescription = description;
+      if (attachPaths.length > 0) {
+        const uploaded = await uploadAttachments({
+          apiKey,
+          storageBaseUrl,
+          attachmentPaths: attachPaths,
+          debug: !!opts.debug,
+        });
+        augmentedDescription = appendAttachmentsToContent(description ?? "", uploaded);
+        spinner.update("Creating issue...");
+      }
+
       const result = await createIssue({
         apiKey,
         apiBaseUrl,
         title,
         orgId,
-        description,
+        description: augmentedDescription,
         projectId,
         labels,
         debug: !!opts.debug,
@@ -4045,9 +4096,18 @@ issues
     [] as string[]
   )
   .option("--clear-labels", "set labels to an empty list")
+  .option(
+    "--attach <path>",
+    "attach a file (uploads and appends a markdown link to --description; if --description is omitted the existing description is fetched and appended to; repeatable)",
+    (value: string, previous: string[]) => {
+      previous.push(value);
+      return previous;
+    },
+    [] as string[]
+  )
   .option("--debug", "enable debug output")
   .option("--json", "output raw JSON")
-  .action(async (issueId: string, opts: { title?: string; description?: string; status?: string; label?: string[]; clearLabels?: boolean; debug?: boolean; json?: boolean }) => {
+  .action(async (issueId: string, opts: { title?: string; description?: string; status?: string; label?: string[]; clearLabels?: boolean; attach?: string[]; debug?: boolean; json?: boolean }) => {
     const rootOpts = program.opts<CliOptions>();
     const cfg = config.readConfig();
     const { apiKey } = getConfig(rootOpts);
@@ -4057,10 +4117,10 @@ issues
       return;
     }
 
-    const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+    const { apiBaseUrl, storageBaseUrl } = resolveBaseUrls(rootOpts, cfg);
 
     const title = opts.title !== undefined ? interpretEscapes(String(opts.title)) : undefined;
-    const description = opts.description !== undefined ? interpretEscapes(String(opts.description)) : undefined;
+    let description = opts.description !== undefined ? interpretEscapes(String(opts.description)) : undefined;
 
     let status: number | undefined = undefined;
     if (opts.status !== undefined) {
@@ -4090,8 +4150,38 @@ issues
       labels = opts.label.map(String);
     }
 
-    const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Updating issue...");
+    const attachPaths = Array.isArray(opts.attach) ? opts.attach : [];
+    const spinner = createTtySpinner(
+      process.stdout.isTTY ?? false,
+      attachPaths.length > 0 ? "Uploading attachments..." : "Updating issue..."
+    );
     try {
+      if (attachPaths.length > 0) {
+        // If the caller did not supply a new description, fetch the existing one
+        // and append to it. This makes "add a screenshot to issue X" a one-step
+        // operation rather than forcing the caller to copy-paste the existing
+        // description first. Small race window if someone else updates
+        // concurrently, which is acceptable for an interactive CLI / agent.
+        if (description === undefined) {
+          const existing = await fetchIssue({ apiKey, apiBaseUrl, issueId, debug: !!opts.debug });
+          if (!existing) {
+            spinner.stop();
+            console.error(`Issue not found: ${issueId}`);
+            process.exitCode = 1;
+            return;
+          }
+          description = (existing as { description?: string | null }).description ?? "";
+        }
+        const uploaded = await uploadAttachments({
+          apiKey,
+          storageBaseUrl,
+          attachmentPaths: attachPaths,
+          debug: !!opts.debug,
+        });
+        description = appendAttachmentsToContent(description ?? "", uploaded);
+        spinner.update("Updating issue...");
+      }
+
       const result = await updateIssue({
         apiKey,
         apiBaseUrl,
@@ -4115,9 +4205,18 @@ issues
 issues
   .command("update-comment <commentId> <content>")
   .description("update an existing issue comment")
+  .option(
+    "--attach <path>",
+    "attach a file (uploads and appends a markdown link to <content>; repeatable)",
+    (value: string, previous: string[]) => {
+      previous.push(value);
+      return previous;
+    },
+    [] as string[]
+  )
   .option("--debug", "enable debug output")
   .option("--json", "output raw JSON")
-  .action(async (commentId: string, content: string, opts: { debug?: boolean; json?: boolean }) => {
+  .action(async (commentId: string, content: string, opts: { attach?: string[]; debug?: boolean; json?: boolean }) => {
     if (opts.debug) {
       // eslint-disable-next-line no-console
       console.error(`Debug: Original content: ${JSON.stringify(content)}`);
@@ -4137,15 +4236,31 @@ issues
       return;
     }
 
-    const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Updating comment...");
+    const attachPaths = Array.isArray(opts.attach) ? opts.attach : [];
+    const spinner = createTtySpinner(
+      process.stdout.isTTY ?? false,
+      attachPaths.length > 0 ? "Uploading attachments..." : "Updating comment..."
+    );
     try {
-      const { apiBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+      const { apiBaseUrl, storageBaseUrl } = resolveBaseUrls(rootOpts, cfg);
+
+      let augmentedContent = content;
+      if (attachPaths.length > 0) {
+        const uploaded = await uploadAttachments({
+          apiKey,
+          storageBaseUrl,
+          attachmentPaths: attachPaths,
+          debug: !!opts.debug,
+        });
+        augmentedContent = appendAttachmentsToContent(content, uploaded);
+        spinner.update("Updating comment...");
+      }
 
       const result = await updateIssueComment({
         apiKey,
         apiBaseUrl,
         commentId,
-        content,
+        content: augmentedContent,
         debug: !!opts.debug,
       });
       spinner.stop();