backlog-mcp-server 0.20.1 → 0.20.3

package/README.md

@@ -307,6 +307,7 @@ Tools for managing issues, their comments, and related items like priorities, ca
 - `remove_related_issue`: Removes the relation between an issue and a related issue.
 - `get_priorities`: Returns list of priorities.
 - `get_categories`: Returns list of categories for a project.
+- `add_category`: Creates a new category for a project.
 - `get_custom_fields`: Returns list of custom fields for a project.
 - `get_issue_types`: Returns list of issue types for a project.
 - `get_resolutions`: Returns list of issue resolutions.

package/build/auth/backlogOAuthClient.d.ts

@@ -1,5 +1,29 @@
 import type { BacklogOAuthConfig } from './backlogOAuthConfig.js';
 import type { BacklogTokenData } from './tokenStore.js';
+/**
+ * A failed Backlog token call, carrying what the caller needs to decide what to
+ * tell the client.
+ *
+ * Whether Backlog rejected the credential or could not be reached decides
+ * whether the client should authorize again or back off and retry. Folded into
+ * a message string the two are the same exception, and the caller is left
+ * parsing prose to tell them apart.
+ *
+ * `status` is absent when the request never produced a response — DNS failure,
+ * refused connection, timeout — which is unambiguously the retry case, so "no
+ * status" reads as "not a rejection" without having to guess.
+ *
+ * `errorCode` is the OAuth error code from the response body, which is where
+ * RFC 6749 §5.2 puts the reason. It is the more precise of the two: the status
+ * alone cannot separate `invalid_grant` from `invalid_client`, and those ask
+ * the caller for opposite behaviour. Absent when the body is not an OAuth error
+ * object, which is every response outside the token endpoint.
+ */
+export declare class BacklogTokenError extends Error {
+    readonly status?: number | undefined;
+    readonly errorCode?: string | undefined;
+    constructor(message: string, status?: number | undefined, errorCode?: string | undefined);
+}
 export declare function buildBacklogAuthorizationUrl(config: BacklogOAuthConfig, redirectUri: string, state: string): string;
 export declare function exchangeBacklogCode(config: BacklogOAuthConfig, code: string, redirectUri: string): Promise<BacklogTokenData>;
 export declare function refreshBacklogToken(config: BacklogOAuthConfig, refreshToken: string): Promise<BacklogTokenData>;

package/build/auth/backlogOAuthClient.js

@@ -1,5 +1,56 @@
 // Copyright (c) 2025 Nulab inc.
 // Licensed under the MIT License.
+/**
+ * A failed Backlog token call, carrying what the caller needs to decide what to
+ * tell the client.
+ *
+ * Whether Backlog rejected the credential or could not be reached decides
+ * whether the client should authorize again or back off and retry. Folded into
+ * a message string the two are the same exception, and the caller is left
+ * parsing prose to tell them apart.
+ *
+ * `status` is absent when the request never produced a response — DNS failure,
+ * refused connection, timeout — which is unambiguously the retry case, so "no
+ * status" reads as "not a rejection" without having to guess.
+ *
+ * `errorCode` is the OAuth error code from the response body, which is where
+ * RFC 6749 §5.2 puts the reason. It is the more precise of the two: the status
+ * alone cannot separate `invalid_grant` from `invalid_client`, and those ask
+ * the caller for opposite behaviour. Absent when the body is not an OAuth error
+ * object, which is every response outside the token endpoint.
+ */
+export class BacklogTokenError extends Error {
+    status;
+    errorCode;
+    constructor(message, status, errorCode) {
+        super(message);
+        this.status = status;
+        this.errorCode = errorCode;
+        this.name = 'BacklogTokenError';
+    }
+}
+/**
+ * The `error` field of an RFC 6749 §5.2 error response, if the body is one.
+ *
+ * Best effort by design: a proxy or a WAF can answer the token endpoint with
+ * HTML, and a body that is not an OAuth error object simply carries no code.
+ */
+function readOAuthErrorCode(body) {
+    try {
+        const parsed = JSON.parse(body);
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            'error' in parsed &&
+            typeof parsed.error === 'string') {
+            return parsed.error;
+        }
+    }
+    catch {
+        // Not JSON. Nothing to read, and nothing worth reporting either: the
+        // status and the raw text are already in the message.
+    }
+    return undefined;
+}
 export function buildBacklogAuthorizationUrl(config, redirectUri, state) {
     const params = new URLSearchParams({
         response_type: 'code',
@@ -35,23 +86,35 @@ export async function refreshBacklogToken(config, refreshToken) {
         client_secret: config.clientSecret,
         refresh_token: refreshToken,
     });
-    const response = await fetch(`https://${config.backlogDomain}/api/v2/oauth2/token`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-        body: params.toString(),
-    });
+    let response;
+    try {
+        response = await fetch(`https://${config.backlogDomain}/api/v2/oauth2/token`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: params.toString(),
+        });
+    }
+    catch (err) {
+        throw new BacklogTokenError(`Could not reach Backlog to refresh the token: ${String(err)}`);
+    }
     if (!response.ok) {
         const text = await response.text();
-        throw new Error(`Backlog token refresh failed (${response.status}): ${text}`);
+        throw new BacklogTokenError(`Backlog token refresh failed (${response.status}): ${text}`, response.status, readOAuthErrorCode(text));
     }
     return await response.json();
 }
 export async function verifyBacklogToken(domain, accessToken) {
-    const response = await fetch(`https://${domain}/api/v2/users/myself`, {
-        headers: { Authorization: `Bearer ${accessToken}` },
-    });
+    let response;
+    try {
+        response = await fetch(`https://${domain}/api/v2/users/myself`, {
+            headers: { Authorization: `Bearer ${accessToken}` },
+        });
+    }
+    catch (err) {
+        throw new BacklogTokenError(`Could not reach Backlog to verify the token: ${String(err)}`);
+    }
     if (!response.ok) {
-        throw new Error(`Backlog token verification failed (${response.status})`);
+        throw new BacklogTokenError(`Backlog token verification failed (${response.status})`, response.status);
     }
     return await response.json();
 }

