backlog-mcp-server 0.5.0 → 0.6.0

package/README.md

@@ -212,6 +212,10 @@ Tools for managing issues, their comments, and related items like priorities, ca
 - `get_resolutions`: Returns list of issue resolutions.
 - `get_watching_list_items`: Returns list of watching items for a user.
 - `get_watching_list_count`: Returns count of watching items for a user.
+- `add_watching`: Adds a new watch to an issue.
+- `update_watching`: Updates an existing watch note.
+- `delete_watching`: Deletes a watch from an issue.
+- `mark_watching_as_read`: Marks a watch as read.
 - `get_version_milestone_list`: Returns list of version milestones for a project.
 - `add_version_milestone`: Creates a new version milestone for a project.
 - `update_version_milestone`: Updates an existing version milestone.

package/build/index.js

@@ -62,10 +62,7 @@ Available toolsets:
 const useFields = argv.optimizeResponse;
 const server = wrapServerWithToolRegistry(new McpServer({
     name: 'backlog',
-    description: useFields
-        ? `You can include only the fields you need using GraphQL-style syntax.
-Start with the example above and customize freely.`
-        : undefined,
+    title: useFields ? 'backlog (field selection enabled)' : 'backlog',
     version: VERSION,
 }));
 const transHelper = createTranslationHelper();

package/build/tools/addWatching.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import { buildToolSchema } from '../types/tool.js';
+import { WatchingListItemSchema } from '../types/zod/backlogOutputDefinition.js';
+const addWatchingSchema = buildToolSchema((t) => ({
+    issueIdOrKey: z
+        .union([z.number(), z.string()])
+        .describe(t('TOOL_ADD_WATCHING_ISSUE_ID_OR_KEY', 'Issue ID or issue key (e.g., 1234 or "PROJECT-123")')),
+    note: z
+        .string()
+        .describe(t('TOOL_ADD_WATCHING_NOTE', 'Optional note for the watch'))
+        .optional()
+        .default(''),
+}));
+export const addWatchingTool = (backlog, { t }) => {
+    return {
+        name: 'add_watching',
+        description: t('TOOL_ADD_WATCHING_DESCRIPTION', 'Adds a new watch to an issue'),
+        schema: z.object(addWatchingSchema(t)),
+        outputSchema: WatchingListItemSchema,
+        handler: async ({ issueIdOrKey, note }) => backlog.postWatchingListItem({
+            issueIdOrKey,
+            note,
+        }),
+    };
+};

package/build/tools/deleteWatching.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { buildToolSchema } from '../types/tool.js';
+import { WatchingListItemSchema } from '../types/zod/backlogOutputDefinition.js';
+const deleteWatchingSchema = buildToolSchema((t) => ({
+    watchId: z
+        .number()
+        .describe(t('TOOL_DELETE_WATCHING_WATCH_ID', 'Watch ID to delete')),
+}));
+export const deleteWatchingTool = (backlog, { t }) => {
+    return {
+        name: 'delete_watching',
+        description: t('TOOL_DELETE_WATCHING_DESCRIPTION', 'Deletes a watch from an issue'),
+        schema: z.object(deleteWatchingSchema(t)),
+        outputSchema: WatchingListItemSchema,
+        handler: async ({ watchId }) => backlog.deletehWatchingListItem(watchId),
+    };
+};

package/build/tools/markWatchingAsRead.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import { buildToolSchema } from '../types/tool.js';
+const markWatchingAsReadSchema = buildToolSchema((t) => ({
+    watchId: z
+        .number()
+        .describe(t('TOOL_MARK_WATCHING_AS_READ_WATCH_ID', 'Watch ID to mark as read')),
+}));
+export const MarkWatchingAsReadResultSchema = z.object({
+    success: z.boolean(),
+    message: z.string(),
+});
+export const markWatchingAsReadTool = (backlog, { t }) => {
+    return {
+        name: 'mark_watching_as_read',
+        description: t('TOOL_MARK_WATCHING_AS_READ_DESCRIPTION', 'Mark a watch as read'),
+        schema: z.object(markWatchingAsReadSchema(t)),
+        outputSchema: MarkWatchingAsReadResultSchema,
+        handler: async ({ watchId }) => {
+            await backlog.resetWatchingListItemAsRead(watchId);
+            return {
+                success: true,
+                message: `Watch ${watchId} marked as read`,
+            };
+        },
+    };
+};

package/build/tools/tools.js

