backlog-mcp-server 0.15.1 → 0.17.0

package/README.ja.md

@@ -303,10 +303,14 @@ PROJECT-KEYプロジェクトの「repo-name」リポジトリで、ブランチ
 私がウォッチしているすべてのアイテムを表示してください。
 ```
 
-### i18n / 説明のオーバーライド
+### ツール説明のオーバーライド
 
 **ホームディレクトリ** に `.backlog-mcp-serverrc.json` ファイルを作成することで、ツールの説明をオーバーライドできます。
 
+これらの文字列のほとんどは、モデルがどのツールを呼ぶか、引数に何を入れるかを判断するために読むツール説明・パラメータ説明です。したがってオーバーライドは、似た2つのツールを区別させたり、チームの運用ルールを添えたりしてツール選択を誘導するための手段であり、応答の言語を変えるためのものではありません。モデルは説明が何語で書かれていても、質問された言語で応答します。
+
+一部のキーは、これとは別にバリデーションエラーのメッセージです（例：`PROJECT_ID_OR_KEY_REQUIRED`）。呼び出しが弾かれたときにツールの実行結果として返るため、モデルの応答を経由してユーザーの目に触れることがあります。
+
 ファイルには、ツール名をキーとし、新しい説明を値とするJSONオブジェクトを含める必要があります。
 例：
 
@@ -321,7 +325,9 @@ PROJECT-KEYプロジェクトの「repo-name」リポジトリで、ブランチ
 
 1. 環境変数（例：`BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION`）
 2. `.backlog-mcp-serverrc.json` 内のエントリ - サポートされる設定ファイル形式：.json、.yaml、.yml
-3. 組み込みのフォールバック値（英語）
+3. 組み込みのデフォルト値
+
+空文字列または文字列以外の値は、どの段階でも無視され、組み込みのデフォルト値が使われます。
 
 サンプル設定：
 
@@ -351,22 +357,24 @@ PROJECT-KEYプロジェクトの「repo-name」リポジトリで、ブランチ
 }
 ```
 
-### 現在の翻訳のエクスポート
+### 現在の説明のエクスポート
+
+`--export-descriptions` フラグを指定してバイナリを実行することで、現在の説明（オーバーライドを含む）をエクスポートできます。このフラグは以前 `--export-translations` という名前でした。旧名も当面は動作しますが、非推奨の警告を出力し、将来のリリースで削除されます。
 
-`--export-translations` フラグを指定してバイナリを実行することで、現在のデフォルト翻訳（オーバーライドを含む）をエクスポートできます。
+ツール一覧の構築時に解決されるすべてのキーと現在の値が、行ったカスタマイズを含めて標準出力に出力されます。ツール説明・パラメータ説明はすべて含まれるため、キー名を調べる用途にはこれを使ってください。
 
-これにより、行ったカスタマイズを含むすべてのツール説明が標準出力に出力されます。
+バリデーションエラーのメッセージは含まれません。これらのキーは、実際に呼び出しが弾かれたときにはじめて解決されるためです。オーバーライド自体は同じ規則で可能ですが、キー名はソースを読んで調べる必要があります。
 
 例：
 
 ```bash
-docker run -i --rm ghcr.io/nulab/backlog-mcp-server node build/index.js --export-translations
+docker run -i --rm ghcr.io/nulab/backlog-mcp-server node build/index.js --export-descriptions
 ```
 
 または
 
 ```bash
-npx github:nulab/backlog-mcp-server --export-translations
+npx github:nulab/backlog-mcp-server --export-descriptions
 ```
 
 ### 環境変数の使用
@@ -537,7 +545,7 @@ pnpm test
 
 サーバーはいくつかのコマンドラインオプションをサポートしています：
 
-- `--export-translations`: すべての翻訳キーと値をエクスポート
+- `--export-descriptions`: ツール一覧の構築時に解決される説明キーと値をエクスポート。旧名は `--export-translations` で、非推奨エイリアスとして当面動作しますが、将来のリリースで削除されます
 - `--optimize-response`: GraphQLスタイルのフィールド選択を有効にする
 - `--max-tokens=NUMBER`: レスポンスの最大トークン制限を設定
 - `--prefix=STRING`: すべてのツール名に付加するオプションの文字列プレフィックス（デフォルト：""）

