backlog-mcp-server 0.18.1 → 0.20.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/createBacklogMcpServer.js

@@ -1,8 +1,8 @@
 // Copyright (c) 2025 Nulab inc.
 // Licensed under the MIT License.
 import { McpServer } from '@modelcontextprotocol/server';
-import { registerDynamicTools, registerTools } from './registerTools.js';
-import { organizationTools } from './tools/dynamicTools/organizations.js';
+import { registerTools } from './registerTools.js';
+import { organizationTools } from './tools/organizations.js';
 import { buildToolsetGroup } from './utils/toolsetUtils.js';
 import { wrapServerWithToolRegistry, } from './utils/wrapServerWithToolRegistry.js';
 // The tool list is fixed for the process lifetime: it only depends on CLI flags
@@ -27,7 +27,11 @@ export function createBacklogMcpServer({ version, useFields, backlog, clientRegi
     // is configured; the `organization` parameter its description points at is
     // published under the same condition.
     if (mcpOption.useOrganization) {
-        registerDynamicTools(server, organizationTools(clientRegistry, descriptionHelper), mcpOption.prefix);
+        registerTools(server, organizationTools(clientRegistry, descriptionHelper), 
+        // `useOrganization: false` regardless of the flag that got us here.
+        // `list_organizations` is what a caller reads to learn what may go in
+        // `organization`; scoping the answer to one organization is circular.
+        { ...mcpOption, useOrganization: false });
     }
     return server;
 }

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

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+import { ErrorLike } from '../../types/result.js';
+import { NativeContentToolDefinition } from '../../types/tool.js';
+export type ComposeNativeContentOptions = {
+    errorHandler?: (err: unknown) => ErrorLike;
+    useOrganization?: boolean;
+};
+type NativeContentInput = {
+    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 composeNativeContentToolHandler(tool: NativeContentToolDefinition<any>, { errorHandler, useOrganization }?: ComposeNativeContentOptions): {
+    schema: z.ZodObject<{
+        [x: string]: any;
+        organization: z.ZodOptional<z.ZodString>;
+    } | {
+        [x: string]: any;
+        organization?: undefined;
+    }, z.core.$strip>;
+    handler: (input: NativeContentInput) => 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/composeNativeContentToolHandler.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 composeNativeContentToolHandler(
+// 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/index.js

@@ -129,22 +129,6 @@ Available toolsets:
 if (hideBin(process.argv).some((arg) => arg.split('=')[0] === '--export-translations')) {
     process.stderr.write('--export-translations is deprecated and will be removed in a future release. Use --export-descriptions.\n');
 }
-// Dynamic toolsets are gone. yargs ignores the unknown flag, so without this the
-// server would start with a quietly different tool list: the flag used to drop
-// `all` from the enabled toolsets, so a setup that passed only this one went from
-// no toolsets plus three meta-tools to every toolset enabled.
-//
-// Only worth saying to someone who had it switched on. A setting left at `false`
-// asked for what it now gets, so a notice claiming the tool list changed would be
-// wrong.
-const asksForDynamicToolsets = (value) => value !== undefined &&
-    !['', '0', 'false', 'no'].includes(value.toLowerCase());
-const dynamicToolsetsFlag = hideBin(process.argv).find((arg) => arg.split('=')[0] === '--dynamic-toolsets');
-if ((dynamicToolsetsFlag !== undefined &&
-    asksForDynamicToolsets(dynamicToolsetsFlag.split('=')[1] ?? 'true')) ||
-    asksForDynamicToolsets(process.env.ENABLE_DYNAMIC_TOOLSETS)) {
-    process.stderr.write('Dynamic toolsets have been removed, and --dynamic-toolsets / ENABLE_DYNAMIC_TOOLSETS no longer do anything. Every toolset is enabled unless you narrow it with --enable-toolsets or ENABLE_TOOLSETS.\n');
-}
 const clientRegistry = oauthConfig
     ? createOAuthBacklogClientRegistry(oauthConfig.backlogDomain)
     : createBacklogClientRegistry();

package/build/lib.d.ts

@@ -14,12 +14,14 @@
  */
 export { allTools } from './tools/tools.js';
 export { composeToolHandler } from './handlers/builders/composeToolHandler.js';
+export { composeNativeContentToolHandler } from './handlers/builders/composeNativeContentToolHandler.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 { ComposeNativeContentOptions } from './handlers/builders/composeNativeContentToolHandler.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';
+export type { ToolDefinition, NativeContentToolDefinition, } from './types/tool.js';
+export type { Toolset, ToolsetGroup } from './types/toolsets.js';
 export type { ErrorLike, SafeResult } from './types/result.js';

package/build/lib.js

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

package/build/registerTools.d.ts

@@ -1,5 +1,4 @@
 import { MCPOptions } from './types/mcp.js';
-import { DynamicToolsetGroup, ToolsetGroup } from './types/toolsets.js';
+import { ToolsetGroup } from './types/toolsets.js';
 import { BacklogMCPServer } from './utils/wrapServerWithToolRegistry.js';
 export declare function registerTools(server: BacklogMCPServer, toolsetGroup: ToolsetGroup, options: MCPOptions): void;
-export declare function registerDynamicTools(server: BacklogMCPServer, dynamicToolsetGroup: DynamicToolsetGroup, prefix: string): void;

package/build/registerTools.js

@@ -1,31 +1,36 @@
 import { backlogErrorHandler } from './backlog/backlogErrorHandler.js';
+import { composeNativeContentToolHandler } from './handlers/builders/composeNativeContentToolHandler.js';
 import { composeToolHandler } from './handlers/builders/composeToolHandler.js';
 export function registerTools(server, toolsetGroup, options) {
     const { useFields, maxTokens, prefix, useOrganization } = options;
     registerToolsets({
         server,
-        toolsetGroup,
+        toolsets: toolsetGroup.toolsets,
         prefix,
-        prepareTool: (tool) => 
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        composeToolHandler(tool, {
+        prepareTool: (tool) => composeToolHandler(tool, {
             useFields,
             errorHandler: backlogErrorHandler,
             maxTokens,
             useOrganization,
         }),
     });
-}
-export function registerDynamicTools(server, dynamicToolsetGroup, prefix) {
+    // Tools that build their own result, registered from the same toolsets so
+    // that `--enable-toolsets` and the prefix cover them too.
     registerToolsets({
         server,
-        toolsetGroup: dynamicToolsetGroup,
+        toolsets: toolsetGroup.toolsets.map((toolset) => ({
+            enabled: toolset.enabled,
+            tools: toolset.nativeContentTools ?? [],
+        })),
         prefix,
-        prepareTool: (tool) => ({ schema: tool.schema, handler: tool.handler }),
+        prepareTool: (tool) => composeNativeContentToolHandler(tool, {
+            errorHandler: backlogErrorHandler,
+            useOrganization,
+        }),
     });
 }
-function registerToolsets({ server, toolsetGroup, prefix, prepareTool, }) {
-    for (const toolset of toolsetGroup.toolsets) {
+function registerToolsets({ server, toolsets, prefix, prepareTool, }) {
+    for (const toolset of toolsets) {
         if (!toolset.enabled) {
             continue;
         }

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 { NativeContentToolDefinition } 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) => NativeContentToolDefinition<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/organizations.d.ts

@@ -0,0 +1,12 @@
+import { DescriptionHelper } from '../createDescriptionHelper.js';
+import { BacklogClientRegistry } from '../utils/backlogClientRegistry.js';
+import { ToolDefinition } from '../types/tool.js';
+import { ToolsetGroup } from '../types/toolsets.js';
+type OrganizationOutput = {
+    name: string;
+    domain: string;
+    isDefault: boolean;
+};
+export declare function organizationTools(registry: BacklogClientRegistry, { t }: DescriptionHelper): ToolsetGroup;
+export declare function listOrganizationsTool(registry: BacklogClientRegistry, t: DescriptionHelper['t']): ToolDefinition<Record<string, never>, OrganizationOutput>;
+export {};

package/build/tools/{dynamicTools/organizations.js → organizations.js}

@@ -16,17 +16,17 @@ export function listOrganizationsTool(registry, t) {
         name: 'list_organizations',
         description: t('TOOL_LIST_ORGANIZATIONS_DESCRIPTION', 'List configured Backlog organizations and identify the default organization.'),
         schema: z.object({}),
-        handler: async () => {
-            const organizations = registry.listOrganizations().map(toToolOutput);
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify(organizations, null, 2),
-                    },
-                ],
-            };
-        },
+        outputFields: ['name', 'domain', 'isDefault'],
+        /**
+         * False even though the handler returns an array.
+         *
+         * `returnsList` decides whether `--optimize-response` publishes a `fields`
+         * parameter, and that pays off where a response grows without bound. This
+         * one is bounded by how many spaces the operator configured, over three
+         * fields — a `fields` enum would cost every client schema to trim nothing.
+         */
+        returnsList: false,
+        handler: async () => registry.listOrganizations().map(toToolOutput),
     };
 }
 function toToolOutput(organization) {

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,
+                nativeContentTools: [getIssueAttachmentTool(backlog, helper)],
                 tools: [
                     getIssueTool(backlog, helper),
                     getIssuesTool(backlog, helper),

package/build/types/tool.d.ts

@@ -29,7 +29,25 @@ export type ToolDefinition<Shape extends z.ZodRawShape, Result> = {
     returnsList: boolean;
 };
 export declare const buildToolSchema: <T extends z.ZodRawShape>(fn: (t: DescriptionHelper['t']) => T) => (t: DescriptionHelper['t']) => T;
-export type DynamicToolDefinition<Shape extends z.ZodRawShape> = {
+/**
+ * A tool that assembles its own `CallToolResult`.
+ *
+ * The exception, not a second way of writing a tool: a `ToolDefinition` returns
+ * a plain value and the handler pipeline turns it into a result, which is what
+ * almost every tool wants. This type exists for the few whose result the
+ * pipeline cannot express or would corrupt — `wrapWithToolResult` ends a tool at
+ * exactly one text block, so `image` and `resource` content is unreachable
+ * through it, and `wrapWithTokenLimit` would cut a base64 payload mid-string and
+ * return it as `kind: 'ok'`, a corrupt file reported as a success.
+ *
+ * The name is the content, not the tool: these produce MCP content types
+ * natively rather than being reshaped into one. What they give up is everything
+ * the pipeline does — field picking, the token limit, JSON serialisation — so
+ * reach for it only when the result shape actually requires it.
+ * `composeNativeContentToolHandler` puts back the two steps that are not about
+ * reshaping, the organization context and error handling.
+ */
+export type NativeContentToolDefinition<Shape extends z.ZodRawShape> = {
     name: string;
     description: string;
     schema: z.ZodObject<Shape>;

package/build/types/toolsets.d.ts

@@ -1,16 +1,23 @@
-import { DynamicToolDefinition, ToolDefinition } from './tool.js';
+import { NativeContentToolDefinition, ToolDefinition } from './tool.js';
 type BaseToolset<TTool> = {
     name: string;
     description: string;
     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.
+     */
+    nativeContentTools?: NativeContentToolDefinition<any>[];
+};
 export type ToolsetGroup = {
     toolsets: Toolset[];
 };
-export type DynamicToolset = BaseToolset<DynamicToolDefinition<any>>;
-export type DynamicToolsetGroup = {
-    toolsets: DynamicToolset[];
-};
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backlog-mcp-server",
-  "version": "0.18.1",
+  "version": "0.20.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",

package/build/tools/dynamicTools/organizations.d.ts

@@ -1,6 +0,0 @@
-import { DescriptionHelper } from '../../createDescriptionHelper.js';
-import { BacklogClientRegistry } from '../../utils/backlogClientRegistry.js';
-import { DynamicToolDefinition } from '../../types/tool.js';
-import { DynamicToolsetGroup } from '../../types/toolsets.js';
-export declare function organizationTools(registry: BacklogClientRegistry, { t }: DescriptionHelper): DynamicToolsetGroup;
-export declare function listOrganizationsTool(registry: BacklogClientRegistry, t: DescriptionHelper['t']): DynamicToolDefinition<Record<string, never>>;