backlog-mcp-server 0.19.0 → 0.20.1

package/README.md

@@ -287,7 +287,6 @@ Tools for managing projects, categories, custom fields, and issue types.
 - `get_project`: Returns information about a specific project.
 - `get_project_users`: Returns list of users in a specific project.
 - `update_project`: Updates an existing project.
-- `delete_project`: Deletes a project.
 
 ### Toolset: `issue`
 

package/build/auth/backlogAuthContext.d.ts

@@ -1,2 +1,20 @@
-export declare function runWithAccessToken<T>(token: string | undefined, fn: () => Promise<T>): Promise<T>;
+/**
+ * Runs `fn` with the OAuth access token of the current request in scope.
+ *
+ * `onAuthError` is invoked the first time a Backlog call inside `fn` is
+ * rejected with an authentication error. It runs at the moment of detection
+ * rather than after `fn` settles, because a response that has already upgraded
+ * to SSE resolves before its handler finishes — the caller cannot rely on
+ * inspecting the outcome afterwards to invalidate anything.
+ */
+export declare function runWithAccessToken<T>(token: string, fn: () => Promise<T>, onAuthError?: () => void): Promise<T>;
 export declare function getCurrentAccessToken(): string | undefined;
+/**
+ * Reports that Backlog rejected the credentials of the current request.
+ *
+ * A no-op outside {@link runWithAccessToken}, which is how API-key mode stays
+ * unaffected: nothing establishes this context on the stdio transport.
+ */
+export declare function reportBacklogAuthError(): void;
+/** Whether {@link reportBacklogAuthError} was called in the current context. */
+export declare function hasBacklogAuthErrorBeenReported(): boolean;

package/build/auth/backlogAuthContext.js

@@ -1,10 +1,36 @@
 // Copyright (c) 2025 Nulab inc.
 // Licensed under the MIT License.
 import { AsyncLocalStorage } from 'node:async_hooks';
