backlog-mcp-server 0.16.0 → 0.17.0

package/build/index.js

@@ -11,6 +11,7 @@ import { createDescriptionHelper } from './createDescriptionHelper.js';
 import { loadDescriptionOverrides } from './loadDescriptionOverrides.js';
 import { createBacklogMcpServer } from './createBacklogMcpServer.js';
 import { runHttpMcpServer } from './httpMcpServer.js';
+import { reportUnknownOverrideKeys } from './reportUnknownOverrideKeys.js';
 import { createBacklogClientRegistry, createOAuthBacklogClientRegistry, } from './utils/backlogClientRegistry.js';
 import { logger } from './utils/logger.js';
 import { buildToolsetGroup } from './utils/toolsetUtils.js';
@@ -144,7 +145,8 @@ if (tokenStore) {
     cleanupTimer.unref();
 }
 const useFields = argv.optimizeResponse;
-const descriptionHelper = createDescriptionHelper(loadDescriptionOverrides());
+const descriptionOverrides = loadDescriptionOverrides();
+const descriptionHelper = createDescriptionHelper(descriptionOverrides);
 const maxTokens = argv.maxTokens;
 const prefix = argv.prefix;
 const enabledToolsets = argv.dynamicToolsets
@@ -162,6 +164,13 @@ const mcpOption = {
 // Sharing it makes toolset state process-wide, which is the only scope left now
 // that the protocol has no sessions.
 const sharedToolsetGroup = buildToolsetGroup(backlog, descriptionHelper, enabledToolsets);
+reportUnknownOverrideKeys({
+    overrides: descriptionOverrides,
+    version,
+    backlog,
+    clientRegistry,
+    mcpOption,
+});
 // Factory: creates a fresh MCP server with all tools registered.
 // Used once per stdio connection; one fresh instance per HTTP request.
 const createServer = () => createBacklogMcpServer({

package/build/loadDescriptionOverrides.d.ts

@@ -1,16 +1,3 @@
-/**
- * Reads description overrides from a `.backlog-mcp-serverrc` file (`.json`,
- * `.yaml` or `.yml`) in the user's home directory.
- *
- * Node-only, and kept separate from `createDescriptionHelper` for that reason:
- * cosmiconfig walks the filesystem and the default search path is the home
- * directory. The CLI calls this and hands the result to the helper.
- *
- * The file is user-authored, so its contents are unknown: anything that is not a
- * string is dropped here rather than passed on. Most overrides end up in a tool
- * description, and a number or an array there would produce an invalid
- * `tools/list` payload.
- */
 export declare function loadDescriptionOverrides(options?: {
     configName?: string;
     searchDir?: string;

package/build/loadDescriptionOverrides.js

@@ -1,24 +1,86 @@
-import { cosmiconfigSync } from 'cosmiconfig';
+import { readFileSync } from 'fs';
+import { load } from 'js-yaml';
 import os from 'os';
+import path from 'path';
+import { logger } from './utils/logger.js';
 /**
- * Reads description overrides from a `.backlog-mcp-serverrc` file (`.json`,
- * `.yaml` or `.yml`) in the user's home directory.
+ * Reads description overrides from a `.backlog-mcp-serverrc` file in the user's
+ * home directory.
  *
  * Node-only, and kept separate from `createDescriptionHelper` for that reason:
- * cosmiconfig walks the filesystem and the default search path is the home
- * directory. The CLI calls this and hands the result to the helper.
+ * this reads the filesystem and needs a home directory. The CLI calls it and
+ * hands the result to the helper.
  *
  * The file is user-authored, so its contents are unknown: anything that is not a
  * string is dropped here rather than passed on. Most overrides end up in a tool
  * description, and a number or an array there would produce an invalid
  * `tools/list` payload.
+ *
+ * A file that exists but cannot be parsed is reported and then ignored.
+ * Overriding descriptions is an add-on, and a trailing comma in an optional file
+ * is not a reason to stop serving the tools — from the client's side an
+ * exception here looks like "the MCP server will not connect", with nothing
+ * pointing at the config file.
+ */
+/**
+ * Checked in this order; the first one that exists wins. The extensionless form
+ * is parsed as YAML, which also accepts JSON.
+ */
+const SUFFIXES = ['', '.json', '.yaml', '.yml'];
+/**
+ * A missing candidate is not a failure — there are four of them and at most one
+ * exists. A candidate that exists but does not parse is, and has to be
+ * distinguished from the missing case so it can be reported rather than skipped.
  */
+function readCandidate(filePath) {
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf-8');
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            'code' in error &&
+            (error.code === 'ENOENT' || error.code === 'ENOTDIR')) {
+            return { status: 'absent' };
+        }
+        return { status: 'unreadable', error };
+    }
+    try {
+        // An empty file is a config file with nothing in it, not a parse failure.
+        // `JSON.parse('')` throws, so it never reaches the caller's object check.
+        if (raw.trim() === '')
+            return { status: 'found', config: undefined };
+        return {
+            status: 'found',
+            config: filePath.endsWith('.json') ? JSON.parse(raw) : load(raw),
+        };
+    }
+    catch (error) {
+        return { status: 'unreadable', error };
+    }
+}
 export function loadDescriptionOverrides(options) {
-    const explorer = cosmiconfigSync(options?.configName ?? 'backlog-mcp-server');
-    const searchPath = options?.searchDir ?? os.homedir();
-    const config = explorer.search(searchPath)?.config;
-    if (typeof config !== 'object' || config === null || Array.isArray(config)) {
-        return {};
+    const configName = options?.configName ?? 'backlog-mcp-server';
+    const searchDir = options?.searchDir ?? os.homedir();
+    for (const suffix of SUFFIXES) {
+        const filePath = path.join(searchDir, `.${configName}rc${suffix}`);
+        const outcome = readCandidate(filePath);
+        if (outcome.status === 'absent')
+            continue;
+        if (outcome.status === 'unreadable') {
+            // `logger.error`, not `warn`: the logger runs at level `error` unless
+            // NODE_ENV says otherwise, so a warning here would never reach the user
+            // this message exists for.
+            logger.error({ err: outcome.error, filePath }, 'Could not read the description override file; continuing with the built-in defaults');
+            return {};
+        }
+        const config = outcome.config;
+        if (typeof config !== 'object' ||
+            config === null ||
+            Array.isArray(config)) {
+            return {};
+        }
+        return Object.fromEntries(Object.entries(config).filter(([, value]) => typeof value === 'string'));
     }
-    return Object.fromEntries(Object.entries(config).filter(([, value]) => typeof value === 'string'));
+    return {};
 }

package/build/reportUnknownOverrideKeys.d.ts

@@ -0,0 +1,22 @@
+import type { Backlog } from 'backlog-js';
+import type { MCPOptions } from './types/mcp.js';
+import type { BacklogClientRegistry } from './utils/backlogClientRegistry.js';
+/**
+ * Reports override keys in the config file that no tool or parameter asks for.
+ *
+ * The override keys are an untyped, unversioned public API: rename one in the
+ * source and every user's override for it stops applying, falls back to the
+ * built-in default, and says nothing. The user sees "I configured this and it
+ * has no effect". This turns that into a line in the server log.
+ *
+ * The comparison is exact, which also catches keys written in the wrong case —
+ * `t()` looks up `key.toUpperCase()`, so a lower-case entry in the config file
+ * never matches anything either.
+ */
+export declare function reportUnknownOverrideKeys({ overrides, version, backlog, clientRegistry, mcpOption, }: {
+    overrides: Record<string, string>;
+    version: string;
+    backlog: Backlog;
+    clientRegistry: BacklogClientRegistry;
+    mcpOption: MCPOptions;
+}): void;

package/build/reportUnknownOverrideKeys.js

@@ -0,0 +1,43 @@
+import { createBacklogMcpServer } from './createBacklogMcpServer.js';
+import { createDescriptionHelper } from './createDescriptionHelper.js';
+import { logger } from './utils/logger.js';
+/**
+ * Reports override keys in the config file that no tool or parameter asks for.
+ *
+ * The override keys are an untyped, unversioned public API: rename one in the
+ * source and every user's override for it stops applying, falls back to the
+ * built-in default, and says nothing. The user sees "I configured this and it
+ * has no effect". This turns that into a line in the server log.
+ *
+ * The comparison is exact, which also catches keys written in the wrong case —
+ * `t()` looks up `key.toUpperCase()`, so a lower-case entry in the config file
+ * never matches anything either.
+ */
+export function reportUnknownOverrideKeys({ overrides, version, backlog, clientRegistry, mcpOption, }) {
+    const configured = Object.keys(overrides);
+    if (configured.length === 0)
+        return;
+    // Keys are only recorded once a tool asks for them, so the set of valid keys
+    // is whatever building the full tool list touches. This is a throwaway helper
+    // and server built purely to collect them: the real ones may have toolsets
+    // disabled, and their keys would then look unknown. ~17ms, and only for users
+    // who actually have a config file.
+    const probe = createDescriptionHelper();
+    createBacklogMcpServer({
+        version,
+        useFields: mcpOption.useFields,
+        backlog,
+        clientRegistry,
+        descriptionHelper: probe,
+        enabledToolsets: ['all'],
+        mcpOption: { ...mcpOption, useOrganization: true },
+        dynamicToolsets: true,
+    });
+    const known = new Set(Object.keys(probe.dump()));
+    const unknown = configured.filter((key) => !known.has(key));
+    if (unknown.length === 0)
+        return;
+    // `error`, not `warn`: the logger drops anything below error in the default
+    // configuration, which is what users run.
+    logger.error({ keys: unknown }, 'These description override keys match no tool or parameter and had no effect');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backlog-mcp-server",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "type": "module",
   "bin": {
     "backlog-mcp-server": "./build/index.js"
@@ -37,17 +37,18 @@
     "@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",
+    "graphql": "^17.0.2",
     "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",