package/README.md

@@ -418,10 +418,14 @@ Create a new pull request from branch "feature/new-feature" to "main" in the rep
 Show me all items I'm watching
 ```
 
-### i18n / Overriding Descriptions
+### Overriding Tool Descriptions
 
 You can override the descriptions of tools by creating a `.backlog-mcp-serverrc.json` file in your **home directory**.
 
+Almost all of these strings are the tool and parameter descriptions the model reads when it decides which tool to call and how to fill in its arguments, so overriding them is a way to steer tool selection — for example to disambiguate two similar tools, or to add a rule your team follows — rather than a way to change the language of the answers you get. The model answers in whatever language you ask in, regardless of the language these descriptions are written in.
+
+A small number of keys are validation error messages instead (for example `PROJECT_ID_OR_KEY_REQUIRED`). Those are returned in the tool result when a call is rejected, so they can reach you by way of the model's reply.
+
 The file should contain a JSON object with the tool names as keys and the new descriptions as values.  
 For example:
 
@@ -436,7 +440,9 @@ When the server starts, it determines the final description for each tool based
 
 1. Environment variables (e.g., `BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION`)
 2. Entries in `.backlog-mcp-serverrc.json` - Supported configuration file formats: .json, .yaml, .yml
-3. Built-in fallback values (English)
+3. Built-in defaults
+
+Empty or non-string values are ignored at every level, and the built-in default is used instead.
 
 Sample config:
 
@@ -466,22 +472,24 @@ Sample config:
 }
 ```
 
-### Exporting Current Translations
+### Exporting Current Descriptions
+
+You can export the current descriptions (including any overrides) by running the binary with the `--export-descriptions` flag. This flag was previously called `--export-translations`; the old name still works but prints a deprecation notice and will be removed in a future release.
 
-You can export the current default translations (including any overrides) by running the binary with the --export-translations flag.
+This prints every key that is resolved while the tool list is built, with its current value, including any customizations you have made. That covers all tool and parameter descriptions, and it is the practical way to discover key names.
 
-This will print all tool descriptions to stdout, including any customizations you have made.
+It does not cover the validation error messages, because those keys are only resolved when a call is actually rejected. They are still overridable by the same rules; you just have to read them out of the source.
 
 Example:
 
 ```bash
-docker run -i --rm ghcr.io/nulab/backlog-mcp-server node build/index.js --export-translations
+docker run -i --rm ghcr.io/nulab/backlog-mcp-server node build/index.js --export-descriptions
 ```
 
 or
 
 ```bash
-npx github:nulab/backlog-mcp-server --export-translations
+npx github:nulab/backlog-mcp-server --export-descriptions
 ```
 
 ### Using Environment Variables
@@ -654,7 +662,7 @@ The server supports several command line options:
 - `--http-json-response`: Prefer JSON responses over SSE. Applies to `2026-07-28` clients only; the backward-compatible `2025-11-25` path is served with the SDK's default response shaping.
 - `--http-allowed-hosts`: Comma-separated allowed `Host` hostnames (port-agnostic). Needed when binding to all interfaces, or on a loopback bind behind a reverse proxy.
 - `--http-allowed-origins`: Comma-separated allowed `Origin` hostnames for browser-based clients. Defaults to the localhost set on a bare loopback bind, and to no `Origin` check otherwise.
-- `--export-translations`: Export all translation keys and values
+- `--export-descriptions`: Export the description keys and values resolved when building the tool list. Was named `--export-translations`; that spelling still works as a deprecated alias and will be removed in a future release
 - `--optimize-response`: Enable GraphQL-style field selection
 - `--max-tokens=NUMBER`: Set maximum token limit for responses
 - `--prefix=STRING`: Optional string prefix to prepend to all tool names (default: "")

