backlog-mcp-server 0.16.0 → 0.18.0

package/build/types/tool.d.ts

@@ -1,16 +1,32 @@
 import { z } from 'zod';
 import { DescriptionHelper } from '../createDescriptionHelper.js';
 import { CallToolResult } from '@modelcontextprotocol/server';
-export type ToolDefinition<Shape extends z.ZodRawShape, OutputShape extends z.ZodRawShape> = {
+export type ToolDefinition<Shape extends z.ZodRawShape, Result> = {
     name: string;
     description: string;
     schema: z.ZodObject<Shape>;
-    outputSchema: z.ZodObject<OutputShape>;
+    outputFields: readonly (keyof Result)[];
     handler: (input: z.infer<z.ZodObject<Shape>> & {
-        fields?: string;
+        fields?: string[];
         organization?: string;
-    }) => Promise<z.infer<z.ZodObject<OutputShape>> | z.infer<z.ZodObject<OutputShape>>[]>;
-    importantFields?: (keyof z.infer<z.ZodObject<OutputShape>>)[];
+    }) => Promise<Result | Result[]>;
+    importantFields?: (keyof Result)[];
+    /**
+     * Whether the Backlog call behind this tool returns a list.
+     *
+     * `--optimize-response` only publishes its `fields` parameter on these. A list
+     * is the case where the response grows without bound — `get_issues` alone
+     * returns up to 100 issues — and where trimming it is worth the schema every
+     * client downloads. A tool that returns one record saves a few hundred bytes at
+     * best, against a cost paid on every session by everyone.
+     *
+     * Verifiable: it is true exactly for the tools whose `backlog-js` method is
+     * declared as `Promise<T[]>`.
+     *
+     * Required rather than optional so that a new tool has to answer the question.
+     * Left optional, forgetting it would silently mean "no field selection".
+     */
+    returnsList: boolean;
 };
 export declare const buildToolSchema: <T extends z.ZodRawShape>(fn: (t: DescriptionHelper["t"]) => T) => (t: DescriptionHelper["t"]) => T;
 export type DynamicToolDefinition<Shape extends z.ZodRawShape> = {
@@ -19,6 +35,3 @@ export type DynamicToolDefinition<Shape extends z.ZodRawShape> = {
     schema: z.ZodObject<Shape>;
     handler: (input: z.infer<z.ZodObject<Shape>>) => Promise<CallToolResult>;
 };
-export interface ToolRegistrar {
-    enableToolsetAndRefresh(toolset: string): Promise<string>;
-}

package/build/types/zod/activityType.d.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+/**
+ * The activity type ids the Backlog API accepts as a filter.
+ *
+ * All that is left of backlogOutputDefinition.ts. That file described API
+ * responses in parallel with the types backlog-js already ships; tools now take
+ * their field names from those types instead. This one is different: it is an
+ * input filter, and backlog-js has no enum for it.
+ */
+export declare const ActivityTypeSchema: z.ZodEnum<{
+    Undefined: number;
+    IssueCreated: number;
+    IssueUpdated: number;
+    IssueCommented: number;
+    IssueDeleted: number;
+    WikiCreated: number;
+    WikiUpdated: number;
+    WikiDeleted: number;
+    FileAdded: number;
+    FileUpdated: number;
+    FileDeleted: number;
+    SvnCommitted: number;
+    GitPushed: number;
+    GitRepositoryCreated: number;
+    IssueMultiUpdated: number;
+    ProjectUserAdded: number;
+    ProjectUserRemoved: number;
+    NotifyAdded: number;
+    PullRequestAdded: number;
+    PullRequestUpdated: number;
+    PullRequestCommented: number;
+    PullRequestMerged: number;
+    MilestoneCreated: number;
+    MilestoneUpdated: number;
+    MilestoneDeleted: number;
+    ProjectGroupAdded: number;
+    ProjectGroupDeleted: number;
+}>;

package/build/types/zod/activityType.js

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+/**
+ * The activity type ids the Backlog API accepts as a filter.
+ *
+ * All that is left of backlogOutputDefinition.ts. That file described API
+ * responses in parallel with the types backlog-js already ships; tools now take
+ * their field names from those types instead. This one is different: it is an
+ * input filter, and backlog-js has no enum for it.
+ */
+export const ActivityTypeSchema = z.nativeEnum({
+    Undefined: -1,
+    IssueCreated: 1,
+    IssueUpdated: 2,
+    IssueCommented: 3,
+    IssueDeleted: 4,
+    WikiCreated: 5,
+    WikiUpdated: 6,
+    WikiDeleted: 7,
+    FileAdded: 8,
+    FileUpdated: 9,
+    FileDeleted: 10,
+    SvnCommitted: 11,
+    GitPushed: 12,
+    GitRepositoryCreated: 13,
+    IssueMultiUpdated: 14,
+    ProjectUserAdded: 15,
+    ProjectUserRemoved: 16,
+    NotifyAdded: 17,
+    PullRequestAdded: 18,
+    PullRequestUpdated: 19,
+    PullRequestCommented: 20,
+    PullRequestMerged: 21,
+    MilestoneCreated: 22,
+    MilestoneUpdated: 23,
+    MilestoneDeleted: 24,
+    ProjectGroupAdded: 25,
+    ProjectGroupDeleted: 26,
+});

package/build/utils/fieldSelection.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+/**
+ * Describes the `fields` parameter that `--optimize-response` adds to a tool.
+ *
+ * The selectable names come straight from the tool's `outputFields`, so they are
+ * published as a JSON Schema enum rather than described in prose. That is the
+ * whole point of the shape: the enum *is* the documentation, an unknown name is
+ * rejected by schema validation instead of being silently dropped, and the text
+ * shrinks to one sentence per tool.
+ *
+ * Selection is one level deep. It used to accept a GraphQL selection set, parsed
+ * with the `graphql` package, which cost ~1 MB for one `parse` call and accepted
+ * far more of the grammar than was ever honoured — aliases, fragments, arguments
+ * and directives all parsed and were then quietly ignored, and descending into an
+ * array field returned `{}` and lost the data.
+ */
+export declare function fieldSelection(outputFields: readonly PropertyKey[], importantFields?: readonly PropertyKey[]): {
+    names: string[];
+    description: string;
+} | undefined;
+/** The `fields` parameter itself, or undefined when the tool has nothing to offer. */
+export declare function fieldSelectionSchema(outputFields: readonly PropertyKey[], importantFields?: readonly PropertyKey[]): z.ZodOptional<z.ZodArray<z.ZodEnum<Record<string, string>>>> | undefined;

package/build/utils/fieldSelection.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+/**
+ * Describes the `fields` parameter that `--optimize-response` adds to a tool.
+ *
+ * The selectable names come straight from the tool's `outputFields`, so they are
+ * published as a JSON Schema enum rather than described in prose. That is the
+ * whole point of the shape: the enum *is* the documentation, an unknown name is
+ * rejected by schema validation instead of being silently dropped, and the text
+ * shrinks to one sentence per tool.
+ *
+ * Selection is one level deep. It used to accept a GraphQL selection set, parsed
+ * with the `graphql` package, which cost ~1 MB for one `parse` call and accepted
+ * far more of the grammar than was ever honoured — aliases, fragments, arguments
+ * and directives all parsed and were then quietly ignored, and descending into an
+ * array field returned `{}` and lost the data.
+ */
+export function fieldSelection(outputFields, importantFields = []) {
+    // `keyof T` admits numbers and symbols. Entity keys are all strings, but taking
+    // PropertyKey here keeps the caller from having to assert that.
+    const names = outputFields.map(String);
+    // `z.enum([])` is not constructible, and a tool with no known output fields has
+    // nothing to select from anyway.
+    if (names.length === 0)
+        return undefined;
+    const useful = importantFields.map(String).filter((f) => names.includes(f));
+    const description = useful.length > 0
+        ? `Return only these fields of the result, to keep the response small. Most callers want: ${useful.join(', ')}.`
+        : 'Return only these fields of the result, to keep the response small.';
+    return { names, description };
+}
+/** The `fields` parameter itself, or undefined when the tool has nothing to offer. */
+export function fieldSelectionSchema(outputFields, importantFields = []) {
+    const selection = fieldSelection(outputFields, importantFields);
+    if (!selection)
+        return undefined;
+    return z
+        .array(z.enum(selection.names))
+        .optional()
+        .describe(selection.description);
+}

package/build/utils/toolsetUtils.d.ts

@@ -1,6 +1,4 @@
 import { Backlog } from 'backlog-js';
-import { ToolsetGroup, Toolset } from '../types/toolsets.js';
+import { ToolsetGroup } from '../types/toolsets.js';
 import { DescriptionHelper } from '../createDescriptionHelper.js';
-export declare function getToolset(group: ToolsetGroup, name: string): Toolset | undefined;
-export declare function enableToolset(group: ToolsetGroup, name: string): string;
 export declare const buildToolsetGroup: (backlog: Backlog, helper: DescriptionHelper, enabledToolsets: string[]) => ToolsetGroup;

package/build/utils/toolsetUtils.js

@@ -1,16 +1,4 @@
 import { allTools } from '../tools/tools.js';
-export function getToolset(group, name) {
-    return group.toolsets.find((t) => t.name === name);
-}
-export function enableToolset(group, name) {
-    const ts = getToolset(group, name);
-    if (!ts)
-        return `Toolset ${name} not found`;
-    if (ts.enabled)
-        return `Toolset ${name} is already enabled`;
-    ts.enabled = true;
-    return `Toolset ${name} enabled`;
-}
 export const buildToolsetGroup = (backlog, helper, enabledToolsets) => {
     const toolsetGroup = allTools(backlog, helper);
     const knownNames = toolsetGroup.toolsets.map((ts) => ts.name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backlog-mcp-server",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "type": "module",
   "bin": {
     "backlog-mcp-server": "./build/index.js"
@@ -37,17 +37,17 @@
     "@modelcontextprotocol/hono": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "backlog-js": "^0.19.1",
-    "cosmiconfig": "^9.0.1",
     "env-var": "^7.5.0",
-    "graphql": "^16.14.1",
     "hono": "^4.12.34",
+    "js-yaml": "^5.2.3",
     "pino": "^10.3.1",
     "yargs": "^18.0.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^25.9.2",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^26.2.0",
     "@types/yargs": "^17.0.35",
     "@typescript-eslint/eslint-plugin": "^8.60.1",
     "@typescript-eslint/parser": "^8.60.1",

package/build/tools/dynamicTools/toolsets.d.ts

@@ -1,15 +0,0 @@
-import { z } from 'zod';
-import { DynamicToolDefinition, ToolRegistrar } from '../../types/tool.js';
-import { DynamicToolsetGroup, ToolsetGroup } from '../../types/toolsets.js';
-import { DescriptionHelper } from '../../createDescriptionHelper.js';
-export declare const dynamicTools: (toolRegistrar: ToolRegistrar, helper: DescriptionHelper, toolsetGroup: ToolsetGroup) => DynamicToolsetGroup;
-declare const enableToolsetSchema: (t: DescriptionHelper["t"]) => {
-    toolset: z.ZodString;
-};
-export declare const enableToolsetTool: (toolRegistrar: ToolRegistrar, { t }: DescriptionHelper) => DynamicToolDefinition<ReturnType<typeof enableToolsetSchema>>;
-export declare const listAvailableToolsets: ({ t }: DescriptionHelper, toolsetGroup: ToolsetGroup) => DynamicToolDefinition<Record<string, never>>;
-declare const getToolsetToolsSchema: (t: DescriptionHelper["t"]) => {
-    toolset: z.ZodString;
-};
-export declare const getToolsetTools: ({ t }: DescriptionHelper, toolsetGroup: ToolsetGroup) => DynamicToolDefinition<ReturnType<typeof getToolsetToolsSchema>>;
-export {};

package/build/tools/dynamicTools/toolsets.js

@@ -1,103 +0,0 @@
-import { z } from 'zod';
-import { buildToolSchema, } from '../../types/tool.js';
-export const dynamicTools = function (toolRegistrar, helper, toolsetGroup) {
-    return {
-        toolsets: [
-            {
-                name: 'dynamic_tools',
-                description: 'Tools for managing Backlog space settings and general information.',
-                enabled: true,
-                tools: [
-                    enableToolsetTool(toolRegistrar, helper),
-                    listAvailableToolsets(helper, toolsetGroup),
-                    getToolsetTools(helper, toolsetGroup),
-                ],
-            },
-        ],
-    };
-};
-const enableToolsetSchema = buildToolSchema((t) => ({
-    toolset: z
-        .string()
-        .describe(t('TOOL_ENABLE_TOOLSET_TOOLSET', 'Enable a toolset')),
-}));
-export const enableToolsetTool = (toolRegistrar, { t }) => {
-    return {
-        name: 'enable_toolset',
-        description: t('TOOL_ENABLE_TOOLSET_DESCRIPTION', 'Enable one of the Backlog MCP server toolsets. Use get_toolset_tools and list_available_toolsets first to inspect what this will enable.'),
-        schema: z.object(enableToolsetSchema(t)),
-        handler: async ({ toolset }) => {
-            const msg = await toolRegistrar.enableToolsetAndRefresh(toolset);
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: msg,
-                    },
-                ],
-            };
-        },
-    };
-};
-export const listAvailableToolsets = ({ t }, toolsetGroup) => {
-    return {
-        name: 'list_available_toolsets',
-        description: t('TOOL_LIST_AVAILABLE_TOOLSETS_DESCRIPTION', 'List all available toolsets.'),
-        schema: z.object({}),
-        handler: async () => {
-            const result = toolsetGroup.toolsets.map((ts) => ({
-                name: ts.name,
-                description: ts.description,
-                currentlyEnabled: ts.enabled,
-                canEnable: true,
-            }));
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify(result, null, 2),
-                    },
-                ],
-            };
-        },
-    };
-};
-const getToolsetToolsSchema = buildToolSchema((t) => ({
-    toolset: z
-        .string()
-        .describe(t('TOOL_GET_TOOLSET_TOOLS_TOOLSET', 'Toolset name to inspect')),
-}));
-export const getToolsetTools = ({ t }, toolsetGroup) => {
-    return {
-        name: 'get_toolset_tools',
-        description: t('TOOL_GET_TOOLSET_TOOLS_DESCRIPTION', 'List all tools in a specific toolset.'),
-        schema: z.object(getToolsetToolsSchema(t)),
-        handler: async ({ toolset }) => {
-            const found = toolsetGroup.toolsets.find((ts) => ts.name === toolset);
-            if (!found) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `Toolset '${toolset}' not found.`,
-                        },
-                    ],
-                };
-            }
-            const tools = found.tools.map((tool) => ({
-                name: tool.name,
-                description: tool.description,
-                toolset: found.name,
-                canEnable: true,
-            }));
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify(tools, null, 2),
-                    },
-                ],
-            };
-        },
-    };
-};