/atlassian-setup

name: atlassian-setup
description: "Connect Jira and Confluence for project tracking and knowledge search. Use when the user says 'connect Jira', 'hook up Confluence', 'my tickets/board'. Not for a personal task app like Todoist/Things/Trello; use `todoist-setup`/`things-setup`/`trello-setup`."
manifest:
  id: atlassian
  auth: oauth2
  category: project_management
  services:
    - jira
    - confluence

Atlassian Setup

Connect your Jira and Confluence to Dex so your daily plans, project health checks, meeting prep, and weekly reviews get richer context from your Atlassian workspace.

What This Enables

Once connected, Dex can:

• **Daily Plan:** See your Jira sprint status, assigned tickets, and overdue items
• **Project Health:** Sprint velocity, epic progress, blocked tickets across projects
• **Meeting Prep:** Surface Jira tickets and Confluence docs relevant to attendees
• **Week Review:** Tickets closed this week, sprint progress, velocity trends
• **Task Sync:** Bi-directional sync between Dex tasks and Jira issues (optional)

Privacy

• Dex reads Jira issues and Confluence pages **on demand** -- nothing is stored permanently
• Data is fetched, summarized, and discarded after the session
• Only YOUR workspace data is accessible (scoped to your OAuth permissions)
• The OAuth token stays local on your machine and is gitignored

When to Run

• User types `/atlassian-setup`
• User asks about connecting Jira or Confluence
• User wants Jira context in daily plans, project health, or meeting prep
• During `/integrate-mcp` if Jira or Confluence is mentioned

---

Setup Flow

Step 1: Check if Already Connected

1. Check `System/integrations/config.yaml` for `atlassian.enabled: true` 2. If enabled, read `System/.atlassian-oauth-token.json` and test the token:

• Call `https://api.atlassian.com/oauth/token/accessible-resources` with the stored token
• If valid, skip to **Step 6** (Configure Projects)

3. If the token is missing, expired, or invalid, continue to Step 2

Step 2: Explain What We're Setting Up

Say:

**Let's connect Jira and Confluence to Dex.**

This uses Atlassian's OAuth flow to securely connect your Atlassian Cloud workspace.
No API tokens to manage -- it uses the standard Atlassian authorization flow.

**What you'll need:**
- An Atlassian Cloud account (e.g., yourcompany.atlassian.net)
- Permission to authorize third-party apps (check with your admin if unsure)
- About 3 minutes

**What gets connected:**
- **Jira:** Your assigned issues, sprint status, project health
- **Confluence:** Search for docs relevant to meetings and projects (read-only)

**Ready to go?**

Wait for confirmation.

Step 3: Add the Atlassian MCP Server

Check the user's MCP configuration. If an Atlassian MCP server is not listed:

1. Explain what we're adding:

I need to add the Atlassian connector to your Dex configuration.

This uses the official Atlassian Remote MCP server which handles OAuth
authentication and provides secure access to your Jira and Confluence data.

2. Add to the user's `.mcp.json`:

{
  "atlassian": {
    "command": "npx",
    "args": ["-y", "mcp-remote@latest", "https://mcp.atlassian.com/v1/sse"]
  }
}

3. Tell the user the MCP server needs to restart for changes to take effect.

Step 4: Authenticate

Guide the user through the OAuth flow:

1. The Atlassian MCP server will open a browser window for authorization 2. User logs in to Atlassian and grants access 3. The MCP server stores the token locally

After auth completes, verify:

• Call the accessible-resources endpoint to confirm the token works
• Save token data to `System/.atlassian-oauth-token.json`

**If authentication succeeds:**

Connected! I can see your Atlassian workspace: [workspace-name]

**If it fails:**

Hmm, that didn't work. A few things to check:

1. **Are you logged in to Atlassian Cloud?** (Not Server/Data Center -- Cloud only)
2. **Does your account have permission to authorize apps?** Check with your admin
3. **Try the auth flow again** -- sometimes it takes two tries

Want to retry?

Retry up to 2 times, then offer to skip and come back later.

Step 5: Select Cloud Site

If the user has access to multiple Atlassian sites:

You have access to multiple Atlassian sites:

1. acme-corp.atlassian.net
2. acme-sandbox.atlassian.net

Which site should Dex connect to?

Save the selected `cloud_id` for API calls.

Step 6: Configure Jira Project

**Which Jira project should Dex sync with?**

This is the project where your tasks and issues live. I'll use it for:
- Sprint status in your daily plan
- Task sync (if you enable it)
- Project health checks

**Enter a project key** (e.g., ACME, PROD, ENG) or say "show me what's available"

If they say "show me what's available":

• Call the Jira projects API to list accessible projects
• Show the list and let them pick

Step 7: Configure Confluence Space (Optional)

**Want to connect Confluence too?** (Optional)

If connected, Dex will search Confluence docs when prepping for meetings --
finding relevant pages shared with attendees or related to your projects.

**Enter a space key** (e.g., TEAM, DOCS, KB) or say "skip" or "show me what's available"

If they say "show me what's available":

• Call the Confluence spaces API to list accessible spaces
• Show the list and let them pick

Step 8: Configure Task Sync Trust Level

**How should Dex handle Jira task sync?**

When you create tasks in Dex or complete issues in Jira, Dex can keep them in sync.

Choose your trust level:

1. **Auto-sync** -- Dex automatically syncs issues and tasks (recommended for personal projects)
2. **Ask each time** -- Dex shows you what changed and asks before syncing
3. **Read-only** -- Dex reads Jira data but never writes back (safest)

Which do you prefer? [1/2/3]

Step 9: Save Configuration

Write to `System/integrations/config.yaml` -- update the atlassian section: