Skip to main content
Glama
mungowang

jira-mcp

by mungowang
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

download_attachment

Read-only

Download a Jira attachment to a local file using its attachment ID or the exact URL from list_attachments, with an HTML-page guard unless allowHtml is true.

Instructions

Download the content of an attachment to a local file (GET /rest/tests/1.0/attachment/{id}). Address it by attachmentId or by the exact url list_attachments returns — pass exactly one of the two. Attachment content lives outside API v1: /rest/tests/1.0/attachment/{id} is the url the official list endpoint itself hands out, so this tool follows it without requiring ZEPHYR_ALLOW_INTERNAL_API. A supplied url must be on the configured Jira host — credentials are never sent to another host. A query string on the url is sent as request parameters rather than kept in the path, so it is never echoed in an error message (error messages carry the method and the path only, because a query string can carry a token). outputPath is written on the machine running this MCP server and its parent directory must already exist; a failed download writes nothing. Jira answers a url that is not attachment content (a login redirect, an unknown path) with HTTP 200 and an HTML PAGE, so a response whose body starts with or is refused and nothing is written — { savedTo, bytes } therefore means the bytes really came from the attachment endpoint. The refusal names the page it caught (its , or the page's first readable text when it has none) so a login redirect, an error page and a wrong host can be told apart. Set allowHtml: true for an attachment that genuinely is an HTML file. Markup that is not a page (XML, SVG) is never affected. Returns { savedTo, bytes }.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
urlNoExact download url as returned by list_attachments; must be on the configured Jira host. Mutually exclusive with attachmentId.
allowHtmlNoSave the response even when it is an HTML page (default false). Only for an attachment that really is an HTML file — it disables the guard against saving a Jira login or error page as attachment content.
outputPathYesLocal path to write the file to, on the machine running this MCP server (the parent directory must exist)
attachmentIdNoNumeric attachment id, as returned by list_attachments or by an upload_attachment response; mutually exclusive with url

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.5

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes far beyond the single readOnlyHint annotation: it discloses that outputPath is written on the MCP host, that the parent directory must pre-exist, that a failed download writes nothing, that credentials are never sent to another host, that query strings are moved out of the path so they never leak into errors, and that HTML responses are refused unless allowHtml is set. This is exactly the kind of side-effect and safety context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Long, but almost every sentence carries security or safety information not available elsewhere, and the core purpose is front-loaded in the first clause. Slightly dense, though nothing is padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description still explains the return value ({ savedTo, bytes }) and the guarantee it carries, plus the HTML-refusal behavior and error-message shape. An agent has everything needed to call it correctly and interpret the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the mutual exclusivity of url/attachmentId, the constraint that url must be on the configured Jira host, the exact semantics of allowHtml as disabling the page guard, and the parent-directory requirement for outputPath.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ("Download the content of an attachment to a local file") and even names the REST endpoint. An agent can immediately distinguish it from list_attachments, upload_attachment, and delete_attachment among the siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear usage context: address the attachment by attachmentId or by the exact url list_attachments returns, and pass exactly one of the two. It also routes the agent to list_attachments as the source of a valid url and explains when to set allowHtml. It does not explicitly name alternative download strategies, but the selection guidance is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools