ima-claude 2.18.0 → 2.20.0

package/plugins/ima-claude/skills/mcp-atlassian/SKILL.md

@@ -1,19 +1,20 @@
 ---
 name: mcp-atlassian
 description: >-
-  Atlassian MCP for Jira and Confluence operations (Claude's bundled integration).
-  Token-efficient workflows for issue management, page creation, search, and user mentions.
+  Hybrid Atlassian integration — MCP-first for Jira/Confluence operations,
+  direct REST API (curl) for gaps the MCP doesn't cover.
   Use when: creating/editing Jira issues, searching with JQL/CQL, creating/updating Confluence
   pages, adding comments, transitioning issue status, looking up users, mentioning/tagging
-  users in Jira or Confluence content, or any Atlassian Cloud operation. Triggers on: Jira,
-  Confluence, JQL, CQL, sprint, epic, story, issue, wiki page, Atlassian, @mention in
-  Jira/Confluence context. Provides 50-80% token savings over naive API usage through
-  field filtering, pagination control, and format selection.
+  users in Jira or Confluence content, downloading/uploading attachments, sprint/board
+  management, bulk operations, or any Atlassian Cloud operation. Triggers on: Jira,
+  Confluence, JQL, CQL, sprint, epic, story, issue, wiki page, Atlassian, attachment,
+  board, backlog, @mention in Jira/Confluence context.
 ---
 
-# Atlassian MCP - Jira & Confluence Integration
+# Atlassian Integration — Hybrid MCP + Direct API
 
-Claude's bundled Atlassian MCP. All tools prefixed `mcp__claude_ai_Atlassian__`.
+MCP-first: use bundled tools (prefixed `mcp__claude_ai_Atlassian__`) for covered operations.
+Direct REST API (curl via Bash) for gaps. See [Decision Logic](#decision-logic) to pick the right approach.
 
 ## Bootstrap (Required First Call)
 
@@ -90,6 +91,51 @@ getAccessibleAtlassianResources  → returns cloudId (UUID or site URL)
 | `search` | Rovo natural language search across Jira + Confluence |
 | `fetch` | Get detail by ARI (Atlassian Resource Identifier). Read-only |
 
+## Direct API — Gap Operations
+
+When the MCP tools don't cover an operation, use `curl` via Bash with direct REST API calls.
+
+### When to Use Direct API
+
+The MCP handles issue CRUD, transitions, comments, Confluence pages, and search well.
+Use direct API **only** for operations not in the Tool Catalog above.
+
+### Auth Setup
+
+Set ENV variables for direct API access. Two auth methods supported:
+
+- **Gateway (Bearer)** — preferred for service accounts: `ATLASSIAN_CLOUD_ID` + `ATLASSIAN_BEARER_TOKEN`
+- **Direct (Basic)** — fallback for personal tokens: `ATLASSIAN_DOMAIN` + `ATLASSIAN_EMAIL` + `ATLASSIAN_API_TOKEN`
+
+Before first direct API call, verify auth works:
+```bash
+curl -s -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+  "https://api.atlassian.com/ex/jira/$ATLASSIAN_CLOUD_ID/rest/api/3/myself" | jq '.displayName'
+```
+
+Full setup guide: [references/direct-api-auth.md](references/direct-api-auth.md)
+
+### Available Recipes
+
+| Operation | Reference | Priority |
+|-----------|-----------|----------|
+| Attachment download/upload (Jira + Confluence) | [direct-api-attachments.md](references/direct-api-attachments.md) | P0 |
+| Sprint/board management (Agile API) | [direct-api-sprints.md](references/direct-api-sprints.md) | P1 |
+| Bulk operations (batch edit, bulk transition) | [direct-api-bulk.md](references/direct-api-bulk.md) | P1 |
+| Comment edit/delete, watchers, components, versions, page deletion | [direct-api-misc.md](references/direct-api-misc.md) | P2 |
+
+### MCP vs Direct API Decision
+
+```
+Can an MCP tool handle it?  →  Use the MCP tool (always preferred)
+Attachment download/upload? →  Direct API (references/direct-api-attachments.md)
+Sprint or board operation?  →  Direct API (references/direct-api-sprints.md)
+Bulk operation (5+ issues)? →  Direct API (references/direct-api-bulk.md)
+Edit/delete comment?        →  Direct API (references/direct-api-misc.md)
+Watchers, components, versions? → Direct API (references/direct-api-misc.md)
+Delete Confluence page?     →  Direct API (references/direct-api-misc.md)
+```
+
 ## User Mentions (@tagging)
 
 **This is the most error-prone area.** Follow these patterns exactly.
@@ -300,6 +346,28 @@ createConfluenceInlineComment(
 )
 ```
 
+### Download Attachments from an Issue (Hybrid)
+
+```
+1. getJiraIssue(issueIdOrKey: "PROJ-123", fields: ["attachment"])
+   → get attachment metadata (filename, content URL)
+2. curl -s -L -H "Authorization: Bearer $ATLASSIAN_BEARER_TOKEN" \
+     -o "mockup.png" "<content-url-from-step-1>"
+```
+
+Full recipes: [references/direct-api-attachments.md](references/direct-api-attachments.md)
+
+### Move Issues to a Sprint (Direct API)
+
+```
+1. curl: GET /rest/agile/1.0/board?projectKeyOrId=PROJ → boardId
+2. curl: GET /rest/agile/1.0/board/{boardId}/sprint?state=active → sprintId
+3. curl: POST /rest/agile/1.0/sprint/{sprintId}/issue
+   body: {"issues": ["PROJ-101", "PROJ-102"]}
+```
+
+Full recipes: [references/direct-api-sprints.md](references/direct-api-sprints.md)
+
 ## Decision Logic
 
 ```
@@ -328,12 +396,24 @@ Creating a Confluence page?
   → Need spaceId (NOT space key). Get from getConfluenceSpaces
 ```
 
-## What This MCP Does NOT Support
+## Limitations
+
+### Not Supported (no MCP or direct API recipe)
 
-- Direct Atlassian storage format (XML) - uses Markdown or ADF only
+- Direct Atlassian storage format (XML) — MCP uses Markdown or ADF only
 - Confluence page permissions management
-- Jira board/sprint management
-- Jira custom field creation
-- Attachment uploads
-- Bulk operations
+- Jira custom field creation (reading custom fields via `editJiraIssue` may work)
 - Confluence page templates
+- Jira automation rules / webhooks
+
+### Covered by Direct API (not in MCP, but recipes available)
+
+| Gap | Recipe |
+|-----|--------|
+| Attachment download/upload | [direct-api-attachments.md](references/direct-api-attachments.md) |
+| Sprint/board management | [direct-api-sprints.md](references/direct-api-sprints.md) |
+| Bulk operations | [direct-api-bulk.md](references/direct-api-bulk.md) |
+| Comment edit/delete | [direct-api-misc.md](references/direct-api-misc.md) |
+| Watchers | [direct-api-misc.md](references/direct-api-misc.md) |
+| Components & versions | [direct-api-misc.md](references/direct-api-misc.md) |
+| Confluence page deletion | [direct-api-misc.md](references/direct-api-misc.md) |

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