Add atlassian-mcp-setup skill

[jiangyon-amd]

Adds .cursor/skills/atlassian-mcp-setup — connects an agent to AMD Jira/Confluence through the mcp-atlassian MCP server.

Design

The token lives in ~/.atlassian.env (mode 600). ~/.claude.json gets only a path to a launcher script that sources the env file and execs uvx mcp-atlassian. Rotating a token is then a one-line edit to a 600 file with no agent config change, and the agent config stays safe to share or paste into a bug report.

The alternative — claude mcp add --env JIRA_API_TOKEN=... as the internal wiki suggests — writes the literal token into ~/.claude.json.

What the skill actually encodes

The setup itself is short; the value is the failure modes, all hit while wiring this up against amd.atlassian.net:

• Cloud vs Server/DC are not interchangeable. *.atlassian.net takes email + API token; jira.xilinx.com takes a PAT. Mixing them gives a bare 401 that names nothing. One mcp-atlassian process also serves exactly one JIRA_URL, so reaching both needs two registered servers.
• Scoped Cloud tokens don't work against the site URL — only via api.atlassian.com/ex/jira/<cloudId>. A scoped token used the classic way fails identically to a wrong password.
• The account email is not derivable from the Linux username. Guessing costs a round trip per attempt and every miss returns the same 401, so brute force yields no information. The skill requires asking.
• Connected in claude mcp list is not evidence of working auth. mcp-atlassian doesn't authenticate at startup, so the launcher connects fine with garbage credentials. Only /myself proves it.
• Unauthenticated serverInfo separates network faults from credential faults, which is why healthcheck.sh runs it before touching credentials.
• MCP tools load at session start, so a correct setup looks broken until a restart. jira_issue.py reads issues over plain REST to cover that window.
• Cloud /rest/api/3 returns ADF trees, not strings — descriptions print as unreadable JSON unless flattened. It also retired GET /search (CHANGE-2046), so JQL goes through /search/jql.

Secret handling

• --token in argv is a hard error (visible in ps to every user on the box, and lands in shell history). Token comes from stdin, an echo-off prompt, or $ATLASSIAN_API_TOKEN.
• healthcheck.sh fails if a token has leaked into ~/.claude.json.
• No token is ever printed, including on error paths.
• --read-only registers with all write tools disabled, enforced by the MCP server rather than by agent discretion.

Files

File
SKILL.md	rules, Cloud/Server table, interaction flow, 11 failure modes
examples.md	6 scenarios incl. 401 debugging and dual Cloud+on-prem
scripts/setup_atlassian_mcp.sh	installs uv, writes env file, registers server, verifies
scripts/mcp-atlassian-launch.sh	credential indirection; also fixes PATH (MCP servers inherit a minimal env, so uvx from pipx is otherwise missing)
scripts/healthcheck.sh	reachability → credentials → MCP, in that order
scripts/jira_issue.py	REST fallback, ADF flattening, JQL; stdlib only

Verification

Run against amd.atlassian.net:

• validate_skill.py passes; bash -n clean on all shell scripts
• setup end to end for both deployment types, into a temp env file — correct env file contents and 600 perms; Server/DC inference from hostname works
• healthcheck.sh green on Jira and Confluence, resolving the real display name
• jira_issue.py fetch, --comments, and --jql all return correct data
• error paths exercised: --token refused, missing env file, 404 on a bad key
• staged diff scanned for ATATT tokens — clean

🤖 Generated with Claude Code