@cubis/foundry 0.3.10

package/Ai Agent Workflow/skills/atlassian-mcp/references/jira-queries.md

@@ -0,0 +1,421 @@
+# Jira Queries and Operations
+
+---
+
+## JQL Fundamentals
+
+### Basic Query Structure
+
+```
+field OPERATOR value [AND|OR field OPERATOR value]
+```
+
+### Common Operators
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `=` | Exact match | `project = "PROJ"` |
+| `!=` | Not equal | `status != Done` |
+| `~` | Contains (text search) | `summary ~ "login bug"` |
+| `!~` | Does not contain | `description !~ "test"` |
+| `>`, `<`, `>=`, `<=` | Comparison | `created >= -7d` |
+| `IN` | Multiple values | `status IN (Open, "In Progress")` |
+| `NOT IN` | Exclude values | `assignee NOT IN (john, jane)` |
+| `IS` | Null check | `assignee IS EMPTY` |
+| `IS NOT` | Not null | `resolution IS NOT EMPTY` |
+| `WAS` | Historical state | `status WAS "In Progress"` |
+| `CHANGED` | Field changed | `status CHANGED FROM Open` |
+
+### Field Reference
+
+**Standard Fields:**
+```jql
+project = PROJ
+issuetype = Bug
+status = "In Progress"
+priority = High
+assignee = currentUser()
+reporter = "john.doe"
+resolution = Unresolved
+labels = backend
+component = "API"
+fixVersion = "2.0"
+affectsVersion = "1.5"
+```
+
+**Date Fields:**
+```jql
+created >= -30d                    -- Last 30 days
+updated >= "2024-01-01"           -- Since specific date
+due <= endOfWeek()                 -- Due this week
+resolved >= startOfMonth()         -- Resolved this month
+```
+
+**Text Search:**
+```jql
+summary ~ "authentication"         -- Summary contains
+description ~ "error AND login"    -- Description search
+text ~ "payment failed"            -- All text fields
+comment ~ "blocked"                -- Comment contains
+```
+
+## Essential JQL Patterns
+
+### Sprint and Backlog Queries
+
+```jql
+-- Current sprint issues
+sprint in openSprints() AND project = PROJ
+
+-- Backlog items
+sprint IS EMPTY AND resolution IS EMPTY AND project = PROJ
+
+-- Sprint completion
+sprint = "Sprint 23" AND status = Done
+
+-- Spillover from last sprint
+sprint in closedSprints() AND resolution IS EMPTY
+
+-- Ready for sprint planning
+status = "Ready for Dev" AND sprint IS EMPTY
+```
+
+### Bug Tracking
+
+```jql
+-- Open bugs by priority
+issuetype = Bug AND resolution IS EMPTY ORDER BY priority DESC
+
+-- Critical production bugs
+issuetype = Bug AND priority IN (Highest, High)
+  AND labels = production AND resolution IS EMPTY
+
+-- Bugs created this week
+issuetype = Bug AND created >= startOfWeek()
+
+-- Bugs without reproduction steps
+issuetype = Bug AND "Reproduction Steps" IS EMPTY
+  AND resolution IS EMPTY
+
+-- Regression bugs
+issuetype = Bug AND labels = regression AND fixVersion = "2.0"
+```
+
+### Team Workload
+
+```jql
+-- My open issues
+assignee = currentUser() AND resolution IS EMPTY
+
+-- Unassigned high priority
+assignee IS EMPTY AND priority IN (Highest, High)
+  AND resolution IS EMPTY
+
+-- Team member workload
+assignee = "jane.smith" AND sprint in openSprints()
+
+-- Blocked issues
+status = Blocked OR labels = blocked
+
+-- Stale issues (no update in 14 days)
+updated <= -14d AND resolution IS EMPTY
+```
+
+### Release Management
+
+```jql
+-- Release candidates
+fixVersion = "2.0" AND status = "Ready for Release"
+
+-- Missing fix version
+resolution = Done AND fixVersion IS EMPTY AND updated >= -30d
+
+-- Release blockers
+fixVersion = "2.0" AND priority = Blocker AND resolution IS EMPTY
+
+-- Changelog items
+fixVersion = "2.0" AND resolution = Done ORDER BY issuetype
+```
+
+## MCP Tool Calls
+
+### Searching Issues
+
+```typescript
+// Basic JQL search
+const searchResult = await client.callTool({
+  name: "jira_search",
+  arguments: {
+    jql: "project = PROJ AND sprint in openSprints()",
+    max_results: 50,
+    fields: ["summary", "status", "assignee", "priority"]
+  }
+});
+
+// Parse response
+const issues = JSON.parse(searchResult.content[0].text);
+for (const issue of issues.issues) {
+  console.log(`${issue.key}: ${issue.fields.summary}`);
+}
+```
+
+### Getting Issue Details
+
+```typescript
+// Get single issue with all fields
+const issue = await client.callTool({
+  name: "jira_get_issue",
+  arguments: {
+    issue_key: "PROJ-123",
+    expand: ["changelog", "comments", "transitions"]
+  }
+});
+
+// Get issue with specific fields
+const issuePartial = await client.callTool({
+  name: "jira_get_issue",
+  arguments: {
+    issue_key: "PROJ-123",
+    fields: ["summary", "description", "customfield_10001"]
+  }
+});
+```
+
+### Creating Issues
+
+```typescript
+// Create a bug
+const newBug = await client.callTool({
+  name: "jira_create_issue",
+  arguments: {
+    project_key: "PROJ",
+    issue_type: "Bug",
+    summary: "Login fails with SSO enabled",
+    description: {
+      type: "doc",
+      version: 1,
+      content: [
+        {
+          type: "paragraph",
+          content: [{ type: "text", text: "Users cannot log in when SSO is enabled." }]
+        },
+        {
+          type: "heading",
+          attrs: { level: 3 },
+          content: [{ type: "text", text: "Steps to Reproduce" }]
+        },
+        {
+          type: "orderedList",
+          content: [
+            { type: "listItem", content: [{ type: "paragraph", content: [{ type: "text", text: "Enable SSO in settings" }] }] },
+            { type: "listItem", content: [{ type: "paragraph", content: [{ type: "text", text: "Log out" }] }] },
+            { type: "listItem", content: [{ type: "paragraph", content: [{ type: "text", text: "Attempt to log in via SSO" }] }] }
+          ]
+        }
+      ]
+    },
+    priority: "High",
+    labels: ["sso", "authentication", "production"],
+    components: ["Authentication"],
+    assignee: "jane.smith"
+  }
+});
+
+console.log(`Created: ${newBug.content[0].text}`); // PROJ-456
+```
+
+### Updating Issues
+
+```typescript
+// Update issue fields
+await client.callTool({
+  name: "jira_update_issue",
+  arguments: {
+    issue_key: "PROJ-123",
+    fields: {
+      summary: "Updated summary",
+      priority: { name: "Highest" },
+      labels: ["urgent", "production"]
+    }
+  }
+});
+
+// Add comment
+await client.callTool({
+  name: "jira_add_comment",
+  arguments: {
+    issue_key: "PROJ-123",
+    body: "Investigating this issue. Initial analysis suggests a race condition."
+  }
+});
+
+// Transition issue
+await client.callTool({
+  name: "jira_transition_issue",
+  arguments: {
+    issue_key: "PROJ-123",
+    transition: "In Progress"
+  }
+});
+```
+
+### Sprint Operations
+
+```typescript
+// Get active sprints
+const sprints = await client.callTool({
+  name: "jira_get_sprints",
+  arguments: {
+    board_id: 42,
+    state: "active"
+  }
+});
+
+// Move issue to sprint
+await client.callTool({
+  name: "jira_move_to_sprint",
+  arguments: {
+    sprint_id: 123,
+    issue_keys: ["PROJ-100", "PROJ-101", "PROJ-102"]
+  }
+});
+
+// Get sprint report
+const report = await client.callTool({
+  name: "jira_get_sprint_report",
+  arguments: {
+    board_id: 42,
+    sprint_id: 123
+  }
+});
+```
+
+## Pagination Handling
+
+```typescript
+async function getAllIssues(jql: string): Promise<Issue[]> {
+  const allIssues: Issue[] = [];
+  let startAt = 0;
+  const maxResults = 100;
+
+  while (true) {
+    const result = await client.callTool({
+      name: "jira_search",
+      arguments: {
+        jql,
+        start_at: startAt,
+        max_results: maxResults,
+        fields: ["summary", "status", "assignee"]
+      }
+    });
+
+    const response = JSON.parse(result.content[0].text);
+    allIssues.push(...response.issues);
+
+    if (startAt + response.issues.length >= response.total) {
+      break;
+    }
+
+    startAt += maxResults;
+  }
+
+  return allIssues;
+}
+```
+
+## Bulk Operations
+
+```typescript
+// Bulk update with JQL
+async function bulkUpdateLabels(jql: string, addLabels: string[]) {
+  const issues = await getAllIssues(jql);
+
+  for (const issue of issues) {
+    const existingLabels = issue.fields.labels || [];
+    await client.callTool({
+      name: "jira_update_issue",
+      arguments: {
+        issue_key: issue.key,
+        fields: {
+          labels: [...new Set([...existingLabels, ...addLabels])]
+        }
+      }
+    });
+
+    // Respect rate limits
+    await delay(100);
+  }
+}
+
+// Usage
+await bulkUpdateLabels(
+  'project = PROJ AND sprint in openSprints() AND labels = backend',
+  ['q4-priority', 'needs-review']
+);
+```
+
+## Error Handling
+
+```typescript
+async function safeJiraCall<T>(
+  operation: () => Promise<T>,
+  retries = 3
+): Promise<T> {
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      return await operation();
+    } catch (error: any) {
+      const status = error.response?.status;
+
+      // Don't retry client errors (except rate limits)
+      if (status >= 400 && status < 500 && status !== 429) {
+        throw error;
+      }
+
+      // Rate limited - wait and retry
+      if (status === 429) {
+        const retryAfter = parseInt(error.response?.headers?.['retry-after'] || '60');
+        console.log(`Rate limited. Waiting ${retryAfter}s...`);
+        await delay(retryAfter * 1000);
+        continue;
+      }
+
+      // Server error - exponential backoff
+      if (attempt < retries) {
+        const backoff = Math.pow(2, attempt) * 1000;
+        console.log(`Attempt ${attempt} failed. Retrying in ${backoff}ms...`);
+        await delay(backoff);
+      } else {
+        throw error;
+      }
+    }
+  }
+  throw new Error('Unexpected end of retry loop');
+}
+```
+
+## Common Anti-Patterns
+
+**Avoid:**
+```jql
+-- Too broad (slow, may timeout)
+project IS NOT EMPTY
+
+-- Missing quotes for multi-word values
+status = In Progress  -- WRONG
+status = "In Progress"  -- CORRECT
+
+-- Case sensitivity issues
+assignee = John  -- May fail
+assignee = "john.doe@company.com"  -- CORRECT
+
+-- Inefficient ordering
+ORDER BY created  -- Missing direction
+ORDER BY created DESC  -- CORRECT
+```
+
+## Related References
+
+- `common-workflows.md` - End-to-end workflow patterns
+- `authentication-patterns.md` - Credential setup for API calls
+- `confluence-operations.md` - Linking Jira issues to Confluence pages

