Jira Connector

SKILL.md

---
name: jira-connector
description: >
  Query, create, and update Jira issues on Atlassian Cloud via the Atlassian Remote MCP Server.
  Use when the user wants to search Jira tickets, view issue details, create or update issues,
  or interact with Confluence/Compass data. Keywords: jira, issue, ticket, confluence, atlassian,
  sprint, backlog, epic, project.
metadata:
  polly:
    polly_managed_connector: true
    auth:
      - env: JIRA_ACCESS_TOKEN
        type: oauth2
        integration_id: jira
        description: Atlassian OAuth access for Jira, Confluence, and Compass
        scopes:
          - read:jira-work
          - write:jira-work
          - read:confluence-space.summary
          - read:confluence-content.all
          - offline_access
    primaryEnv: JIRA_ACCESS_TOKEN
---

# Jira Connector

Interact with Jira, Confluence, and Compass on Atlassian Cloud through the Atlassian Remote MCP Server.

---

## Prerequisites

### 1. Ensure mcporter is available
Always run this before invoking any Jira tools:
```bash
export PATH="$HOME/lib/node/bin:$PATH"
if ! command -v mcporter &>/dev/null; then
  npm install -g mcporter --prefix ~/lib/node
fi
```

### 2. Authentication

This skill uses **Polly-managed OAuth2 authentication**. The access token is automatically managed and refreshed by Polly's auth system via the `JIRA_ACCESS_TOKEN` environment variable.

**No manual token refresh is needed** — Polly handles token refresh automatically when needed.

On first use, if not connected, call:
```
manage_auth(action="connect", integration_id="jira", auth_env="JIRA_ACCESS_TOKEN")
```

---

## Invocation Pattern

```bash
export PATH="$HOME/lib/node/bin:$PATH"
mcporter --config ~/.mcporter/mcporter.json call jira.<tool_name> [key=value ...]
```

---

## Common Workflows

### Get cloud ID (required for most tools)
Always call this first if you don't have the cloudId cached:
```bash
mcporter --config ~/.mcporter/mcporter.json call jira.getAccessibleAtlassianResources
```
Returns a list of sites with their `id` (cloudId) and `url`.

### Search issues with JQL
```bash
mcporter --config ~/.mcporter/mcporter.json call jira.searchIssuesUsingJql cloudId=<cloudId> jql="project=PROJ AND status='In Progress'"
```

### Get issue details
```bash
mcporter --config ~/.mcporter/mcporter.json call jira.getIssue cloudId=<cloudId> issueIdOrKey=PROJ-123
```

### Create issue
```bash
mcporter --config ~/.mcporter/mcporter.json call jira.createIssue cloudId=<cloudId> projectKey=PROJ summary="New task" issueType=Task
```

### Update issue
```bash
mcporter --config ~/.mcporter/mcporter.json call jira.updateIssue cloudId=<cloudId> issueIdOrKey=PROJ-123 fields='{"summary":"Updated title"}'
```

### Add comment
```bash
mcporter --config ~/.mcporter/mcporter.json call jira.addCommentToIssue cloudId=<cloudId> issueIdOrKey=PROJ-123 comment="Status update"
```

### Transition issue (move to different status)
```bash
mcporter --config ~/.mcporter/mcporter.json call jira.transitionIssue cloudId=<cloudId> issueIdOrKey=PROJ-123 transitionId=<id>
```

---

## Available Tools

### Jira Issue Tools
- `getIssue` — Get full issue details
- `searchIssuesUsingJql` — Search with JQL
- `createIssue` — Create new issue
- `updateIssue` — Update existing issue
- `addCommentToIssue` — Add comment
- `transitionIssue` — Change issue status
- `assignIssue` — Assign to user
- `getIssueComments` — Get all comments
- `getIssueChangelog` — Get issue history

### Jira Project Tools
- `getProjects` — List projects
- `getProject` — Get project details
- `getProjectVersions` — Get release versions
- `getProjectComponents` — Get components

### Jira Board Tools
- `getAllBoards` — List all boards
- `getBoard` — Get board details
- `getBoardIssues` — Get issues on board
- `getBacklogForBoard` — Get backlog items
- `getSprintsForBoard` — List sprints

### Confluence Tools
- `getConfluenceSpaces` — List spaces
- `getConfluencePage` — Get page content
- `searchConfluence` — Search Confluence

---

## Notes

- Access tokens are valid for ~1 hour and are **automatically refreshed by Polly's auth system**
- The LLM never directly accesses refresh tokens — they are managed securely by Polly
- The `JIRA_ACCESS_TOKEN` environment variable is injected automatically when the skill runs
- Always get cloudId first before calling other tools
- JQL (Jira Query Language) is used for complex searches