backlog-mcp-server 0.20.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/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/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,7 +86,6 @@ export const allTools = (backlog, helper) => {
                     getProjectTool(backlog, helper),
                     getProjectUsersTool(backlog, helper),
                     updateProjectTool(backlog, helper),
-                    deleteProjectTool(backlog, helper),
                 ],
             },
             {

package/package.json

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