@groupby/ai-dev 0.5.16 → 0.5.17

package/teams/firstspirit-caas/mcp/jira-tools.py

@@ -0,0 +1,2122 @@
+#!/usr/bin/env python3
+import json
+import re
+import ssl
+import sys
+import os
+import urllib.request
+from urllib.request import Request
+from urllib.parse import quote, urljoin, urlparse
+import tempfile
+
+
+# Some corporate hosts (notably Bamboo / ci.e-spirit.de) present only a leaf
+# cert and rely on AIA chasing for the intermediate. macOS curl handles that
+# via Security framework; Python's stdlib SSL does not. ``truststore`` (PyPI)
+# delegates to the OS trust store and resolves this transparently — install
+# it with ``pip install truststore`` if Bamboo calls fail with
+# ``unable to get local issuer certificate``. We inject lazily so the MCP
+# keeps working when truststore is absent (the JIRA and Bitbucket hosts ship
+# full chains and don't need it).
+try:
+    import truststore as _truststore
+    _truststore.inject_into_ssl()
+except ImportError:
+    pass
+
+import socket as _socket
+# Force IPv4: jira.crownpeak.com (AWS ALB) publishes AAAA records whose IPv6
+# path is unreachable from some corporate networks, so urllib burns a full
+# connect-timeout on IPv6 before falling back to IPv4 on every call. Filtering
+# getaddrinfo to AF_INET keeps DNS dynamic (ALB IPs rotate) but skips IPv6.
+_orig_getaddrinfo = _socket.getaddrinfo
+def _getaddrinfo_ipv4(host, port, family=0, *a, **kw):
+    return _orig_getaddrinfo(host, port, _socket.AF_INET, *a, **kw)
+_socket.getaddrinfo = _getaddrinfo_ipv4
+
+# Jira configuration
+JIRA_BASE = os.environ.get("JIRA_BASE_URL", "").rstrip("/")
+JIRA_TOKEN = os.environ.get("JIRA_TOKEN")
+
+# Bitbucket configuration
+BITBUCKET_BASE = os. environ.get("BITBUCKET_BASE_URL", "").rstrip("/")
+BITBUCKET_TOKEN = os.environ.get("BITBUCKET_TOKEN")
+
+# Bamboo configuration (optional — only needed for get_bamboo_* tools)
+BAMBOO_BASE = os.environ.get("BAMBOO_BASE_URL", "").rstrip("/")
+BAMBOO_TOKEN = os.environ.get("BAMBOO_TOKEN")
+
+
+def jira_request(endpoint, method="GET", data=None):
+    """Make a request to Jira REST API v2."""
+    if not JIRA_BASE:
+        raise RuntimeError(
+            "JIRA_BASE_URL is empty. The planetexpress plugin sets this from "
+            "its bundled .mcp.json — reinstall or update the plugin to restore "
+            "the default."
+        )
+    if not JIRA_TOKEN:
+        raise RuntimeError(
+            "JIRA_TOKEN is empty. The planetexpress plugin reads it from your "
+            "user config (~/.claude/settings.json → pluginConfigs.planetexpress."
+            "options.jira_token). Run `/plugin` and reconfigure planetexpress "
+            "to set the Jira personal access token, then restart Claude Code."
+        )
+    auth_header = f"Bearer {JIRA_TOKEN}"
+    url = f"{JIRA_BASE}/rest/api/2/{endpoint}"
+    body = json.dumps(data).encode() if data is not None else None
+    req = Request(
+        url,
+        headers={"Authorization": auth_header, "Content-Type": "application/json"},
+        data=body, method=method
+    )
+    try:
+        with urllib.request.urlopen(req) as resp:
+            raw = resp.read()
+            return json.loads(raw) if raw else {}
+    except Exception as e:
+        raise RuntimeError(f"{e} (URL: {url})") from e
+
+
+def _bitbucket_call(api_root, endpoint, method="GET", data=None):
+    """Shared Bitbucket call — used by bitbucket_request (api/1.0) and the
+    build-status endpoint (build-status/1.0). ``api_root`` is the full path
+    prefix between host and endpoint, e.g. ``/rest/api/1.0/``."""
+    if not BITBUCKET_BASE:
+        raise RuntimeError(
+            "BITBUCKET_BASE_URL is empty. The planetexpress plugin sets this "
+            "from its bundled .mcp.json — reinstall or update the plugin to "
+            "restore the default."
+        )
+    if not BITBUCKET_TOKEN:
+        raise RuntimeError(
+            "BITBUCKET_TOKEN is empty. The planetexpress plugin reads it from "
+            "your user config (~/.claude/settings.json → pluginConfigs."
+            "planetexpress.options.bitbucket_token). Run `/plugin` and "
+            "reconfigure planetexpress to set the Bitbucket HTTP access token, "
+            "then restart Claude Code."
+        )
+    body = json.dumps(data).encode() if data else None
+    url = f"{BITBUCKET_BASE}{api_root}{endpoint}"
+    req = Request(
+        url,
+        headers={"Authorization": f"Bearer {BITBUCKET_TOKEN}", "Content-Type": "application/json"},
+        data=body, method=method
+    )
+    try:
+        with urllib.request.urlopen(req) as resp:
+            raw = resp.read()
+            return json.loads(raw) if raw else {}
+    except Exception as e:
+        raise RuntimeError(f"{e} (URL: {url})") from e
+
+
+def bitbucket_request(endpoint, method="GET", data=None):
+    """Make a request to Bitbucket REST API 1.0."""
+    return _bitbucket_call("/rest/api/1.0/", endpoint, method, data)
+
+
+def jira_devstatus_request(endpoint):
+    """Make a GET request to Jira's internal /rest/dev-status endpoint.
+
+    Used to fetch Development-panel data (linked PRs, branches, commits)
+    that is *not* exposed via the standard /rest/api/2 issue API.
+    Atlassian flags this endpoint as undocumented and subject to change.
+    """
+    if not JIRA_BASE or not JIRA_TOKEN:
+        raise RuntimeError(
+            "JIRA_BASE_URL or JIRA_TOKEN is unset — see jira_request() for "
+            "configuration details."
+        )
+    url = f"{JIRA_BASE}/rest/dev-status/1.0/{endpoint}"
+    req = Request(url, headers={"Authorization": f"Bearer {JIRA_TOKEN}"})
+    try:
+        with urllib.request.urlopen(req) as resp:
+            raw = resp.read()
+            return json.loads(raw) if raw else {}
+    except Exception as e:
+        raise RuntimeError(f"{e} (URL: {url})") from e
+
+
+def bamboo_request(path, accept_json=True, return_headers=False):
+    """Make a request to Bamboo. ``path`` includes leading slash (e.g.
+    ``/rest/api/latest/result/...`` or ``/download/...``).
+
+    When ``accept_json=False`` returns raw bytes (used for log/artifact
+    downloads). When ``return_headers=True`` returns ``(raw_bytes,
+    content_type)`` instead — used by the artifact fetch tool to detect text
+    vs binary from the real Content-Type.
+    """
+    if not BAMBOO_BASE:
+        raise RuntimeError(
+            "BAMBOO_BASE_URL is empty. The planetexpress plugin sets this "
+            "from its bundled .mcp.json — reinstall or update the plugin to "
+            "restore the default."
+        )
+    if not BAMBOO_TOKEN:
+        raise RuntimeError(
+            "BAMBOO_TOKEN is empty. The planetexpress plugin reads it from "
+            "your user config (planetexpress.options.bamboo_token). Run "
+            "`/plugin` and configure the Bamboo personal access token, then "
+            "restart Claude Code."
+        )
+    url = f"{BAMBOO_BASE}{path}"
+    headers = {"Authorization": f"Bearer {BAMBOO_TOKEN}"}
+    if accept_json:
+        headers["Accept"] = "application/json"
+    req = Request(url, headers=headers)
+    try:
+        with urllib.request.urlopen(req) as resp:
+            raw = resp.read()
+            if return_headers:
+                try:
+                    ctype = resp.headers.get("Content-Type", "") or ""
+                except Exception:
+                    ctype = ""
+                return raw, ctype
+            return (json.loads(raw) if raw else {}) if accept_json else raw
+    except ssl.SSLCertVerificationError as e:
+        raise RuntimeError(
+            f"{e} (URL: {url}). The server may serve an incomplete cert chain "
+            "(e.g. ci.e-spirit.de). Install the `truststore` package — "
+            "`pip3 install truststore` — to use the OS trust store for "
+            "AIA chasing, then restart the MCP."
+        ) from e
+    except Exception as e:
+        raise RuntimeError(f"{e} (URL: {url})") from e
+
+
+def get_ticket(ticket_id:  str) -> dict:
+    """Fetch Jira ticket details including comments and attachment metadata."""
+    data = jira_request(f"issue/{quote(ticket_id)}")
+    fields = data. get("fields", {})
+
+    # Extract comments
+    comment_data = fields.get("comment", {})
+    comments = []
+    for c in comment_data.get("comments", []):
+        comments.append({
+            "id": c.get("id"),
+            "author": (c.get("author") or {}).get("displayName", "Unknown"),
+            "body": c.get("body", ""),
+            "created": c.get("created", ""),
+            "updated": c.get("updated", ""),
+        })
+
+    # Extract attachment metadata (content is fetched separately via download_jira_attachment)
+    attachments = []
+    for a in fields.get("attachment", []):
+        attachments.append({
+            "id": a.get("id"),
+            "filename": a.get("filename", ""),
+            "size": a.get("size"),
+            "mimeType": a.get("mimeType", ""),
+            "author": (a.get("author") or {}).get("displayName", "Unknown"),
+            "created": a.get("created", ""),
+        })
+
+    # Extract issue links (relationships to other tickets). The relationship
+    # phrase is taken from THIS ticket's perspective: a link carrying an
+    # outwardIssue uses the type's outward phrase, an inwardIssue the inward.
+    links = []
+    for link in fields.get("issuelinks", []) or []:
+        link_type = link.get("type", {}) or {}
+        if link.get("outwardIssue"):
+            relationship = link_type.get("outward", "")
+            other = link["outwardIssue"]
+        elif link.get("inwardIssue"):
+            relationship = link_type.get("inward", "")
+            other = link["inwardIssue"]
+        else:
+            continue
+        other_fields = other.get("fields", {}) or {}
+        links.append({
+            "relationship": relationship,
+            "type": link_type.get("name", ""),
+            "key": other.get("key", ""),
+            "summary": other_fields.get("summary", ""),
+            "status": (other_fields.get("status") or {}).get("name", ""),
+            "link": f"{JIRA_BASE}/browse/{other.get('key', '')}",
+        })
+
+    return {
+        "key": data["key"],
+        "summary":  fields.get("summary", "No summary"),
+        "description": fields.get("description") or "No description",
+        "issuetype": (fields.get("issuetype") or {}).get("name", "Unknown"),
+        "status": fields.get("status", {}).get("name", "Unknown"),
+        "labels": fields.get("labels", []) or [],
+        "priority": fields.get("priority", {}).get("name", "Unknown"),
+        "assignee": (fields.get("assignee") or {}).get("displayName", "Unassigned"),
+        "reporter": (fields.get("reporter") or {}).get("displayName", "Unknown"),
+        "created": fields.get("created", ""),
+        "updated": fields.get("updated", ""),
+        "link": f"{JIRA_BASE}/browse/{data['key']}",
+        "comments": comments,
+        "attachments": attachments,
+        "links": links,
+    }
+
+
+def add_jira_comment(ticket_id: str, body: str) -> dict:
+    """Add a comment to a Jira ticket. ``body`` uses Jira wiki markup."""
+    data = jira_request(
+        f"issue/{quote(ticket_id)}/comment",
+        method="POST",
+        data={"body": body},
+    )
+    return {
+        "id": data.get("id"),
+        "author": (data.get("author") or {}).get("displayName", "Unknown"),
+        "created": data.get("created", ""),
+        "link": f"{JIRA_BASE}/browse/{ticket_id}?focusedCommentId={data.get('id')}",
+    }
+
+
+def create_jira_ticket(
+    project_key: str,
+    summary: str,
+    issue_type: str = "Story",
+    description: str = "",
+    priority: str = "",
+    assignee: str = "",
+    labels: str = "",
+    parent: str = "",
+) -> dict:
+    """Create a new Jira ticket.
+
+    ``description`` uses Jira wiki markup. ``labels`` is a comma-separated list.
+    ``parent`` is the key of the parent ticket (required when ``issue_type`` is
+    ``Sub-task``).
+    """
+    fields: dict = {
+        "project": {"key": project_key},
+        "summary": summary,
+        "issuetype": {"name": issue_type},
+    }
+    if description:
+        fields["description"] = description
+    if priority:
+        fields["priority"] = {"name": priority}
+    if assignee:
+        fields["assignee"] = {"name": assignee}
+    label_list = [l.strip() for l in labels.split(",") if l.strip()]
+    if label_list:
+        fields["labels"] = label_list
+    if parent:
+        fields["parent"] = {"key": parent}
+
+    data = jira_request("issue", method="POST", data={"fields": fields})
+    key = data.get("key", "")
+    return {
+        "key": key,
+        "id": data.get("id"),
+        "link": f"{JIRA_BASE}/browse/{key}" if key else "",
+    }
+
+
+def update_jira_ticket(
+    issue_key: str,
+    description: str = "",
+    summary: str = "",
+    add_labels: str = "",
+    remove_labels: str = "",
+) -> dict:
+    """Update an existing Jira ticket's description, summary and/or labels.
+
+    Uses PUT /rest/api/2/issue/{key} which returns 204 No Content on success.
+    ``add_labels`` / ``remove_labels`` are comma-separated label lists applied
+    additively via Jira's ``update`` verb, so existing labels are preserved.
+    At least one of description, summary, add_labels or remove_labels must be
+    provided.
+    """
+    if not issue_key:
+        raise ValueError("issue_key must not be empty")
+    to_add = [l.strip() for l in add_labels.split(",") if l.strip()]
+    to_remove = [l.strip() for l in remove_labels.split(",") if l.strip()]
+    if not description and not summary and not to_add and not to_remove:
+        raise ValueError(
+            "At least one of 'description', 'summary', 'add_labels' or "
+            "'remove_labels' must be provided"
+        )
+    payload: dict = {}
+    fields: dict = {}
+    if description:
+        fields["description"] = description
+    if summary:
+        fields["summary"] = summary
+    if fields:
+        payload["fields"] = fields
+    label_ops = [{"add": l} for l in to_add] + [{"remove": l} for l in to_remove]
+    if label_ops:
+        payload["update"] = {"labels": label_ops}
+    jira_request(f"issue/{quote(issue_key)}", method="PUT", data=payload)
+    return {
+        "key": issue_key,
+        "updated": True,
+        "added_labels": to_add,
+        "removed_labels": to_remove,
+        "link": f"{JIRA_BASE}/browse/{issue_key}",
+    }
+
+
+def get_jira_transitions(issue_key: str) -> dict:
+    """List the workflow transitions currently available on a Jira ticket.
+
+    Jira only exposes transitions reachable from the ticket's *current* status,
+    so a multi-step move (e.g. Triage -> Backlog -> Committed) is walked one
+    transition at a time. Each entry gives the transition ``name`` and the
+    ``to_status`` it lands the ticket in — pass that status to
+    ``transition_jira_ticket``.
+    """
+    if not issue_key:
+        raise ValueError("issue_key must not be empty")
+    data = jira_request(f"issue/{quote(issue_key)}/transitions")
+    transitions = []
+    for t in data.get("transitions", []) or []:
+        transitions.append({
+            "id": t.get("id"),
+            "name": t.get("name"),
+            "to_status": (t.get("to") or {}).get("name"),
+        })
+    return {"key": issue_key, "transitions": transitions}
+
+
+def transition_jira_ticket(issue_key: str, status: str) -> dict:
+    """Move a Jira ticket to a new status by performing a workflow transition.
+
+    ``status`` is matched (case-insensitively) against the target status of the
+    transitions currently available on the ticket — matching either the target
+    status name or the transition name. Only one step is performed per call;
+    for a multi-step move call this repeatedly (the reachable set changes after
+    each transition). If no available transition matches, raises with the list
+    of transitions that ARE available from the current status.
+    """
+    if not issue_key:
+        raise ValueError("issue_key must not be empty")
+    if not status:
+        raise ValueError("status must not be empty")
+    available = get_jira_transitions(issue_key)["transitions"]
+    target = status.strip().lower()
+    match = next(
+        (
+            t for t in available
+            if (t.get("to_status") or "").lower() == target
+            or (t.get("name") or "").lower() == target
+        ),
+        None,
+    )
+    if not match:
+        options = ", ".join(
+            f"{t['name']} -> {t['to_status']}" for t in available
+        ) or "(none)"
+        raise ValueError(
+            f"No transition to '{status}' available from the current status of "
+            f"{issue_key}. Available transitions: {options}"
+        )
+    jira_request(
+        f"issue/{quote(issue_key)}/transitions",
+        method="POST",
+        data={"transition": {"id": match["id"]}},
+    )
+    return {
+        "key": issue_key,
+        "transitioned": True,
+        "transition": match["name"],
+        "status": match["to_status"],
+        "link": f"{JIRA_BASE}/browse/{issue_key}",
+    }
+
+
+def get_jira_link_types() -> dict:
+    """Fetch the issue-link relationship types configured on this Jira
+    instance (Relates, Blocks, custom types like 'follows on from', ...).
+
+    Each type carries its human-readable ``outward`` and ``inward`` phrases,
+    which are the valid relationship values for ``link_jira_issues``.
+    """
+    data = jira_request("issueLinkType")
+    types = []
+    for t in data.get("issueLinkTypes", []) or []:
+        types.append({
+            "id": t.get("id"),
+            "name": t.get("name"),
+            "inward": t.get("inward"),
+            "outward": t.get("outward"),
+        })
+    return {"link_types": types}
+
+
+def link_jira_issues(from_issue: str, to_issue: str, relationship: str) -> dict:
+    """Create a directional issue link between two tickets using a natural
+    relationship phrase.
+
+    ``relationship`` is a phrase such as ``blocks``, ``is blocked by``,
+    ``relates to`` or ``follows on from`` (discover valid phrases via
+    ``get_jira_link_types``). The phrase is resolved against the instance's
+    link types to pick the link type AND direction: the result reads
+    ``from_issue <relationship> to_issue``.
+    """
+    if not from_issue or not to_issue:
+        raise ValueError("from_issue and to_issue must not be empty")
+    if not relationship or not relationship.strip():
+        raise ValueError("relationship must not be empty")
+
+    rel = relationship.strip().lower()
+    raw = jira_request("issueLinkType")
+    link_types = raw.get("issueLinkTypes", []) or []
+
+    # Resolve the phrase to (type, direction, applied-phrase) candidates.
+    candidates = []
+    for t in link_types:
+        name = (t.get("name") or "")
+        outward = (t.get("outward") or "")
+        inward = (t.get("inward") or "")
+        if rel == outward.lower():
+            candidates.append((t, "outward", outward))
+        # Symmetry guard: a symmetric type (inward == outward) must yield only
+        # the outward candidate, otherwise it would falsely look ambiguous.
+        if rel == inward.lower() and inward.lower() != outward.lower():
+            candidates.append((t, "inward", inward))
+        if rel == name.lower():
+            candidates.append((t, "outward", outward))
+
+    # De-duplicate by (type name, direction).
+    seen = {}
+    for t, direction, phrase in candidates:
+        seen.setdefault((t.get("name"), direction), (t, direction, phrase))
+    unique = list(seen.values())
+
+    if not unique:
+        phrases = sorted({
+            p for t in link_types
+            for p in (t.get("outward"), t.get("inward")) if p
+        })
+        raise ValueError(
+            f"No link type matches relationship {relationship!r}. "
+            f"Available phrases: {', '.join(phrases)}"
+        )
+    if len(unique) > 1:
+        opts = "; ".join(
+            f"{t.get('name')} ({direction}: {phrase})"
+            for t, direction, phrase in unique
+        )
+        raise ValueError(
+            f"Relationship {relationship!r} is ambiguous across link types: "
+            f"{opts}. Use a more specific phrase."
+        )
+
+    link_type, direction, phrase = unique[0]
+    # Jira renders a stored link as ``inwardIssue <outward-phrase> outwardIssue``
+    # (equivalently ``outwardIssue <inward-phrase> inwardIssue``). So to make the
+    # link read ``from_issue <relationship> to_issue`` the from_issue goes into
+    # the slot OPPOSITE the matched phrase's name.
+    if direction == "outward":
+        inward_key, outward_key = from_issue, to_issue
+    else:
+        outward_key, inward_key = from_issue, to_issue
+
+    jira_request(
+        "issueLink",
+        method="POST",
+        data={
+            "type": {"name": link_type.get("name")},
+            "outwardIssue": {"key": outward_key},
+            "inwardIssue": {"key": inward_key},
+        },
+    )
+
+    return {
+        "from": from_issue,
+        "to": to_issue,
+        "type": link_type.get("name"),
+        "relationship": phrase,
+        "summary": f"{from_issue} {phrase} {to_issue}",
+        "from_link": f"{JIRA_BASE}/browse/{from_issue}",
+        "to_link": f"{JIRA_BASE}/browse/{to_issue}",
+    }
+
+
+def download_jira_attachment(attachment_id: str) -> dict:
+    """Download a Jira attachment by ID and save it to a temp file.
+
+    Returns the local file path so the AI can read/inspect the file.
+    Text-based files (source code, XML, JSON, CSV, plain text, etc.) are
+    returned inline as ``content`` to avoid an extra read round-trip.
+    """
+    # Fetch attachment metadata to get the download URL and filename
+    meta = jira_request(f"attachment/{quote(attachment_id)}")
+    content_url = meta.get("content", "")
+    filename = meta.get("filename", f"attachment_{attachment_id}")
+    mime_type = meta.get("mimeType", "application/octet-stream")
+
+    if not content_url:
+        return {"error": "No download URL found for this attachment"}
+
+    # Download the actual file content
+    auth_header = f"Bearer {JIRA_TOKEN}"
+    req = Request(content_url, headers={"Authorization": auth_header})
+    with urllib.request.urlopen(req) as resp:
+        file_bytes = resp.read()
+
+    # Save to a temp file (preserving the original extension)
+    suffix = ""
+    if "." in filename:
+        suffix = "." + filename.rsplit(".", 1)[1]
+    tmp = tempfile.NamedTemporaryFile(delete=False, suffix=suffix, prefix="jira_att_")
+    tmp.write(file_bytes)
+    tmp.close()
+
+    result = {
+        "id": attachment_id,
+        "filename": filename,
+        "mimeType": mime_type,
+        "size": len(file_bytes),
+        "localPath": tmp.name,
+    }
+
+    # For text-based files, include content inline so the AI can read it directly
+    TEXT_MIMES = (
+        "text/", "application/json", "application/xml", "application/xhtml",
+        "application/javascript", "application/typescript", "application/x-yaml",
+        "application/yaml", "application/csv", "application/sql",
+        "application/x-sh", "application/x-python",
+    )
+    if any(mime_type.startswith(m) for m in TEXT_MIMES):
+        try:
+            result["content"] = file_bytes.decode("utf-8")
+        except UnicodeDecodeError:
+            try:
+                result["content"] = file_bytes.decode("latin-1")
+            except UnicodeDecodeError:
+                pass  # Binary after all — the AI can read via localPath
+
+    return result
+
+
+def get_bitbucket_pr(project:  str, repo: str, pr_id: str) -> dict:
+    """Fetch Bitbucket pull request details."""
+    data = bitbucket_request(f"projects/{quote(project)}/repos/{quote(repo)}/pull-requests/{quote(pr_id)}")
+    from_ref = data.get("fromRef", {}) or {}
+    to_ref = data.get("toRef", {}) or {}
+    return {
+        "id": data. get("id"),
+        "title": data.get("title"),
+        "description": data.get("description") or "No description",
+        "state": data.get("state"),
+        "author": data.get("author", {}).get("user", {}).get("displayName", "Unknown"),
+        "fromRef": from_ref.get("displayId", ""),
+        "fromCommit": from_ref.get("latestCommit", ""),
+        "toRef": to_ref.get("displayId", ""),
+        "toCommit": to_ref.get("latestCommit", ""),
+        "reviewers": [r.get("user", {}).get("displayName", "") for r in data.get("reviewers", [])],
+        "link": data.get("links", {}).get("self", [{}])[0].get("href", "")
+    }
+
+
+_PR_URL_RE = re.compile(r"/projects/([^/]+)/repos/([^/]+)/pull-requests/")
+
+
+def _parse_pr_url(url: str):
+    """Parse a Bitbucket Server PR URL into (project, slug). Returns (None, None) on failure."""
+    if not url:
+        return None, None
+    m = _PR_URL_RE.search(url)
+    return (m.group(1), m.group(2)) if m else (None, None)
+
+
+def get_jira_dev_info(ticket_id: str, data_type: str = "pullrequest") -> dict:
+    """Fetch the Development-panel data for a Jira ticket: linked Bitbucket
+    PRs, branches, commits, or repositories.
+
+    Resolves the ticket key to a numeric id (required by the dev-status
+    endpoint), then flattens results across all configured Bitbucket
+    application links. Each item carries its source ``_instance.baseUrl``
+    so callers can tell which Bitbucket the link belongs to.
+    """
+    valid = {"pullrequest", "branch", "commit", "repository"}
+    if data_type not in valid:
+        raise ValueError(f"data_type must be one of {sorted(valid)}, got {data_type!r}")
+
+    issue = jira_request(f"issue/{quote(ticket_id)}?fields=*none")
+    issue_id = issue.get("id")
+    if not issue_id:
+        raise RuntimeError(f"Could not resolve numeric id for ticket {ticket_id}")
+
+    raw = jira_devstatus_request(
+        f"issue/detail?issueId={quote(str(issue_id))}"
+        f"&applicationType=stash&dataType={quote(data_type)}"
+    )
+
+    items = []
+    instances = []
+    for detail in raw.get("detail", []) or []:
+        inst = detail.get("_instance") or {}
+        if inst:
+            instances.append({
+                "name": inst.get("name"),
+                "baseUrl": inst.get("baseUrl"),
+                "primary": inst.get("primary"),
+            })
+        instance_url = inst.get("baseUrl", "")
+
+        if data_type == "pullrequest":
+            for pr in detail.get("pullRequests", []) or []:
+                project, slug = _parse_pr_url(pr.get("url", ""))
+                src = pr.get("source") or {}
+                dst = pr.get("destination") or {}
+                items.append({
+                    "id": pr.get("id"),
+                    "name": pr.get("name"),
+                    "url": pr.get("url"),
+                    "status": pr.get("status"),
+                    "lastUpdate": pr.get("lastUpdate"),
+                    "source": src.get("branch"),
+                    "destination": dst.get("branch"),
+                    "author": (pr.get("author") or {}).get("name"),
+                    "reviewers": [r.get("name") for r in pr.get("reviewers", []) or []],
+                    "commentCount": pr.get("commentCount"),
+                    "repository": {
+                        "project": project,
+                        "slug": slug,
+                        "name": (src.get("repository") or {}).get("name"),
+                        "instanceUrl": instance_url,
+                    },
+                })
+        elif data_type == "branch":
+            for b in detail.get("branches", []) or []:
+                items.append({
+                    "name": b.get("name"),
+                    "url": b.get("url"),
+                    "createPullRequestUrl": b.get("createPullRequestUrl"),
+                    "repository": (b.get("repository") or {}).get("name"),
+                    "instanceUrl": instance_url,
+                })
+        elif data_type == "commit":
+            for c in detail.get("commits", []) or []:
+                items.append({
+                    "id": c.get("id"),
+                    "displayId": c.get("displayId"),
+                    "message": c.get("message"),
+                    "url": c.get("url"),
+                    "author": (c.get("author") or {}).get("name"),
+                    "instanceUrl": instance_url,
+                })
+        elif data_type == "repository":
+            for r in detail.get("repositories", []) or []:
+                items.append({
+                    "name": r.get("name"),
+                    "url": r.get("url"),
+                    "avatarDescription": r.get("avatarDescription"),
+                    "instanceUrl": instance_url,
+                })
+
+    return {
+        "ticket": ticket_id,
+        "issueId": issue_id,
+        "dataType": data_type,
+        "errors": raw.get("errors", []),
+        "instances": instances,
+        "items": items,
+    }
+
+
+def get_bitbucket_commit_build_status(commit_id: str) -> dict:
+    """Fetch CI build statuses posted to a commit (Bamboo/etc. report here).
+
+    Returns the raw statuses plus a derived ``aggregateState`` so callers
+    can branch on a single field: ``GREEN`` (all SUCCESSFUL), ``RED`` (any
+    FAILED with no SUCCESSFUL), ``RUNNING`` (any INPROGRESS), ``MIXED``
+    (FAILED + SUCCESSFUL or other combos), ``NONE`` (no statuses posted).
+    """
+    data = _bitbucket_call("/rest/build-status/1.0/", f"commits/{quote(commit_id)}")
+    statuses = []
+    for v in data.get("values", []) or []:
+        statuses.append({
+            "state": v.get("state"),
+            "key": v.get("key"),
+            "name": v.get("name"),
+            "url": v.get("url"),
+            "description": v.get("description"),
+            "dateAdded": v.get("dateAdded"),
+        })
+
+    states = {s["state"] for s in statuses if s.get("state")}
+    if not states:
+        agg = "NONE"
+    elif "INPROGRESS" in states:
+        agg = "RUNNING"
+    elif states == {"SUCCESSFUL"}:
+        agg = "GREEN"
+    elif "SUCCESSFUL" in states and ("FAILED" in states or "CANCELLED" in states):
+        agg = "MIXED"
+    else:
+        agg = "RED"
+
+    return {
+        "commit": commit_id,
+        "aggregateState": agg,
+        "statuses": statuses,
+    }
+
+
+def get_bamboo_build(build_key: str) -> dict:
+    """Fetch a Bamboo build (chain or job) with per-job results and failed
+    tests in one call.
+
+    ``build_key`` is e.g. ``HAUPIA-HAUPIATESTMETRICS36-8`` (chain build) or
+    ``HAUPIA-HAUPIATESTMETRICS36-CC-1`` (job build). The chain key returns
+    aggregated test counts plus per-job results; the job key returns just
+    that job. Failed-test details are included in both — empty array when
+    the build is green.
+    """
+    data = bamboo_request(
+        f"/rest/api/latest/result/{quote(build_key)}"
+        f"?expand=stages.stage.results.result,testResults.failedTests.testResult.errors"
+    )
+
+    jobs = []
+    for stage in (data.get("stages") or {}).get("stage", []) or []:
+        for r in (stage.get("results") or {}).get("result", []) or []:
+            jobs.append({
+                "key": r.get("buildResultKey"),
+                "shortName": r.get("shortName") or (r.get("plan") or {}).get("shortName"),
+                "state": r.get("state"),
+                "successful": r.get("successful"),
+                "durationDescription": r.get("buildDurationDescription"),
+            })
+
+    def _extract_failed(payload):
+        out = []
+        ft_root = ((payload.get("testResults") or {}).get("failedTests") or {})
+        for t in ft_root.get("testResult", []) or []:
+            errs = (t.get("errors") or {}).get("error", []) or []
+            out.append({
+                "className": t.get("className"),
+                "methodName": t.get("methodName"),
+                "status": t.get("status"),
+                "duration": t.get("duration"),
+                "buildResultKey": t.get("buildResultKey") or payload.get("buildResultKey"),
+                "errors": [{"message": (e.get("message") or "")[:4096]} for e in errs],
+            })
+        return out
+
+    failed = _extract_failed(data)
+
+    # Chain-level results return failedTestCount but an empty failedTests list;
+    # the per-test details live on each failed job. Fan out so callers don't
+    # need a second tool round-trip when a chain build is red.
+    if data.get("failedTestCount") and not failed:
+        for job in jobs:
+            if job.get("successful") is False or job.get("state") == "Failed":
+                try:
+                    job_data = bamboo_request(
+                        f"/rest/api/latest/result/{quote(job['key'])}"
+                        f"?expand=testResults.failedTests.testResult.errors"
+                    )
+                    failed.extend(_extract_failed(job_data))
+                except Exception:
+                    continue
+
+    plan = data.get("plan") or {}
+    key = data.get("buildResultKey")
+    browse_url = f"{BAMBOO_BASE}/browse/{key}" if key else ""
+
+    return {
+        "key": key,
+        "planKey": plan.get("key"),
+        "planName": plan.get("name"),
+        "branchName": data.get("planName"),
+        "state": data.get("state"),
+        "lifeCycleState": data.get("lifeCycleState"),
+        "successful": data.get("successful"),
+        "started": data.get("buildStartedTime"),
+        "completed": data.get("buildCompletedTime"),
+        "durationSeconds": data.get("buildDurationInSeconds"),
+        "vcsRevision": data.get("vcsRevisionKey"),
+        "testSummary": data.get("buildTestSummary"),
+        "successfulTestCount": data.get("successfulTestCount"),
+        "failedTestCount": data.get("failedTestCount"),
+        "skippedTestCount": data.get("skippedTestCount"),
+        "url": browse_url,
+        "jobs": jobs,
+        "failedTests": failed,
+    }
+
+
+def get_bamboo_build_log(
+    job_key: str,
+    build_number: str,
+    tail_lines: str = "200",
+    grep: str = "",
+) -> dict:
+    """Fetch the build log for a Bamboo job. Returns a tail of the log
+    (optionally filtered with a regex first) plus the full log saved to a
+    temp file so the caller can ``Read`` it when more lines are needed.
+
+    ``job_key`` is the job-level key (e.g. ``HAUPIA-HAUPIATESTMETRICS36-CC``),
+    not the chain key. ``build_number`` is the build number (e.g. ``8``).
+    ``tail_lines`` is clamped to [1, 2000]; default 200.
+    """
+    raw = bamboo_request(
+        f"/download/{quote(job_key)}/build_logs/{quote(job_key)}-{quote(str(build_number))}.log",
+        accept_json=False,
+    )
+    text = raw.decode("utf-8", errors="replace")
+    lines = text.splitlines()
+    total = len(lines)
+
+    if grep:
+        try:
+            pat = re.compile(grep)
+            lines = [l for l in lines if pat.search(l)]
+        except re.error as e:
+            raise ValueError(f"Invalid grep regex {grep!r}: {e}")
+
+    try:
+        n = max(1, min(2000, int(tail_lines)))
+    except (TypeError, ValueError):
+        n = 200
+
+    returned = lines[-n:]
+
+    tmp = tempfile.NamedTemporaryFile(
+        delete=False,
+        suffix=".log",
+        prefix=f"bamboo_{job_key}_{build_number}_",
+    )
+    tmp.write(text.encode("utf-8"))
+    tmp.close()
+
+    return {
+        "jobKey": job_key,
+        "buildNumber": build_number,
+        "totalLines": total,
+        "returnedLines": len(returned),
+        "content": "\n".join(returned),
+        "localPath": tmp.name,
+    }
+
+
+_TEXT_EXTS = (
+    ".html", ".htm", ".json", ".txt", ".xml", ".log",
+    ".csv", ".md", ".yaml", ".yml",
+)
+
+
+def _looks_like_file(path):
+    """True when the last path segment has a filename extension."""
+    seg = path.rstrip("/").rsplit("/", 1)[-1]
+    return "." in seg and not seg.startswith(".")
+
+
+def _parse_artifact_index(html, base_url):
+    """Parse a Bamboo artifact directory index (Apache-style HTML). Returns
+    child entries as ``{"href", "name", "isDir"}`` (``name`` is the child's
+    last path segment), excluding the parent-directory link.
+
+    Bamboo serves child links as absolute ``/artifact/{plan}/…/build-N/…``
+    paths that do NOT share the fetched ``/browse/…`` URL's prefix, so a child
+    cannot be identified by prefix-matching the base path. Instead the parent
+    link is excluded (by its "Parent Directory" text and by resolving to an
+    ancestor of the current path) and everything else on these minimal listing
+    pages is a child."""
+    base_path = urlparse(base_url).path.rstrip("/")
+    out = []
+    seen = set()
+    for m in re.finditer(r'<a\s+href="?([^"\s>]+)"?[^>]*>(.*?)</a>', html, re.IGNORECASE | re.DOTALL):
+        raw_href, text = m.group(1), m.group(2)
+        if "parent" in re.sub(r"<[^>]*>", "", text).strip().lower():
+            continue
+        abs_url = urljoin(base_url + "/", raw_href)
+        child_path = urlparse(abs_url).path.rstrip("/")
+        if child_path == base_path or base_path.startswith(child_path + "/"):
+            continue
+        if abs_url in seen:
+            continue
+        seen.add(abs_url)
+        name = child_path.rsplit("/", 1)[-1]
+        out.append({"href": abs_url, "name": name, "isDir": not _looks_like_file(child_path)})
+    return out
+
+
+def _rel(url):
+    """Strip BAMBOO_BASE so the result can be re-prepended by bamboo_request."""
+    if url.startswith(BAMBOO_BASE):
+        return url[len(BAMBOO_BASE):]
+    return urlparse(url).path
+
+
+def _collect_dir_files(dir_href, max_files, prefix="", _depth=0):
+    """Recurse a Bamboo artifact directory index, returning leaf files as
+    ``{"name": <path relative to the artifact root>, "path": <download URL>}``.
+    The relative name is accumulated from each child's segment during descent,
+    which is robust to the browse→artifact URL-space change. Bounded by
+    ``max_files`` and depth 8."""
+    if _depth > 8:
+        return []
+    try:
+        raw, _ = bamboo_request(_rel(dir_href), accept_json=False, return_headers=True)
+    except Exception:
+        return []
+    html = raw.decode("utf-8", errors="replace")
+    files = []
+    for entry in _parse_artifact_index(html, dir_href):
+        if len(files) >= max_files:
+            break
+        rel = f"{prefix}/{entry['name']}" if prefix else entry["name"]
+        if entry["isDir"]:
+            files.extend(_collect_dir_files(entry["href"], max_files - len(files), rel, _depth + 1))
+        else:
+            files.append({"name": rel, "path": entry["href"]})
+    return files
+
+
+def list_bamboo_artifacts(build_key, max_files="200"):
+    """List a Bamboo build's published artifacts, expanding directory
+    artifacts into their contained files.
+
+    ``build_key`` may be a chain key (e.g. ``PLAN-21``) or a job key
+    (``PLAN-BUILD-21``); artifacts attach to job results, so chain keys are
+    walked across all jobs. Each artifact reports ``isDirectory`` and, for
+    directories, a ``files`` list of {name (relative), path (download URL)}.
+    """
+    try:
+        cap = max(1, min(2000, int(max_files)))
+    except (TypeError, ValueError):
+        cap = 200
+
+    data = bamboo_request(
+        f"/rest/api/latest/result/{quote(build_key)}"
+        f"?expand=stages.stage.results.result.artifacts,artifacts"
+    )
+
+    raw_artifacts = list((data.get("artifacts") or {}).get("artifact") or [])
+    for stage in (data.get("stages") or {}).get("stage", []) or []:
+        for r in (stage.get("results") or {}).get("result", []) or []:
+            raw_artifacts.extend((r.get("artifacts") or {}).get("artifact") or [])
+
+    seen = set()
+    artifacts = []
+    truncated = False
+    for a in raw_artifacts:
+        href = (a.get("link") or {}).get("href") or ""
+        if not href or href in seen:
+            continue
+        seen.add(href)
+        is_dir = not _looks_like_file(urlparse(href).path)
+        files = []
+        if is_dir:
+            files = _collect_dir_files(href, cap)
+            if len(files) >= cap:
+                truncated = True
+        artifacts.append({
+            "name": a.get("name"),
+            "href": href,
+            "producerJobKey": a.get("producerJobKey"),
+            "shared": a.get("shared"),
+            "size": a.get("size"),
+            "prettySize": a.get("prettySizeDescription"),
+            "isDirectory": is_dir,
+            "files": files,
+        })
+
+    return {"buildKey": build_key, "artifacts": artifacts, "truncated": truncated}
+
+
+def _is_textual(content_type, filename):
+    ct = (content_type or "").lower()
+    if ct.startswith("text/"):
+        return True
+    if any(t in ct for t in ("application/json", "application/xml", "application/javascript")):
+        return True
+    return filename.lower().endswith(_TEXT_EXTS)
+
+
+def get_bamboo_artifact(build_key, name="", href="", file="", max_inline_bytes="262144"):
+    """Download one Bamboo artifact file, save it to a temp file, and inline
+    its text content when small enough.
+
+    Provide ``href`` for a direct download, or ``name`` to resolve an artifact
+    by name (case-insensitive) via list_bamboo_artifacts. For a directory
+    artifact, ``file`` selects the contained file (exact relative match, else
+    suffix match); if omitted and the directory holds exactly one file, that
+    file is used. Text under ``max_inline_bytes`` is returned in ``content``;
+    otherwise ``content`` is null and the caller Reads ``localPath``.
+    """
+    try:
+        cap = max(0, min(5_000_000, int(max_inline_bytes)))
+    except (TypeError, ValueError):
+        cap = 262144
+
+    artifact_name = name or ""
+    rel_file = ""
+    url = href
+
+    if not url:
+        if not name:
+            raise ValueError("Provide either 'href' or 'name'.")
+        listing = list_bamboo_artifacts(build_key)
+        arts = listing["artifacts"]
+        match = next((a for a in arts if (a.get("name") or "").lower() == name.lower()), None)
+        if match is None:
+            avail = ", ".join(repr(a.get("name")) for a in arts) or "(none)"
+            raise RuntimeError(f"No artifact named {name!r}. Available: {avail}")
+        artifact_name = match.get("name") or name
+        if not match["isDirectory"]:
+            url = match["href"]
+        else:
+            files = match["files"]
+            if not files:
+                raise RuntimeError(f"Artifact {artifact_name!r} is an empty directory.")
+            if file:
+                exact = [f for f in files if f["name"] == file]
+                suffix = [f for f in files if f["name"].endswith(file)]
+                chosen = exact or suffix
+                if not chosen:
+                    avail = ", ".join(repr(f["name"]) for f in files)
+                    raise RuntimeError(f"No file {file!r} in {artifact_name!r}. Available: {avail}")
+                if len(chosen) > 1:
+                    matched = ", ".join(repr(f["name"]) for f in chosen)
+                    raise RuntimeError(f"Ambiguous file {file!r}: matches {matched}")
+                url = chosen[0]["path"]
+                rel_file = chosen[0]["name"]
+            elif len(files) == 1:
+                url = files[0]["path"]
+                rel_file = files[0]["name"]
+            else:
+                avail = ", ".join(repr(f["name"]) for f in files)
+                raise RuntimeError(
+                    f"Artifact {artifact_name!r} is a directory; specify 'file'. Available: {avail}"
+                )
+
+    raw, ctype = bamboo_request(_rel(url), accept_json=False, return_headers=True)
+    filename = rel_file or urlparse(url).path.rstrip("/").rsplit("/", 1)[-1] or "artifact"
+
+    content = None
+    note = ""
+    if _is_textual(ctype, filename):
+        if len(raw) > cap:
+            note = f"too large ({len(raw)} bytes) — Read localPath"
+        else:
+            try:
+                content = raw.decode("utf-8")
+            except UnicodeDecodeError:
+                note = "not valid UTF-8 — Read localPath"
+    else:
+        note = f"binary ({ctype or 'unknown content-type'}) — Read localPath"
+
+    suffix = "." + filename.rsplit(".", 1)[-1] if "." in filename else ""
+    tmp = tempfile.NamedTemporaryFile(
+        delete=False, suffix=suffix,
+        prefix=f"bamboo_artifact_{re.sub(r'[^A-Za-z0-9]+', '_', build_key)}_",
+    )
+    tmp.write(raw)
+    tmp.close()
+
+    return {
+        "buildKey": build_key,
+        "artifactName": artifact_name,
+        "file": rel_file or filename,
+        "url": url,
+        "contentType": ctype,
+        "sizeBytes": len(raw),
+        "content": content,
+        "note": note,
+        "localPath": tmp.name,
+    }
+
+
+def _bamboo_key_from_ref(ref):
+    """Accept a Bamboo browse URL or a bare key and return the key.
+
+    e.g. ``https://ci.e-spirit.de/browse/CAASCAASCONNECT-BUILD`` and
+    ``CAASCAASCONNECT-BUILD`` both yield ``CAASCAASCONNECT-BUILD``.
+    """
+    ref = (ref or "").strip()
+    if "/browse/" in ref:
+        ref = ref.split("/browse/", 1)[1]
+    return ref.split("?", 1)[0].split("#", 1)[0].strip("/")
+
+
+def _bamboo_max_results(value, default=200):
+    try:
+        return max(1, min(int(str(value)), 2000))
+    except (TypeError, ValueError):
+        return default
+
+
+def list_bamboo_branch_plans(plan, max_results="200"):
+    """List the branch plans of a Bamboo plan.
+
+    ``plan`` is a plan key (e.g. ``CAASCAASCONNECT-BUILD``) or a browse URL
+    (``https://ci.e-spirit.de/browse/CAASCAASCONNECT-BUILD``). Returns the base
+    plan plus one entry per branch plan (shortName = git branch, key = the
+    branch plan's build key, enabled flag, browse url). Empty branchPlans means
+    the plan tracks no feature branches (master only).
+    """
+    key = _bamboo_key_from_ref(plan)
+    n = _bamboo_max_results(max_results)
+    data = bamboo_request(
+        f"/rest/api/latest/plan/{quote(key)}/branch.json"
+        f"?max-results={n}&expand=branches.branch"
+    )
+    root = data.get("branches") or {}
+    branches = []
+    for b in root.get("branch", []) or []:
+        bkey = b.get("key")
+        branches.append({
+            "shortName": b.get("shortName"),
+            "key": bkey,
+            "enabled": b.get("enabled"),
+            "url": f"{BAMBOO_BASE}/browse/{bkey}" if bkey else "",
+        })
+    return {
+        "planKey": data.get("key") or key,
+        "url": f"{BAMBOO_BASE}/browse/{key}",
+        "branchCount": root.get("size", len(branches)),
+        "branchPlans": branches,
+    }
+
+
+def list_bamboo_plans(project, max_results="200"):
+    """List the plans in a Bamboo project.
+
+    ``project`` is a project key (e.g. ``CAASCAASCONNECT``) or a browse URL
+    (``https://ci.e-spirit.de/browse/CAASCAASCONNECT``). Returns one entry per
+    plan (shortName, key, planName, enabled, browse url). To then list a plan's
+    feature-branch builds, feed a plan key into list_bamboo_branch_plans.
+    """
+    key = _bamboo_key_from_ref(project)
+    n = _bamboo_max_results(max_results)
+    data = bamboo_request(
+        f"/rest/api/latest/project/{quote(key)}.json"
+        f"?max-results={n}&expand=plans.plan"
+    )
+    root = data.get("plans") or {}
+    plans = []
+    for p in root.get("plan", []) or []:
+        pkey = p.get("key")
+        plans.append({
+            "shortName": p.get("shortName"),
+            "key": pkey,
+            "planName": p.get("name"),
+            "enabled": p.get("enabled"),
+            "url": f"{BAMBOO_BASE}/browse/{pkey}" if pkey else "",
+        })
+    return {
+        "projectKey": data.get("key") or key,
+        "projectName": data.get("name"),
+        "url": f"{BAMBOO_BASE}/browse/{key}",
+        "planCount": root.get("size", len(plans)),
+        "plans": plans,
+    }
+
+
+def _bamboo_run(x):
+    rkey = x.get("key")
+    return {
+        "buildNumber": x.get("buildNumber"),
+        "key": rkey,
+        "state": x.get("state"),
+        "completed": x.get("buildCompletedTime"),
+        "relativeTime": x.get("buildRelativeTime"),
+        "url": f"{BAMBOO_BASE}/browse/{rkey}" if rkey else "",
+    }
+
+
+def list_bamboo_plan_runs(plan, max_results="25"):
+    """List the retained build results (runs) of a Bamboo plan or branch plan.
+
+    ``plan`` is a plan key (e.g. ``CAASCAASCONNECT-BUILD``), a branch plan key
+    (e.g. ``CAASCAASCONNECT-BUILD502``) or a browse URL. Runs come back
+    newest-first. Bamboo expires old build results, so retainedCount and
+    oldestRetained describe what is still kept, NOT the all-time history;
+    latestBuildNumber is the newest run's number and — because build numbers are
+    monotonic — also the total number of times the plan has ever run.
+    """
+    key = _bamboo_key_from_ref(plan)
+    n = _bamboo_max_results(max_results, default=25)
+    data = bamboo_request(
+        f"/rest/api/latest/result/{quote(key)}.json"
+        f"?max-results={n}&expand=results.result"
+    )
+    root = data.get("results") or {}
+    runs = [_bamboo_run(x) for x in root.get("result", []) or []]
+    size = root.get("size", len(runs))
+    newest = runs[0] if runs else None
+    oldest = runs[-1] if runs else None
+    if size and len(runs) < size:
+        tail = bamboo_request(
+            f"/rest/api/latest/result/{quote(key)}.json"
+            f"?max-results=1&start-index={size - 1}&expand=results.result"
+        )
+        tr = (tail.get("results") or {}).get("result", []) or []
+        if tr:
+            oldest = _bamboo_run(tr[0])
+    return {
+        "planKey": key,
+        "url": f"{BAMBOO_BASE}/browse/{key}",
+        "retainedCount": size,
+        "latestBuildNumber": newest["buildNumber"] if newest else None,
+        "newest": newest,
+        "oldestRetained": oldest,
+        "runs": runs,
+    }
+
+
+def get_bitbucket_pr_changes(project: str, repo: str, pr_id: str) -> dict:
+    """Fetch changed files in a Bitbucket pull request."""
+    data = bitbucket_request(f"projects/{quote(project)}/repos/{quote(repo)}/pull-requests/{quote(pr_id)}/changes")
+    changes = []
+    for value in data.get("values", []):
+        path = value.get("path", {})
+        changes.append({
+            "path":  path.get("toString", path.get("name", "")),
+            "type": value.get("type", "UNKNOWN")
+        })
+    return {
+        "project": project,
+        "repo": repo,
+        "pr_id": pr_id,
+        "changes":  changes
+    }
+
+
+def search_bitbucket_prs(project: str, repo:  str, state: str = "OPEN") -> dict:
+    """Search for pull requests in a Bitbucket repository."""
+    data = bitbucket_request(f"projects/{quote(project)}/repos/{quote(repo)}/pull-requests?state={quote(state)}")
+    prs = []
+    for pr in data.get("values", []):
+        prs.append({
+            "id": pr.get("id"),
+            "title": pr.get("title"),
+            "state": pr.get("state"),
+            "author": pr.get("author", {}).get("user", {}).get("displayName", "Unknown"),
+            "fromRef":  pr.get("fromRef", {}).get("displayId", ""),
+            "toRef": pr. get("toRef", {}).get("displayId", "")
+        })
+    return {"project": project, "repo": repo, "state": state, "pull_requests": prs}
+
+
+def get_commits_for_branch(project: str, repo: str, branch: str, limit: str = "25") -> dict:
+    """Fetch commits for a specific branch."""
+    data = bitbucket_request(
+        f"projects/{quote(project)}/repos/{quote(repo)}/commits?until={quote(branch, safe='')}&limit={quote(limit)}"
+    )
+    commits = []
+    for commit in data.get("values", []):
+        commits.append({
+            "id": commit.get("id"),
+            "displayId": commit.get("displayId"),
+            "message": commit.get("message", "").strip(),
+            "author": commit.get("author", {}).get("name", "Unknown"),
+            "authorEmail": commit.get("author", {}).get("emailAddress", ""),
+            "authorTimestamp": commit.get("authorTimestamp"),
+            "committer": commit.get("committer", {}).get("name", "Unknown"),
+            "committerTimestamp": commit.get("committerTimestamp")
+        })
+    return {"project": project, "repo": repo, "branch": branch, "commits": commits}
+
+
+def get_commit_details(project: str, repo: str, commit_id: str) -> dict:
+    """Fetch details of a specific commit."""
+    data = bitbucket_request(
+        f"projects/{quote(project)}/repos/{quote(repo)}/commits/{quote(commit_id)}"
+    )
+    parents = [{"id": p.get("id"), "displayId": p.get("displayId")} for p in data.get("parents", [])]
+    return {
+        "id": data.get("id"),
+        "displayId": data.get("displayId"),
+        "message": data.get("message", "").strip(),
+        "author": data.get("author", {}).get("name", "Unknown"),
+        "authorEmail": data.get("author", {}).get("emailAddress", ""),
+        "authorTimestamp": data.get("authorTimestamp"),
+        "committer": data.get("committer", {}).get("name", "Unknown"),
+        "committerTimestamp": data.get("committerTimestamp"),
+        "parents": parents
+    }
+
+
+def get_commit_comments(project: str, repo: str, commit_id: str) -> dict:
+    """Fetch comments on a specific commit.
+
+    Bitbucket Server requires fetching the diff with withComments=true to get
+    comment IDs, then fetching each comment individually.
+    """
+    # First, get the diff with comment IDs
+    diff_data = bitbucket_request(
+        f"projects/{quote(project)}/repos/{quote(repo)}/commits/{quote(commit_id)}/diff?withComments=true"
+    )
+
+    # Extract all comment IDs from the diff
+    comment_ids = set()
+    for diff in diff_data.get("diffs", []):
+        for hunk in diff.get("hunks", []):
+            for segment in hunk.get("segments", []):
+                for line in segment.get("lines", []):
+                    for cid in line.get("commentIds", []):
+                        comment_ids.add(cid)
+
+    # Fetch each comment individually
+    comments = []
+    for cid in comment_ids:
+        try:
+            comment = bitbucket_request(
+                f"projects/{quote(project)}/repos/{quote(repo)}/commits/{quote(commit_id)}/comments/{cid}"
+            )
+            comments.append({
+                "id": comment.get("id"),
+                "text": comment.get("text", ""),
+                "author": comment.get("author", {}).get("displayName", "Unknown"),
+                "authorEmail": comment.get("author", {}).get("emailAddress", ""),
+                "createdDate": comment.get("createdDate"),
+                "updatedDate": comment.get("updatedDate"),
+                "state": comment.get("state"),
+                "severity": comment.get("severity"),
+                "threadResolved": comment.get("threadResolved", False)
+            })
+        except Exception:
+            pass  # Skip comments that can't be fetched
+
+    return {"project": project, "repo": repo, "commit_id": commit_id, "comments": comments}
+
+
+def _build_pr_anchor_map(project: str, repo: str, pr_id: str) -> dict:
+    """Build a mapping from comment ID to file/line anchor using the PR diff.
+
+    The activities endpoint does not always include anchor information for
+    inline comments.  The diff endpoint with ``withComments=true`` embeds
+    ``commentIds`` on each line, so we can reliably reconstruct the mapping.
+    """
+    try:
+        diff_data = bitbucket_request(
+            f"projects/{quote(project)}/repos/{quote(repo)}/pull-requests/{quote(pr_id)}/diff?withComments=true"
+        )
+    except Exception:
+        return {}
+
+    anchor_map: dict = {}
+    for diff in diff_data.get("diffs", []):
+        dest_path = (diff.get("destination") or {}).get("toString", "")
+        src_path = (diff.get("source") or {}).get("toString", "")
+        for hunk in diff.get("hunks", []):
+            for segment in hunk.get("segments", []):
+                seg_type = segment.get("type", "")
+                for line in segment.get("lines", []):
+                    for cid in line.get("commentIds", []):
+                        if cid in anchor_map:
+                            continue
+                        if seg_type == "REMOVED":
+                            anchor_map[cid] = {
+                                "path": src_path or dest_path,
+                                "srcPath": src_path if src_path != dest_path else None,
+                                "line": line.get("source"),
+                                "lineType": "REMOVED",
+                                "fileType": "FROM",
+                                "orphaned": False,
+                                "diffType": "EFFECTIVE",
+                            }
+                        else:
+                            anchor_map[cid] = {
+                                "path": dest_path or src_path,
+                                "srcPath": src_path if src_path != dest_path else None,
+                                "line": line.get("destination"),
+                                "lineType": seg_type if seg_type in ("ADDED", "REMOVED") else "CONTEXT",
+                                "fileType": "TO",
+                                "orphaned": False,
+                                "diffType": "EFFECTIVE",
+                            }
+    return anchor_map
+
+
+def get_bitbucket_pr_comments(project: str, repo: str, pr_id: str, limit: str = "25") -> dict:
+    """Fetch comments on a Bitbucket pull request via the activities endpoint."""
+    data = bitbucket_request(
+        f"projects/{quote(project)}/repos/{quote(repo)}/pull-requests/{quote(pr_id)}/activities?limit={quote(limit)}"
+    )
+
+    # Build anchor map from diff as fallback for missing anchors
+    anchor_map = _build_pr_anchor_map(project, repo, pr_id)
+
+    def extract_anchor(anchor):
+        """Extract anchor information from a Bitbucket anchor object."""
+        if not anchor:
+            return None
+        return {
+            "path": anchor.get("path", ""),
+            "srcPath": anchor.get("srcPath"),
+            "line": anchor.get("line"),
+            "lineType": anchor.get("lineType"),
+            "fileType": anchor.get("fileType"),
+            "orphaned": anchor.get("orphaned", False),
+            "diffType": anchor.get("diffType"),
+        }
+
+    def flatten_comment(comment, parent_id=None, inherited_anchor=None):
+        """Recursively flatten a comment and its replies.
+
+        Replies don't carry their own anchor — they inherit it from the
+        root comment of the thread so every entry in the flat list knows
+        which file/line it belongs to.
+        """
+        own_anchor = extract_anchor(comment.get("anchor"))
+        anchor = own_anchor or inherited_anchor
+        entry = {
+            "id": comment.get("id"),
+            "text": comment.get("text", ""),
+            "author": comment.get("author", {}).get("displayName", "Unknown"),
+            "createdDate": comment.get("createdDate"),
+            "updatedDate": comment.get("updatedDate"),
+            "state": comment.get("state"),
+            "severity": comment.get("severity"),
+            "threadResolved": comment.get("threadResolved", False),
+            "parent": parent_id,
+            "anchor": anchor
+        }
+        result = [entry]
+        for reply in comment.get("comments", []):
+            result.extend(flatten_comment(reply, parent_id=comment.get("id"), inherited_anchor=anchor))
+        return result
+
+    comments = []
+    for activity in data.get("values", []):
+        if activity.get("action") == "COMMENTED":
+            comment = activity.get("comment") or {}
+            # Anchor can live on the comment itself, at the activity level
+            # (commentAnchor), or in the diff-based anchor map.
+            root_anchor = (
+                extract_anchor(comment.get("anchor"))
+                or extract_anchor(activity.get("commentAnchor"))
+                or anchor_map.get(comment.get("id"))
+            )
+            comments.extend(flatten_comment(comment, inherited_anchor=root_anchor))
+
+    return {"project": project, "repo": repo, "pr_id": pr_id, "comments": comments}
+
+
+def reply_to_bitbucket_pr_comment(project: str, repo: str, pr_id: str, comment_id: str, text: str) -> dict:
+    """Reply to a comment on a Bitbucket pull request."""
+    prefixed_text = f"**[Claude Code]** {text}"
+    data = bitbucket_request(
+        f"projects/{quote(project)}/repos/{quote(repo)}/pull-requests/{quote(pr_id)}/comments",
+        method="POST",
+        data={"parent": {"id": int(comment_id)}, "text": prefixed_text}
+    )
+    return {
+        "id": data.get("id"),
+        "text": data.get("text", ""),
+        "author": data.get("author", {}).get("displayName", "Unknown"),
+        "createdDate": data.get("createdDate"),
+        "parent": int(comment_id)
+    }
+
+
+def add_bitbucket_pr_comment(
+    project: str,
+    repo: str,
+    pr_id: str,
+    text: str,
+    path: str = "",
+    line: str = "",
+    line_type: str = "ADDED",
+) -> dict:
+    """Post a new top-level or inline comment on a Bitbucket pull request.
+
+    When ``path`` is empty the comment is posted as a general (non-anchored)
+    PR comment. When ``path`` is provided the comment is anchored to that file;
+    if ``line`` is also provided, it is anchored to that specific line.
+
+    ``line_type`` is one of ``ADDED``, ``REMOVED`` or ``CONTEXT`` and defaults
+    to ``ADDED`` (the lineType used by Bitbucket for newly added lines in the
+    to-side of the diff).
+    """
+    prefixed_text = f"**[Claude Code]** {text}"
+    body: dict = {"text": prefixed_text}
+    if path:
+        anchor: dict = {"path": path, "fileType": "TO"}
+        if line:
+            anchor["line"] = int(line)
+            anchor["lineType"] = line_type
+        body["anchor"] = anchor
+    posted = bitbucket_request(
+        f"projects/{quote(project)}/repos/{quote(repo)}/pull-requests/{quote(pr_id)}/comments",
+        method="POST",
+        data=body,
+    )
+    # Bitbucket's POST response omits the anchor field even when anchoring
+    # succeeded. Re-fetch the comment so the returned anchor is authoritative.
+    comment_id = posted.get("id")
+    data = posted
+    if comment_id is not None:
+        try:
+            data = bitbucket_request(
+                f"projects/{quote(project)}/repos/{quote(repo)}/pull-requests/{quote(pr_id)}/comments/{comment_id}"
+            )
+        except Exception:
+            data = posted
+    return {
+        "id": data.get("id"),
+        "text": data.get("text", ""),
+        "author": data.get("author", {}).get("displayName", "Unknown"),
+        "createdDate": data.get("createdDate"),
+        "anchor": data.get("anchor"),
+    }
+
+
+def create_bitbucket_pr(
+    project: str,
+    repo: str,
+    title: str,
+    from_branch: str,
+    to_branch: str = "master",
+    description: str = "",
+    reviewers: str = ""
+) -> dict:
+    """Create a Bitbucket pull request.
+
+    ``from_branch`` and ``to_branch`` are plain branch names (no ``refs/heads/`` prefix).
+    ``reviewers`` is an optional comma-separated list of Bitbucket usernames.
+    """
+    body = {
+        "title": title,
+        "description": description,
+        "fromRef": {
+            "id": f"refs/heads/{from_branch}",
+            "repository": {"slug": repo, "project": {"key": project}},
+        },
+        "toRef": {
+            "id": f"refs/heads/{to_branch}",
+            "repository": {"slug": repo, "project": {"key": project}},
+        },
+    }
+    reviewer_list = [{"user": {"name": r.strip()}} for r in reviewers.split(",") if r.strip()]
+    if reviewer_list:
+        body["reviewers"] = reviewer_list
+
+    data = bitbucket_request(
+        f"projects/{quote(project)}/repos/{quote(repo)}/pull-requests",
+        method="POST",
+        data=body,
+    )
+    return {
+        "id": data.get("id"),
+        "title": data.get("title"),
+        "state": data.get("state"),
+        "fromRef": data.get("fromRef", {}).get("displayId", ""),
+        "toRef": data.get("toRef", {}).get("displayId", ""),
+        "link": data.get("links", {}).get("self", [{}])[0].get("href", ""),
+    }
+
+
+def resolve_bitbucket_pr_comment(project: str, repo: str, pr_id: str, comment_id: str) -> dict:
+    """Resolve a comment thread on a Bitbucket pull request."""
+    comment_endpoint = (
+        f"projects/{quote(project)}/repos/{quote(repo)}/pull-requests/{quote(pr_id)}/comments/{quote(comment_id)}"
+    )
+    # Fetch current comment to get version and text (optimistic locking)
+    current = bitbucket_request(comment_endpoint)
+    data = bitbucket_request(
+        comment_endpoint,
+        method="PUT",
+        data={
+            "text": current.get("text", ""),
+            "version": current.get("version"),
+            "state": "RESOLVED"
+        }
+    )
+    return {
+        "id": data.get("id"),
+        "text": data.get("text", ""),
+        "state": data.get("state"),
+        "threadResolved": data.get("threadResolved", False),
+        "version": data.get("version")
+    }
+
+
+# MCP Protocol handling
+TOOLS = {
+    "get_jira_ticket": {
+        "description": "Fetch details of a Jira ticket (summary, description, comments, status, labels, assignee, priority, issuetype). Also lists attachments with id/filename/size/mimeType so you can selectively download them via download_jira_attachment.",
+        "parameters": {"ticket_id": "Jira ticket ID, e.g. CORE-4711"},
+        "fn": get_ticket
+    },
+    "add_jira_comment": {
+        "description": (
+            "Add a comment to a Jira ticket. Body uses Jira wiki markup "
+            "(h3., *bold*, {{monospace}}, bullets with *, links with [text|url]). "
+            "MANDATORY: before calling this tool you MUST show the full verbatim comment body to the user "
+            "and obtain explicit approval to post it. Never call this tool without that explicit go-ahead — "
+            "not even if the user asked you to 'post a comment' earlier. Posting to Jira is user-visible and "
+            "not easily reversible."
+        ),
+        "parameters": {
+            "ticket_id": "Jira ticket ID, e.g. NAV-399",
+            "body": "Comment body in Jira wiki markup"
+        },
+        "fn": add_jira_comment
+    },
+    "download_jira_attachment": {
+        "description": "Download a single Jira attachment by its ID (from get_jira_ticket attachments list). Saves the file locally and returns the path. For text-based files the content is also returned inline.",
+        "parameters": {"attachment_id": "Attachment ID from the ticket's attachments list"},
+        "fn": download_jira_attachment
+    },
+    "create_jira_ticket": {
+        "description": (
+            "Create a new Jira ticket in the given project. ``description`` uses Jira wiki "
+            "markup. ``labels`` is a comma-separated list. ``parent`` is the key of the parent "
+            "ticket (required when issue_type is 'Sub-task'). "
+            "MANDATORY: before calling this tool you MUST show the user the full verbatim ticket "
+            "fields (project, summary, issue type, description, priority, assignee, labels, "
+            "parent) and obtain explicit approval to create it. Never call this tool without "
+            "that explicit go-ahead — not even if the user asked you to 'create a ticket' "
+            "earlier. Creating a Jira ticket is user-visible and not easily reversible."
+        ),
+        "parameters": {
+            "project_key": "Jira project key, e.g. HP, NAV, CORE",
+            "summary": "Ticket summary / title (one line)",
+            "issue_type": "Issue type name, e.g. Story, Task, Bug, Sub-task. Default: Story",
+            "description": "Optional ticket body in Jira wiki markup",
+            "priority": "Optional priority name, e.g. Highest, High, Medium, Low, Lowest",
+            "assignee": "Optional Jira username to assign",
+            "labels": "Optional comma-separated labels",
+            "parent": "Parent ticket key — required when issue_type is Sub-task"
+        },
+        "optional": ("issue_type", "description", "priority", "assignee", "labels", "parent"),
+        "fn": create_jira_ticket
+    },
+    "update_jira_ticket": {
+        "description": (
+            "Update an existing Jira ticket's description, summary and/or labels. "
+            "description uses Jira wiki markup. add_labels/remove_labels are comma-separated and applied "
+            "additively (existing labels are preserved). At least one of description, summary, add_labels "
+            "or remove_labels must be provided. "
+            "MANDATORY: before calling this tool you MUST show the user the full verbatim changes "
+            "(new description/summary and the exact labels being added or removed) and obtain explicit "
+            "approval to apply them. Never call this tool without that explicit go-ahead — not even if the "
+            "user asked you to 'update the ticket' earlier. Updating a Jira ticket is user-visible and not "
+            "easily reversible."
+        ),
+        "parameters": {
+            "issue_key": "Jira ticket key, e.g. HP-1234",
+            "description": "New ticket description in Jira wiki markup (optional)",
+            "summary": "New ticket title / summary line (optional)",
+            "add_labels": "Optional comma-separated labels to add",
+            "remove_labels": "Optional comma-separated labels to remove",
+        },
+        "optional": ("description", "summary", "add_labels", "remove_labels"),
+        "fn": update_jira_ticket,
+    },
+    "get_jira_transitions": {
+        "description": (
+            "List the workflow transitions currently available on a Jira ticket. Jira only exposes "
+            "transitions reachable from the ticket's current status, so a multi-step move (e.g. "
+            "Triage -> Backlog -> Committed) is walked one transition at a time. Each entry gives the "
+            "transition name and the to_status it lands the ticket in. Use this to discover the valid "
+            "status value to pass to transition_jira_ticket."
+        ),
+        "parameters": {"issue_key": "Jira ticket key, e.g. PX-386"},
+        "fn": get_jira_transitions,
+    },
+    "transition_jira_ticket": {
+        "description": (
+            "Move a Jira ticket to a new status by performing a workflow transition. 'status' is matched "
+            "case-insensitively against the target status (or transition name) of the transitions currently "
+            "available on the ticket. Only ONE step is performed per call; for a multi-step move "
+            "(e.g. Triage -> Backlog -> Committed) call this repeatedly, discovering the next step with "
+            "get_jira_transitions. If no available transition matches, the error lists the transitions that "
+            "ARE available from the current status. "
+            "MANDATORY: before calling this tool you MUST show the user the exact status change "
+            "(from -> to) and obtain explicit approval. Never call this tool without that explicit "
+            "go-ahead — not even if the user asked you to 'move the ticket' earlier. Transitioning a Jira "
+            "ticket is user-visible and not easily reversible."
+        ),
+        "parameters": {
+            "issue_key": "Jira ticket key, e.g. PX-386",
+            "status": "Target status name, e.g. Backlog, Committed, Specify, In Implementation",
+        },
+        "fn": transition_jira_ticket,
+    },
+    "get_jira_link_types": {
+        "description": (
+            "Fetch the issue-link relationship types configured on this Jira "
+            "instance (e.g. Relates, Blocks, 'follows on from'). Each type lists "
+            "its outward and inward phrases. Use this to discover the valid "
+            "relationship phrases to pass to link_jira_issues."
+        ),
+        "parameters": {},
+        "fn": get_jira_link_types,
+    },
+    "link_jira_issues": {
+        "description": (
+            "Create a directional link between two Jira tickets using a natural "
+            "relationship phrase. The link reads from_issue <relationship> "
+            "to_issue (e.g. from_issue='HP-1', to_issue='HP-2', "
+            "relationship='blocks' means HP-1 blocks HP-2). 'relationship' is a "
+            "phrase like 'blocks', 'is blocked by', 'relates to' or 'follows on "
+            "from' — discover valid phrases with get_jira_link_types. "
+            "MANDATORY: before calling this tool you MUST show the user the exact "
+            "link to be created (from_issue, relationship, to_issue) and obtain "
+            "explicit approval to create it. Never call this tool without that "
+            "explicit go-ahead — not even if the user asked you to 'link the "
+            "tickets' earlier. Creating a Jira link is user-visible and not "
+            "easily reversible."
+        ),
+        "parameters": {
+            "from_issue": "Jira ticket key the relationship starts from, e.g. HP-1234",
+            "to_issue": "Jira ticket key the relationship points to, e.g. HP-5678",
+            "relationship": "Relationship phrase, e.g. 'blocks', 'is blocked by', 'relates to', 'follows on from'",
+        },
+        "fn": link_jira_issues,
+    },
+    "get_bitbucket_pr": {
+        "description":  "Fetch details of a Bitbucket pull request",
+        "parameters": {
+            "project": "Bitbucket project key, e.g. CXT",
+            "repo": "Repository slug, e.g. cxt-mixpanel-analytics-module",
+            "pr_id":  "Pull request ID number"
+        },
+        "fn":  get_bitbucket_pr
+    },
+    "get_bitbucket_pr_changes": {
+        "description": "Fetch the list of changed files in a Bitbucket pull request",
+        "parameters": {
+            "project": "Bitbucket project key, e.g. CXT",
+            "repo": "Repository slug, e.g. cxt-mixpanel-analytics-module",
+            "pr_id": "Pull request ID number"
+        },
+        "fn": get_bitbucket_pr_changes
+    },
+    "search_bitbucket_prs": {
+        "description": "Search for pull requests in a Bitbucket repository",
+        "parameters": {
+            "project": "Bitbucket project key, e.g. CXT",
+            "repo": "Repository slug, e.g. cxt-mixpanel-analytics-module",
+            "state": "PR state:  OPEN, MERGED, DECLINED, or ALL (default: OPEN)"
+        },
+        "fn": search_bitbucket_prs
+    },
+    "get_commits_for_branch": {
+        "description": "Fetch commits for a specific branch in a Bitbucket repository",
+        "parameters": {
+            "project": "Bitbucket project key, e.g. CXT",
+            "repo": "Repository slug, e.g. cxt-mixpanel-analytics-module",
+            "branch": "Branch name, e.g. feature/my-branch or master",
+            "limit": "Maximum number of commits to return (default: 25)"
+        },
+        "fn": get_commits_for_branch
+    },
+    "get_commit_details": {
+        "description": "Fetch details of a specific commit in a Bitbucket repository",
+        "parameters": {
+            "project": "Bitbucket project key, e.g. CXT",
+            "repo": "Repository slug, e.g. cxt-mixpanel-analytics-module",
+            "commit_id": "Commit SHA (full or abbreviated)"
+        },
+        "fn": get_commit_details
+    },
+    "get_commit_comments": {
+        "description": "Fetch comments on a specific commit in a Bitbucket repository",
+        "parameters": {
+            "project": "Bitbucket project key, e.g. CXT",
+            "repo": "Repository slug, e.g. cxt-mixpanel-analytics-module",
+            "commit_id": "Commit SHA (full or abbreviated)"
+        },
+        "fn": get_commit_comments
+    },
+    "get_bitbucket_pr_comments": {
+        "description": "Fetch comments on a Bitbucket pull request (general and inline comments with thread structure)",
+        "parameters": {
+            "project": "Bitbucket project key, e.g. CXT",
+            "repo": "Repository slug, e.g. cxt-mixpanel-analytics-module",
+            "pr_id": "Pull request ID number",
+            "limit": "Maximum number of activities to return (default: 25)"
+        },
+        "fn": get_bitbucket_pr_comments
+    },
+    "reply_to_bitbucket_pr_comment": {
+        "description": "Reply to a comment on a Bitbucket pull request. The reply is automatically prefixed with **[Claude Code]**",
+        "parameters": {
+            "project": "Bitbucket project key, e.g. CXT",
+            "repo": "Repository slug, e.g. cxt-mixpanel-analytics-module",
+            "pr_id": "Pull request ID number",
+            "comment_id": "ID of the comment to reply to",
+            "text": "The reply text (will be prefixed with **[Claude Code]** automatically)"
+        },
+        "fn": reply_to_bitbucket_pr_comment
+    },
+    "add_bitbucket_pr_comment": {
+        "description": (
+            "Post a new comment on a Bitbucket pull request — either a general top-level "
+            "comment (omit path/line) or an inline comment anchored to a file (path) or a "
+            "specific line of a file (path + line). The comment body is automatically prefixed "
+            "with **[Claude Code]**. Use this for new review remarks; use "
+            "reply_to_bitbucket_pr_comment to continue an existing thread. "
+            "MANDATORY: before calling this tool you MUST show the full verbatim comment body "
+            "to the user and obtain explicit approval to post it. Never call this tool without "
+            "that explicit go-ahead — not even if the user asked you to 'post a comment' "
+            "earlier. Posting to Bitbucket is user-visible and not easily reversible."
+        ),
+        "parameters": {
+            "project": "Bitbucket project key, e.g. CXT",
+            "repo": "Repository slug, e.g. cxt-mixpanel-analytics-module",
+            "pr_id": "Pull request ID number",
+            "text": "The comment body (will be prefixed with **[Claude Code]** automatically)",
+            "path": "Optional file path to anchor the comment to (e.g. src/foo/Bar.kt). Omit for a general PR comment.",
+            "line": "Optional line number within path for an inline comment. Requires path.",
+            "line_type": "Optional line type for anchoring: ADDED, REMOVED or CONTEXT. Default ADDED."
+        },
+        "optional": ("path", "line", "line_type"),
+        "fn": add_bitbucket_pr_comment
+    },
+    "resolve_bitbucket_pr_comment": {
+        "description": "Resolve a comment thread on a Bitbucket pull request",
+        "parameters": {
+            "project": "Bitbucket project key, e.g. CXT",
+            "repo": "Repository slug, e.g. cxt-mixpanel-analytics-module",
+            "pr_id": "Pull request ID number",
+            "comment_id": "ID of the root comment of the thread to resolve"
+        },
+        "fn": resolve_bitbucket_pr_comment
+    },
+    "create_bitbucket_pr": {
+        "description": "Create a Bitbucket pull request from a source branch into a target branch",
+        "parameters": {
+            "project": "Bitbucket project key, e.g. NAV",
+            "repo": "Repository slug, e.g. navigation-service-deployment",
+            "title": "PR title",
+            "from_branch": "Source branch name without refs/heads/ prefix, e.g. issue/NAV-399",
+            "to_branch": "Target branch name without refs/heads/ prefix (default: master)",
+            "description": "PR description, markdown supported (default: empty)",
+            "reviewers": "Comma-separated Bitbucket usernames to add as reviewers (optional)"
+        },
+        "optional": ("to_branch", "description", "reviewers"),
+        "fn": create_bitbucket_pr
+    },
+    "get_jira_dev_info": {
+        "description": (
+            "Fetch the Jira Development-panel data for a ticket — the linked "
+            "Bitbucket pull requests, branches, commits, or repositories that "
+            "do NOT appear via get_jira_ticket (different API). Use this as the "
+            "first step when asked about a ticket's PRs/builds: each returned "
+            "item carries `repository.project` + `slug` + `id`, ready to pass "
+            "into get_bitbucket_pr. Then take the PR's `fromCommit` and call "
+            "get_bitbucket_commit_build_status to see if CI is green."
+        ),
+        "parameters": {
+            "ticket_id": "Jira ticket key, e.g. HP-1615",
+            "data_type": "One of: pullrequest (default), branch, commit, repository"
+        },
+        "optional": ("data_type",),
+        "fn": get_jira_dev_info
+    },
+    "get_bitbucket_commit_build_status": {
+        "description": (
+            "Fetch CI build statuses (Bamboo etc.) posted to a commit. Returns "
+            "raw statuses plus an aggregateState in {GREEN, RED, RUNNING, "
+            "MIXED, NONE}. Feed a PR's fromCommit here. For any non-GREEN "
+            "result, parse the build key out of the returned status URL "
+            "(e.g. /browse/HAUPIA-HAUPIATESTMETRICS36-8) and pass it to "
+            "get_bamboo_build for failure details."
+        ),
+        "parameters": {
+            "commit_id": "Full commit SHA (40-char hex). Project/repo not needed — Bitbucket resolves SHAs globally."
+        },
+        "fn": get_bitbucket_commit_build_status
+    },
+    "get_bamboo_build": {
+        "description": (
+            "Fetch a Bamboo build (chain or job) with per-job results AND "
+            "failed-test details in one call. Empty failedTests when green. "
+            "Use when get_bitbucket_commit_build_status returns RED/MIXED. If "
+            "a specific job failed and you need more than the test errors "
+            "(e.g. Gradle output, artifact errors), call get_bamboo_build_log "
+            "with that job's key and build number."
+        ),
+        "parameters": {
+            "build_key": "Bamboo build result key, e.g. HAUPIA-HAUPIATESTMETRICS36-8 (chain) or HAUPIA-HAUPIATESTMETRICS36-CC-1 (job)"
+        },
+        "fn": get_bamboo_build
+    },
+    "get_bamboo_build_log": {
+        "description": (
+            "Fetch the build log for a specific Bamboo job. Returns the last "
+            "tail_lines lines (default 200, max 2000), optionally filtered by "
+            "a regex (grep), plus the full log saved to a temp file at "
+            "localPath so you can Read more if needed. job_key is the job-"
+            "level key (e.g. HAUPIA-HAUPIATESTMETRICS36-CC), NOT the chain key."
+        ),
+        "parameters": {
+            "job_key": "Bamboo job key, e.g. HAUPIA-HAUPIATESTMETRICS36-CC",
+            "build_number": "Build number, e.g. 8",
+            "tail_lines": "Number of trailing lines to include (default 200, clamped to 1-2000)",
+            "grep": "Optional regex; if set, only matching lines are kept before tailing"
+        },
+        "optional": ("tail_lines", "grep"),
+        "fn": get_bamboo_build_log
+    },
+    "list_bamboo_artifacts": {
+        "description": (
+            "List a Bamboo build's published artifacts, expanding directory "
+            "artifacts into their files. Accepts a chain key (e.g. PLAN-21) or "
+            "job key (PLAN-BUILD-21) — artifacts attach to jobs, so chain keys "
+            "are walked across all jobs. Each artifact reports isDirectory and, "
+            "for directories, a files[] list of {name (relative path), path "
+            "(download URL)}. Feed a file's artifact name + relative name into "
+            "get_bamboo_artifact to download it. Use after get_bamboo_build to "
+            "grab reports (e.g. the OWASP dependency-check HTML)."
+        ),
+        "parameters": {
+            "build_key": "Bamboo build key — chain (PLAN-21) or job (PLAN-BUILD-21)",
+            "max_files": "Max files to collect from directory artifacts (default 200, clamped 1-2000)"
+        },
+        "optional": ("max_files",),
+        "fn": list_bamboo_artifacts
+    },
+    "get_bamboo_artifact": {
+        "description": (
+            "Download one Bamboo artifact file, save it to a temp file "
+            "(localPath), and inline its text content when small. Provide href "
+            "for a direct download, or name to resolve via list_bamboo_artifacts; "
+            "for a directory artifact pass file to pick the contained file "
+            "(relative name or suffix). Text under max_inline_bytes is returned "
+            "in content; larger or binary files return content=null with a note "
+            "— Read localPath then. Large HTML reports (e.g. dependency-check) "
+            "come back as localPath; grep that file for findings."
+        ),
+        "parameters": {
+            "build_key": "Bamboo build key (chain or job)",
+            "name": "Artifact name to resolve (case-insensitive), e.g. 'owasp dependency check report'",
+            "href": "Direct artifact download URL (from list_bamboo_artifacts); alternative to name",
+            "file": "For directory artifacts: contained file's relative path or suffix, e.g. 'dependency-check-report.html'",
+            "max_inline_bytes": "Inline text size cap (default 262144, clamped 0-5000000)"
+        },
+        "optional": ("name", "href", "file", "max_inline_bytes"),
+        "fn": get_bamboo_artifact
+    },
+    "list_bamboo_plans": {
+        "description": (
+            "List the plans in a Bamboo project. Accepts a project key "
+            "(e.g. CAASCAASCONNECT) or a browse URL "
+            "(https://ci.e-spirit.de/browse/CAASCAASCONNECT). Each entry gives "
+            "the plan key, name, enabled flag and browse url. Feed a returned "
+            "plan key into list_bamboo_branch_plans to list its feature-branch "
+            "builds."
+        ),
+        "parameters": {
+            "project": "Bamboo project key or browse URL, e.g. CAASCAASCONNECT",
+            "max_results": "Max plans to return (default 200, clamped 1-2000)",
+        },
+        "optional": ("max_results",),
+        "fn": list_bamboo_plans,
+    },
+    "list_bamboo_branch_plans": {
+        "description": (
+            "List the branch plans of a Bamboo plan. Accepts a plan key "
+            "(e.g. CAASCAASCONNECT-BUILD) or a browse URL "
+            "(https://ci.e-spirit.de/browse/CAASCAASCONNECT-BUILD). Each entry "
+            "gives shortName (the git branch), key (the branch plan's build "
+            "key, e.g. CAASCAASCONNECT-BUILD502), enabled flag and browse url. "
+            "Empty branchPlans means the plan builds master only. Use "
+            "list_bamboo_plans first if you only have a project key."
+        ),
+        "parameters": {
+            "plan": "Bamboo plan key or browse URL, e.g. CAASCAASCONNECT-BUILD",
+            "max_results": "Max branch plans to return (default 200, clamped 1-2000)",
+        },
+        "optional": ("max_results",),
+        "fn": list_bamboo_branch_plans,
+    },
+    "list_bamboo_plan_runs": {
+        "description": (
+            "List the retained build results (runs) of a Bamboo plan or branch "
+            "plan, newest-first. Accepts a plan key (CAASCAASCONNECT-BUILD), a "
+            "branch plan key (CAASCAASCONNECT-BUILD502) or a browse URL. Returns "
+            "newest and oldestRetained runs (buildNumber, key, state, completed "
+            "time), retainedCount and latestBuildNumber. NOTE: Bamboo expires "
+            "old results, so oldestRetained/retainedCount reflect what is still "
+            "kept, not the full history; latestBuildNumber is the total times "
+            "the plan has ever run (build numbers are monotonic)."
+        ),
+        "parameters": {
+            "plan": "Bamboo plan/branch-plan key or browse URL, e.g. CAASCAASCONNECT-BUILD",
+            "max_results": "Max runs to list (default 25, clamped 1-2000)",
+        },
+        "optional": ("max_results",),
+        "fn": list_bamboo_plan_runs,
+    }
+}
+
+
+def handle_request(req):
+    """Handle MCP JSON-RPC requests."""
+    method = req.get("method")
+
+    if method == "initialize": 
+        return {
+            "protocolVersion": "2024-11-05",
+            "serverInfo": {
+                "name": "jira-tools",
+                "version": "1.0.0"
+            },
+            "capabilities": {
+                "tools": {}
+            }
+        }
+
+    if method == "notifications/initialized": 
+        return None
+
+    if method == "tools/list":
+        return {"tools": [
+            {
+                "name": name,
+                "description": t["description"],
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {k: {"type": "string", "description": v} for k, v in t["parameters"].items()},
+                    "required": [
+                        k for k in t["parameters"].keys()
+                        if k not in ("state", "limit") and k not in t.get("optional", ())
+                    ]
+                }
+            } for name, t in TOOLS.items()
+        ]}
+
+    if method == "tools/call":
+        tool_name = req["params"]["name"]
+        args = req["params"]["arguments"]
+        try:
+            result = TOOLS[tool_name]["fn"](**args)
+            return {"content": [{"type": "text", "text": json.dumps(result, indent=2)}]}
+        except Exception as e:
+            error_detail = {
+                "error": str(e),
+                "tool": tool_name,
+                "hint": "Check environment variables (JIRA_BASE_URL, JIRA_TOKEN, BITBUCKET_BASE_URL, BITBUCKET_TOKEN). Do NOT retry via WebFetch — the URL requires authentication headers."
+            }
+            return {"content": [{"type": "text", "text": json.dumps(error_detail, indent=2)}], "isError": True}
+
+    return {"error": {"code": -32601, "message": f"Unknown method: {method}"}}
+
+
+def main():
+    """Main entry point for MCP server."""
+    for line in sys.stdin:
+        req = json.loads(line)
+        result = handle_request(req)
+
+        # Notifications don't get responses
+        if result is None: 
+            continue
+
+        resp = {"jsonrpc": "2.0", "id": req. get("id")}
+        if "error" in result and "code" in result. get("error", {}):
+            resp["error"] = result["error"]
+        else:
+            resp["result"] = result
+        print(json.dumps(resp), flush=True)
+
+
+if __name__ == "__main__":
+    main()