package/build/createBacklogMcpServer.d.ts

@@ -1,5 +1,5 @@
 import type { Backlog } from 'backlog-js';
-import type { TranslationHelper } from './createTranslationHelper.js';
+import type { DescriptionHelper } from './createDescriptionHelper.js';
 import type { MCPOptions } from './types/mcp.js';
 import type { ToolsetGroup } from './types/toolsets.js';
 import type { BacklogClientRegistry } from './utils/backlogClientRegistry.js';
@@ -9,7 +9,7 @@ export type CreateBacklogMcpServerConfig = {
     useFields: boolean;
     backlog: Backlog;
     clientRegistry: BacklogClientRegistry;
-    transHelper: TranslationHelper;
+    descriptionHelper: DescriptionHelper;
     enabledToolsets: string[];
     mcpOption: MCPOptions;
     dynamicToolsets: boolean;
@@ -26,4 +26,4 @@ export type CreateBacklogMcpServerConfig = {
  * Builds a fresh MCP server instance with all Backlog tools registered.
  * Used once per stdio connection; one instance per HTTP request for Streamable HTTP.
  */
-export declare function createBacklogMcpServer({ version, useFields, backlog, clientRegistry, transHelper, enabledToolsets, mcpOption, dynamicToolsets, toolsetGroup: sharedToolsetGroup, }: CreateBacklogMcpServerConfig): BacklogMCPServer;
+export declare function createBacklogMcpServer({ version, useFields, backlog, clientRegistry, descriptionHelper, enabledToolsets, mcpOption, dynamicToolsets, toolsetGroup: sharedToolsetGroup, }: CreateBacklogMcpServerConfig): BacklogMCPServer;

package/build/createBacklogMcpServer.js

@@ -17,24 +17,24 @@ const TOOL_LIST_CACHE_HINT = {
  * Builds a fresh MCP server instance with all Backlog tools registered.
  * Used once per stdio connection; one instance per HTTP request for Streamable HTTP.
  */
-export function createBacklogMcpServer({ version, useFields, backlog, clientRegistry, transHelper, enabledToolsets, mcpOption, dynamicToolsets, toolsetGroup: sharedToolsetGroup, }) {
+export function createBacklogMcpServer({ version, useFields, backlog, clientRegistry, descriptionHelper, enabledToolsets, mcpOption, dynamicToolsets, toolsetGroup: sharedToolsetGroup, }) {
     const server = wrapServerWithToolRegistry(new McpServer({
         name: 'backlog',
         title: useFields ? 'backlog (field selection enabled)' : 'backlog',
         version,
     }, dynamicToolsets ? undefined : { cacheHints: TOOL_LIST_CACHE_HINT }));
     const toolsetGroup = sharedToolsetGroup ??
-        buildToolsetGroup(backlog, transHelper, enabledToolsets);
+        buildToolsetGroup(backlog, descriptionHelper, enabledToolsets);
     registerTools(server, toolsetGroup, mcpOption);
     // `list_organizations` only has something to report when more than one space
     // is configured; the `organization` parameter its description points at is
     // published under the same condition.
     if (mcpOption.useOrganization) {
-        registerDynamicTools(server, organizationTools(clientRegistry, transHelper), mcpOption.prefix);
+        registerDynamicTools(server, organizationTools(clientRegistry, descriptionHelper), mcpOption.prefix);
     }
     if (dynamicToolsets) {
         const registrar = createToolRegistrar(server, toolsetGroup, mcpOption);
-        const dynamicToolsetGroup = dynamicTools(registrar, transHelper, toolsetGroup);
+        const dynamicToolsetGroup = dynamicTools(registrar, descriptionHelper, toolsetGroup);
         registerDynamicTools(server, dynamicToolsetGroup, mcpOption.prefix);
     }
     return server;

package/build/createDescriptionHelper.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Resolves the strings every tool definition passes through `t()`. Almost all of
+ * them are tool and parameter descriptions, read by the model when it picks a
+ * tool and fills in arguments. A few are validation error messages — `deleteVersion`
+ * and `resolveIdOrField` throw them — which do surface, as the text of a failed
+ * tool result.
+ *
+ * This module intentionally imports nothing. Every tool in `src/tools/` depends on
+ * it, so anything imported here is reachable from the tool layer — and the tool
+ * layer is meant to run on non-Node runtimes too. Discovering and reading the
+ * override file needs a filesystem and a home directory, so that part lives in
+ * `loadDescriptionOverrides` and the CLI passes the result in.
+ */
+export interface DescriptionHelper {
+    t: (key: string, fallback: string) => string;
+    dump: () => Record<string, string>;
+}
+export declare function createDescriptionHelper(overrides?: Record<string, string>): DescriptionHelper;

package/build/{createTranslationHelper.js → createDescriptionHelper.js}

@@ -1,4 +1,4 @@
-export function createTranslationHelper(overrides = {}) {
+export function createDescriptionHelper(overrides = {}) {
     const usedKeys = {};
     function toEnvKey(key) {
         return `BACKLOG_MCP_${key}`;

package/build/index.js

@@ -7,10 +7,11 @@ import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import { getBacklogOAuthConfig } from './auth/backlogOAuthConfig.js';
 import { createTokenStore } from './auth/tokenStore.js';
-import { createTranslationHelper } from './createTranslationHelper.js';
-import { loadTranslationOverrides } from './loadTranslationOverrides.js';
+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';
@@ -98,9 +99,14 @@ const argv = yargs(hideBin(process.argv))
     describe: 'Optional string prefix to prepend to all generated outputs',
     default: env.get('PREFIX').default('').asString(),
 })
-    .option('export-translations', {
+    .option('export-descriptions', {
     type: 'boolean',
-    describe: 'Export translations and exit',
+    // Deprecated alias, to be removed in a future release. Kept because the old name is
+    // documented with docker and npx examples, and dropping it outright would
+    // not fail loudly: yargs ignores unknown flags, so the process would fall
+    // through to starting a server and the caller would see a hang.
+    alias: 'export-translations',
+    describe: 'Export tool and parameter descriptions and exit',
     default: false,
 })
     .option('enable-toolsets', {
@@ -121,6 +127,13 @@ Available toolsets:
     default: env.get('ENABLE_DYNAMIC_TOOLSETS').default('false').asBool(),
 })
     .parseSync();
+// The alias resolves both spellings to the same argv key, so which one was typed
+// is only visible in the raw arguments. Written straight to stderr rather than
+// through `logger`, which drops anything below `error` in production — and stdout
+// carries the JSON-RPC stream, so a notice there would corrupt the protocol.
+if (hideBin(process.argv).some((arg) => arg.split('=')[0] === '--export-translations')) {
+    process.stderr.write('--export-translations is deprecated and will be removed in a future release. Use --export-descriptions.\n');
+}
 const clientRegistry = oauthConfig
     ? createOAuthBacklogClientRegistry(oauthConfig.backlogDomain)
     : createBacklogClientRegistry();
@@ -132,7 +145,8 @@ if (tokenStore) {
     cleanupTimer.unref();
 }
 const useFields = argv.optimizeResponse;
-const transHelper = createTranslationHelper(loadTranslationOverrides());
+const descriptionOverrides = loadDescriptionOverrides();
+const descriptionHelper = createDescriptionHelper(descriptionOverrides);
 const maxTokens = argv.maxTokens;
 const prefix = argv.prefix;
 const enabledToolsets = argv.dynamicToolsets
@@ -149,7 +163,14 @@ const mcpOption = {
 // each request — so a per-server group would lose the enablement immediately.
 // Sharing it makes toolset state process-wide, which is the only scope left now
 // that the protocol has no sessions.
-const sharedToolsetGroup = buildToolsetGroup(backlog, transHelper, enabledToolsets);
+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({
@@ -157,14 +178,14 @@ const createServer = () => createBacklogMcpServer({
     useFields,
     backlog,
     clientRegistry,
-    transHelper,
+    descriptionHelper,
     enabledToolsets,
     mcpOption,
     dynamicToolsets: argv.dynamicToolsets,
     toolsetGroup: sharedToolsetGroup,
 });
-if (argv.exportTranslations) {
-    // Translation keys are only recorded once a tool asks for them, so build a
+if (argv.exportDescriptions) {
+    // Description keys are only recorded once a tool asks for them, so build a
     // server with every toolset enabled before dumping. Without this the dump is
     // empty, because no tool has been created yet at this point.
     createBacklogMcpServer({
@@ -172,12 +193,12 @@ if (argv.exportTranslations) {
         useFields,
         backlog,
         clientRegistry,
-        transHelper,
+        descriptionHelper,
         enabledToolsets: ['all'],
         mcpOption,
         dynamicToolsets: true,
     });
-    const data = transHelper.dump();
+    const data = descriptionHelper.dump();
     // eslint-disable-next-line no-console
     console.log(JSON.stringify(data, null, 2));
     process.exit(0);

package/build/lib.d.ts

@@ -7,19 +7,19 @@
  * This module exposes the pieces needed to build a server, and nothing that runs
  * on import.
  *
- * Nothing reachable from here may touch a Node built-in. `loadTranslationOverrides`
+ * Nothing reachable from here may touch a Node built-in. `loadDescriptionOverrides`
  * is the counter-example worth remembering: it reads the override file from disk,
  * so it belongs to the CLI and is deliberately absent below. Consumers on other
- * runtimes pass their own overrides to `createTranslationHelper`.
+ * runtimes pass their own overrides to `createDescriptionHelper`.
  */
 export { allTools } from './tools/tools.js';
 export { composeToolHandler } from './handlers/builders/composeToolHandler.js';
-export { createTranslationHelper } from './createTranslationHelper.js';
+export { createDescriptionHelper } from './createDescriptionHelper.js';
 export { backlogErrorHandler } from './backlog/backlogErrorHandler.js';
 export { buildToolSchema } from './types/tool.js';
 export { isErrorLike } from './types/result.js';
 export type { ComposeOptions } from './handlers/builders/composeToolHandler.js';
-export type { TranslationHelper } from './createTranslationHelper.js';
+export type { DescriptionHelper } from './createDescriptionHelper.js';
 export type { ToolDefinition, DynamicToolDefinition, ToolRegistrar, } from './types/tool.js';
 export type { Toolset, ToolsetGroup, DynamicToolset, DynamicToolsetGroup, } from './types/toolsets.js';
 export type { ErrorLike, SafeResult } from './types/result.js';

package/build/lib.js

@@ -7,14 +7,14 @@
  * This module exposes the pieces needed to build a server, and nothing that runs
  * on import.
  *
- * Nothing reachable from here may touch a Node built-in. `loadTranslationOverrides`
+ * Nothing reachable from here may touch a Node built-in. `loadDescriptionOverrides`
  * is the counter-example worth remembering: it reads the override file from disk,
  * so it belongs to the CLI and is deliberately absent below. Consumers on other
- * runtimes pass their own overrides to `createTranslationHelper`.
+ * runtimes pass their own overrides to `createDescriptionHelper`.
  */
 export { allTools } from './tools/tools.js';
 export { composeToolHandler } from './handlers/builders/composeToolHandler.js';
-export { createTranslationHelper } from './createTranslationHelper.js';
+export { createDescriptionHelper } from './createDescriptionHelper.js';
 export { backlogErrorHandler } from './backlog/backlogErrorHandler.js';
 export { buildToolSchema } from './types/tool.js';
 export { isErrorLike } from './types/result.js';

package/build/loadDescriptionOverrides.d.ts

@@ -0,0 +1,4 @@
+export declare function loadDescriptionOverrides(options?: {
+    configName?: string;
+    searchDir?: string;
+}): Record<string, string>;

package/build/loadDescriptionOverrides.js

@@ -0,0 +1,86 @@
+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 in the user's
+ * home directory.
+ *
+ * Node-only, and kept separate from `createDescriptionHelper` for that reason:
+ * 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 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 {};
+}

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/build/tools/addDocument.d.ts

@@ -1,9 +1,9 @@
 import { Backlog } from 'backlog-js';
 import { z } from 'zod';
-import { TranslationHelper } from '../createTranslationHelper.js';
+import { DescriptionHelper } from '../createDescriptionHelper.js';
 import { DocumentItemSchema } from '../types/zod/backlogOutputDefinition.js';
 import { ToolDefinition } from '../types/tool.js';
-declare const addDocumentSchema: (t: TranslationHelper["t"]) => {
+declare const addDocumentSchema: (t: DescriptionHelper["t"]) => {
     projectId: z.ZodNumber;
     title: z.ZodOptional<z.ZodString>;
     content: z.ZodOptional<z.ZodString>;
@@ -11,5 +11,5 @@ declare const addDocumentSchema: (t: TranslationHelper["t"]) => {
     parentId: z.ZodOptional<z.ZodString>;
     addLast: z.ZodOptional<z.ZodBoolean>;
 };
-export declare const addDocumentTool: (backlog: Backlog, { t }: TranslationHelper) => ToolDefinition<ReturnType<typeof addDocumentSchema>, (typeof DocumentItemSchema)["shape"]>;
+export declare const addDocumentTool: (backlog: Backlog, { t }: DescriptionHelper) => ToolDefinition<ReturnType<typeof addDocumentSchema>, (typeof DocumentItemSchema)["shape"]>;
 export {};

package/build/tools/addIssue.d.ts

@@ -1,9 +1,9 @@
 import { Backlog } from 'backlog-js';
 import { z } from 'zod';
-import { TranslationHelper } from '../createTranslationHelper.js';
+import { DescriptionHelper } from '../createDescriptionHelper.js';
 import { IssueSchema } from '../types/zod/backlogOutputDefinition.js';
 import { ToolDefinition } from '../types/tool.js';
-declare const addIssueSchema: (t: TranslationHelper["t"]) => {
+declare const addIssueSchema: (t: DescriptionHelper["t"]) => {
     projectId: z.ZodNumber;
     summary: z.ZodString;
     issueTypeId: z.ZodNumber;
@@ -26,5 +26,5 @@ declare const addIssueSchema: (t: TranslationHelper["t"]) => {
         otherValue: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
 };
-export declare const addIssueTool: (backlog: Backlog, { t }: TranslationHelper) => ToolDefinition<ReturnType<typeof addIssueSchema>, (typeof IssueSchema)["shape"]>;
+export declare const addIssueTool: (backlog: Backlog, { t }: DescriptionHelper) => ToolDefinition<ReturnType<typeof addIssueSchema>, (typeof IssueSchema)["shape"]>;
 export {};

package/build/tools/addIssueComment.d.ts

@@ -1,14 +1,14 @@
 import { z } from 'zod';
 import { Backlog } from 'backlog-js';
 import { ToolDefinition } from '../types/tool.js';
-import { TranslationHelper } from '../createTranslationHelper.js';
+import { DescriptionHelper } from '../createDescriptionHelper.js';
 import { IssueCommentSchema } from '../types/zod/backlogOutputDefinition.js';
-declare const addIssueCommentSchema: (t: TranslationHelper["t"]) => {
+declare const addIssueCommentSchema: (t: DescriptionHelper["t"]) => {
     issueId: z.ZodOptional<z.ZodNumber>;
     issueKey: z.ZodOptional<z.ZodString>;
     content: z.ZodString;
     notifiedUserId: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
     attachmentId: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
 };
-export declare const addIssueCommentTool: (backlog: Backlog, { t }: TranslationHelper) => ToolDefinition<ReturnType<typeof addIssueCommentSchema>, (typeof IssueCommentSchema)["shape"]>;
+export declare const addIssueCommentTool: (backlog: Backlog, { t }: DescriptionHelper) => ToolDefinition<ReturnType<typeof addIssueCommentSchema>, (typeof IssueCommentSchema)["shape"]>;
 export {};

package/build/tools/addProject.d.ts

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 import { Backlog } from 'backlog-js';
 import { ToolDefinition } from '../types/tool.js';
-import { TranslationHelper } from '../createTranslationHelper.js';
+import { DescriptionHelper } from '../createDescriptionHelper.js';
 import { ProjectSchema } from '../types/zod/backlogOutputDefinition.js';
-declare const addProjectSchema: (t: TranslationHelper["t"]) => {
+declare const addProjectSchema: (t: DescriptionHelper["t"]) => {
     name: z.ZodString;
     key: z.ZodString;
     chartEnabled: z.ZodOptional<z.ZodBoolean>;
@@ -14,5 +14,5 @@ declare const addProjectSchema: (t: TranslationHelper["t"]) => {
         markdown: "markdown";
     }>>;
 };
-export declare const addProjectTool: (backlog: Backlog, { t }: TranslationHelper) => ToolDefinition<ReturnType<typeof addProjectSchema>, (typeof ProjectSchema)["shape"]>;
+export declare const addProjectTool: (backlog: Backlog, { t }: DescriptionHelper) => ToolDefinition<ReturnType<typeof addProjectSchema>, (typeof ProjectSchema)["shape"]>;
 export {};

package/build/tools/addPullRequest.d.ts

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 import { Backlog } from 'backlog-js';
 import { ToolDefinition } from '../types/tool.js';
-import { TranslationHelper } from '../createTranslationHelper.js';
+import { DescriptionHelper } from '../createDescriptionHelper.js';
 import { PullRequestSchema } from '../types/zod/backlogOutputDefinition.js';
-declare const addPullRequestSchema: (t: TranslationHelper["t"]) => {
+declare const addPullRequestSchema: (t: DescriptionHelper["t"]) => {
     projectId: z.ZodOptional<z.ZodNumber>;
     projectKey: z.ZodOptional<z.ZodString>;
     repoId: z.ZodOptional<z.ZodNumber>;
@@ -16,5 +16,5 @@ declare const addPullRequestSchema: (t: TranslationHelper["t"]) => {
     assigneeId: z.ZodOptional<z.ZodNumber>;
     notifiedUserId: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
 };
-export declare const addPullRequestTool: (backlog: Backlog, { t }: TranslationHelper) => ToolDefinition<ReturnType<typeof addPullRequestSchema>, (typeof PullRequestSchema)["shape"]>;
+export declare const addPullRequestTool: (backlog: Backlog, { t }: DescriptionHelper) => ToolDefinition<ReturnType<typeof addPullRequestSchema>, (typeof PullRequestSchema)["shape"]>;
 export {};

package/build/tools/addPullRequestComment.d.ts

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 import { Backlog } from 'backlog-js';
 import { ToolDefinition } from '../types/tool.js';
-import { TranslationHelper } from '../createTranslationHelper.js';
+import { DescriptionHelper } from '../createDescriptionHelper.js';
 import { PullRequestCommentSchema } from '../types/zod/backlogOutputDefinition.js';
-declare const addPullRequestCommentSchema: (t: TranslationHelper["t"]) => {
+declare const addPullRequestCommentSchema: (t: DescriptionHelper["t"]) => {
     projectId: z.ZodOptional<z.ZodNumber>;
     projectKey: z.ZodOptional<z.ZodString>;
     repoId: z.ZodOptional<z.ZodNumber>;
@@ -12,5 +12,5 @@ declare const addPullRequestCommentSchema: (t: TranslationHelper["t"]) => {
     content: z.ZodString;
     notifiedUserId: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
 };
-export declare const addPullRequestCommentTool: (backlog: Backlog, { t }: TranslationHelper) => ToolDefinition<ReturnType<typeof addPullRequestCommentSchema>, (typeof PullRequestCommentSchema)["shape"]>;
+export declare const addPullRequestCommentTool: (backlog: Backlog, { t }: DescriptionHelper) => ToolDefinition<ReturnType<typeof addPullRequestCommentSchema>, (typeof PullRequestCommentSchema)["shape"]>;
 export {};