feat(attachments): [3/4] add download tools for issue, wiki, and pull request

package.json

@@ -28,7 +28,7 @@
   ],
   "dependencies": {
     "@hono/node-server": "^1.19.14",
-    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "backlog-js": "^0.16.0",
     "cosmiconfig": "^9.0.0",
     "dotenv": "^16.5.0",
@@ -37,6 +37,7 @@
     "hono": "^4.12.14",
     "pino": "^9.9.0",
     "pino-pretty": "^13.1.1",
+    "sharp": "^0.34.5",
     "yargs": "^18.0.0",
     "zod": "^3.24.3"
   },

src/registerTools.test.ts

@@ -7,6 +7,8 @@ import { allTools } from './tools/tools';
 import { buildToolsetGroup } from './utils/toolsetUtils.js';
 import { wrapServerWithToolRegistry } from './utils/wrapServerWithToolRegistry.js';
 import type { Toolset } from './types/toolsets.js';
+import { z } from 'zod';
+import type { DynamicToolDefinition } from './types/tool.js';
 
 vi.mock('./handlers/builders/composeToolHandler');
 
@@ -77,8 +79,57 @@ describe('registerTools', () => {
       prefix: '',
     });
 
-    expect(mockServer.tool).toHaveBeenCalledTimes(
-      toolsetGroup.toolsets.flatMap((a) => a.tools).length
+    const totalTools =
+      toolsetGroup.toolsets.flatMap((a) => a.tools).length +
+      toolsetGroup.toolsets.flatMap((a) => a.dynamicTools ?? []).length;
+    expect(mockServer.tool).toHaveBeenCalledTimes(totalTools);
+  });
+
+  it('wraps dynamic tool errors with backlog error handling', async () => {
+    const mockServer = wrapServerWithToolRegistry({
+      tool: vi.fn(),
+    } as unknown as McpServer);
+    const throwingDynamicTool: DynamicToolDefinition<{
+      attachmentId: z.ZodNumber;
+    }> = {
+      name: 'broken_dynamic_tool',
+      description: 'Broken dynamic tool',
+      schema: z.object({
+        attachmentId: z.number(),
+      }),
+      handler: async () => {
+        throw new Error('boom');
+      },
+    };
+
+    registerTools(
+      mockServer,
+      {
+        toolsets: [
+          {
+            name: 'broken',
+            description: 'Broken toolset',
+            enabled: true,
+            tools: [],
+            dynamicTools: [throwingDynamicTool],
+          },
+        ],
+      },
+      {
+        useFields: false,
+        prefix: '',
+        maxTokens: 5000,
+      }
     );
+
+    const handler = (mockServer.tool as Mock).mock.calls.find(
+      (call) => call[0] === 'broken_dynamic_tool'
+    )?.[3];
+
+    expect(handler).toBeTypeOf('function');
+    await expect(handler({ attachmentId: 1 }, {})).resolves.toEqual({
+      isError: true,
+      content: [{ type: 'text', text: 'boom' }],
+    });
   });
 });

src/registerTools.ts

@@ -4,20 +4,25 @@ import { MCPOptions } from './types/mcp.js';
 import { DynamicToolDefinition, ToolDefinition } from './types/tool.js';
 import { DynamicToolsetGroup, ToolsetGroup } from './types/toolsets.js';
 import { BacklogMCPServer } from './utils/wrapServerWithToolRegistry.js';
+import { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import {
+  CallToolResult,
+  ServerNotification,
+  ServerRequest,
+} from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
 
-type ToolsetSource = ToolsetGroup | DynamicToolsetGroup;
-
-type RegisterOptions = {
-  server: BacklogMCPServer;
-  toolsetGroup: ToolsetSource;
-  prefix: string;
-  onlyEnabled?: boolean;
-  handlerStrategy: (
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    tool: ToolDefinition<any, any> | DynamicToolDefinition<any>
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  ) => (...args: any[]) => any;
-};
+type RegisterOptions<TToolsetGroup extends ToolsetGroup | DynamicToolsetGroup> =
+  {
+    server: BacklogMCPServer;
+    toolsetGroup: TToolsetGroup;
+    prefix: string;
+    onlyEnabled?: boolean;
+    handlerStrategy: (
+      tool: TToolsetGroup['toolsets'][number]['tools'][number]
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ) => (...args: any[]) => any;
+  };
 
 export function registerTools(
   server: BacklogMCPServer,
@@ -38,6 +43,23 @@ export function registerTools(
         maxTokens,
       }),
   });
