backlog-mcp-server 0.18.1 → 0.19.0

package/README.md

@@ -294,6 +294,7 @@ Tools for managing projects, categories, custom fields, and issue types.
 Tools for managing issues, their comments, and related items like priorities, categories, custom fields, issue types, resolutions, and watching lists.
 
 - `get_issue`: Returns information about a specific issue.
+- `get_issue_attachment`: Downloads one attachment of an issue. Returns it as image or embedded resource content, or as base64 with `format: "base64"`.
 - `get_issues`: Returns list of issues.
 - `count_issues`: Returns count of issues.
 - `add_issue`: Creates a new issue in the specified project.

package/build/handlers/builders/composeDynamicToolHandler.d.ts

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+import { ErrorLike } from '../../types/result.js';
+import { DynamicToolDefinition } from '../../types/tool.js';
+export type ComposeDynamicOptions = {
+    errorHandler?: (err: unknown) => ErrorLike;
+    useOrganization?: boolean;
+};
+type DynamicInput = {
+    organization?: string;
+} & Record<string, unknown>;
+/**
+ * Builds the schema and handler a dynamic tool is registered with.
+ *
+ * The counterpart of `composeToolHandler` for tools that produce a
+ * `CallToolResult` themselves. Those cannot go through the whole pipeline:
+ * field picking, the token limit and `wrapWithToolResult` all assume a JSON
+ * value they may reshape, and reshaping is exactly what a tool returning binary
+ * content must not allow — a base64 payload cut at the token limit is a corrupt
+ * file reported as a success.
+ *
+ * The two steps that are not about reshaping still apply, and are why this
+ * exists rather than registering the handler directly:
+ *
+ * - `wrapWithOrganizationContext`, without which a dynamic tool ignores
+ *   `organization` and always talks to the default space;
+ * - `wrapWithErrorHandling`, without which a thrown Backlog error escapes as a
+ *   protocol error rather than an `isError` result, and never reaches the
+ *   handler that reacts to Backlog rejecting a credential.
+ *
+ * As in `composeToolHandler`, the returned schema is a fresh object: the tool
+ * definition is never mutated, because one toolset group is shared across
+ * per-request servers.
+ */
+export declare function composeDynamicToolHandler(tool: DynamicToolDefinition<any>, { errorHandler, useOrganization }?: ComposeDynamicOptions): {
+    schema: z.ZodObject<{
+        [x: string]: any;
+        organization: z.ZodOptional<z.ZodString>;
+    } | {
+        [x: string]: any;
+        organization?: undefined;
+    }, z.core.$strip>;
+    handler: (input: DynamicInput) => Promise<{
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            "io.modelcontextprotocol/serverInfo"?: {
+                version: string;
+                websiteUrl?: string | undefined;
+                description?: string | undefined;
+                icons?: {
+                    src: string;
+                    mimeType?: string | undefined;
+                    sizes?: string[] | undefined;
+                    theme?: "dark" | "light" | undefined;
+                }[] | undefined;
+                name: string;
+                title?: string | undefined;
+            } | undefined;
+        } | undefined;
+        content: ({
+            type: "text";
+            text: string;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            type: "image";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            type: "audio";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            uri: string;
+            description?: string | undefined;
+            mimeType?: string | undefined;
+            size?: number | undefined;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "dark" | "light" | undefined;
+            }[] | undefined;
+            name: string;
+            title?: string | undefined;
+            type: "resource_link";
+        } | {
+            type: "resource";
+            resource: {
+                uri: string;
+                mimeType?: string | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+                text: string;
+            } | {
+                uri: string;
+                mimeType?: string | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+                blob: string;
+            };
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        })[];
+        structuredContent?: unknown;
+        isError?: boolean | undefined;
+    }>;
+};
+export {};