package/build/auth/bearerAuthMiddleware.js

@@ -1,6 +1,6 @@
 // Copyright (c) 2025 Nulab inc.
 // Licensed under the MIT License.
-import { verifyBacklogToken } from './backlogOAuthClient.js';
+import { BacklogTokenError, verifyBacklogToken } from './backlogOAuthClient.js';
 import { hasBacklogAuthErrorBeenReported, runWithAccessToken, } from './backlogAuthContext.js';
 import { logger } from '../utils/logger.js';
 const CACHE_TTL_MS = 5 * 60 * 1000;
@@ -44,7 +44,27 @@ export function createBearerAuthMiddleware(store, config, mcpPath) {
                 store.cacheVerification(mcpToken, authInfo, CACHE_TTL_MS);
             }
             catch (err) {
-                logger.warn({ err }, 'Bearer token verification failed');
+                // Only Backlog rejecting the token means this client should
+                // authenticate again. A Backlog outage answered with 401 would send
+                // every connected client through the whole authorization flow, and the
+                // token that flow produced would fail verification just the same.
+                const rejected = err instanceof BacklogTokenError &&
+                    (err.status === 401 || err.status === 403);
+                if (!rejected) {
+                    logger.error({ err }, 'Could not verify the bearer token with Backlog');
+                    c.header('Retry-After', '30');
+                    return c.json({
+                        error: 'temporarily_unavailable',
+                        error_description: 'Could not verify the token with Backlog',
+                    }, 503);
+                }
+                // A rejection here is the same fact `onAuthError` below acts on — the
+                // stored Backlog token is spent — so it gets the same treatment.
+                // Dropping the entry is what makes this recoverable: the client's next
+                // request fails the `getMcpToken` check above, and it reaches for its
+                // refresh token instead of replaying a credential that cannot work.
+                logger.warn({ err, clientId: tokenEntry.clientId }, 'Backlog rejected the stored access token during verification; revoking the MCP token');
+                store.revokeMcpToken(mcpToken);
                 return unauthorized('Token verification failed');
             }
         }

package/build/auth/oauthRoutes.js

@@ -2,10 +2,12 @@
 // Licensed under the MIT License.
 import { randomUUID, randomBytes, createHash } from 'node:crypto';
 import { Hono } from 'hono';
-import { buildBacklogAuthorizationUrl, exchangeBacklogCode, refreshBacklogToken, } from './backlogOAuthClient.js';
+import { BacklogTokenError, buildBacklogAuthorizationUrl, exchangeBacklogCode, refreshBacklogToken, } from './backlogOAuthClient.js';
 import { logger } from '../utils/logger.js';
 const AUTH_CODE_TTL_MS = 10 * 60 * 1000;
 const REFRESH_TOKEN_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+/** Seconds left until `expiresAt`, floored at zero so it is never negative. */
