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

pshiko · pshiko · commit 6ab219e1152a · 2026-06-04T02:16:45.000+09:00
Confluence Cloud removed the legacy /download/attachments/{id}/{file} endpoint (CHANGE-2735) that an attachment's _links.download still points to; it now returns 401 for API-token / scoped-token auth while metadata endpoints keep working. This breaks confluence_get_page_images and the attachment download tools (0 downloaded, all "Fetch failed").

Resolve attachment download URLs to the v1 REST endpoint /rest/api/content/{cid}/child/attachment/{aid}/download, which still authenticates correctly. Controlled by CONFLUENCE_ATTACHMENT_DOWNLOAD_USE_V1: unset = auto (v1 on Cloud, legacy link on Server/DC), true = always v1, false = always legacy.
diff --git a/.env.example b/.env.example
@@ -183,6 +183,17 @@ MCP_VERY_VERBOSE=true   # Enables DEBUG level logging (equivalent to 'mcp-atlass
 # Optional: Comma-separated list of Jira project keys to limit searches and other operations to.
 #JIRA_PROJECTS_FILTER=PROJ,DEVOPS
 
+# --- Confluence Cloud attachment download workaround ---
+# Confluence Cloud removed the legacy /download/attachments/... endpoint that an
+# attachment's `_links.download` still points to; it now returns 401 for
+# API-token / scoped-token auth (metadata endpoints keep working). Controls
+# whether attachment/image downloads use the v1 REST endpoint
+# (/rest/api/content/{id}/child/attachment/{aid}/download) instead:
+#   unset (default) -> auto: v1 on Cloud, legacy link on Server/DC
+#   true            -> always v1
+#   false           -> always the legacy link
+#CONFLUENCE_ATTACHMENT_DOWNLOAD_USE_V1=true
+
 # --- SLA Metrics Configuration ---
 # Configure how SLA metrics are calculated for Jira issues.
 # Default metrics to calculate (comma-separated).
diff --git a/docs/configuration.mdx b/docs/configuration.mdx
@@ -150,6 +150,7 @@ This guide covers IDE integration, environment variables, and advanced configura
 | `MCP_VERBOSE` | Enable verbose logging (`true`/`false`) |
 | `MCP_VERY_VERBOSE` | Enable debug logging (`true`/`false`) |
 | `MCP_LOGGING_STDOUT` | Log to stdout instead of stderr (`true`/`false`) |
+| `CONFLUENCE_ATTACHMENT_DOWNLOAD_USE_V1` | Download Confluence attachments via the v1 REST endpoint instead of the legacy `/download/` link (removed on Cloud). Unset = auto (v1 on Cloud, legacy on Server/DC); `true`/`false` to force. |
 | `ATLASSIAN_OAUTH_PROXY_ENABLE` | Enable OAuth proxy + DCR + `/.well-known/*` routes (`true`/`false`) |
 | `PUBLIC_BASE_URL` | Public base URL for OAuth discovery metadata |
 | `ATLASSIAN_OAUTH_ALLOWED_CLIENT_REDIRECT_URIS` | Comma-separated allowed redirect URI patterns for DCR clients |
diff --git a/docs/tools/confluence-attachments.mdx b/docs/tools/confluence-attachments.mdx
@@ -82,6 +82,8 @@ Confluence API returns generic MIME types — use the `mediaTypeDescription` fie
 
 Download an attachment from Confluence as an embedded resource.
 
+<Note>On Confluence Cloud, attachment downloads automatically use the v1 REST endpoint (the legacy `/download/` link was removed and returns 401 for API/scoped tokens). Override with `CONFLUENCE_ATTACHMENT_DOWNLOAD_USE_V1`.</Note>
+
 **Parameters:**
 
 | Parameter | Type | Required | Description |
@@ -120,6 +122,8 @@ Permanently delete an attachment from Confluence.
 
 Get all images attached to a Confluence page as inline image content.
 
+<Note>On Confluence Cloud, images are fetched via the v1 REST endpoint automatically (the legacy `/download/` link was removed and returns 401 for API/scoped tokens). Override with `CONFLUENCE_ATTACHMENT_DOWNLOAD_USE_V1`.</Note>
+
 **Parameters:**
 
 | Parameter | Type | Required | Description |