package/build/handlers/builders/composeDynamicToolHandler.js

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import { wrapWithErrorHandling } from '../transformers/wrapWithErrorHandling.js';
+import { wrapWithOrganizationContext } from '../transformers/wrapWithOrganizationContext.js';
+import { isErrorLike } from '../../types/result.js';
+/**
+ * Builds the schema and handler a dynamic tool is registered with.
+ *
+ * The counterpart of `composeToolHandler` for tools that produce a
+ * `CallToolResult` themselves. Those cannot go through the whole pipeline:
+ * field picking, the token limit and `wrapWithToolResult` all assume a JSON
+ * value they may reshape, and reshaping is exactly what a tool returning binary
+ * content must not allow — a base64 payload cut at the token limit is a corrupt
+ * file reported as a success.
+ *
+ * The two steps that are not about reshaping still apply, and are why this
+ * exists rather than registering the handler directly:
+ *
+ * - `wrapWithOrganizationContext`, without which a dynamic tool ignores
+ *   `organization` and always talks to the default space;
+ * - `wrapWithErrorHandling`, without which a thrown Backlog error escapes as a
+ *   protocol error rather than an `isError` result, and never reaches the
+ *   handler that reacts to Backlog rejecting a credential.
+ *
+ * As in `composeToolHandler`, the returned schema is a fresh object: the tool
+ * definition is never mutated, because one toolset group is shared across
+ * per-request servers.
+ */
+export function composeDynamicToolHandler(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+tool, { errorHandler, useOrganization = false } = {}) {
+    // `extend` even with nothing to add, so the returned schema is always a copy.
+    // Handing back `tool.schema` itself would make the invariant above hold only
+    // when `useOrganization` is set.
+    const schema = tool.schema.extend(useOrganization
+        ? {
+            organization: z
+                .string()
+                .optional()
+                .describe('Optional organization name. Use list_organizations to inspect available organizations.'),
+        }
+        : {});
+    const handler = wrapWithErrorHandling(wrapWithOrganizationContext(tool.handler), errorHandler);
+    return {
+        schema,
+        handler: async (input) => {
+            const result = await handler(input);
+            return isErrorLike(result)
+                ? {
+                    isError: true,
+                    content: [{ type: 'text', text: result.message }],
+                }
+                : result.data;
+        },
+    };
+}

package/build/lib.d.ts

@@ -14,11 +14,13 @@
  */
 export { allTools } from './tools/tools.js';
 export { composeToolHandler } from './handlers/builders/composeToolHandler.js';
+export { composeDynamicToolHandler } from './handlers/builders/composeDynamicToolHandler.js';
 export { createDescriptionHelper } from './createDescriptionHelper.js';
 export { backlogErrorHandler } from './backlog/backlogErrorHandler.js';
 export { buildToolSchema } from './types/tool.js';
 export { isErrorLike } from './types/result.js';
 export type { ComposeOptions } from './handlers/builders/composeToolHandler.js';
+export type { ComposeDynamicOptions } from './handlers/builders/composeDynamicToolHandler.js';
 export type { DescriptionHelper } from './createDescriptionHelper.js';
 export type { ToolDefinition, DynamicToolDefinition } from './types/tool.js';
 export type { Toolset, ToolsetGroup, DynamicToolset, DynamicToolsetGroup, } from './types/toolsets.js';

package/build/lib.js

@@ -14,6 +14,7 @@
  */
 export { allTools } from './tools/tools.js';
 export { composeToolHandler } from './handlers/builders/composeToolHandler.js';
+export { composeDynamicToolHandler } from './handlers/builders/composeDynamicToolHandler.js';
 export { createDescriptionHelper } from './createDescriptionHelper.js';
 export { backlogErrorHandler } from './backlog/backlogErrorHandler.js';
 export { buildToolSchema } from './types/tool.js';

package/build/registerTools.js

@@ -1,4 +1,5 @@
 import { backlogErrorHandler } from './backlog/backlogErrorHandler.js';