package/Ai Agent Workflow/skills/atlassian-mcp/references/mcp-server-setup.md

@@ -0,0 +1,292 @@
+# MCP Server Setup
+
+---
+
+## Server Options Overview
+
+### Official Atlassian MCP Server
+
+Atlassian provides an official MCP server for cloud products:
+
+```bash
+# Install via npm
+npm install -g @anthropic/mcp-atlassian
+
+# Or use npx directly
+npx @anthropic/mcp-atlassian
+```
+
+**Capabilities:**
+- Jira Cloud and Confluence Cloud integration
+- OAuth 2.1 authentication flow
+- Read/write operations for issues and pages
+- JQL and CQL query support
+
+### Open-Source Alternatives
+
+**mcp-atlassian (sooperset)** - Most feature-rich community option:
+```bash
+# Install with uv (recommended)
+uv tool install mcp-atlassian
+
+# Or with pip
+pip install mcp-atlassian
+```
+
+**atlassian-mcp (xuanxt)** - TypeScript-based alternative:
+```bash
+npm install atlassian-mcp
+```
+
+### Comparison Matrix
+
+| Feature | Official | sooperset | xuanxt |
+|---------|----------|-----------|--------|
+| Jira Cloud | Yes | Yes | Yes |
+| Jira Server/DC | No | Yes | Limited |
+| Confluence Cloud | Yes | Yes | Yes |
+| Confluence Server/DC | No | Yes | No |
+| OAuth 2.1 | Yes | Yes | No |
+| API Token Auth | Yes | Yes | Yes |
+| PAT (Server) | No | Yes | No |
+| Rate Limiting | Built-in | Configurable | Manual |
+
+## Claude Desktop Configuration
+
+### Basic Setup
+
+Edit your Claude Desktop config file:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+**Linux:** `~/.config/claude/claude_desktop_config.json`
+
+### Configuration Examples
+
+**Official Server with OAuth:**
+```json
+{
+  "mcpServers": {
+    "atlassian": {
+      "command": "npx",
+      "args": ["@anthropic/mcp-atlassian"],
+      "env": {
+        "ATLASSIAN_SITE_URL": "https://your-company.atlassian.net",
+        "ATLASSIAN_AUTH_TYPE": "oauth"
+      }
+    }
+  }
+}
+```
+
+**sooperset with API Token:**
+```json
+{
+  "mcpServers": {
+    "atlassian": {
+      "command": "uvx",
+      "args": ["mcp-atlassian"],
+      "env": {
+        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
+        "CONFLUENCE_USERNAME": "your-email@company.com",
+        "CONFLUENCE_API_TOKEN": "your-api-token",
+        "JIRA_URL": "https://your-company.atlassian.net",
+        "JIRA_USERNAME": "your-email@company.com",
+        "JIRA_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+**Server/Data Center with PAT:**
+```json
+{
+  "mcpServers": {
+    "atlassian": {
+      "command": "uvx",
+      "args": ["mcp-atlassian"],
+      "env": {
+        "JIRA_URL": "https://jira.internal.company.com",
+        "JIRA_PERSONAL_TOKEN": "your-personal-access-token",
+        "CONFLUENCE_URL": "https://confluence.internal.company.com",
+        "CONFLUENCE_PERSONAL_TOKEN": "your-personal-access-token"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables Reference
+
+### Jira Configuration
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `JIRA_URL` | Base URL of Jira instance | Yes |
+| `JIRA_USERNAME` | Email for cloud, username for server | Cloud only |
+| `JIRA_API_TOKEN` | API token (cloud) | Cloud only |
+| `JIRA_PERSONAL_TOKEN` | PAT (server/DC) | Server only |
+| `JIRA_SSL_VERIFY` | Verify SSL certificates (default: true) | No |
+
+### Confluence Configuration
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `CONFLUENCE_URL` | Base URL with /wiki suffix for cloud | Yes |
+| `CONFLUENCE_USERNAME` | Email for cloud | Cloud only |
+| `CONFLUENCE_API_TOKEN` | API token (cloud) | Cloud only |
+| `CONFLUENCE_PERSONAL_TOKEN` | PAT (server/DC) | Server only |
+
+### Advanced Options
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MCP_LOG_LEVEL` | Logging verbosity (DEBUG, INFO, WARN, ERROR) | INFO |
+| `MCP_TIMEOUT` | Request timeout in seconds | 30 |
+| `MCP_MAX_RETRIES` | Maximum retry attempts | 3 |
+| `MCP_RATE_LIMIT` | Requests per second | 10 |
+
+## Verification and Testing
+
+### Check Server Status
+
+```bash
+# Test official server
+npx @anthropic/mcp-atlassian --version
+
+# Test sooperset server
+uvx mcp-atlassian --help
+
+# Verify environment variables
+env | grep -E "(JIRA|CONFLUENCE)_"
+```
+
+### Test Connection
+
+Create a simple test script:
+
+```typescript
+// test-connection.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+async function testConnection() {
+  const transport = new StdioClientTransport({
+    command: "uvx",
+    args: ["mcp-atlassian"],
+    env: process.env,
+  });
+
+  const client = new Client(
+    { name: "test-client", version: "1.0.0" },
+    { capabilities: {} }
+  );
+
+  await client.connect(transport);
+
+  // List available tools
+  const tools = await client.listTools();
+  console.log("Available tools:", tools.tools.map(t => t.name));
+
+  // Test a simple read operation
+  const result = await client.callTool({
+    name: "jira_get_issue",
+    arguments: { issue_key: "TEST-1" }
+  });
+  console.log("Test result:", result);
+
+  await client.close();
+}
+
+testConnection().catch(console.error);
+```
+
+## When to Use Each Server
+
+**Choose Official Server when:**
+- Using only Atlassian Cloud products
+- Need OAuth 2.1 compliance
+- Require official support
+- Building for enterprise deployment
+
+**Choose sooperset when:**
+- Need Server/Data Center support
+- Want PAT authentication
+- Require advanced filtering
+- Need both Jira and Confluence
+
+**Choose xuanxt when:**
+- Want TypeScript-native implementation
+- Building custom extensions
+- Need minimal dependencies
+
+## Troubleshooting
+
+### Common Issues
+
+**"Connection refused" error:**
+```bash
+# Check if server is running
+ps aux | grep mcp-atlassian
+
+# Verify URL is reachable
+curl -I https://your-company.atlassian.net
+
+# Check firewall/proxy settings
+echo $HTTP_PROXY $HTTPS_PROXY
+```
+
+**"Authentication failed" error:**
+```bash
+# Verify API token is valid (cloud)
+curl -u "email@company.com:API_TOKEN" \
+  "https://your-company.atlassian.net/rest/api/3/myself"
+
+# Verify PAT is valid (server)
+curl -H "Authorization: Bearer YOUR_PAT" \
+  "https://jira.internal.company.com/rest/api/2/myself"
+```
+
+**"Rate limit exceeded" error:**
+```json
+{
+  "mcpServers": {
+    "atlassian": {
+      "env": {
+        "MCP_RATE_LIMIT": "5"
+      }
+    }
+  }
+}
+```
+
+### Debug Mode
+
+Enable verbose logging:
+
+```json
+{
+  "mcpServers": {
+    "atlassian": {
+      "env": {
+        "MCP_LOG_LEVEL": "DEBUG"
+      }
+    }
+  }
+}
+```
+
+## Security Best Practices
+
+1. **Never commit credentials** - Use environment variables or secrets management
+2. **Rotate API tokens regularly** - Set calendar reminders for 90-day rotation
+3. **Use minimal scopes** - Request only necessary permissions
+4. **Enable audit logging** - Track API usage for compliance
+5. **Restrict network access** - Use allowlists where possible
+
+## Related References
+
+- `authentication-patterns.md` - OAuth 2.1 and API token setup details
+- `jira-queries.md` - JQL syntax after connection is established
+- `confluence-operations.md` - CQL and page operations