backlog-mcp-server 0.4.0 → 0.5.0

package/README.ja.md

@@ -12,6 +12,7 @@ Backlog API とやり取りするための Model Context Protocol（MCP）サー
 
 - プロジェクトツール（作成、読み取り、更新、削除）
 - 課題とコメントの追跡（作成、更新、削除、一覧表示）
+- 発生バージョン/マイルストーンの管理（作成、読み取り、更新、削除）
 - Wikiページサポート
 - Gitリポジトリとプルリクエストツール
 - 通知ツール
@@ -65,7 +66,34 @@ Backlog API とやり取りするための Model Context Protocol（MCP）サー
 docker pull ghcr.io/nulab/backlog-mcp-server:latest
 ```
 
-### オプション2: 手動セットアップ (Node.js)
+### オプション2: npx経由でのインストール
+
+リポジトリをクローンせずに `npx` を使用してサーバーを直接実行することもできます。これは、完全なインストールなしでサーバーを実行する便利な方法です。
+
+1. MCP設定を開きます
+2. MCP設定セクションに移動します
+3. 次の設定を追加します：
+
+```json
+{
+  "mcpServers": {
+    "backlog": {
+      "command": "npx",
+      "args": [
+        "backlog-mcp-server"
+      ],
+      "env": {
+        "BACKLOG_DOMAIN": "your-domain.backlog.com",
+        "BACKLOG_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+`your-domain.backlog.com` を実際のBacklogドメインに、`your-api-key` を実際のBacklog APIキーに置き換えてください。
+
+### オプション3: 手動セットアップ (Node.js)
 
 1. クローンしてインストール：
    ```bash
@@ -105,7 +133,7 @@ docker pull ghcr.io/nulab/backlog-mcp-server:latest
 |-----------------|--------------------------------------------------------------------------------------|
 | `space`         | Backlogスペース設定と一般情報を管理するためのツール                                  |
 | `project`       | プロジェクト、カテゴリ、カスタムフィールド、課題タイプを管理するためのツール             |
-| `issue`         | 課題とそのコメントを管理するためのツール                                             |
+| `issue`         | 課題とそのコメント、発生バージョン/マイルストーンを管理するためのツール                                             |
 | `wiki`          | Wikiページを管理するためのツール                                                     |
 | `git`           | Gitリポジトリとプルリクエストを管理するためのツール                                    |
 | `notifications` | ユーザー通知を管理するためのツール                                                   |

package/README.md

@@ -12,6 +12,7 @@ A Model Context Protocol (MCP) server for interacting with the Backlog API. This
 
 - Project tools (create, read, update, delete)
 - Issue tracking and comments (create, update, delete, list)
+- Version/Milestone management (create, read, update, delete)
 - Wiki page support
 - Git repository and pull request tools
 - Notification tools
@@ -65,7 +66,34 @@ Replace `your-domain.backlog.com` with your Backlog domain and `your-api-key` wi
 docker pull ghcr.io/nulab/backlog-mcp-server:latest
 ```
 
-### Option 2: Manual Setup (Node.js)
+### Option 2: Install via npx
+
+You can also run the server directly using `npx` without cloning the repository. This is a convenient way to run the server without a full installation.
+
+1. Open MCP settings
+2. Navigate to the MCP configuration section
+3. Add the following configuration:
+
+```json
+{
+  "mcpServers": {
+    "backlog": {
+      "command": "npx",
+      "args": [
+        "backlog-mcp-server"
+      ],
+      "env": {
+        "BACKLOG_DOMAIN": "your-domain.backlog.com",
+        "BACKLOG_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+Replace `your-domain.backlog.com` with your Backlog domain and `your-api-key` with your Backlog API key.
+
+### Option 3: Manual Setup (Node.js)
 
 1. Clone and install:
    ```bash
@@ -105,7 +133,7 @@ The following toolsets are available (enabled by default when `"all"` is used):
 |-----------------|--------------------------------------------------------------------------------------|
 | `space`         | Tools for managing Backlog space settings and general information                   |
 | `project`       | Tools for managing projects, categories, custom fields, and issue types              |
-| `issue`         | Tools for managing issues and their comments                                         |
+| `issue`         | Tools for managing issues and their comments, version milestones                    |
 | `wiki`          | Tools for managing wiki pages                                                        |
 | `git`           | Tools for managing Git repositories and pull requests                                |
 | `notifications` | Tools for managing user notifications                                                |
@@ -184,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.
+- `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.
+- `delete_version_milestone`: Deletes a version milestone.
 
 ### Toolset: `wiki`
 Tools for managing wiki pages.

package/build/backlog/customFields.js

@@ -7,10 +7,64 @@ export function customFieldsToPayload(customFields) {
     }
     const result = {};
     for (const field of customFields) {
-        result[`customField_${field.id}`] = field.value;
-        if (field.otherValue) {
+        if (field.value !== undefined) {
+            result[`customField_${field.id}`] = field.value;
+        }
+        if (field.otherValue !== undefined) {
             result[`customField_${field.id}_otherValue`] = field.otherValue;
         }
     }
     return result;
 }
+export function customFieldFiltersToPayload(customFields) {
+    if (!customFields || customFields.length === 0) {
+        return {};
+    }
+    const result = {};
+    for (const field of customFields) {
+        const baseKey = `customField_${field.id}`;
+        switch (field.type) {
+            case 'text': {
+                if (field.value.trim().length > 0) {
+                    result[baseKey] = field.value;
+                }
+                break;
+            }
+            case 'numeric': {
+                if (field.min !== undefined) {
+                    result[`${baseKey}_min`] = field.min;
+                }
+                if (field.max !== undefined) {
+                    result[`${baseKey}_max`] = field.max;
+                }
+                break;
+            }
+            case 'date': {
+                if (field.min) {
+                    result[`${baseKey}_min`] = field.min;
+                }
+                if (field.max) {
+                    result[`${baseKey}_max`] = field.max;
+                }
+                break;
+            }
+            case 'list': {
+                if (Array.isArray(field.value)) {
+                    const values = field.value.filter((value) => Number.isFinite(value));
+                    if (values.length > 0) {
+                        result[`${baseKey}[]`] = values;
+                    }
+                }
+                else if (Number.isFinite(field.value)) {
+                    result[baseKey] = field.value;
+                }
+                break;
+            }
+            default: {
+                const exhaustiveCheck = field;
+                throw new Error(`Unsupported custom field filter type: ${exhaustiveCheck}`);
+            }
+        }
+    }
+    return result;
+}

package/build/config.js

@@ -0,0 +1,99 @@
+// 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

@@ -0,0 +1,11 @@
+// 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

@@ -0,0 +1,87 @@
+// 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

@@ -0,0 +1,100 @@
+// 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/index.js

@@ -11,6 +11,7 @@ import { hideBin } from 'yargs/helpers';
 import { createTranslationHelper } from './createTranslationHelper.js';
 import { registerDyamicTools, registerTools } from './registerTools.js';
 import { dynamicTools } from './tools/dynamicTools/toolsets.js';
+import { logger } from './utils/logger.js';
 import { createToolRegistrar } from './utils/toolRegistrar.js';
 import { buildToolsetGroup } from './utils/toolsetUtils.js';
 import { wrapServerWithToolRegistry } from './utils/wrapServerWithToolRegistry.js';
@@ -94,9 +95,9 @@ if (argv.exportTranslations) {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error('Backlog MCP Server running on stdio');
+    logger.info('Backlog MCP Server running on stdio');
 }
 main().catch((error) => {
-    console.error('Fatal error in main():', error);
+    logger.error({ err: error }, 'Fatal error in main()');
     process.exit(1);
 });

package/build/tools/addIssue.js

@@ -66,7 +66,10 @@ const addIssueSchema = buildToolSchema((t) => ({
         id: z
             .number()
             .describe(t('TOOL_ADD_ISSUE_CUSTOM_FIELD_ID', 'The ID of the custom field (e.g., 12345)')),
-        value: z.union([z.string().max(255), z.number(), z.array(z.string())]),
+        value: z
+            .union([z.number(), z.array(z.number())])
+            .optional()
+            .describe('The ID(s) of the custom field item. For single-select fields, provide a number. For multi-select fields, provide an array of numbers representing the selected item IDs.'),
         otherValue: z
             .string()
             .optional()

package/build/tools/addVersionMilestone.js

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import { buildToolSchema } from '../types/tool.js';
+import { VersionSchema } from '../types/zod/backlogOutputDefinition.js';
+import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
+const addVersionMilestoneSchema = buildToolSchema((t) => ({
+    projectId: z
+        .number()
+        .optional()
+        .describe(t('TOOL_ADD_VERSION_MILESTONE_PROJECT_ID', 'Project ID')),
+    projectKey: z
+        .string()
+        .optional()
+        .describe(t('TOOL_ADD_VERSION_MILESTONE_PROJECT_KEY', 'Project key')),
+    name: z
+        .string()
+        .describe(t('TOOL_ADD_VERSION_MILESTONE_NAME', 'Version name')),
+    description: z
+        .string()
+        .optional()
+        .describe(t('TOOL_ADD_VERSION_MILESTONE_DESCRIPTION', 'Version description')),
+    startDate: z
+        .string()
+        .optional()
+        .describe(t('TOOL_ADD_VERSION_MILESTONE_START_DATE', 'Start date of the version')),
+    releaseDueDate: z
+        .string()
+        .optional()
+        .describe(t('TOOL_ADD_VERSION_MILESTONE_RELEASE_DUE_DATE', 'Release due date of the version')),
+}));
+export const addVersionMilestoneTool = (backlog, { t }) => {
+    return {
+        name: 'add_version_milestone',
+        description: t('TOOL_ADD_VERSION_MILESTONE_DESCRIPTION', 'Creates a new version milestone'),
+        schema: z.object(addVersionMilestoneSchema(t)),
+        outputSchema: VersionSchema,
+        importantFields: [
+            'id',
+            'name',
+            'description',
+            'startDate',
+            'releaseDueDate',
+        ],
+        handler: async ({ projectId, projectKey, ...params }) => {
+            const result = resolveIdOrKey('project', { id: projectId, key: projectKey }, t);
+            if (!result.ok) {
+                throw result.error;
+            }
+            return backlog.postVersions(result.value, params);
+        },
+    };
+};

package/build/tools/countIssues.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
 import { buildToolSchema } from '../types/tool.js';
 import { IssueCountSchema } from '../types/zod/backlogOutputDefinition.js';
-import { customFieldsToPayload } from '../backlog/customFields.js';
+import { customFieldFiltersToPayload } from '../backlog/customFields.js';
+import { buildCustomFieldFilterSchema } from './shared/customFieldFiltersSchema.js';
 const countIssuesSchema = buildToolSchema((t) => ({
     projectId: z
         .array(z.number())
@@ -84,16 +85,9 @@ const countIssuesSchema = buildToolSchema((t) => ({
         .optional()
         .describe(t('TOOL_COUNT_ISSUES_UPDATED_UNTIL', 'Updated until (yyyy-MM-dd)')),
     customFields: z
-        .array(z.object({
-        id: z
-            .number()
-            .describe(t('TOOL_COUNT_ISSUES_CUSTOM_FIELD_ID', 'Custom field ID')),
-        value: z
-            .union([z.string(), z.number(), z.array(z.string())])
-            .describe(t('TOOL_COUNT_ISSUES_CUSTOM_FIELD_VALUE', 'Custom field value')),
-    }))
-        .optional()
-        .describe(t('TOOL_COUNT_ISSUES_CUSTOM_FIELDS', 'Custom fields')),
+        .array(buildCustomFieldFilterSchema(t))
+        .optional()
+        .describe(t('TOOL_COUNT_ISSUES_CUSTOM_FIELDS', 'Custom field filters (text, numeric, date, or list)')),
 }));
 export const countIssuesTool = (backlog, { t }) => {
     return {
@@ -104,7 +98,7 @@ export const countIssuesTool = (backlog, { t }) => {
         handler: async ({ customFields, ...rest }) => {
             return backlog.getIssuesCount({
                 ...rest,
-                ...customFieldsToPayload(customFields),
+                ...customFieldFiltersToPayload(customFields),
             });
         },
     };

package/build/tools/deleteVersion.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { buildToolSchema } from '../types/tool.js';
+import { VersionSchema } from '../types/zod/backlogOutputDefinition.js';
+import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
+const deleteVersionSchema = buildToolSchema((t) => ({
+    projectId: z
+        .number()
+        .optional()
+        .describe(t('TOOL_DELETE_VERSION_PROJECT_ID', 'The numeric ID of the project (e.g., 12345)')),
+    projectKey: z
+        .string()
+        .optional()
+        .describe(t('TOOL_DELETE_VERSION_PROJECT_KEY', "The key of the project (e.g., 'PROJECT')")),
+    id: z
+        .number()
+        .describe(t('TOOL_DELETE_VERSION_ID', 'The numeric ID of the version to delete (e.g., 67890)')),
+}));
+export const deleteVersionTool = (backlog, { t }) => {
+    return {
+        name: 'delete_version',
+        description: t('TOOL_DELETE_VERSION_DESCRIPTION', 'Deletes a version from a project'),
+        schema: z.object(deleteVersionSchema(t)),
+        outputSchema: VersionSchema,
+        handler: async ({ projectId, projectKey, id }) => {
+            const result = resolveIdOrKey('project', { id: projectId, key: projectKey }, t);
+            if (!result.ok) {
+                throw result.error;
+            }
+            if (!id) {
+                throw new Error(t('TOOL_DELETE_VERSION_MISSING_ID', 'Version ID is required'));
+            }
+            return backlog.deleteVersions(result.value, id);
+        },
+    };
+};

package/build/tools/getIssues.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
 import { buildToolSchema } from '../types/tool.js';
 import { IssueSchema } from '../types/zod/backlogOutputDefinition.js';
-import { customFieldsToPayload } from '../backlog/customFields.js';
+import { customFieldFiltersToPayload } from '../backlog/customFields.js';
+import { buildCustomFieldFilterSchema } from './shared/customFieldFiltersSchema.js';
 const getIssuesSchema = buildToolSchema((t) => ({
     projectId: z
         .array(z.number())
@@ -120,16 +121,9 @@ const getIssuesSchema = buildToolSchema((t) => ({
         .optional()
         .describe(t('TOOL_GET_ISSUES_COUNT', 'Number of issues to retrieve')),
     customFields: z
-        .array(z.object({
-        id: z
-            .number()
-            .describe(t('TOOL_GET_ISSUES_CUSTOM_FIELD_ID', 'Custom field ID')),
-        value: z
-            .union([z.string(), z.number(), z.array(z.string())])
-            .describe(t('TOOL_GET_ISSUES_CUSTOM_FIELD_VALUE', 'Custom field value')),
-    }))
-        .optional()
-        .describe(t('TOOL_GET_ISSUES_CUSTOM_FIELDS', 'Custom fields')),
+        .array(buildCustomFieldFilterSchema(t))
+        .optional()
+        .describe(t('TOOL_GET_ISSUES_CUSTOM_FIELDS', 'Custom field filters (text, numeric, date, or list)')),
 }));
 export const getIssuesTool = (backlog, { t }) => {
     return {
@@ -148,7 +142,7 @@ export const getIssuesTool = (backlog, { t }) => {
         handler: async ({ customFields, ...rest }) => {
             return backlog.getIssues({
                 ...rest,
-                ...customFieldsToPayload(customFields),
+                ...customFieldFiltersToPayload(customFields),
             });
         },
     };

package/build/tools/getVersionMilestoneList.js

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import { buildToolSchema } from '../types/tool.js';
+import { VersionSchema } from '../types/zod/backlogOutputDefinition.js';
+import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
+const getVersionMilestoneListSchema = buildToolSchema((t) => ({
+    projectId: z
+        .number()
+        .optional()
+        .describe(t('TOOL_GET_VERSION_MILESTONE_PROJECT_ID', 'The numeric ID of the project (e.g., 12345)')),
+    projectKey: z
+        .string()
+        .optional()
+        .describe(t('TOOL_GET_VERSION_MILESTONE_PROJECT_KEY', 'The key of the project (e.g., TEST_PROJECT)')),
+}));
+export const getVersionMilestoneListTool = (backlog, { t }) => {
+    return {
+        name: 'get_version_milestone_list',
+        description: t('TOOL_GET_VERSION_MILESTONE_LIST_DESCRIPTION', 'Returns list of versions/milestones in the Backlog space'),
+        schema: z.object(getVersionMilestoneListSchema(t)),
+        outputSchema: VersionSchema,
+        importantFields: [
+            'id',
+            'name',
+            'description',
+            'startDate',
+            'releaseDueDate',
+            'archived',
+        ],
+        handler: async ({ projectId, projectKey }) => {
+            const result = resolveIdOrKey('project', { id: projectId, key: projectKey }, t);
+            if (!result.ok) {
+                throw result.error;
+            }
+            return backlog.getVersions(result.value);
+        },
+    };
+};

package/build/tools/shared/customFieldFiltersSchema.js

@@ -0,0 +1,78 @@
+import { z, ZodIssueCode } from 'zod';
+export const buildCustomFieldFilterSchema = (t) => {
+    const schema = z.discriminatedUnion('type', [
+        z
+            .object({
+            type: z.literal('text'),
+            id: z
+                .number()
+                .describe(t('TOOL_CUSTOM_FIELD_FILTER_ID', 'Custom field ID (e.g., 12345)')),
+            value: z
+                .string()
+                .min(1)
+                .describe(t('TOOL_CUSTOM_FIELD_FILTER_TEXT_VALUE', 'Keyword to match for the custom field')),
+        })
+            .describe(t('TOOL_CUSTOM_FIELD_FILTER_TEXT', 'Text custom field filter')),
+        z
+            .object({
+            type: z.literal('numeric'),
+            id: z
+                .number()
+                .describe(t('TOOL_CUSTOM_FIELD_FILTER_ID', 'Custom field ID (e.g., 12345)')),
+            min: z
+                .number()
+                .optional()
+                .describe(t('TOOL_CUSTOM_FIELD_FILTER_NUMERIC_MIN', 'Minimum numeric value (inclusive)')),
+            max: z
+                .number()
+                .optional()
+                .describe(t('TOOL_CUSTOM_FIELD_FILTER_NUMERIC_MAX', 'Maximum numeric value (inclusive)')),
+        })
+            .describe(t('TOOL_CUSTOM_FIELD_FILTER_NUMERIC', 'Numeric custom field filter')),
+        z
+            .object({
+            type: z.literal('date'),
+            id: z
+                .number()
+                .describe(t('TOOL_CUSTOM_FIELD_FILTER_ID', 'Custom field ID (e.g., 12345)')),
+            min: z
+                .string()
+                .optional()
+                .describe(t('TOOL_CUSTOM_FIELD_FILTER_DATE_MIN', 'Start date (yyyy-MM-dd)')),
+            max: z
+                .string()
+                .optional()
+                .describe(t('TOOL_CUSTOM_FIELD_FILTER_DATE_MAX', 'End date (yyyy-MM-dd)')),
+        })
+            .describe(t('TOOL_CUSTOM_FIELD_FILTER_DATE', 'Date custom field filter')),
+        z
+            .object({
+            type: z.literal('list'),
+            id: z
+                .number()
+                .describe(t('TOOL_CUSTOM_FIELD_FILTER_ID', 'Custom field ID (e.g., 12345)')),
+            value: z
+                .union([z.number(), z.array(z.number()).min(1)])
+                .describe(t('TOOL_CUSTOM_FIELD_FILTER_LIST_VALUE', 'Value ID(s) to match for list-type custom field')),
+        })
+            .describe(t('TOOL_CUSTOM_FIELD_FILTER_LIST', 'List custom field filter')),
+    ]);
+    return schema.superRefine((data, ctx) => {
+        if (data.type === 'numeric' &&
+            data.min === undefined &&
+            data.max === undefined) {
+            ctx.addIssue({
+                code: ZodIssueCode.custom,
+                message: t('TOOL_CUSTOM_FIELD_FILTER_NUMERIC_REQUIRED', 'Provide at least one of min or max for numeric filters'),
+                path: ['min'],
+            });
+        }
+        if (data.type === 'date' && !data.min && !data.max) {
+            ctx.addIssue({
+                code: ZodIssueCode.custom,
+                message: t('TOOL_CUSTOM_FIELD_FILTER_DATE_REQUIRED', 'Provide at least one of min or max for date filters'),
+                path: ['min'],
+            });
+        }
+    });
+};

package/build/tools/tools.js

@@ -42,6 +42,10 @@ import { updatePullRequestCommentTool } from './updatePullRequestComment.js';
 import { getDocumentTool } from './getDocument.js';
 import { getDocumentsTool } from './getDocuments.js';
 import { getDocumentTreeTool } from './getDocumentTree.js';
+import { getVersionMilestoneListTool } from './getVersionMilestoneList.js';
+import { addVersionMilestoneTool } from './addVersionMilestone.js';
+import { updateVersionMilestoneTool } from './updateVersionMilestone.js';
+import { deleteVersionTool } from './deleteVersion.js';
 export const allTools = (backlog, helper) => {
     return {
         toolsets: [
@@ -87,6 +91,10 @@ export const allTools = (backlog, helper) => {
                     getResolutionsTool(backlog, helper),
                     getWatchingListItemsTool(backlog, helper),
                     getWatchingListCountTool(backlog, helper),
+                    getVersionMilestoneListTool(backlog, helper),
+                    addVersionMilestoneTool(backlog, helper),
+                    updateVersionMilestoneTool(backlog, helper),
+                    deleteVersionTool(backlog, helper),
                 ],
             },
             {

package/build/tools/updateIssue.js

@@ -85,7 +85,10 @@ const updateIssueSchema = buildToolSchema((t) => ({
         id: z
             .number()
             .describe(t('TOOL_UPDATE_ISSUE_CUSTOM_FIELD_ID', 'The ID of the custom field (e.g., 12345)')),
-        value: z.union([z.string().max(255), z.number(), z.array(z.string())]),
+        value: z
+            .union([z.number(), z.array(z.number())])
+            .optional()
+            .describe('The ID(s) of the custom field item. For single-select fields, provide a number. For multi-select fields, provide an array of numbers representing the selected item IDs.'),
         otherValue: z
             .string()
             .optional()

package/build/tools/updateVersionMilestone.js

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+import { buildToolSchema } from '../types/tool.js';
+import { VersionSchema } from '../types/zod/backlogOutputDefinition.js';
+import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
+const updateVersionMilestoneSchema = buildToolSchema((t) => ({
+    projectId: z
+        .number()
+        .optional()
+        .describe(t('TOOL_UPDATE_VERSION_MILESTONE_PROJECT_ID', 'The numeric ID of the project (e.g., 12345)')),
+    projectKey: z
+        .string()
+        .optional()
+        .describe(t('TOOL_UPDATE_VERSION_MILESTONE_PROJECT_KEY', "The key of the project (e.g., 'PROJECT')")),
+    id: z.number().describe(t('TOOL_UPDATE_VERSION_MILESTONE_ID', 'Version ID')),
+    name: z
+        .string()
+        .describe(t('TOOL_UPDATE_VERSION_MILESTONE_NAME', 'Version name')),
+    description: z
+        .string()
+        .optional()
+        .describe(t('TOOL_UPDATE_VERSION_MILESTONE_DESCRIPTION', 'Version description')),
+    startDate: z
+        .string()
+        .optional()
+        .describe(t('TOOL_UPDATE_VERSION_MILESTONE_START_DATE', 'Start date')),
+    releaseDueDate: z
+        .string()
+        .optional()
+        .describe(t('TOOL_UPDATE_VERSION_MILESTONE_RELEASE_DUE_DATE', 'Release due date')),
+    archived: z
+        .boolean()
+        .optional()
+        .describe(t('TOOL_UPDATE_VERSION_MILESTONE_ARCHIVED', 'Archive status of the version')),
+}));
+export const updateVersionMilestoneTool = (backlog, { t }) => {
+    return {
+        name: 'update_version_milestone',
+        description: t('TOOL_UPDATE_VERSION_MILESTONE_DESCRIPTION', 'Updates an existing version milestone'),
+        schema: z.object(updateVersionMilestoneSchema(t)),
+        outputSchema: VersionSchema,
+        importantFields: [
+            'id',
+            'name',
+            'description',
+            'startDate',
+            'releaseDueDate',
+            'archived',
+        ],
+        handler: async ({ projectId, projectKey, id, ...params }) => {
+            const result = resolveIdOrKey('project', { id: projectId, key: projectKey }, t);
+            if (!result.ok) {
+                throw result.error;
+            }
+            return backlog.patchVersions(result.value, id, params);
+        },
+    };
+};

package/build/utils/logger.js

@@ -0,0 +1,20 @@
+import pino from 'pino';
+if (!process.env.NODE_ENV) {
+    process.env.NODE_ENV = 'production';
+}
+const isProd = process.env.NODE_ENV === 'production';
+export const logger = pino({
+    level: isProd ? 'error' : 'debug',
+    transport: isProd
+        ? undefined
+        : {
+            target: 'pino-pretty',
+            options: {
+                destination: 2,
+                colorize: true,
+                translateTime: 'SYS:yyyy-mm-dd HH:MM:ss.l',
+                ignore: 'pid,hostname',
+                singleLine: true,
+            },
+        },
+}, isProd ? pino.destination({ dest: 2, sync: false }) : undefined);

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "backlog-mcp-server",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "bin": {
     "backlog-mcp-server": "./build/index.js"
   },
   "license": "MIT",
   "scripts": {
+    "dev": "tsx src/index.ts",
     "prebuild": "node scripts/replace-version.js",
     "build": "tsc && chmod 755 build/index.js",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest",
@@ -21,17 +22,20 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.9.0",
-    "backlog-js": "^0.13.6",
+    "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",
     "zod": "^3.24.3"
   },
   "devDependencies": {
     "@eslint/js": "^9.24.0",
+    "tsx": "^4.20.6",
     "@release-it/conventional-changelog": "^10.0.1",
     "@types/jest": "^29.5.14",
     "@types/node": "^22.14.1",