+
+  // Register dynamic tools within toolsets (e.g., attachment downloads)
+  for (const toolset of toolsetGroup.toolsets) {
+    if (!toolset.enabled || !toolset.dynamicTools) {
+      continue;
+    }
+
+    for (const tool of toolset.dynamicTools) {
+      const toolNameWithPrefix = `${prefix}${tool.name}`;
+      server.registerOnce(
+        toolNameWithPrefix,
+        tool.description,
+        tool.schema.shape,
+        wrapDynamicToolHandler(tool)
+      );
+    }
+  }
 }
 
 export function registerDynamicTools(
@@ -49,16 +71,18 @@ export function registerDynamicTools(
     server,
     toolsetGroup: dynamicToolsetGroup,
     prefix,
-    handlerStrategy: (tool) => tool.handler,
+    handlerStrategy: (tool) => wrapDynamicToolHandler(tool),
   });
 }
 
-function registerToolsets({
+function registerToolsets<
+  TToolsetGroup extends ToolsetGroup | DynamicToolsetGroup,
+>({
   server,
   toolsetGroup,
   prefix,
   handlerStrategy,
-}: RegisterOptions) {
+}: RegisterOptions<TToolsetGroup>) {
   for (const toolset of toolsetGroup.toolsets) {
     if (!toolset.enabled) {
       continue;
@@ -77,3 +101,27 @@ function registerToolsets({
     }
   }
 }
+
+function wrapDynamicToolHandler<Shape extends z.ZodRawShape>(
+  tool: DynamicToolDefinition<Shape>
+): (
+  input: z.infer<z.ZodObject<Shape>>,
+  extra: RequestHandlerExtra<ServerRequest, ServerNotification>
+) => Promise<CallToolResult> {
+  return async (input, _extra) => {
+    try {
+      return await tool.handler(input);
+    } catch (error) {
+      const parsedError = backlogErrorHandler(error);
+      return {
+        isError: true,
+        content: [
+          {
+            type: 'text',
+            text: parsedError.message,
+          },
+        ],
+      };
+    }
+  };
+}

src/tools/dynamicTools/toolsets.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, vi, it } from 'vitest';
 import { z } from 'zod';
-import { ToolDefinition, ToolRegistrar } from '../../types/tool.js';
+import {
+  DynamicToolDefinition,
+  ToolDefinition,
+  ToolRegistrar,
+} from '../../types/tool.js';
 import { ToolsetGroup } from '../../types/toolsets.js';
 import {
   enableToolsetTool,
@@ -30,6 +34,14 @@ describe('dynamicTools', () => {
       content: [{ type: 'text', text: 'dummy' }],
     }),
   };
+  const dummyDynamicTool: DynamicToolDefinition<any> = {
+    name: 'get_issue_attachment',
+    description: 'Downloads an issue attachment',
+    schema: z.object({}),
+    handler: async () => ({
+      content: [{ type: 'text', text: 'dynamic dummy' }],
+    }),
+  };
 
   const mockToolsetGroup: ToolsetGroup = {
     toolsets: [
@@ -38,6 +50,7 @@ describe('dynamicTools', () => {
         description: 'Project management tools',
         enabled: false,
         tools: [dummyTool],
+        dynamicTools: [dummyDynamicTool],
       },
     ],
   };
@@ -99,6 +112,14 @@ describe('dynamicTools', () => {
         description: 'Returns a list of projects',
         toolset: 'project',
         canEnable: true,
+        dynamic: false,
+      });
+      expect(json[1]).toEqual({
+        name: 'get_issue_attachment',
+        description: 'Downloads an issue attachment',
+        toolset: 'project',
+        canEnable: true,
+        dynamic: true,
       });
     }
   });

src/tools/dynamicTools/toolsets.ts

@@ -121,12 +121,22 @@ export const getToolsetTools = (
         };
       }
 
-      const tools = found.tools.map((tool) => ({
-        name: tool.name,
-        description: tool.description,
-        toolset: found.name,
-        canEnable: true,
-      }));
+      const tools = [
+        ...found.tools.map((tool) => ({
+          name: tool.name,
+          description: tool.description,
+          toolset: found.name,
+          canEnable: true,
+          dynamic: false,
+        })),
+        ...(found.dynamicTools ?? []).map((tool) => ({
+          name: tool.name,
+          description: tool.description,
+          toolset: found.name,
+          canEnable: true,
+          dynamic: true,
+        })),
+      ];
 
       return {
         content: [