@cleepi/atlassian

Cleevio taste layer over Atlassian's Rovo MCP server for the ticket → spec → implementation pipeline. Soft-aware of @cleepi/sdd.

What's in the box

• Skill (skills/atlassian/SKILL.md) — teaches the agent which Jira/Confluence fields map to which spec sections, what to ignore (status churn, bot comments, sprint metadata), and how to degrade honestly when something's missing. Loaded automatically when the conversation is ticket-shaped, or explicitly with /skill:atlassian.
• Prompt — /spec-from-ticket <KEY|URL> fetches the ticket, optionally pulls up to 3 linked Confluence pages, and hands off to /spec when @cleepi/sdd is installed (or to a structured manual printout when it isn't).
• MCP config snippet (mcp.example.json) — paste into your .mcp.json to wire Atlassian's remote MCP server into pi via pi-mcp-adapter with OAuth and a curated allowlist covering reads (for ticket context) and the useful Jira writes (create, edit, transition, comment). The pi-mcp-adapter proxy stays enabled for exploring further upstream tools.

This package ships no TypeScript tool code. All HTTP, OAuth, and ADF rendering live in Atlassian's MCP server and pi-mcp-adapter. See ADR 0005 for why.

Install

# 1. The MCP adapter (one-time, per machine)
pi install npm:pi-mcp-adapter

# 2. This package
pi install git:github.com/cleevio/cleepi/packages/atlassian

You'll usually want @cleepi/sdd alongside — that's what /spec-from-ticket hands off to:

pi install git:github.com/cleevio/cleepi/packages/sdd

There's no hard dependency. /spec-from-ticket works without sdd; it just degrades to a structured printout and suggests installing sdd.

Configure the MCP server

Copy mcp.example.json contents into your .mcp.json (project) or ~/.config/mcp/mcp.json (user-global). If you already have an .mcp.json, merge the atlassian entry into your existing mcpServers block.

Then restart pi.

First-run OAuth

The first time the agent calls a Jira or Confluence tool, pi-mcp-adapter launches your browser. Sign in to Atlassian and consent to the requested read scopes. Tokens are stored by the adapter; you won't be asked again until they expire.

Admin one-time setup (per Atlassian organisation)

This isn't your job as a Cleevian unless you're also a Cleevio Atlassian admin. Document for the admin:

• In Atlassian Administration → Rovo MCP server settings, enable the permission groups you want available through the package:
  • Required for the primary /spec-from-ticket workflow (read-only): read_jira, search_jira, read_confluence.
  • Required to use the bundled write tools (createJiraIssue, editJiraIssue, transitionJiraIssue, addCommentToJiraIssue): write_jira.
  • Optional, only if Confluence writes are desired via the MCP proxy (not promoted by this package, available through pi-mcp-adapter's mcp tool): write_confluence.
• The permission groups are the authoritative safety layer. Per ADR 0006, this package does not duplicate the gate client-side via excludeTools. If your organisation should not be able to write Jira from pi, do not enable write_jira upstream.
• The first user to authorize through MCP for the Cleevio site must have access to both Jira and Confluence. This ensures the Atlassian MCP app installs with the right scope footprint for everyone else.
• No OAuth app registration is needed. Atlassian's MCP server uses OAuth Dynamic Client Registration.

If OAuth succeeds but tool calls fail with a scope error, the relevant permission group isn't enabled yet.

Usage

/spec-from-ticket PROJ-123
/spec-from-ticket https://cleevio.atlassian.net/browse/PROJ-123

The prompt:

1. Fetches the Jira issue.
2. Scans the description and top-level comments for linked Confluence pages; fetches up to 3.
3. Hands off to /spec (sdd installed) or prints a structured summary (sdd absent).

Known limitations in v0.1.0

• Jira comments come back as ADF, not Markdown. The description field renders as Markdown when responseContentFormat: "markdown", but comment bodies are returned as ADF (Atlassian Document Format, nested JSON). The agent reads ADF well enough for spec drafting, but tooling that expects pure Markdown will need to walk the tree. Verified live against honem.atlassian.net.
• Single-site assumption. If your Atlassian account spans multiple Cloud sites, the agent will call getAccessibleAtlassianResources to pick one. Behavior is best-effort.
• Write tools are admin-gated upstream. The bundled allowlist promotes createJiraIssue, editJiraIssue, transitionJiraIssue, addCommentToJiraIssue — but these are only callable if your org admin has enabled the write_jira permission group in Atlassian Administration → Rovo MCP server. If they're missing from mcp({server: "atlassian"}), that's why.
• Confluence writes, worklogs, and Compass tools are reachable via the proxy (mcp({tool: "..."})) but not promoted via directTools. Use deliberately.

Troubleshooting

| Symptom | Likely cause | |---|---| | mcp tool not found | pi-mcp-adapter not installed. Run pi install npm:pi-mcp-adapter, restart pi. | | atlassian server not found by adapter | Snippet not merged into .mcp.json, or pi not restarted. | | OAuth opens browser then fails | Admin hasn't enabled read_jira / read_confluence permission groups. | | Tool call returns "insufficient scope" | Same as above. | | /spec-from-ticket says "sdd not loaded" | Install @cleepi/sdd or accept the manual printout path. |

Related

• SPEC.md — what this package is and isn't.
• CHANGELOG.md — release history.
• Spec 0003 (repo) — v0.1.0 design.
• ADR 0005 (repo) — MCP over native rationale.