+import { composeDynamicToolHandler } from './handlers/builders/composeDynamicToolHandler.js';
 import { composeToolHandler } from './handlers/builders/composeToolHandler.js';
 export function registerTools(server, toolsetGroup, options) {
     const { useFields, maxTokens, prefix, useOrganization } = options;
@@ -15,6 +16,23 @@ export function registerTools(server, toolsetGroup, options) {
             useOrganization,
         }),
     });
+    // Tools that build their own result, registered from the same toolsets so
+    // that `--enable-toolsets` and the prefix cover them too.
+    registerToolsets({
+        server,
+        toolsetGroup: {
+            toolsets: toolsetGroup.toolsets.map((toolset) => ({
+                name: toolset.name,
+                description: toolset.description,
+                enabled: toolset.enabled,
+                tools: toolset.dynamicTools ?? [],
+            })),
+        },
+        prefix,
+        prepareTool: (tool) => composeDynamicToolHandler(
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        tool, { errorHandler: backlogErrorHandler, useOrganization }),
+    });
 }
 export function registerDynamicTools(server, dynamicToolsetGroup, prefix) {
     registerToolsets({

package/build/tools/addDocument.js

@@ -46,6 +46,7 @@ export const addDocumentTool = (backlog, { t }) => {
             'created',
             'updatedUser',
             'updated',
+            'childDocumentIds',
         ]),
         importantFields: ['id', 'projectId', 'title', 'plain', 'createdUser'],
         handler: async (params) => {

package/build/tools/getDocument.js

@@ -26,6 +26,7 @@ export const getDocumentTool = (backlog, { t }) => {
             'created',
             'updatedUser',
             'updated',
+            'childDocumentIds',
         ]),
         importantFields: ['id', 'title', 'createdUser'],
         handler: async ({ documentId }) => {

package/build/tools/getDocuments.js

@@ -31,6 +31,7 @@ export const getDocumentsTool = (backlog, { t }) => {
             'created',
             'updatedUser',
             'updated',
+            'childDocumentIds',
         ]),
         importantFields: ['id', 'projectId', 'title', 'plain'],
         handler: async ({ projectIds, offset }) => {

package/build/tools/getIssueAttachment.d.ts

@@ -0,0 +1,16 @@
+import { Backlog } from 'backlog-js';
+import { z } from 'zod';
+import { DescriptionHelper } from '../createDescriptionHelper.js';
+import { DynamicToolDefinition } from '../types/tool.js';
+declare const getIssueAttachmentSchema: (t: DescriptionHelper['t']) => {
+    issueId: z.ZodOptional<z.ZodNumber>;
+    issueKey: z.ZodOptional<z.ZodString>;
+    attachmentId: z.ZodNumber;
+    format: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        base64: "base64";
+    }>>;
+    maxBytes: z.ZodOptional<z.ZodNumber>;
+};
+export declare const getIssueAttachmentTool: (backlog: Backlog, { t }: DescriptionHelper) => DynamicToolDefinition<ReturnType<typeof getIssueAttachmentSchema>>;
+export {};

package/build/tools/getIssueAttachment.js

@@ -0,0 +1,345 @@
+import { z } from 'zod';
+import { buildToolSchema } from '../types/tool.js';
+import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
+const MEBIBYTE = 1024 * 1024;
+/**
+ * Both limits are about what survives the transport, not about what Backlog
+ * allows. Base64 inflates by 4/3, and the MCP SDK caps a single stdio message
+ * at 10 MiB by default, so 7 MiB of raw bytes is the point beyond which a
+ * successful download would still fail to reach the client.
+ */
+const DEFAULT_MAX_BYTES = 5 * MEBIBYTE;
+const MAX_ATTACHMENT_BYTES = 7 * MEBIBYTE;
+/**
+ * The raster types this tool returns as MCP `image` content.
+ *
+ * Narrower than the raster types Backlog serves, and the limit
+ * does not come from MCP — `ImageContent.mimeType` is an unconstrained string
+ * in the schema. It comes from the far end: a Claude-backed host forwards the
+ * block to the Messages API, which documents support for `image/jpeg`,
+ * `image/png`, `image/gif` and `image/webp` and nothing else
+ * (https://platform.claude.com/docs/en/build-with-claude/vision). An
+ * `image/bmp` block is rejected there, and a rejected block costs the caller
+ * the metadata as well as the file rather than merely failing to draw.
+ *
+ * These four are therefore what is safe to inline. A host backed by something
+ * other than Claude may well accept more; nothing here asserts otherwise, it
+ * just does not rely on it.
+ *
+ * `image/svg+xml` is absent for an unrelated reason — an SVG can carry script,
+ * and it is text, so it goes down the text path below where it can be read
+ * rather than executed.
+ *
+ * Anything not here is returned as an embedded resource, which every client
+ * can hold.
+ */
+const INLINE_IMAGE_TYPES = new Set([
+    'image/gif',
+    'image/jpeg',
+    'image/png',
+    'image/webp',
+]);
+/**
+ * Types whose bytes are meant to be read rather than rendered.
+ *
+ * These are returned as `resource.text`. Handing a caller base64 of a CSV is
+ * the same as handing it nothing: the point of fetching a log or a spreadsheet
+ * is the content, and base64 has to be decoded by something that can already
+ * read the file.
+ */
+const TEXT_TYPES = new Set([
+    'application/json',
+    'application/xml',
+    'image/svg+xml',
+    'text/csv',
+    'text/html',
+    'text/plain',
+]);
+const getIssueAttachmentSchema = buildToolSchema((t) => ({
+    issueId: z
+        .number()
+        .int()
+        .optional()
+        .describe(t('TOOL_GET_ISSUE_ATTACHMENT_ISSUE_ID', 'The numeric ID of the issue (e.g., 12345)')),
+    issueKey: z
+        .string()
+        .optional()
+        .describe(t('TOOL_GET_ISSUE_ATTACHMENT_ISSUE_KEY', "The key of the issue (e.g., 'PROJ-123')")),
+    attachmentId: z
+        .number()
+        .int()
+        .positive()
+        .describe(t('TOOL_GET_ISSUE_ATTACHMENT_ATTACHMENT_ID', "The numeric ID of the attachment. Get it from get_issue (the issue's `attachments` array).")),
+    format: z
+        .enum(['auto', 'base64'])
+        .optional()
+        .describe(t('TOOL_GET_ISSUE_ATTACHMENT_FORMAT', "How to return the file. 'auto' (default) returns a verified raster image as MCP image content and anything else as an embedded resource, so a client can render it. 'base64' returns a single JSON object with the encoded bytes in `content`, for callers that process the file programmatically — note that this puts the whole encoding in the caller's context.")),
+    maxBytes: z
+        .number()
+        .int()
+        .positive()
+        .max(MAX_ATTACHMENT_BYTES)
+        .optional()
+        .describe(t('TOOL_GET_ISSUE_ATTACHMENT_MAX_BYTES', `Maximum raw attachment size in bytes. Defaults to ${DEFAULT_MAX_BYTES} and cannot exceed ${MAX_ATTACHMENT_BYTES}.`)),
+}));
+function isReadableByteStream(body) {
+    return (typeof body === 'object' &&
+        body !== null &&
+        'getReader' in body &&
+        typeof body.getReader === 'function');
+}
+/**
+ * Reads the whole body, refusing to buffer more than `maxBytes`.
+ *
+ * The limit is checked per chunk rather than against a `Content-Length`:
+ * `backlog-js` does not surface response headers, and a header would be the
+ * server's claim rather than what actually arrived.
+ */
+async function readBody(body, maxBytes) {
+    if (!isReadableByteStream(body)) {
+        throw new Error('Backlog returned an unsupported attachment body.');
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let size = 0;
+    let finished = false;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                finished = true;
+                break;
+            }
+            if (!(value instanceof Uint8Array)) {
+                throw new Error('Backlog returned a non-binary attachment chunk.');
+            }
+            size += value.byteLength;
+            if (size > maxBytes) {
+                throw new Error(`Attachment exceeds the ${maxBytes}-byte response limit. Raise maxBytes (up to ${MAX_ATTACHMENT_BYTES}) if the file really is this large.`);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        // Leaving the loop before the stream ends leaves the response in flight —
+        // `releaseLock` detaches the reader, it does not abort what is arriving.
+        // Cancelling here rather than at each `throw` covers every way out,
+        // including a `read()` that rejects, and cannot be forgotten by the next
+        // early return added above.
+        if (!finished) {
+            try {
+                await reader.cancel();
+            }
+            catch {
+                // Best effort: keep whatever error got us here.
+            }
+        }
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return { bytes, size };
+}
+/**
+ * `btoa` over a string built in 32 KiB slices.
+ *
+ * `String.fromCharCode(...bytes)` on a multi-megabyte array overflows the call
+ * stack, and `Buffer` is not available to this module: `src/lib.ts` exposes the
+ * tool layer to consumers that do not run on Node.
+ */
+function toBase64(bytes) {
+    const chunks = [];
+    const chunkSize = 0x8000;
+    for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+        chunks.push(String.fromCharCode(...bytes.subarray(offset, offset + chunkSize)));
+    }
+    return globalThis.btoa(chunks.join(''));
+}
+/**
+ * A name safe to put in metadata and a resource URI.
+ *
+ * `backlog-js` decodes `Content-Disposition` since 0.20.1, so what arrives is
+ * already the real name. What is left is that it is the server's string: strip
+ * any directory part and control characters rather than pass those on, and
+ * fall back to the id when nothing usable remains.
+ */
+function normalizeFilename(rawName, attachmentId) {
+    const basename = (rawName ?? '').split(/[/\\]/).pop() ?? '';
+    const cleaned = Array.from(basename)
+        .filter((character) => {
+        const codePoint = character.codePointAt(0) ?? 0;
+        return codePoint > 0x1f && codePoint !== 0x7f;
+    })
+        .join('')
+        .trim();
+    return !cleaned || cleaned === '.' || cleaned === '..'
+        ? `attachment-${attachmentId}`
+        : cleaned;
+}
+/**
+ * The bare MIME type of a raw `Content-Type` header.
+ *
+ * `File.FileData.contentType` is the header verbatim — `backlog-js` reads it
+ * with `response.headers.get('Content-Type')` and hands it over unparsed — so
+ * it may carry parameters and any casing. Every decision below is an exact
+ * lookup in `INLINE_IMAGE_TYPES` or `TEXT_TYPES`, and `text/csv;charset=UTF-8`
+ * misses both: the CSV would come back as base64, which is the case this tool
+ * exists to serve.
+ */
+function bareMimeType(rawContentType) {
+    return rawContentType.split(';')[0].trim().toLowerCase();
+}
+function startsWith(bytes, signature) {
+    return signature.every((byte, index) => bytes[index] === byte);
+}
+/**
+ * Whether the bytes really are the raster format the extension promises.
+ *
+ * A client renders `image` content without checking it, so an attachment named
+ * `.png` that is not a PNG would otherwise become a broken image with no
+ * explanation. Mismatches fall back to an embedded resource.
+ */
+function isExpectedImage(bytes, contentType) {
+    switch (contentType) {
+        case 'image/gif':
+            return (startsWith(bytes, [0x47, 0x49, 0x46, 0x38, 0x37, 0x61]) ||
+                startsWith(bytes, [0x47, 0x49, 0x46, 0x38, 0x39, 0x61]));
+        case 'image/jpeg':
+            return startsWith(bytes, [0xff, 0xd8, 0xff]);
+        case 'image/png':
+            return startsWith(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+        case 'image/webp':
+            return (startsWith(bytes, [0x52, 0x49, 0x46, 0x46]) &&
+                bytes[8] === 0x57 &&
+                bytes[9] === 0x45 &&
+                bytes[10] === 0x42 &&
+                bytes[11] === 0x50);
+        default:
+            return false;
+    }
+}
+/**
+ * The raster type the bytes actually are, if it is one this tool inlines.
+ *
+ * A file saved under the wrong extension — a PNG named `.jpg` is the common
+ * one — is served happily by Backlog. Trusting the name and giving up would
+ * turn it into an opaque blob no client draws, when the bytes needed to
+ * identify it are already in hand.
+ */
+function sniffImageType(bytes) {
+    for (const type of INLINE_IMAGE_TYPES) {
+        if (isExpectedImage(bytes, type)) {
+            return type;
+        }
+    }
+    return undefined;
+}
+/**
+ * `undefined` rather than replacement characters when the bytes are not UTF-8,
+ * so a binary file under a `.txt` name falls back to a blob instead of
+ * arriving as mojibake that reads like a successful download.
+ */
+function decodeUtf8(bytes) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        return undefined;
+    }
+}
+function getSpaceNamespace(sourceUrl) {
+    try {
+        return new URL(sourceUrl).host || 'unknown-space';
+    }
+    catch {
+        return 'unknown-space';
+    }
+}
+/**
+ * A synthetic `backlog://` URI, never the URL the download came from.
+ *
+ * In API-key mode `backlog-js` puts the key in the query string, and
+ * `File.FileData.url` carries it verbatim — echoing it into a resource URI
+ * would hand the caller a working credential.
+ */
+function buildResourceUri(sourceUrl, issueIdOrKey, attachmentId, filename) {
+    const space = encodeURIComponent(getSpaceNamespace(sourceUrl));
+    return `backlog://attachments/${space}/issues/${encodeURIComponent(String(issueIdOrKey))}/attachments/${attachmentId}/${encodeURIComponent(filename)}`;
+}
+function errorResult(message) {
+    return {
+        isError: true,
+        content: [{ type: 'text', text: message }],
+    };
+}
+export const getIssueAttachmentTool = (backlog, { t }) => {
+    return {
+        name: 'get_issue_attachment',
+        description: t('TOOL_GET_ISSUE_ATTACHMENT_DESCRIPTION', "Downloads one attachment of an issue. Returns it as MCP image or embedded resource content by default, or as base64 in a JSON object with `format: 'base64'`. Call get_issue first to obtain the attachmentId from the issue's `attachments` array."),
+        schema: z.object(getIssueAttachmentSchema(t)),
+        handler: async ({ issueId, issueKey, attachmentId, format, maxBytes }) => {
+            const resolved = resolveIdOrKey('issue', { id: issueId, key: issueKey }, t);
+            if (!resolved.ok) {
+                return errorResult(resolved.error.message);
+            }
+            const fileData = await backlog.getIssueAttachment(resolved.value, attachmentId);
+            const filename = normalizeFilename('filename' in fileData ? fileData.filename : undefined, attachmentId);
+            const { bytes, size } = await readBody(fileData.body, maxBytes ?? DEFAULT_MAX_BYTES);
+            // What the bytes are beats what the server says, because Backlog derives
+            // `Content-Type` from the extension too — an attachment saved as `.jpg`
+            // whose bytes are a PNG is served as `image/jpeg`. Only when nothing
+            // matches and the server promised a raster does the type become opaque:
+            // saying `image/png` for something that is not one makes a client draw a
+            // broken image with no explanation.
+            const declaredType = bareMimeType(fileData.contentType) || 'application/octet-stream';
+            const contentType = sniffImageType(bytes) ??
+                (INLINE_IMAGE_TYPES.has(declaredType)
+                    ? 'application/octet-stream'
+                    : declaredType);
+            if (format === 'base64') {
+                const data = toBase64(bytes);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ filename, contentType, size, content: data }, null, 2),
+                        },
+                    ],
+                };
+            }
+            const metadata = {
+                filename,
+                contentType,
+                size,
+                attachmentId,
+                issueIdOrKey: resolved.value,
+            };
+            if (INLINE_IMAGE_TYPES.has(contentType)) {
+                return {
+                    content: [
+                        { type: 'text', text: JSON.stringify(metadata, null, 2) },
+                        { type: 'image', data: toBase64(bytes), mimeType: contentType },
+                    ],
+                };
+            }
+            const uri = buildResourceUri(fileData.url, resolved.value, attachmentId, filename);
+            const text = TEXT_TYPES.has(contentType) ? decodeUtf8(bytes) : undefined;
+            const binaryContent = {
+                type: 'resource',
+                resource: text === undefined
+                    ? { uri, blob: toBase64(bytes), mimeType: contentType }
+                    : { uri, text, mimeType: contentType },
+            };
+            return {
+                content: [
+                    { type: 'text', text: JSON.stringify(metadata, null, 2) },
+                    binaryContent,
+                ],
+            };
+        },
+    };
+};

