backlog-mcp-server 0.19.0 → 0.20.0

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/{composeDynamicToolHandler.d.ts → composeNativeContentToolHandler.d.ts}

@@ -1,11 +1,11 @@
 import { z } from 'zod';
 import { ErrorLike } from '../../types/result.js';
-import { DynamicToolDefinition } from '../../types/tool.js';
-export type ComposeDynamicOptions = {
+import { NativeContentToolDefinition } from '../../types/tool.js';
+export type ComposeNativeContentOptions = {
     errorHandler?: (err: unknown) => ErrorLike;
     useOrganization?: boolean;
 };
-type DynamicInput = {
+type NativeContentInput = {
     organization?: string;
 } & Record<string, unknown>;
 /**
@@ -31,7 +31,7 @@ type DynamicInput = {
  * definition is never mutated, because one toolset group is shared across
  * per-request servers.
  */
-export declare function composeDynamicToolHandler(tool: DynamicToolDefinition<any>, { errorHandler, useOrganization }?: ComposeDynamicOptions): {
+export declare function composeNativeContentToolHandler(tool: NativeContentToolDefinition<any>, { errorHandler, useOrganization }?: ComposeNativeContentOptions): {
     schema: z.ZodObject<{
         [x: string]: any;
         organization: z.ZodOptional<z.ZodString>;
@@ -39,7 +39,7 @@ export declare function composeDynamicToolHandler(tool: DynamicToolDefinition<an
         [x: string]: any;
         organization?: undefined;
     }, z.core.$strip>;
-    handler: (input: DynamicInput) => Promise<{
+    handler: (input: NativeContentInput) => Promise<{
         [x: string]: unknown;
         _meta?: {
             [x: string]: unknown;

package/build/handlers/builders/{composeDynamicToolHandler.js → composeNativeContentToolHandler.js}

@@ -25,7 +25,7 @@ import { isErrorLike } from '../../types/result.js';
  * definition is never mutated, because one toolset group is shared across
  * per-request servers.
  */
-export function composeDynamicToolHandler(
+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.

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,14 +14,14 @@
  */
 export { allTools } from './tools/tools.js';
 export { composeToolHandler } from './handlers/builders/composeToolHandler.js';
-export { composeDynamicToolHandler } from './handlers/builders/composeDynamicToolHandler.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 { ComposeDynamicOptions } from './handlers/builders/composeDynamicToolHandler.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,7 +14,7 @@
  */
 export { allTools } from './tools/tools.js';
 export { composeToolHandler } from './handlers/builders/composeToolHandler.js';
-export { composeDynamicToolHandler } from './handlers/builders/composeDynamicToolHandler.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,15 +1,13 @@
 import { backlogErrorHandler } from './backlog/backlogErrorHandler.js';
-import { composeDynamicToolHandler } from './handlers/builders/composeDynamicToolHandler.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,
@@ -20,30 +18,19 @@ export function registerTools(server, toolsetGroup, options) {
     // 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 ?? [],
-            })),
-        },
+        toolsets: toolsetGroup.toolsets.map((toolset) => ({
+            enabled: toolset.enabled,
+            tools: toolset.nativeContentTools ?? [],
+        })),
         prefix,
-        prepareTool: (tool) => composeDynamicToolHandler(
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        tool, { errorHandler: backlogErrorHandler, useOrganization }),
-    });
-}
-export function registerDynamicTools(server, dynamicToolsetGroup, prefix) {
-    registerToolsets({
-        server,
-        toolsetGroup: dynamicToolsetGroup,
-        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/getIssueAttachment.d.ts

@@ -1,7 +1,7 @@
 import { Backlog } from 'backlog-js';
 import { z } from 'zod';
 import { DescriptionHelper } from '../createDescriptionHelper.js';
-import { DynamicToolDefinition } from '../types/tool.js';
+import { NativeContentToolDefinition } from '../types/tool.js';
 declare const getIssueAttachmentSchema: (t: DescriptionHelper['t']) => {
     issueId: z.ZodOptional<z.ZodNumber>;
     issueKey: z.ZodOptional<z.ZodString>;
@@ -12,5 +12,5 @@ declare const getIssueAttachmentSchema: (t: DescriptionHelper['t']) => {
     }>>;
     maxBytes: z.ZodOptional<z.ZodNumber>;
 };
-export declare const getIssueAttachmentTool: (backlog: Backlog, { t }: DescriptionHelper) => DynamicToolDefinition<ReturnType<typeof getIssueAttachmentSchema>>;
+export declare const getIssueAttachmentTool: (backlog: Backlog, { t }: DescriptionHelper) => NativeContentToolDefinition<ReturnType<typeof getIssueAttachmentSchema>>;
 export {};

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

@@ -94,7 +94,7 @@ export const allTools = (backlog, helper) => {
                 name: 'issue',
                 description: 'Tools for managing issues and their comments.',
                 enabled: false,
-                dynamicTools: [getIssueAttachmentTool(backlog, helper)],
+                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,4 +1,4 @@
-import { DynamicToolDefinition, ToolDefinition } from './tool.js';
+import { NativeContentToolDefinition, ToolDefinition } from './tool.js';
 type BaseToolset<TTool> = {
     name: string;
     description: string;
@@ -15,13 +15,9 @@ export type Toolset = BaseToolset<ToolDefinition<any, any>> & {
      * must not be. Keeping them in one toolset is what makes `--enable-toolsets`
      * and the prefix apply to both.
      */
-    dynamicTools?: DynamicToolDefinition<any>[];
+    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.19.0",
+  "version": "0.20.0",
   "type": "module",
   "bin": {
     "backlog-mcp-server": "./build/index.js"

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>>;