ima-claude 2.16.0 → 2.20.0

package/plugins/ima-claude/skills/mcp-atlassian/references/direct-api-attachments.md

@@ -0,0 +1,115 @@
+# Atlassian Direct API — Attachments
+
+MCP gap: no attachment download or upload. Use these curl recipes.
+
+See [direct-api-auth.md](direct-api-auth.md) for auth setup.
+
+All examples use Gateway (Bearer) auth. Substitute Basic auth headers if needed.
+
+---
+
+### List Attachments on a Jira Issue
+
+**API:** `GET /rest/api/3/issue/{issueKey}?fields=attachment`
+**When:** Need to see what files are attached before downloading.
+
+```bash
+curl -s \
+  -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+  "https://api.atlassian.com/ex/jira/$ATLASSIAN_CLOUD_ID/rest/api/3/issue/PROJ-123?fields=attachment" \
+  | jq '.fields.attachment[] | {id, filename, mimeType, size, content}'
+```
+
+**Tip:** You can also use MCP `getJiraIssue` with `fields: ["attachment"]` — the `content` URL in the response is what you need for download.
+
+#### Response Shape
+
+```json
+{
+  "id": "10001",
+  "filename": "mockup.png",
+  "mimeType": "image/png",
+  "size": 245678,
+  "content": "https://yoursite.atlassian.net/rest/api/3/attachment/content/10001"
+}
+```
+
+---
+
+### Download a Single Attachment
+
+**API:** `GET` the `content` URL from the attachment metadata
+**When:** Need the actual binary file (image, PDF, document).
+
+```bash
+# Get the download URL from attachment metadata
+ATTACHMENT_URL=$(curl -s \
+  -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+  "https://api.atlassian.com/ex/jira/$ATLASSIAN_CLOUD_ID/rest/api/3/issue/PROJ-123?fields=attachment" \
+  | jq -r '.fields.attachment[] | select(.filename == "mockup.png") | .content')
+
+# Download the file
+curl -s -L \
+  -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+  -o "mockup.png" \
+  "$ATTACHMENT_URL"
+```
+
+#### Notes
+- The `-L` flag follows redirects — Atlassian may redirect to a CDN URL
+- For Gateway auth, the `content` URL may use the direct domain. The Bearer token works with both
+- To download ALL attachments from an issue, pipe through a loop:
+
+```bash
+curl -s \
+  -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+  "https://api.atlassian.com/ex/jira/$ATLASSIAN_CLOUD_ID/rest/api/3/issue/PROJ-123?fields=attachment" \
+  | jq -r '.fields.attachment[] | "\(.content)\t\(.filename)"' \
+  | while IFS=$'\t' read -r url fname; do
+      curl -s -L -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" -o "$fname" "$url"
+      echo "Downloaded: $fname"
+    done
+```
+
+---
+
+### Upload Attachment to a Jira Issue
+
+**API:** `POST /rest/api/3/issue/{issueKey}/attachments`
+**When:** Attaching generated files, screenshots, or documents to an issue.
+
+```bash
+curl -s -X POST \
+  -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+  -H "X-Atlassian-Token: no-check" \
+  -F "file=@/path/to/file.pdf" \
+  "https://api.atlassian.com/ex/jira/$ATLASSIAN_CLOUD_ID/rest/api/3/issue/PROJ-123/attachments" \
+  | jq '.[0] | {id, filename, size}'
+```
+
+#### Notes
+- **Do NOT set `Content-Type: application/json`** — this is `multipart/form-data` (curl sets it automatically with `-F`)
+- `X-Atlassian-Token: no-check` is required (XSRF protection bypass for attachments)
+- Response is an array of attachment objects (one per file)
+- Multiple files: use multiple `-F "file=@path"` flags
+
+---
+
+### Upload Attachment to a Confluence Page
+
+**API:** `POST /wiki/rest/api/content/{pageId}/child/attachment`
+**When:** Attaching files to Confluence pages.
+
+```bash
+curl -s -X POST \
+  -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+  -H "X-Atlassian-Token: no-check" \
+  -F "file=@/path/to/diagram.png" \
+  "https://api.atlassian.com/ex/confluence/$ATLASSIAN_CLOUD_ID/wiki/rest/api/content/12345/child/attachment" \
+  | jq '.results[0] | {id: .id, title: .title}'
+```
+
+#### Notes
+- Use the **Confluence v1 API** (not v2) for attachment uploads
+- Page ID is numeric — get it from MCP `getConfluencePage` or `searchConfluenceUsingCql`
+- To update an existing attachment, use `PUT` with the same endpoint and filename

