fix(confluence): use v1 REST endpoint for attachment downloads on Cloud

[pshiko]

Description

Attachment/image downloads fail on Confluence Cloud: confluence_get_page_images returns downloaded: 0 (every image Fetch failed) and confluence_download_attachment / confluence_download_content_attachments return 401.

Root cause: these tools follow the attachment's _links.download (and the v2 attachment downloadLink), which points to the legacy /wiki/download/attachments/{id}/{file} path. Atlassian deprecated and removed that endpoint platform-wide on Cloud (changelog CHANGE-2735 — "Deprecation of /download/attachments/ APIs"); it now returns 401 for API-token / scoped-token auth while metadata endpoints keep working. The v2 Attachment API is metadata-only and its downloadLink is the same removed /download/ path, so it is not a replacement for the binary.

This resolves attachment download URLs to the v1 REST endpoint /rest/api/content/{cid}/child/attachment/{aid}/download, which is not in the deprecation list and authenticates correctly with the same credentials.

Refs: https://community.developer.atlassian.com/t/deprecation-of-download-attachments-apis/94448

Fixes: #1368

Changes

• Add _resolve_attachment_download_url() in confluence/attachments.py that resolves an attachment download link, optionally rewriting it to the v1 REST endpoint (parses the content id from the legacy link, or accepts it explicitly).
• Route the attachment-download paths through it: confluence_get_page_images, confluence_download_attachment, confluence_download_content_attachments, and the download_content_attachments mixin.
• Add CONFLUENCE_ATTACHMENT_DOWNLOAD_USE_V1 (ConfluenceConfig.attachment_download_use_v1, tri-state): unset = auto (v1 on Cloud, legacy link on Server/DC), true = always v1, false = always the legacy link. Default preserves existing Server/DC behaviour.
• Docs: .env.example, docs/configuration.mdx, a troubleshooting entry, and a note on the attachment tools.
• Unit tests for _resolve_attachment_download_url (auto Cloud / auto Server-DC / explicit true / explicit false / explicit content_id / missing attachment_id fallback).

Testing

• Unit tests added/updated
• Integration tests passed (suite-level integration/e2e tests are skipped without live credentials)
• Manual checks performed: against a real Confluence Cloud page — get_page_images went from 0 downloaded to all images, and the v1 URL returns the image bytes

Test result

• uv run pytest → 2584 passed, 161 skipped.
• pre-commit (ruff-format, ruff, mypy) and pyright are clean for the changed files.

Checklist

• Code follows project style guidelines (linting passes).
• Tests added/updated for changes.
• All tests pass locally.
• Documentation updated (if needed).

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a Confluence Cloud workaround for Atlassian’s removal of legacy /download/attachments/... links by optionally rewriting attachment download URLs to the v1 REST download endpoint, with config/env/documentation updates and unit tests.

Changes:

• Introduces ConfluenceConfig.attachment_download_use_v1 with CONFLUENCE_ATTACHMENT_DOWNLOAD_USE_V1 env support.
• Adds _resolve_attachment_download_url() to rewrite legacy download links to /rest/api/content/{id}/child/attachment/{aid}/download (auto-enabled on Cloud).
• Updates server handlers + docs and adds unit tests for the new URL resolution behavior.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/unit/confluence/test_attachments.py	Adds unit tests covering legacy vs v1-rewritten attachment download URLs.
src/mcp_atlassian/servers/confluence.py	Switches attachment/image download URL handling to the new resolver method.
src/mcp_atlassian/confluence/config.py	Adds config + env var parsing for v1 download rewriting.
src/mcp_atlassian/confluence/attachments.py	Implements the download URL resolver and uses it in attachment downloads.
docs/troubleshooting.mdx	Documents 401 failures for legacy Cloud download links and the workaround/env var.
docs/tools/confluence-attachments.mdx	Notes Cloud download behavior and override env var in tool docs.
docs/configuration.mdx	Documents CONFLUENCE_ATTACHMENT_DOWNLOAD_USE_V1.
.env.example	Adds example configuration and explanation for the new env var.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.