atlassian-jira

SKILL.md

---
name: atlassian-jira
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:
  openclaw:
    requires:
      files:
        - ~/.mcporter/mcporter.json
        - ~/.credentials/*--jira_auth.json
---

# Atlassian Jira (via Atlassian Remote MCP Server)

Interact with Jira, Confluence, and Compass on Atlassian Cloud through the
[Atlassian Remote MCP Server](https://mcp.atlassian.com/v1/mcp) using `mcporter`.

---

## How It Works

The Atlassian MCP server speaks the Model Context Protocol over HTTPS.
We connect to it using **mcporter** — a CLI that can call MCP tools directly —
authenticated with an OAuth 2.1 bearer token stored in the credentials file.

The connection flow is:
1. Discover OAuth endpoints from the MCP server's `/.well-known/oauth-authorization-server`
2. Dynamically register a public client (no pre-created app needed)
3. Run PKCE authorization flow — user opens a URL in their browser and pastes back the redirect
4. Exchange the auth code for access + refresh tokens
5. Store tokens in `~/.credentials/<id>--jira_auth.json`
6. Configure mcporter with the bearer token
7. Call Jira tools via `mcporter call jira.<tool>`

---

## First-Time Setup

If `~/.credentials/*--jira_auth.json` does not exist, run the setup script to
authenticate the user via OAuth 2.1 PKCE:

```bash
python3 /home/polly/skills/user/atlassian-jira/scripts/oauth_setup.py
```

This script will:
1. Discover OAuth metadata from the MCP server
2. Register a dynamic client
3. Print an authorization URL — **give this URL to the user to open in their browser**
4. Wait for the user to paste back the redirect URL (e.g. `http://localhost:8080/callback?code=...`)
5. Exchange the code for tokens and write the credentials + mcporter config

---

## Invocation Pattern

Always call Jira tools like this:

```bash
MCPORTER="node /home/polly/.npm-global/node_modules/mcporter/dist/cli.js --config /home/polly/.mcporter/mcporter.json"
$MCPORTER call jira.<tool_name> [key=value ...]
```

**Never** hardcode tokens in commands. The token is read from the mcporter config file.

---

## Common Workflows

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

### Search issues with JQL
```bash
$MCPORTER call jira.searchJiraIssuesUsingJql \
  cloudId=<cloudId> \
  jql="project = SEQ AND created >= -30d ORDER BY created DESC" \
  maxResults=10
```
> **Note:** JQL must include a filter clause (e.g. `created >= -Xd`, `project = X`).
> Unbounded queries like `ORDER BY created DESC` alone are rejected.

### Get a specific issue
```bash
$MCPORTER call jira.getJiraIssue \
  cloudId=<cloudId> \
  issueIdOrKey=SEQ-207
```

### Create an issue
```bash
$MCPORTER call jira.createJiraIssue \
  cloudId=<cloudId> \
  projectKey=SEQ \
  summary="My new issue" \
  issueType=Task
```

### Update an issue
```bash
$MCPORTER call jira.updateJiraIssue \
  cloudId=<cloudId> \
  issueIdOrKey=SEQ-207 \
  summary="Updated summary"
```

### List available tools
```bash
$MCPORTER list jira --schema
```

---

## Token Refresh

The access token expires in ~8 hours. To refresh it, run:

```bash
python3 /home/polly/skills/user/atlassian-jira/scripts/refresh_token.py
```

This reads the refresh token from `~/.credentials/*--jira_auth.json`,
exchanges it for a new access token, and updates both the credentials file
and the mcporter config.

---

## File Locations

| File | Purpose |
|------|---------|
| `~/.credentials/<id>--jira_auth.json` | OAuth tokens (access + refresh) |
| `~/.mcporter/mcporter.json` | mcporter server config with bearer token |
| `~/.npm-global/node_modules/mcporter/` | mcporter installation |
| `scripts/oauth_setup.py` | One-time OAuth PKCE setup script |
| `scripts/refresh_token.py` | Token refresh script |

---

## Error Reference

| Error | Cause | Fix |
|-------|-------|-----|
| `Unbounded JQL queries are not allowed` | JQL has no filter, only ORDER BY | Add `created >= -30d` or `project = X` |
| `401 Unauthorized` | Token expired | Run `refresh_token.py` |
| `invalid_type: expected array` | Passed a string where array expected | Omit the `fields` param or check tool schema |
| `403 Forbidden` | Wrong endpoint or Cloudflare block | Use the correct endpoints from `/.well-known/` discovery |