-const accessTokenStorage = new AsyncLocalStorage();
-export function runWithAccessToken(token, fn) {
-    return accessTokenStorage.run(token, fn);
+const authContextStorage = new AsyncLocalStorage();
+/**
+ * Runs `fn` with the OAuth access token of the current request in scope.
+ *
+ * `onAuthError` is invoked the first time a Backlog call inside `fn` is
+ * rejected with an authentication error. It runs at the moment of detection
+ * rather than after `fn` settles, because a response that has already upgraded
+ * to SSE resolves before its handler finishes — the caller cannot rely on
+ * inspecting the outcome afterwards to invalidate anything.
+ */
+export function runWithAccessToken(token, fn, onAuthError) {
+    return authContextStorage.run({ accessToken: token, onAuthError, authErrorReported: false }, fn);
 }
 export function getCurrentAccessToken() {
-    return accessTokenStorage.getStore();
+    return authContextStorage.getStore()?.accessToken;
+}
+/**
+ * Reports that Backlog rejected the credentials of the current request.
+ *
+ * A no-op outside {@link runWithAccessToken}, which is how API-key mode stays
+ * unaffected: nothing establishes this context on the stdio transport.
+ */
+export function reportBacklogAuthError() {
+    const context = authContextStorage.getStore();
+    if (!context || context.authErrorReported)
+        return;
+    context.authErrorReported = true;
+    context.onAuthError?.();
+}
+/** Whether {@link reportBacklogAuthError} was called in the current context. */
+export function hasBacklogAuthErrorBeenReported() {
+    return authContextStorage.getStore()?.authErrorReported ?? false;
 }

package/build/auth/bearerAuthMiddleware.js

@@ -1,15 +1,23 @@
 // Copyright (c) 2025 Nulab inc.
 // Licensed under the MIT License.
 import { verifyBacklogToken } from './backlogOAuthClient.js';
+import { hasBacklogAuthErrorBeenReported, runWithAccessToken, } from './backlogAuthContext.js';
 import { logger } from '../utils/logger.js';
 const CACHE_TTL_MS = 5 * 60 * 1000;
 export function createBearerAuthMiddleware(store, config, mcpPath) {
     const prmPath = mcpPath === '/' ? '' : mcpPath;
     const resourceMetadataUrl = `${config.serverBaseUrl}/.well-known/oauth-protected-resource${prmPath}`;
+    const wwwAuthenticate = (description) => description
+        ? `Bearer error="invalid_token", error_description="${description}", resource_metadata="${resourceMetadataUrl}"`
+        : `Bearer resource_metadata="${resourceMetadataUrl}"`;
     return async (c, next) => {
+        const unauthorized = (description, header = description) => {
+            c.header('WWW-Authenticate', wwwAuthenticate(header));
+            return c.json({ error: 'invalid_token', error_description: description }, 401);
+        };
         const authHeader = c.req.header('authorization');
         if (!authHeader) {
-            c.header('WWW-Authenticate', `Bearer resource_metadata="${resourceMetadataUrl}"`);
+            c.header('WWW-Authenticate', wwwAuthenticate());
             return c.json({
                 error: 'invalid_token',
                 error_description: 'Missing Authorization header',
@@ -17,42 +25,49 @@ export function createBearerAuthMiddleware(store, config, mcpPath) {
         }
         const [type, mcpToken] = authHeader.split(' ');
         if (type?.toLowerCase() !== 'bearer' || !mcpToken) {
-            c.header('WWW-Authenticate', `Bearer error="invalid_token", error_description="Invalid Authorization header format", resource_metadata="${resourceMetadataUrl}"`);
-            return c.json({ error: 'invalid_token', error_description: 'Expected Bearer token' }, 401);
+            return unauthorized('Expected Bearer token', 'Invalid Authorization header format');
         }
         const tokenEntry = store.getMcpToken(mcpToken);
         if (!tokenEntry) {
-            c.header('WWW-Authenticate', `Bearer error="invalid_token", error_description="Unknown or expired token", resource_metadata="${resourceMetadataUrl}"`);
-            return c.json({
-                error: 'invalid_token',
-                error_description: 'Unknown or expired token',
-            }, 401);
+            return unauthorized('Unknown or expired token');
         }
-        const cached = store.getCachedVerification(mcpToken);
-        if (cached) {
-            c.set('authInfo', cached);
-            await next();
-            return;
+        let authInfo = store.getCachedVerification(mcpToken);
+        if (!authInfo) {
+            try {
+                const user = await verifyBacklogToken(config.backlogDomain, tokenEntry.backlogAccessToken);
+                authInfo = {
+                    token: tokenEntry.backlogAccessToken,
+                    clientId: String(user.id),
+                    scopes: [],
+                    expiresAt: Math.floor(Date.now() / 1000) + CACHE_TTL_MS / 1000,
+                };
+                store.cacheVerification(mcpToken, authInfo, CACHE_TTL_MS);
+            }
+            catch (err) {
+                logger.warn({ err }, 'Bearer token verification failed');
+                return unauthorized('Token verification failed');
+            }
         }
-        try {
-            const user = await verifyBacklogToken(config.backlogDomain, tokenEntry.backlogAccessToken);
-            const authInfo = {
-                token: tokenEntry.backlogAccessToken,
-                clientId: String(user.id),
-                scopes: [],
-                expiresAt: Math.floor(Date.now() / 1000) + CACHE_TTL_MS / 1000,
-            };
-            store.cacheVerification(mcpToken, authInfo, CACHE_TTL_MS);
-            c.set('authInfo', authInfo);
+        c.set('authInfo', authInfo);
+        // The stored token is the only credential a downstream Backlog call has, so
+        // Backlog rejecting it is an authentication event and not a tool failure.
+        // Dropping the entry here is what lets the client recover: the next request
+        // fails the `getMcpToken` check above and is told to re-authenticate.
+        //
+        // Invalidation happens the moment the failure is reported rather than after
+        // `next()` settles, because a response that upgraded to SSE resolves before
+        // its handler has run.
+        const onAuthError = () => {
+            logger.warn({ clientId: tokenEntry.clientId }, 'Backlog rejected the stored access token; revoking the MCP token');
+            store.revokeMcpToken(mcpToken);
+        };
+        await runWithAccessToken(tokenEntry.backlogAccessToken, async () => {
             await next();
-        }
-        catch (err) {
-            logger.warn({ err }, 'Bearer token verification failed');
-            c.header('WWW-Authenticate', `Bearer error="invalid_token", error_description="Token verification failed", resource_metadata="${resourceMetadataUrl}"`);
-            return c.json({
-                error: 'invalid_token',
-                error_description: 'Token verification failed',
-            }, 401);
-        }
+            // Read inside the context: `next()` resolving is not the end of the
+            // async scope, but it is the point at which the response is decided.
+            if (hasBacklogAuthErrorBeenReported()) {
+                c.res = unauthorized('Backlog rejected the access token');
+            }
+        }, onAuthError);
     };
 }

package/build/auth/tokenStore.d.ts

@@ -55,6 +55,16 @@ export declare function createTokenStore(): {
     cacheVerification(token: string, authInfo: AuthInfo, ttlMs: number): void;
     storeMcpToken(mcpToken: string, entry: McpTokenEntry): void;
     getMcpToken(mcpToken: string): McpTokenEntry | undefined;
+    /**
+     * Drops an MCP access token and its cached verification, so the next
+     * request on it is rejected by the bearer middleware.
+     *
+     * The refresh token is deliberately left in place: a Backlog 401 says the
+     * access token is spent, not that the grant is gone, so a client should be
+     * able to recover through the refresh grant before falling back to a full
+     * re-authorization.
+     */
+    revokeMcpToken(mcpToken: string): void;
     storeMcpRefreshToken(mcpRefreshToken: string, entry: McpRefreshEntry): void;
     consumeMcpRefreshToken(mcpRefreshToken: string): McpRefreshEntry | undefined;
     cleanup(): void;

package/build/auth/tokenStore.js

@@ -85,6 +85,19 @@ export function createTokenStore() {
             }
             return entry;
         },
+        /**
+         * Drops an MCP access token and its cached verification, so the next
+         * request on it is rejected by the bearer middleware.
+         *
+         * The refresh token is deliberately left in place: a Backlog 401 says the
+         * access token is spent, not that the grant is gone, so a client should be
+         * able to recover through the refresh grant before falling back to a full
+         * re-authorization.
+         */
+        revokeMcpToken(mcpToken) {
+            mcpAccessTokens.delete(mcpToken);
+            verificationCache.delete(mcpToken);
+        },
         storeMcpRefreshToken(mcpRefreshToken, entry) {
             mcpRefreshTokens.set(mcpRefreshToken, entry);
         },

package/build/backlog/backlogErrorHandler.js

@@ -1,6 +1,20 @@
+import { getCurrentAccessToken, reportBacklogAuthError, } from '../auth/backlogAuthContext.js';
 import { parseBacklogAPIError } from './parseBacklogAPIError.js';
 export const backlogErrorHandler = (err) => {
-    const parsed = parseBacklogAPIError(err);
+    // Only an OAuth request carries an access token in its context; the stdio
+    // transport authenticates with an API key and never establishes one. The
+    // comparison is against `undefined` rather than truthiness so this asks
+    // exactly what `reportBacklogAuthError` asks — whether a context exists —
+    // and the two cannot answer differently for the same request.
+    const authMode = getCurrentAccessToken() !== undefined ? 'oauth' : 'apiKey';
+    const parsed = parseBacklogAPIError(err, { authMode });
+    // Backlog rejecting an OAuth token is authoritative: the credential this
+    // request was issued is spent. Reporting it lets the transport invalidate the
+    // token and tell the client to re-authenticate, instead of returning the
+    // failure as tool output the client cannot act on.
+    if (parsed.type === 'BacklogAuthError') {
+        reportBacklogAuthError();
+    }
     return {
         kind: 'error',
         message: parsed.message,

package/build/backlog/parseBacklogAPIError.d.ts

@@ -5,4 +5,11 @@ export type ParsedBacklogAPIError = {
     code?: number;
     url?: string;
 };
-export declare function parseBacklogAPIError(err: unknown): ParsedBacklogAPIError;
+/**
+ * How the rejected request was authenticated. It decides only the wording of an
+ * authentication failure: in OAuth mode there is no API key to go and check.
+ */
+export type BacklogAuthMode = 'apiKey' | 'oauth';
+export declare function parseBacklogAPIError(err: unknown, options?: {
+    authMode?: BacklogAuthMode;
+}): ParsedBacklogAPIError;

package/build/backlog/parseBacklogAPIError.js

@@ -1,4 +1,8 @@
-export function parseBacklogAPIError(err) {
+const authErrorMessage = (status, authMode) => authMode === 'oauth'
+    ? `Authentication failed (HTTP ${status}). The Backlog access token was rejected. Re-authenticate with Backlog, or check that your account has permission for this resource.`
+    : `Authentication failed (HTTP ${status}). Please check your API key or permissions.`;
+export function parseBacklogAPIError(err, options = {}) {
+    const { authMode = 'apiKey' } = options;
     const e = err;
     if (e._name && e._status && e._url) {
         const status = e._status;
@@ -8,7 +12,7 @@ export function parseBacklogAPIError(err) {
         if (e._name === 'BacklogAuthError') {
             return {
                 type: 'BacklogAuthError',
-                message: `Authentication failed (HTTP ${status}). Please check your API key or permissions.`,
+                message: authErrorMessage(status, authMode),
                 status,
                 url,
             };

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/httpMcpServer.js

@@ -4,7 +4,6 @@ import { serve } from '@hono/node-server';
 import { hostHeaderValidation, localhostHostValidation, localhostOriginValidation, originValidation, } from '@modelcontextprotocol/hono';
 import { createMcpHandler } from '@modelcontextprotocol/server';
 import { Hono } from 'hono';
-import { runWithAccessToken } from './auth/backlogAuthContext.js';
 import { logger } from './utils/logger.js';
 const LOCALHOST_BINDS = ['127.0.0.1', 'localhost', '::1'];
 export const runHttpMcpServer = async (options) => {
@@ -58,14 +57,12 @@ export const runHttpMcpServer = async (options) => {
         responseMode: enableJsonResponse ? 'json' : 'auto',
         onerror: (err) => logger.error({ err }, 'MCP handler error'),
     });
+    // The bearer middleware owns the OAuth request context: it scopes the access
+    // token around this dispatch and converts a Backlog rejection into a 401.
     app.all(mcpPath, async (c) => {
         const authInfo = oauthEnabled ? c.get('authInfo') : undefined;
-        const accessToken = authInfo?.token;
         try {
-            const dispatch = () => mcpHandler.fetch(c.req.raw, { authInfo });
-            return accessToken
-                ? await runWithAccessToken(accessToken, dispatch)
-                : await dispatch();
+            return await mcpHandler.fetch(c.req.raw, { authInfo });
         }
         catch (error) {
             logger.error({ err: error }, 'Error handling MCP request');

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

@@ -7,7 +7,6 @@ import { addWikiTool } from './addWiki.js';
 import { updateWikiTool } from './updateWiki.js';
 import { countIssuesTool } from './countIssues.js';
 import { deleteIssueTool } from './deleteIssue.js';
-import { deleteProjectTool } from './deleteProject.js';
 import { getCategoriesTool } from './getCategories.js';
 import { getCustomFieldsTool } from './getCustomFields.js';
 import { getGitRepositoriesTool } from './getGitRepositories.js';
@@ -87,14 +86,13 @@ export const allTools = (backlog, helper) => {
                     getProjectTool(backlog, helper),
                     getProjectUsersTool(backlog, helper),
                     updateProjectTool(backlog, helper),
-                    deleteProjectTool(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.1",
   "type": "module",
   "bin": {
     "backlog-mcp-server": "./build/index.js"

package/build/tools/deleteProject.d.ts

@@ -1,11 +0,0 @@
-import { z } from 'zod';
-import type { Entity } from 'backlog-js';
-import { Backlog } from 'backlog-js';
-import { ToolDefinition } from '../types/tool.js';
-import { DescriptionHelper } from '../createDescriptionHelper.js';
-declare const deleteProjectSchema: (t: DescriptionHelper['t']) => {
-    projectId: z.ZodOptional<z.ZodNumber>;
-    projectKey: z.ZodOptional<z.ZodString>;
-};
-export declare const deleteProjectTool: (backlog: Backlog, { t }: DescriptionHelper) => ToolDefinition<ReturnType<typeof deleteProjectSchema>, Entity.Project.Project>;
-export {};

package/build/tools/deleteProject.js

@@ -1,49 +0,0 @@
-import { z } from 'zod';
-import { buildToolSchema } from '../types/tool.js';
-import { outputFields } from '../types/outputFields.js';
-import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
-const deleteProjectSchema = buildToolSchema((t) => ({
-    projectId: z
-        .number()
-        .optional()
-        .describe(t('TOOL_DELETE_PROJECT_PROJECT_ID', 'The numeric ID of the project (e.g., 12345)')),
-    projectKey: z
-        .string()
-        .optional()
-        .describe(t('TOOL_DELETE_PROJECT_PROJECT_KEY', "The key of the project (e.g., 'PROJECT')")),
-}));
-export const deleteProjectTool = (backlog, { t }) => {
-    return {
-        name: 'delete_project',
-        description: t('TOOL_DELETE_PROJECT_DESCRIPTION', 'Deletes a project'),
-        schema: z.object(deleteProjectSchema(t)),
-        returnsList: false,
-        outputFields: outputFields()([
-            'id',
-            'projectKey',
-            'name',
-            'chartEnabled',
-            'useResolvedForChart',
-            'subtaskingEnabled',
-            'projectLeaderCanEditProjectLeader',
-            'useWiki',
-            'useFileSharing',
-            'useWikiTreeView',
-            'useOriginalImageSizeAtWiki',
-            'useSubversion',
-            'useGit',
-            'textFormattingRule',
-            'archived',
-            'displayOrder',
-            'useDevAttributes',
-            'grandchildIssueEnabled',
-        ]),
-        handler: async ({ projectId, projectKey }) => {
-            const result = resolveIdOrKey('project', { id: projectId, key: projectKey }, t);
-            if (!result.ok) {
-                throw result.error;
-            }
-            return backlog.deleteProject(result.value);
-        },
-    };
-};

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