package/plugins/ima-claude/skills/mcp-atlassian/references/direct-api-auth.md

@@ -0,0 +1,103 @@
+# Atlassian Direct REST API — Authentication
+
+When the bundled MCP tools don't cover an operation, use `curl` via Bash with these auth patterns.
+
+## ENV Variables
+
+| Variable | Required | Purpose | Example |
+|----------|----------|---------|---------|
+| `ATLASSIAN_CLOUD_ID` | Yes (gateway) | Cloud instance ID | `a1b2c3d4-e5f6-...` |
+| `ATLASSIAN_BEARER_TOKEN` | Yes (gateway) | Service account token (`ATSTT...`) | `ATSTT...` |
+| `ATLASSIAN_DOMAIN` | Yes (basic) | Site domain | `yoursite.atlassian.net` |
+| `ATLASSIAN_EMAIL` | Yes (basic) | Account email | `you@company.com` |
+| `ATLASSIAN_API_TOKEN` | Yes (basic) | Personal API token | `abc123...` |
+
+**Choose one auth method.** Gateway (Bearer) is preferred for service accounts. Basic is the fallback for personal tokens.
+
+## Base URLs
+
+### Jira REST API v3
+
+| Auth Method | Base URL |
+|-------------|----------|
+| Gateway (Bearer) | `https://api.atlassian.com/ex/jira/$ATLASSIAN_CLOUD_ID/rest/api/3` |
+| Direct (Basic) | `https://$ATLASSIAN_DOMAIN/rest/api/3` |
+
+### Jira Agile API v1
+
+| Auth Method | Base URL |
+|-------------|----------|
+| Gateway (Bearer) | `https://api.atlassian.com/ex/jira/$ATLASSIAN_CLOUD_ID/rest/agile/1.0` |
+| Direct (Basic) | `https://$ATLASSIAN_DOMAIN/rest/agile/1.0` |
+
+### Confluence REST API
+
+| Auth Method | Base URL |
+|-------------|----------|
+| Gateway (Bearer) | `https://api.atlassian.com/ex/confluence/$ATLASSIAN_CLOUD_ID/wiki/rest/api` |
+| Direct (Basic) | `https://$ATLASSIAN_DOMAIN/wiki/rest/api` |
+
+### Confluence v2 API
+
+| Auth Method | Base URL |
+|-------------|----------|
+| Gateway (Bearer) | `https://api.atlassian.com/ex/confluence/$ATLASSIAN_CLOUD_ID/wiki/api/v2` |
+| Direct (Basic) | `https://$ATLASSIAN_DOMAIN/wiki/api/v2` |
+
+## Reusable Header Blocks
+
+### Gateway (Bearer) — copy into any curl
+
+```bash
+-H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+-H "Content-Type: application/json" \
+-H "Accept: application/json"
+```
+
+### Direct (Basic) — copy into any curl
+
+```bash
+-H "Authorization: Basic $(echo -n "$ATLASSIAN_EMAIL:$ATLASSIAN_API_TOKEN" | base64)" \
+-H "Content-Type: application/json" \
+-H "Accept: application/json"
+```
+
+## Verify Your Setup
+
+Run this before any direct API session. Should return your display name.
+
+```bash
+# Gateway auth
+curl -s \
+  -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+  "https://api.atlassian.com/ex/jira/$ATLASSIAN_CLOUD_ID/rest/api/3/myself" \
+  | jq '.displayName'
+
+# Basic auth
+curl -s \
+  -H "Authorization: Basic $(echo -n "$ATLASSIAN_EMAIL:$ATLASSIAN_API_TOKEN" | base64)" \
+  "https://$ATLASSIAN_DOMAIN/rest/api/3/myself" \
+  | jq '.displayName'
+```
+
+## Getting the Cloud ID
+
+The MCP's `getAccessibleAtlassianResources` returns the `cloudId`. You can also get it via:
+
+```bash
+curl -s \
+  -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+  "https://api.atlassian.com/oauth/token/accessible-resources" \
+  | jq '.[0].id'
+```
+
+Store it: `export ATLASSIAN_CLOUD_ID="<value>"`
+
+## Error Patterns
+
+| Status | Meaning | Fix |
+|--------|---------|-----|
+| 401 | Bad credentials | Check token/email/apiToken values |
+| 403 | Missing scope or permission | Token needs the right OAuth scopes or project access |
+| 404 | Wrong base URL or resource not found | Check gateway vs direct URL, verify resource exists |
+| 429 | Rate limited | Wait and retry; Jira Cloud allows ~100 req/min |