+const remainingSeconds = (expiresAt) => Math.max(0, Math.floor((expiresAt - Date.now()) / 1000));
 const LOCALHOST_HOSTS = ['localhost', '127.0.0.1', '[::1]'];
 const SUPPORTED_AUTH_METHODS = ['client_secret_post', 'none'];
 function verifyPkce(codeVerifier, codeChallenge) {
@@ -278,6 +280,9 @@ export function createOAuthRoutes(config, store, mcpPath) {
         store.storeAuthCode(mcpCode, {
             mcpClientId: pending.mcpClientId,
             backlogTokens,
+            // Resolved here, against the response just received, rather than at
+            // `/token` where `expires_in` would be counted from the wrong instant.
+            backlogAccessTokenExpiresAt: Date.now() + backlogTokens.expires_in * 1000,
             codeChallenge: pending.codeChallenge,
             redirectUri: pending.redirectUri,
             resource: pending.resource,
@@ -336,7 +341,7 @@ export function createOAuthRoutes(config, store, mcpPath) {
             store.storeMcpToken(mcpAccessToken, {
                 backlogAccessToken: entry.backlogTokens.access_token,
                 clientId,
-                expiresAt: Date.now() + entry.backlogTokens.expires_in * 1000,
+                expiresAt: entry.backlogAccessTokenExpiresAt,
             });
             store.storeMcpRefreshToken(mcpRefreshToken, {
                 backlogRefreshToken: entry.backlogTokens.refresh_token,
@@ -346,7 +351,10 @@ export function createOAuthRoutes(config, store, mcpPath) {
             return c.json({
                 access_token: mcpAccessToken,
                 token_type: 'bearer',
-                expires_in: entry.backlogTokens.expires_in,
+                // What is left, not what Backlog reported at `/callback`. A client
+                // uses this to decide when to refresh, so handing it the original
+                // duration would have it wait past the real expiry.
+                expires_in: remainingSeconds(entry.backlogAccessTokenExpiresAt),
                 refresh_token: mcpRefreshToken,
             });
         }
@@ -384,6 +392,34 @@ export function createOAuthRoutes(config, store, mcpPath) {
                 });
             }
             catch (err) {
+                // `invalid_grant` is Backlog stating the grant is gone: revoked from
+                // the user's settings, or a refresh token it no longer recognises.
+                // That is the one answer that moves the client to a fresh
+                // authorization. Reported as 503 the same failure asks it to back off
+                // and retry a grant that can never come back, so it retries on a
+                // schedule forever. The consumed entry stays consumed in this branch:
+                // what it holds is a refresh token Backlog has already disowned, and
+                // keeping it until its TTL lapses only hands the next attempt the same
+                // dead credential.
+                //
+                // The code is read from the body rather than inferred from the status,
+                // because the status cannot separate the two rejections the token
+                // endpoint makes: `invalid_client` rejects *this server's* credentials,
+                // which is the operator's misconfiguration and not the client's grant,
+                // and re-authorizing would fail at the same wall. A bare 400 with no
+                // readable code is still treated as a dead grant — that is what the
+                // status means on this endpoint when nothing more specific is said.
+                //
+                // Everything else leaves the grant's fate unknown — unreachable, a
+                // timeout, a 5xx, a rejected client secret — so the entry goes back and
+                // the client is told to retry.
+                const grantIsGone = err instanceof BacklogTokenError &&
+                    (err.errorCode === 'invalid_grant' ||
+                        (err.status === 400 && err.errorCode === undefined));
+                if (grantIsGone) {
+                    logger.warn({ err, clientId }, 'Backlog no longer recognizes the refresh grant; the client must authorize again');
+                    return c.json(oauthError('invalid_grant', 'Backlog no longer recognizes this grant. A new authorization is required.'), 400);
+                }
                 logger.error({ err }, 'Failed to refresh Backlog token');
                 store.storeMcpRefreshToken(refreshToken, refreshEntry);
                 return c.json(oauthError('server_error', 'Failed to refresh upstream token'), 503);

package/build/auth/tokenStore.d.ts

@@ -28,6 +28,17 @@ type PendingAuthorization = {
 type AuthCodeEntry = {
     mcpClientId: string;
     backlogTokens: BacklogTokenData;
+    /**
+     * When the Backlog access token in `backlogTokens` actually expires, in
+     * epoch milliseconds, resolved at `/callback`.
+     *
+     * `backlogTokens.expires_in` is a duration counted from the moment Backlog
+     * answered, and this entry then sits here until the client redeems the code
+     * — up to `AUTH_CODE_TTL_MS`. Re-basing that duration at `/token` would put
+     * the expiry later than the real one by however long the redemption took,
+     * leaving a window where this server treats a spent Backlog token as live.
+     */
+    backlogAccessTokenExpiresAt: number;
     codeChallenge: string;
     redirectUri: string;
     resource?: string;

package/build/tools/addCategory.d.ts

@@ -0,0 +1,12 @@
+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 addCategorySchema: (t: DescriptionHelper['t']) => {
+    projectId: z.ZodOptional<z.ZodNumber>;
+    projectKey: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+};
+export declare const addCategoryTool: (backlog: Backlog, { t }: DescriptionHelper) => ToolDefinition<ReturnType<typeof addCategorySchema>, Entity.Project.Category>;
+export {};

package/build/tools/addCategory.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { buildToolSchema } from '../types/tool.js';
+import { outputFields } from '../types/outputFields.js';
+import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
+const addCategorySchema = buildToolSchema((t) => ({
+    projectId: z
+        .number()
+        .optional()
+        .describe(t('TOOL_ADD_CATEGORY_PROJECT_ID', 'The numeric ID of the project (e.g., 12345)')),
+    projectKey: z
+        .string()
+        .optional()
+        .describe(t('TOOL_ADD_CATEGORY_PROJECT_KEY', "The key of the project (e.g., 'PROJECT')")),
+    name: z
+        .string()
+        .describe(t('TOOL_ADD_CATEGORY_NAME', 'The name of the category')),
+}));
+export const addCategoryTool = (backlog, { t }) => {
+    return {
+        name: 'add_category',
+        description: t('TOOL_ADD_CATEGORY_DESCRIPTION', 'Creates a new category for a project'),
+        schema: z.object(addCategorySchema(t)),
+        importantFields: ['id', 'projectId', 'name'],
+        returnsList: false,
+        outputFields: outputFields()([
+            'id',
+            'projectId',
+            'name',
+            'displayOrder',
+        ]),
+        handler: async ({ projectId, projectKey, ...params }) => {
+            const result = resolveIdOrKey('project', { id: projectId, key: projectKey }, t);
+            if (!result.ok) {
+                throw result.error;
+            }
+            return backlog.postCategories(result.value, params);
+        },
+    };
+};

package/build/tools/tools.js

@@ -7,6 +7,7 @@ import { addWikiTool } from './addWiki.js';
 import { updateWikiTool } from './updateWiki.js';
 import { countIssuesTool } from './countIssues.js';
 import { deleteIssueTool } from './deleteIssue.js';
+import { addCategoryTool } from './addCategory.js';
 import { getCategoriesTool } from './getCategories.js';
 import { getCustomFieldsTool } from './getCustomFields.js';
 import { getGitRepositoriesTool } from './getGitRepositories.js';
@@ -108,6 +109,7 @@ export const allTools = (backlog, helper) => {
                     removeRelatedIssueTool(backlog, helper),
                     getPrioritiesTool(backlog, helper),
                     getCategoriesTool(backlog, helper),
+                    addCategoryTool(backlog, helper),
                     getCustomFieldsTool(backlog, helper),
                     getIssueTypesTool(backlog, helper),
                     getResolutionsTool(backlog, helper),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backlog-mcp-server",
-  "version": "0.20.1",
+  "version": "0.20.3",
   "type": "module",
   "bin": {
     "backlog-mcp-server": "./build/index.js"
@@ -42,20 +42,20 @@
     "js-yaml": "^5.4.1",
     "pino": "^10.3.1",
     "yargs": "^18.1.0",
-    "zod": "^4.4.3"
+    "zod": "^4.5.4"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^26.4.0",
+    "@types/node": "^26.4.1",
     "@types/yargs": "^17.0.35",
-    "@vitest/coverage-v8": "^4.1.11",
-    "oxfmt": "^0.65.0",
-    "oxlint": "^1.80.0",
+    "@vitest/coverage-v8": "^5.0.0",
+    "oxfmt": "^0.66.0",
+    "oxlint": "^1.81.0",
     "oxlint-tsgolint": "^7.0.2001",
     "pino-pretty": "^13.1.3",
-    "tsx": "^4.23.12",
+    "tsx": "^4.23.13",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.0"
   },
   "scripts": {
     "preinstall": "npx only-allow pnpm",