diff --git a/docs/troubleshooting.mdx b/docs/troubleshooting.mdx
@@ -141,6 +141,22 @@ Header values containing sensitive information are automatically masked in logs.
     ```
   </Accordion>
 
+  <Accordion title="401 Unauthorized — Confluence attachment / image download (Cloud)">
+    **Symptom:** Reading pages works, but `confluence_get_page_images` returns
+    `downloaded: 0` (every image `"Fetch failed"`) and `confluence_download_attachment` /
+    `confluence_download_content_attachments` fail. Logs show
+    `401 ... /wiki/download/attachments/...`.
+
+    **Cause:** Confluence Cloud removed the legacy `/download/attachments/...` endpoint
+    (changelog [CHANGE-2735](https://developer.atlassian.com/cloud/confluence/changelog/) /
+    ["Deprecation of /download/attachments/ APIs"](https://community.developer.atlassian.com/t/deprecation-of-download-attachments-apis/94448)).
+    It now returns 401 for API-token / scoped-token auth, while metadata endpoints keep working.
+
+    **Fix:** On Cloud this is handled automatically — downloads use the v1 REST endpoint
+    `/rest/api/content/{id}/child/attachment/{aid}/download`. To force the behaviour, set
+    `CONFLUENCE_ATTACHMENT_DOWNLOAD_USE_V1=true` (or `false` to keep the legacy link).
+  </Accordion>
+
   <Accordion title="401 Unauthorized — Personal Access Token (PAT)">
     **Cause:** Invalid PAT or PAT doesn't have required permissions.
 
diff --git a/src/mcp_atlassian/confluence/attachments.py b/src/mcp_atlassian/confluence/attachments.py
@@ -2,6 +2,7 @@
 
 import logging
 import os
+import re
 from pathlib import Path
 from typing import Any
 
@@ -32,6 +33,70 @@ def _v2_adapter(self) -> ConfluenceV2Adapter | None:
             )
         return None
 
+    def _resolve_attachment_download_url(
+        self,
+        download_url: str | None,
+        attachment_id: str | None = None,
+        content_id: str | None = None,
+    ) -> str:
+        """Resolve an attachment's download URL to an absolute URL.
+
+        Confluence Cloud removed the legacy ``/download/attachments/{cid}/{file}``
+        endpoint that the attachment's ``_links.download`` still points to; it now
+        returns 401 for API-token / scoped-token auth (while metadata endpoints
+        keep working). Depending on ``config.attachment_download_use_v1`` this
+        rewrites the link to the v1 REST endpoint
+        ``/rest/api/content/{cid}/child/attachment/{aid}/download`` (which still
+        authenticates correctly):
+
+        - ``None`` (default): auto — v1 on Cloud, the legacy link on Server/DC.
+        - ``True``: always use v1.
+        - ``False``: always use the legacy link.
+
+        Args:
+            download_url: The (possibly relative) download link from the API.
+            attachment_id: The attachment ID (e.g. ``att123``); required for v1.
+            content_id: The parent content ID. If omitted, it is parsed from the
+                legacy download link.
+
+        Returns:
+            An absolute URL to fetch the attachment binary from.
+        """
+        resolved = (
+            resolve_relative_url(download_url, self.config.url) if download_url else ""
+        )
+        use_v1 = self.config.attachment_download_use_v1
+        if use_v1 is None:
+            # Auto: Cloud removed the legacy endpoint, so default to v1 there;
+            # Server/DC keeps the legacy link.
+            use_v1 = self.config.is_cloud
+        if not (use_v1 and attachment_id and download_url):
+            return resolved
+
+        if not content_id:
+            match = re.search(r"/download/attachments/([^/]+)/", download_url)
+            if not match:
+                logger.debug(
+                    "Could not derive content_id from download URL %s; "
+                    "falling back to the original link",
+                    download_url,
+                )
+                return resolved
+            content_id = match.group(1)
+
+        base = self.config.url.rstrip("/")
+        v1_url = (
+            f"{base}/rest/api/content/{content_id}"
+            f"/child/attachment/{attachment_id}/download"
+        )
+        # Preserve only the documented ``version`` query param (if present) so a
+        # version-specific link keeps that version, without forwarding the other
+        # legacy params (api / cacheVersion / ...) the v1 endpoint doesn't document.
+        version_match = re.search(r"[?&]version=([^&]+)", download_url)
+        if version_match:
+            v1_url = f"{v1_url}?version={version_match.group(1)}"
+        return v1_url
+
     def upload_attachment(
         self,
         content_id: str,
@@ -321,9 +386,11 @@ def download_content_attachments(
             safe_filename = Path(attachment.title).name
             file_path = target_path / safe_filename
 
-            # Prepend base URL if download URL is relative
-            download_url = resolve_relative_url(
-                attachment.download_url, self.config.url
+            # Resolve to an absolute URL (and optionally the v1 endpoint)
+            download_url = self._resolve_attachment_download_url(
+                attachment.download_url,
+                attachment_id=attachment.id,
+                content_id=content_id,
             )
 
             # Download the attachment
diff --git a/src/mcp_atlassian/confluence/config.py b/src/mcp_atlassian/confluence/config.py
@@ -5,7 +5,7 @@
 from dataclasses import dataclass
 from typing import Literal
 
-from ..utils.env import get_custom_headers, is_env_ssl_verify
+from ..utils.env import get_custom_headers, is_env_ssl_verify, is_env_truthy
 from ..utils.oauth import (
     BYOAccessTokenOAuthConfig,
     OAuthConfig,
@@ -40,6 +40,14 @@ class ConfluenceConfig:
     client_key: str | None = None  # Client private key file path (.pem)
     client_key_password: str | None = None  # Password for encrypted private key
     timeout: int = 75  # Connection timeout in seconds
+    # Cloud removed the legacy /download/attachments/... endpoint (CHANGE-2735);
+    # it now 401s for API-token / scoped-token auth. Controls whether attachment
+    # downloads use the v1 REST endpoint
+    # (/rest/api/content/{id}/child/attachment/{aid}/download) instead:
+    #   None  -> auto: v1 on Cloud, legacy link on Server/DC (default)
+    #   True  -> always v1
+    #   False -> always the legacy link
+    attachment_download_use_v1: bool | None = None
 
     @property
     def is_cloud(self) -> bool:
@@ -187,6 +195,13 @@ def from_env(cls) -> "ConfluenceConfig":
         ):
             timeout = int(os.getenv("CONFLUENCE_TIMEOUT", "75"))
 
+        _use_v1_raw = os.getenv("CONFLUENCE_ATTACHMENT_DOWNLOAD_USE_V1")
+        attachment_download_use_v1 = (
+            None
+            if _use_v1_raw is None
+            else is_env_truthy("CONFLUENCE_ATTACHMENT_DOWNLOAD_USE_V1")
+        )
+
         return cls(
             url=url or "",
             auth_type=auth_type,
@@ -205,6 +220,7 @@ def from_env(cls) -> "ConfluenceConfig":
             client_key=client_key,
             client_key_password=client_key_password,
             timeout=timeout,
+            attachment_download_use_v1=attachment_download_use_v1,
         )
 
     def is_auth_configured(self) -> bool:
diff --git a/src/mcp_atlassian/servers/confluence.py b/src/mcp_atlassian/servers/confluence.py
@@ -21,7 +21,6 @@
     fetch_and_encode_attachment,
     is_image_attachment,
 )
-from mcp_atlassian.utils.urls import resolve_relative_url
 
 logger = logging.getLogger(__name__)
 
@@ -1626,7 +1625,9 @@ async def download_attachment(
                 ),
             )
 
-        download_url = resolve_relative_url(download_url, confluence_fetcher.config.url)
+        download_url = confluence_fetcher._resolve_attachment_download_url(
+            download_url, attachment_id=attachment_id
+        )
 
         filename = attachment_data.get("title") or attachment_id
         mime_type = (
@@ -1814,8 +1815,10 @@ async def download_content_attachments(
             )
             continue
 
-        download_url = resolve_relative_url(
-            attachment.download_url, confluence_fetcher.config.url
+        download_url = confluence_fetcher._resolve_attachment_download_url(
+            attachment.download_url,
+            attachment_id=attachment.id,
+            content_id=content_id,
         )
 
         encoded, mime_type, fetched_bytes = fetch_and_encode_attachment(
@@ -2028,7 +2031,11 @@ async def get_page_images(
             failed.append({"filename": filename, "error": "No download URL"})
             continue
 
-        download_url = resolve_relative_url(download_url, confluence_fetcher.config.url)
+        download_url = confluence_fetcher._resolve_attachment_download_url(
+            download_url,
+            attachment_id=attachment.id,
+            content_id=content_id,
+        )
 
         encoded, _, fetched_bytes = fetch_and_encode_attachment(
             fetch_fn=confluence_fetcher.fetch_attachment_content,
diff --git a/tests/unit/confluence/test_attachments.py b/tests/unit/confluence/test_attachments.py
@@ -9,6 +9,7 @@
 from mcp.types import EmbeddedResource, TextContent
 
 from mcp_atlassian.confluence.attachments import AttachmentsMixin
+from mcp_atlassian.confluence.config import ConfluenceConfig
 
 # Test scenarios for AttachmentsMixin
 #
@@ -1487,3 +1488,88 @@ def test_download_content_attachments_absolute_escape(
         """download_content_attachments rejects directory escape."""
         with pytest.raises(ValueError, match="Path traversal detected"):
             confluence_mixin.download_content_attachments("12345", "/etc")
+
+
+class TestResolveAttachmentDownloadUrl:
+    """Tests for AttachmentsMixin._resolve_attachment_download_url.
+
+    Covers the CONFLUENCE_ATTACHMENT_DOWNLOAD_USE_V1 Cloud workaround: when
+    enabled, the (removed) legacy /download/attachments/... link is rewritten to
+    the v1 REST endpoint; otherwise the original link is preserved.
+    """
+
+    def _make_mixin(
+        self, *, use_v1: bool | None, url: str = "https://example.atlassian.net/wiki"
+    ) -> AttachmentsMixin:
+        with patch(
+            "mcp_atlassian.confluence.attachments.ConfluenceClient.__init__",
+            return_value=None,
+        ):
+            mixin = AttachmentsMixin()
+        config = ConfluenceConfig(url=url, auth_type="basic")
+        config.attachment_download_use_v1 = use_v1
+        mixin.config = config
+        return mixin
+
+    def test_v1_enabled_builds_rest_endpoint(self) -> None:
+        mixin = self._make_mixin(use_v1=True)
+        url = mixin._resolve_attachment_download_url(
+            "/download/attachments/123/foo.png?version=1&api=v2",
+            attachment_id="att999",
+        )
+        assert url == (
+            "https://example.atlassian.net/wiki"
+            "/rest/api/content/123/child/attachment/att999/download?version=1"
+        )
+
+    def test_v1_preserves_only_version_param(self) -> None:
+        # The v1 download endpoint documents only ``version``; keep that (so a
+        # version-specific link doesn't fall back to latest) and drop the other
+        # legacy query params (cacheVersion / api / ...).
+        mixin = self._make_mixin(use_v1=True)
+        url = mixin._resolve_attachment_download_url(
+            "/download/attachments/123/foo.png?version=3&cacheVersion=1&api=v2",
+            attachment_id="att999",
+        )
+        assert url.endswith("/att999/download?version=3")
+        assert "cacheVersion" not in url
+        assert "api=v2" not in url
+
+    def test_v1_enabled_uses_explicit_content_id(self) -> None:
+        mixin = self._make_mixin(use_v1=True)
+        url = mixin._resolve_attachment_download_url(
+            "/download/attachments/123/foo.png",
+            attachment_id="att999",
+            content_id="555",
+        )
+        assert "/rest/api/content/555/child/attachment/att999/download" in url
+
+    def test_disabled_returns_legacy_link(self) -> None:
+        mixin = self._make_mixin(use_v1=False)
+        url = mixin._resolve_attachment_download_url(
+            "/download/attachments/123/foo.png", attachment_id="att999"
+        )
+        assert "/download/attachments/123/" in url
+        assert "/child/attachment/" not in url
+
+    def test_missing_attachment_id_falls_back_to_legacy(self) -> None:
+        mixin = self._make_mixin(use_v1=True)
+        url = mixin._resolve_attachment_download_url(
+            "/download/attachments/123/foo.png", attachment_id=None
+        )
+        assert "/download/attachments/123/" in url
+        assert "/child/attachment/" not in url
+
+    def test_auto_cloud_uses_v1(self) -> None:
+        mixin = self._make_mixin(use_v1=None)
+        url = mixin._resolve_attachment_download_url(
+            "/download/attachments/123/foo.png", attachment_id="att999"
+        )
+        assert "/rest/api/content/123/child/attachment/att999/download" in url
+
+    def test_auto_server_dc_returns_legacy(self) -> None:
+        mixin = self._make_mixin(use_v1=None, url="https://confluence.example.com")
+        url = mixin._resolve_attachment_download_url(
+            "/download/attachments/123/foo.png", attachment_id="att999"
+        )
+        assert "/child/attachment/" not in url