package/plugins/ima-claude/skills/mcp-atlassian/references/direct-api-bulk.md

@@ -0,0 +1,149 @@
+# Atlassian Direct API — Bulk Operations
+
+MCP gap: no batch/bulk endpoints. Use these patterns for multi-issue operations.
+
+See [direct-api-auth.md](direct-api-auth.md) for auth setup.
+
+All examples use Gateway (Bearer) auth.
+
+---
+
+### Bulk Edit Issues (Jira v3)
+
+**API:** `POST /rest/api/3/issue/bulk`
+**When:** Updating the same fields on many issues at once.
+
+```bash
+curl -s -X POST \
+  -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "issueUpdates": [
+      {
+        "issueIdOrKey": "PROJ-101",
+        "fields": {"priority": {"name": "High"}, "labels": ["urgent"]}
+      },
+      {
+        "issueIdOrKey": "PROJ-102",
+        "fields": {"priority": {"name": "High"}, "labels": ["urgent"]}
+      }
+    ]
+  }' \
+  "https://api.atlassian.com/ex/jira/$ATLASSIAN_CLOUD_ID/rest/api/3/issue/bulk" \
+  | jq '.errors'
+```
+
+#### Notes
+- Max ~50 issues per request (Atlassian soft limit)
+- Response includes per-issue errors — check `.errors` for partial failures
+- Each issue can have different field updates
+- This endpoint may not be available on all Jira Cloud plans
+
+---
+
+### Bulk Transition (Loop Pattern)
+
+**When:** Moving many issues through a workflow step (e.g., close all done issues).
+
+This uses the MCP `transitionJiraIssue` in a loop. No direct bulk transition API exists.
+
+**Pattern:**
+1. Find issues with JQL via MCP `searchJiraIssuesUsingJql`
+2. Get transitions for one representative issue via MCP `getTransitionsForJiraIssue`
+3. Loop `transitionJiraIssue` for each issue
+
+```
+# Step 1: Find issues
+searchJiraIssuesUsingJql
+  cloudId: "<cloudId>"
+  jql: "project = PROJ AND status = 'In Review'"
+  maxResults: 50
+  fields: ["summary", "status"]
+
+# Step 2: Get transition ID (same for all issues in the same workflow)
+getTransitionsForJiraIssue
+  cloudId: "<cloudId>"
+  issueIdOrKey: "PROJ-101"  # any issue from the results
+
+# Step 3: Transition each issue
+# Repeat for each issue key from Step 1:
+transitionJiraIssue
+  cloudId: "<cloudId>"
+  issueIdOrKey: "PROJ-101"
+  transition: {"id": "<transitionId>"}
+```
+
+#### Notes
+- Rate limit: ~100 requests/minute for Jira Cloud
+- For large batches (50+ issues), add a brief delay between calls
+- If issues span different workflows, group by issue type and get transitions per group
+
+---
+
+### Paginated JQL Fetch
+
+**When:** Fetching more results than the default page size (50).
+
+Use MCP `searchJiraIssuesUsingJql` with pagination:
+
+```
+# Page 1
+searchJiraIssuesUsingJql
+  cloudId: "<cloudId>"
+  jql: "project = PROJ AND status != Done"
+  maxResults: 50
+  startAt: 0
+  fields: ["summary", "status"]
+
+# Page 2
+searchJiraIssuesUsingJql
+  cloudId: "<cloudId>"
+  jql: "project = PROJ AND status != Done"
+  maxResults: 50
+  startAt: 50
+  fields: ["summary", "status"]
+```
+
+Or via direct API for more control:
+
+```bash
+curl -s \
+  -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jql": "project = PROJ AND status != Done ORDER BY created DESC",
+    "maxResults": 100,
+    "startAt": 0,
+    "fields": ["summary", "status", "assignee"]
+  }' \
+  "https://api.atlassian.com/ex/jira/$ATLASSIAN_CLOUD_ID/rest/api/3/search" \
+  | jq '{total: .total, count: (.issues | length), issues: [.issues[] | {key, summary: .fields.summary, status: .fields.status.name}]}'
+```
+
+#### Notes
+- MCP `searchJiraIssuesUsingJql` max is typically 50 per page
+- Direct API `POST /search` supports up to 100 per page
+- Check `.total` in response to know when to stop paginating
+- Use `POST` (not `GET`) for the search endpoint — JQL strings can exceed URL length limits
+
+---
+
+### Bulk Add Labels
+
+**When:** Tagging many issues with the same label.
+
+```bash
+# For each issue, use the update operations syntax
+for KEY in PROJ-101 PROJ-102 PROJ-103; do
+  curl -s -X PUT \
+    -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+    -H "Content-Type: application/json" \
+    -d '{"update": {"labels": [{"add": "reviewed"}]}}' \
+    "https://api.atlassian.com/ex/jira/$ATLASSIAN_CLOUD_ID/rest/api/3/issue/$KEY"
+  echo "Labeled: $KEY"
+done
+```
+
+#### Notes
+- Uses Jira's `update` operations (add/remove/set) — more precise than replacing the entire `fields.labels` array
+- Same pattern works for `components`, `fixVersions`, and other array fields