@@ -4,6 +4,7 @@ import { addProjectTool } from './addProject.js';
 import { addPullRequestTool } from './addPullRequest.js';
 import { addPullRequestCommentTool } from './addPullRequestComment.js';
 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';
@@ -30,6 +31,10 @@ import { getSpaceTool } from './getSpace.js';
 import { getUsersTool } from './getUsers.js';
 import { getWatchingListCountTool } from './getWatchingListCount.js';
 import { getWatchingListItemsTool } from './getWatchingListItems.js';
+import { addWatchingTool } from './addWatching.js';
+import { updateWatchingTool } from './updateWatching.js';
+import { deleteWatchingTool } from './deleteWatching.js';
+import { markWatchingAsReadTool } from './markWatchingAsRead.js';
 import { getWikiTool } from './getWiki.js';
 import { getWikiPagesTool } from './getWikiPages.js';
 import { getWikisCountTool } from './getWikisCount.js';
@@ -91,6 +96,10 @@ export const allTools = (backlog, helper) => {
                     getResolutionsTool(backlog, helper),
                     getWatchingListItemsTool(backlog, helper),
                     getWatchingListCountTool(backlog, helper),
+                    addWatchingTool(backlog, helper),
+                    updateWatchingTool(backlog, helper),
+                    deleteWatchingTool(backlog, helper),
+                    markWatchingAsReadTool(backlog, helper),
                     getVersionMilestoneListTool(backlog, helper),
                     addVersionMilestoneTool(backlog, helper),
                     updateVersionMilestoneTool(backlog, helper),
@@ -106,6 +115,7 @@ export const allTools = (backlog, helper) => {
                     getWikisCountTool(backlog, helper),
                     getWikiTool(backlog, helper),
                     addWikiTool(backlog, helper),
+                    updateWikiTool(backlog, helper),
                 ],
             },
             {

package/build/tools/updateWatching.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import { buildToolSchema } from '../types/tool.js';
+import { WatchingListItemSchema } from '../types/zod/backlogOutputDefinition.js';
+const updateWatchingSchema = buildToolSchema((t) => ({
+    watchId: z.number().describe(t('TOOL_UPDATE_WATCHING_WATCH_ID', 'Watch ID')),
+    note: z
+        .string()
+        .describe(t('TOOL_UPDATE_WATCHING_NOTE', 'Updated note for the watch')),
+}));
+export const updateWatchingTool = (backlog, { t }) => {
+    return {
+        name: 'update_watching',
+        description: t('TOOL_UPDATE_WATCHING_DESCRIPTION', 'Updates an existing watch note'),
+        schema: z.object(updateWatchingSchema(t)),
+        outputSchema: WatchingListItemSchema,
+        handler: async ({ watchId, note }) => backlog.patchWatchingListItem(watchId, note),
+    };
+};

package/build/tools/updateWiki.js

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import { buildToolSchema } from '../types/tool.js';
+import { WikiSchema } from '../types/zod/backlogOutputDefinition.js';
+const updateWikiSchema = buildToolSchema((t) => ({
+    wikiId: z
+        .union([z.string(), z.number()])
+        .describe(t('TOOL_UPDATE_WIKI_ID', 'Wiki ID')),
+    name: z
+        .string()
+        .optional()
+        .describe(t('TOOL_UPDATE_WIKI_NAME', 'Name of the wiki page')),
+    content: z
+        .string()
+        .optional()
+        .describe(t('TOOL_UPDATE_WIKI_CONTENT', 'Content of the wiki page')),
+    mailNotify: z
+        .boolean()
+        .optional()
+        .describe(t('TOOL_UPDATE_WIKI_MAIL_NOTIFY', 'Whether to send notification emails (default: false)')),
+}));
+export const updateWikiTool = (backlog, { t }) => {
+    return {
+        name: 'update_wiki',
+        description: t('TOOL_UPDATE_WIKI_DESCRIPTION', 'Updates an existing wiki page'),
+        schema: z.object(updateWikiSchema(t)),
+        outputSchema: WikiSchema,
+        importantFields: ['id', 'name', 'content', 'updatedUser'],
+        handler: async ({ wikiId, name, content, mailNotify }) => {
+            const wikiIdNumber = typeof wikiId === 'string' ? parseInt(wikiId, 10) : wikiId;
+            return backlog.patchWiki(wikiIdNumber, {
+                name,
+                content,
+                mailNotify,
+            });
+        },
+    };
+};

package/build/version.js

@@ -1 +1 @@
-export const VERSION = '0.4.0';
+export const VERSION = '0.6.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backlog-mcp-server",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "bin": {
     "backlog-mcp-server": "./build/index.js"
@@ -21,13 +21,12 @@
     "build"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.9.0",
+    "@modelcontextprotocol/sdk": "^1.24.0",
     "backlog-js": "^0.15.0",
     "cosmiconfig": "^9.0.0",
     "dotenv": "^16.5.0",
     "env-var": "^7.5.0",
     "graphql": "^16.11.0",
-    "node-fetch": "^3.3.2",
     "pino": "^9.9.0",
     "pino-pretty": "^13.1.1",
     "yargs": "^18.0.0",
@@ -36,7 +35,7 @@
   "devDependencies": {
     "@eslint/js": "^9.24.0",
     "tsx": "^4.20.6",
-    "@release-it/conventional-changelog": "^10.0.1",
+    "@release-it/conventional-changelog": "^10.0.2",
     "@types/jest": "^29.5.14",
     "@types/node": "^22.14.1",
     "@types/yargs": "^17.0.33",

package/build/config.js

@@ -1,99 +0,0 @@
-// Copyright (c) 2025 Nulab inc.
-// Licensed under the MIT License.
-import dotenv from 'dotenv';
-import { default as env } from 'env-var';
-import yargs from 'yargs';
-import { hideBin } from 'yargs/helpers';
-import { VERSION } from './version.js';
-dotenv.config();
-// Define Read Guard policies
-const READ_GUARD_POLICIES = ['off', 'filter', 'deny'];
-// Define Write Guard policies
-const WRITE_GUARD_POLICIES = ['on', 'off'];
-export const config = yargs(hideBin(process.argv))
-    .option('backlog-domain', {
-    type: 'string',
-    describe: 'Backlog domain',
-    default: env.get('BACKLOG_DOMAIN').required().asString(),
-})
-    .option('backlog-api-key', {
-    type: 'string',
-    describe: 'Backlog API key',
-    default: env.get('BACKLOG_API_KEY').required().asString(),
-})
-    .option('max-tokens', {
-    type: 'number',
-    describe: 'Maximum number of tokens allowed in the response',
-    default: env.get('MAX_TOKENS').default('50000').asIntPositive(),
-})
-    .option('optimize-response', {
-    type: 'boolean',
-    describe: 'Enable GraphQL-style response optimization to include only requested fields',
-    default: env.get('OPTIMIZE_RESPONSE').default('false').asBool(),
-})
-    .option('prefix', {
-    type: 'string',
-    describe: 'Optional string prefix to prepend to all generated outputs',
-    default: env.get('PREFIX').default('').asString(),
-})
-    .option('export-translations', {
-    type: 'boolean',
-    describe: 'Export translations and exit',
-    default: false,
-})
-    .option('enable-toolsets', {
-    type: 'array',
-    describe: `Specify which toolsets to enable. Defaults to 'all'.`,
-    default: env.get('ENABLE_TOOLSETS').default('all').asArray(','),
-})
-    .option('dynamic-toolsets', {
-    type: 'boolean',
-    describe: 'Enable dynamic toolsets such as enable_toolset, list_available_toolsets, etc.',
-    default: env.get('ENABLE_DYNAMIC_TOOLSETS').default('false').asBool(),
-})
-    // Project-Scoped Access Controls
-    .option('allowed-project-ids', {
-    type: 'array',
-    describe: 'Comma-separated list of allowed Backlog project IDs',
-    default: env.get('BACKLOG_ALLOWED_PROJECT_IDS').default('').asArray(',').filter(Boolean),
-})
-    .option('allowed-project-keys', {
-    type: 'array',
-    describe: 'Comma-separated list of allowed Backlog project keys',
-    default: env.get('BACKLOG_ALLOWED_PROJECT_KEYS').default('').asArray(',').filter(Boolean),
-})
-    .option('write-guard', {
-    choices: WRITE_GUARD_POLICIES,
-    describe: 'Policy for write operations (create/update/delete)',
-    default: env
-        .get('BACKLOG_WRITE_GUARD')
-        .default('off')
-        .asEnum(WRITE_GUARD_POLICIES),
-})
-    .option('read-guard', {
-    choices: READ_GUARD_POLICIES,
-    describe: 'Policy for read operations (get/list/search)',
-    default: env
-        .get('BACKLOG_READ_GUARD')
-        .default('off')
-        .asEnum(READ_GUARD_POLICIES),
-})
-    .option('default-project-id', {
-    type: 'number',
-    describe: 'Default project ID to use for create operations when project is omitted',
-    default: env.get('BACKLOG_DEFAULT_PROJECT_ID').asInt(),
-})
-    .option('unguarded-ok', {
-    type: 'string',
-    describe: 'Explicitly allow running in production without guards',
-    default: env.get('BACKLOG_UNGUARDED_OK').asString(),
-})
-    .option('key-resolve-ttl-sec', {
-    type: 'number',
-    describe: 'Cache TTL in seconds for project key-to-ID resolution',
-    default: env.get('BACKLOG_KEY_RESOLVE_TTL_SEC').default(300).asInt(),
-})
-    .version(VERSION)
-    .help()
-    .alias('h', 'help')
-    .parseSync();

package/build/errors/ProjectAccessForbiddenError.js

@@ -1,11 +0,0 @@
-// Copyright (c) 2025 Nulab inc.
-// Licensed under the MIT License.
-export class ProjectAccessForbiddenError extends Error {
-    code = -32040;
-    data;
-    constructor(message, data) {
-        super(message);
-        this.name = 'ProjectAccessForbiddenError';
-        this.data = data;
-    }
-}

package/build/guards/ProjectGuardService.js

@@ -1,87 +0,0 @@
-// Copyright (c) 2025 Nulab inc.
-// Licensed under the MIT License.
-import { logger } from '../utils/logger.js';
-export class ProjectGuardService {
-    allowedProjectIds = new Set();
-    projectKeyCache = new Map();
-    config;
-    backlog;
-    constructor(backlog, config) {
-        this.backlog = backlog;
-        this.config = config;
-    }
-    async initialize() {
-        // 1. Parse IDs from config
-        this.config.allowedProjectIds.forEach((id) => {
-            const numericId = Number(id);
-            if (!isNaN(numericId)) {
-                this.allowedProjectIds.add(numericId);
-            }
-        });
-        if (this.config.allowedProjectKeys.length > 0) {
-            const projects = await this.backlog.getProjects();
-            const projectMap = new Map();
-            projects.forEach((p) => projectMap.set(p.projectKey, p.id));
-            for (const key of this.config.allowedProjectKeys) {
-                const id = projectMap.get(key);
-                if (id) {
-                    this.allowedProjectIds.add(id);
-                }
-                else {
-                    throw new Error(`Failed to resolve project key: ${key}`);
-                }
-            }
-        }
-        this.performStartupValidation();
-    }
-    performStartupValidation() {
-        const isProduction = process.env.NODE_ENV === 'production';
-        const guardsEnabled = this.config.readGuard !== 'off' || this.config.writeGuard !== 'off';
-        if (guardsEnabled && this.allowedProjectIds.size === 0) {
-            throw new Error('FATAL: Guards are enabled but no allowed projects are configured.');
-        }
-        if (this.allowedProjectIds.size > 0 && !guardsEnabled) {
-            const message = 'WARNING: Allowed projects are configured but both read and write guards are off.';
-            if (isProduction) {
-                throw new Error(`FATAL: ${message}`);
-            }
-            else {
-                logger.warn(message);
-            }
-        }
-        if (this.allowedProjectIds.size === 0 &&
-            !guardsEnabled &&
-            isProduction) {
-            if (this.config.unguardedOk !== 'I_UNDERSTAND_THE_RISKS') {
-                throw new Error('FATAL: Running in production without guards requires BACKLOG_UNGUARDED_OK=I_UNDERSTAND_THE_RISKS');
-            }
-        }
-        else if (this.allowedProjectIds.size === 0 && !guardsEnabled) {
-            logger.warn('WARNING: Server is running in a fully unguarded mode.');
-        }
-    }
-    get readGuardPolicy() {
-        return this.config.readGuard;
-    }
-    get writeGuardPolicy() {
-        return this.config.writeGuard;
-    }
-    isAllowed(projectId) {
-        if (this.allowedProjectIds.size === 0) {
-            return true; // No restrictions
-        }
-        return this.allowedProjectIds.has(projectId);
-    }
-    filterProjectIds(projectIds) {
-        if (this.allowedProjectIds.size === 0) {
-            return projectIds;
-        }
-        return projectIds.filter((id) => this.allowedProjectIds.has(id));
-    }
-    getAllowedProjectIds() {
-        return this.allowedProjectIds;
-    }
-    getDefaultProjectId() {
-        return this.config.defaultProjectId;
-    }
-}

package/build/handlers/transformers/wrapWithProjectGuard.js

@@ -1,100 +0,0 @@
-// Copyright (c) 2025 Nulab inc.
-// Licensed under the MIT License.
-import { ProjectAccessForbiddenError, } from '../../errors/ProjectAccessForbiddenError.js';
-import { logger } from '../../utils/logger.js';
-const getOperationType = (toolName) => {
-    const lowerToolName = toolName.toLowerCase();
-    if (lowerToolName.startsWith('add') ||
-        lowerToolName.startsWith('update') ||
-        lowerToolName.startsWith('delete') ||
-        lowerToolName.includes('mark') ||
-        lowerToolName.includes('reset')) {
-        return 'write';
-    }
-    if (lowerToolName.startsWith('get') ||
-        lowerToolName.startsWith('count') ||
-        lowerToolName.startsWith('list')) {
-        return 'read';
-    }
-    return 'neutral';
-};
-export const wrapWithProjectGuard = (handler, toolName, guardService, backlog) => {
-    return async (params) => {
-        const operationType = getOperationType(toolName);
-        const { projectId, projectKey } = params;
-        if (operationType === 'write') {
-            if (guardService.writeGuardPolicy === 'on') {
-                let targetProjectId = projectId;
-                if (projectKey) {
-                    // This is a simplified resolution. A real implementation would cache.
-                    const project = await backlog.getProject(projectKey);
-                    targetProjectId = project.id;
-                }
-                if (!targetProjectId) {
-                    targetProjectId = guardService.getDefaultProjectId();
-                }
-                if (!targetProjectId || !guardService.isAllowed(targetProjectId)) {
-                    const errorData = {
-                        policy: 'on',
-                        allowedProjectIds: [...guardService.getAllowedProjectIds()],
-                        requestedProjectId: targetProjectId,
-                        requestedProjectKey: projectKey,
-                    };
-                    logger.warn({ toolName, operationType, result: 'blocked', ...errorData }, 'Project write access blocked');
-                    throw new ProjectAccessForbiddenError('Write operation is not allowed for this project', errorData);
-                }
-                params.projectId = targetProjectId;
-                logger.info({
-                    toolName,
-                    operationType,
-                    result: 'allowed',
-                    projectId: targetProjectId,
-                }, 'Project write access allowed');
-            }
-        }
-        else if (operationType === 'read') {
-            const policy = guardService.readGuardPolicy;
-            if (policy === 'deny') {
-                let targetProjectId = projectId;
-                if (projectKey) {
-                    const project = await backlog.getProject(projectKey);
-                    targetProjectId = project.id;
-                }
-                if (targetProjectId && !guardService.isAllowed(targetProjectId)) {
-                    const errorData = {
-                        policy: 'deny',
-                        allowedProjectIds: [...guardService.getAllowedProjectIds()],
-                        requestedProjectId: targetProjectId,
-                    };
-                    logger.warn({ toolName, operationType, result: 'blocked', ...errorData }, 'Project read access blocked');
-                    throw new ProjectAccessForbiddenError('Read operation is not allowed for this project', errorData);
-                }
-                if (!targetProjectId && guardService.getAllowedProjectIds().size > 1) {
-                    const errorData = {
-                        policy: 'deny',
-                        allowedProjectIds: [...guardService.getAllowedProjectIds()],
-                    };
-                    logger.warn({ toolName, operationType, result: 'blocked', ...errorData }, 'Project read access blocked (ambiguous project)');
-                    throw new ProjectAccessForbiddenError('Project must be specified for read operations when multiple projects are allowed.', errorData);
-                }
-                logger.info({
-                    toolName,
-                    operationType,
-                    result: 'allowed',
-                    policy,
-                    projectId: targetProjectId,
-                }, 'Project read access allowed');
-            }
-            else if (policy === 'filter') {
-                const allowedIds = [...guardService.getAllowedProjectIds()];
-                if (params.projectId) {
-                    params.projectId = guardService.filterProjectIds(Array.isArray(params.projectId) ? params.projectId : [params.projectId]);
-                }
-                else {
-                    params.projectId = allowedIds;
-                }
-            }
-        }
-        return handler(params);
-    };
-};

package/build/tools/downloadDocumentAttachment.js

@@ -1 +0,0 @@
-export {};