@cubis/foundry 0.3.33 → 0.3.35

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/atlassian-mcp/references/jira-queries.md

@@ -1,421 +0,0 @@
-# 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/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/atlassian-mcp/references/mcp-server-setup.md

@@ -1,292 +0,0 @@
-# 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