package/plugins/ima-claude/skills/mcp-atlassian/references/direct-api-misc.md

@@ -0,0 +1,195 @@
+# Atlassian Direct API — Miscellaneous Operations
+
+MCP gaps: comment edit/delete, watchers, components, versions, page deletion.
+
+See [direct-api-auth.md](direct-api-auth.md) for auth setup.
+
+All examples use Gateway (Bearer) auth.
+
+---
+
+## Comments
+
+### Edit a Jira Comment
+
+**API:** `PUT /rest/api/3/issue/{issueKey}/comment/{commentId}`
+**When:** Correcting or updating an existing comment.
+
+```bash
+curl -s -X PUT \
+  -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "body": {
+      "type": "doc",
+      "version": 1,
+      "content": [
+        {
+          "type": "paragraph",
+          "content": [{"type": "text", "text": "Updated comment text"}]
+        }
+      ]
+    }
+  }' \
+  "https://api.atlassian.com/ex/jira/$ATLASSIAN_CLOUD_ID/rest/api/3/issue/PROJ-123/comment/10042"
+```
+
+#### Notes
+- Comment body must be ADF (not Markdown) for the v3 API
+- Get comment IDs from `getJiraIssue` with `fields: ["comment"]`
+- Only the comment author or an admin can edit
+
+### Delete a Jira Comment
+
+**API:** `DELETE /rest/api/3/issue/{issueKey}/comment/{commentId}`
+**When:** Removing erroneous or sensitive comments.
+
+```bash
+curl -s -X DELETE \
+  -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+  "https://api.atlassian.com/ex/jira/$ATLASSIAN_CLOUD_ID/rest/api/3/issue/PROJ-123/comment/10042"
+```
+
+#### Notes
+- Returns HTTP 204 on success (no body)
+- Only the comment author or an admin can delete
+
+---
+
+## Watchers
+
+### Get Watchers
+
+**API:** `GET /rest/api/3/issue/{issueKey}/watchers`
+**When:** Checking who is watching an issue.
+
+```bash
+curl -s \
+  -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+  "https://api.atlassian.com/ex/jira/$ATLASSIAN_CLOUD_ID/rest/api/3/issue/PROJ-123/watchers" \
+  | jq '.watchers[] | {accountId, displayName}'
+```
+
+### Add a Watcher
+
+**API:** `POST /rest/api/3/issue/{issueKey}/watchers`
+**When:** Subscribing someone to issue notifications.
+
+```bash
+curl -s -X POST \
+  -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '"5b10a2844c20165700ede21g"' \
+  "https://api.atlassian.com/ex/jira/$ATLASSIAN_CLOUD_ID/rest/api/3/issue/PROJ-123/watchers"
+```
+
+#### Notes
+- Body is a **raw JSON string** (the accountId in quotes), not an object
+- Get `accountId` from MCP `lookupJiraAccountId`
+
+### Remove a Watcher
+
+**API:** `DELETE /rest/api/3/issue/{issueKey}/watchers?accountId={accountId}`
+**When:** Unsubscribing someone from issue notifications.
+
+```bash
+curl -s -X DELETE \
+  -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+  "https://api.atlassian.com/ex/jira/$ATLASSIAN_CLOUD_ID/rest/api/3/issue/PROJ-123/watchers?accountId=5b10a2844c20165700ede21g"
+```
+
+---
+
+## Components
+
+### List Project Components
+
+**API:** `GET /rest/api/3/project/{projectKey}/components`
+**When:** Finding component IDs for issue creation or filtering.
+
+```bash
+curl -s \
+  -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+  "https://api.atlassian.com/ex/jira/$ATLASSIAN_CLOUD_ID/rest/api/3/project/PROJ/components" \
+  | jq '.[] | {id, name, lead: .lead.displayName}'
+```
+
+### Create a Component
+
+**API:** `POST /rest/api/3/component`
+**When:** Adding a new component to a project.
+
+```bash
+curl -s -X POST \
+  -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Authentication",
+    "project": "PROJ",
+    "description": "Auth and identity management",
+    "leadAccountId": "5b10a2844c20165700ede21g"
+  }' \
+  "https://api.atlassian.com/ex/jira/$ATLASSIAN_CLOUD_ID/rest/api/3/component" \
+  | jq '{id, name}'
+```
+
+---
+
+## Versions (Releases)
+
+### List Project Versions
+
+**API:** `GET /rest/api/3/project/{projectKey}/versions`
+**When:** Finding version IDs for fix-version assignment.
+
+```bash
+curl -s \
+  -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+  "https://api.atlassian.com/ex/jira/$ATLASSIAN_CLOUD_ID/rest/api/3/project/PROJ/versions" \
+  | jq '.[] | {id, name, released, releaseDate}'
+```
+
+### Create a Version
+
+**API:** `POST /rest/api/3/version`
+**When:** Setting up a new release version.
+
+```bash
+curl -s -X POST \
+  -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "v2.1.0",
+    "projectId": 10001,
+    "description": "Q2 release",
+    "releaseDate": "2026-06-30",
+    "released": false
+  }' \
+  "https://api.atlassian.com/ex/jira/$ATLASSIAN_CLOUD_ID/rest/api/3/version" \
+  | jq '{id, name}'
+```
+
+#### Notes
+- Uses numeric `projectId`, not project key — get it from `getVisibleJiraProjects`
+
+---
+
+## Confluence Page Deletion
+
+### Delete a Confluence Page
+
+**API:** `DELETE /wiki/api/v2/pages/{pageId}`
+**When:** Removing outdated or draft Confluence pages.
+
+```bash
+curl -s -X DELETE \
+  -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+  "https://api.atlassian.com/ex/confluence/$ATLASSIAN_CLOUD_ID/wiki/api/v2/pages/12345"
+```
+
+#### Notes
+- Uses Confluence **v2 API** (not v1)
+- Returns HTTP 204 on success
+- Page is moved to trash first (recoverable for 30 days)
+- Get page ID from MCP `getConfluencePage` or `searchConfluenceUsingCql`
+- Child pages become orphans — reassign or delete them first