package/build/tools/getNotifications.js

@@ -35,6 +35,9 @@ export const getNotificationsTool = (backlog, { t }) => {
             'comment',
             'pullRequest',
             'pullRequestComment',
+            'document',
+            'documentComment',
+            'documentCommentReply',
             'sender',
             'created',
         ]),

package/build/tools/tools.js

@@ -13,6 +13,7 @@ import { getCustomFieldsTool } from './getCustomFields.js';
 import { getGitRepositoriesTool } from './getGitRepositories.js';
 import { getGitRepositoryTool } from './getGitRepository.js';
 import { getIssueTool } from './getIssue.js';
+import { getIssueAttachmentTool } from './getIssueAttachment.js';
 import { getIssueCommentsTool } from './getIssueComments.js';
 import { getIssuesTool } from './getIssues.js';
 import { getRelatedIssuesTool } from './getRelatedIssues.js';
@@ -93,6 +94,7 @@ export const allTools = (backlog, helper) => {
                 name: 'issue',
                 description: 'Tools for managing issues and their comments.',
                 enabled: false,
+                dynamicTools: [getIssueAttachmentTool(backlog, helper)],
                 tools: [
                     getIssueTool(backlog, helper),
                     getIssuesTool(backlog, helper),

package/build/types/toolsets.d.ts

@@ -5,7 +5,18 @@ type BaseToolset<TTool> = {
     enabled: boolean;
     tools: TTool[];
 };
-export type Toolset = BaseToolset<ToolDefinition<any, any>>;
+export type Toolset = BaseToolset<ToolDefinition<any, any>> & {
+    /**
+     * Tools of this toolset that build their own `CallToolResult`.
+     *
+     * A separate field rather than a member of `tools`, because the two are
+     * registered through different pipelines: a `ToolDefinition` is reshaped by
+     * field picking and the token limit, which a tool returning binary content
+     * must not be. Keeping them in one toolset is what makes `--enable-toolsets`
+     * and the prefix apply to both.
+     */
+    dynamicTools?: DynamicToolDefinition<any>[];
+};
 export type ToolsetGroup = {
     toolsets: Toolset[];
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backlog-mcp-server",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "type": "module",
   "bin": {
     "backlog-mcp-server": "./build/index.js"
@@ -36,7 +36,7 @@
     "@hono/node-server": "^2.1.1",
     "@modelcontextprotocol/hono": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
-    "backlog-js": "^0.19.1",
+    "backlog-js": "^0.20.1",
     "env-var": "^7.5.0",
     "hono": "^4.13.5",
     "js-yaml": "^5.4.1",