backlog-mcp-server 0.15.1 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/README.ja.md +16 -8
  2. package/README.md +16 -8
  3. package/build/createBacklogMcpServer.d.ts +3 -3
  4. package/build/createBacklogMcpServer.js +4 -4
  5. package/build/createDescriptionHelper.d.ts +18 -0
  6. package/build/{createTranslationHelper.js → createDescriptionHelper.js} +1 -1
  7. package/build/index.js +23 -11
  8. package/build/lib.d.ts +4 -4
  9. package/build/lib.js +3 -3
  10. package/build/{loadTranslationOverrides.d.ts → loadDescriptionOverrides.d.ts} +3 -3
  11. package/build/{loadTranslationOverrides.js → loadDescriptionOverrides.js} +3 -3
  12. package/build/tools/addDocument.d.ts +3 -3
  13. package/build/tools/addIssue.d.ts +3 -3
  14. package/build/tools/addIssueComment.d.ts +3 -3
  15. package/build/tools/addProject.d.ts +3 -3
  16. package/build/tools/addPullRequest.d.ts +3 -3
  17. package/build/tools/addPullRequestComment.d.ts +3 -3
  18. package/build/tools/addRelatedIssue.d.ts +3 -3
  19. package/build/tools/addVersionMilestone.d.ts +3 -3
  20. package/build/tools/addWatching.d.ts +3 -3
  21. package/build/tools/addWiki.d.ts +3 -3
  22. package/build/tools/countIssues.d.ts +3 -3
  23. package/build/tools/deleteIssue.d.ts +3 -3
  24. package/build/tools/deleteProject.d.ts +3 -3
  25. package/build/tools/deleteVersion.d.ts +3 -3
  26. package/build/tools/deleteWatching.d.ts +3 -3
  27. package/build/tools/dynamicTools/organizations.d.ts +3 -3
  28. package/build/tools/dynamicTools/toolsets.d.ts +7 -7
  29. package/build/tools/getCategories.d.ts +3 -3
  30. package/build/tools/getCustomFields.d.ts +3 -3
  31. package/build/tools/getDocument.d.ts +3 -3
  32. package/build/tools/getDocumentTree.d.ts +3 -3
  33. package/build/tools/getDocuments.d.ts +3 -3
  34. package/build/tools/getGitRepositories.d.ts +3 -3
  35. package/build/tools/getGitRepository.d.ts +3 -3
  36. package/build/tools/getIssue.d.ts +3 -3
  37. package/build/tools/getIssueComments.d.ts +3 -3
  38. package/build/tools/getIssueTypes.d.ts +3 -3
  39. package/build/tools/getIssues.d.ts +3 -3
  40. package/build/tools/getMyself.d.ts +3 -3
  41. package/build/tools/getNotifications.d.ts +3 -3
  42. package/build/tools/getNotificationsCount.d.ts +3 -3
  43. package/build/tools/getPriorities.d.ts +3 -3
  44. package/build/tools/getProject.d.ts +3 -3
  45. package/build/tools/getProjectList.d.ts +3 -3
  46. package/build/tools/getProjectUsers.d.ts +3 -3
  47. package/build/tools/getPullRequest.d.ts +3 -3
  48. package/build/tools/getPullRequestComments.d.ts +3 -3
  49. package/build/tools/getPullRequests.d.ts +3 -3
  50. package/build/tools/getPullRequestsCount.d.ts +3 -3
  51. package/build/tools/getRelatedIssues.d.ts +3 -3
  52. package/build/tools/getResolutions.d.ts +3 -3
  53. package/build/tools/getSpace.d.ts +3 -3
  54. package/build/tools/getSpaceActivities.d.ts +3 -3
  55. package/build/tools/getUserRecentUpdates.d.ts +3 -3
  56. package/build/tools/getUserStarsCount.d.ts +3 -3
  57. package/build/tools/getUsers.d.ts +3 -3
  58. package/build/tools/getVersionMilestoneList.d.ts +3 -3
  59. package/build/tools/getWatchingListCount.d.ts +3 -3
  60. package/build/tools/getWatchingListItems.d.ts +3 -3
  61. package/build/tools/getWiki.d.ts +3 -3
  62. package/build/tools/getWikiPages.d.ts +3 -3
  63. package/build/tools/getWikisCount.d.ts +3 -3
  64. package/build/tools/markNotificationAsRead.d.ts +3 -3
  65. package/build/tools/markWatchingAsRead.d.ts +3 -3
  66. package/build/tools/removeRelatedIssue.d.ts +3 -3
  67. package/build/tools/resetUnreadNotificationCount.d.ts +3 -3
  68. package/build/tools/shared/customFieldFiltersSchema.d.ts +2 -2
  69. package/build/tools/tools.d.ts +2 -2
  70. package/build/tools/updateIssue.d.ts +3 -3
  71. package/build/tools/updateIssueComment.d.ts +3 -3
  72. package/build/tools/updateProject.d.ts +3 -3
  73. package/build/tools/updatePullRequest.d.ts +3 -3
  74. package/build/tools/updatePullRequestComment.d.ts +3 -3
  75. package/build/tools/updateVersionMilestone.d.ts +3 -3
  76. package/build/tools/updateWatching.d.ts +3 -3
  77. package/build/tools/updateWiki.d.ts +3 -3
  78. package/build/types/tool.d.ts +2 -2
  79. package/build/utils/resolveIdOrKey.d.ts +3 -3
  80. package/build/utils/toolsetUtils.d.ts +2 -2
  81. package/package.json +2 -2
  82. package/build/createTranslationHelper.d.ts +0 -16
package/README.ja.md CHANGED
@@ -303,10 +303,14 @@ PROJECT-KEYプロジェクトの「repo-name」リポジトリで、ブランチ
303
303
  私がウォッチしているすべてのアイテムを表示してください。
304
304
  ```
305
305
 
306
- ### i18n / 説明のオーバーライド
306
+ ### ツール説明のオーバーライド
307
307
 
308
308
  **ホームディレクトリ** に `.backlog-mcp-serverrc.json` ファイルを作成することで、ツールの説明をオーバーライドできます。
309
309
 
310
+ これらの文字列のほとんどは、モデルがどのツールを呼ぶか、引数に何を入れるかを判断するために読むツール説明・パラメータ説明です。したがってオーバーライドは、似た2つのツールを区別させたり、チームの運用ルールを添えたりしてツール選択を誘導するための手段であり、応答の言語を変えるためのものではありません。モデルは説明が何語で書かれていても、質問された言語で応答します。
311
+
312
+ 一部のキーは、これとは別にバリデーションエラーのメッセージです(例:`PROJECT_ID_OR_KEY_REQUIRED`)。呼び出しが弾かれたときにツールの実行結果として返るため、モデルの応答を経由してユーザーの目に触れることがあります。
313
+
310
314
  ファイルには、ツール名をキーとし、新しい説明を値とするJSONオブジェクトを含める必要があります。
311
315
  例:
312
316
 
@@ -321,7 +325,9 @@ PROJECT-KEYプロジェクトの「repo-name」リポジトリで、ブランチ
321
325
 
322
326
  1. 環境変数(例:`BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION`)
323
327
  2. `.backlog-mcp-serverrc.json` 内のエントリ - サポートされる設定ファイル形式:.json、.yaml、.yml
324
- 3. 組み込みのフォールバック値(英語)
328
+ 3. 組み込みのデフォルト値
329
+
330
+ 空文字列または文字列以外の値は、どの段階でも無視され、組み込みのデフォルト値が使われます。
325
331
 
326
332
  サンプル設定:
327
333
 
@@ -351,22 +357,24 @@ PROJECT-KEYプロジェクトの「repo-name」リポジトリで、ブランチ
351
357
  }
352
358
  ```
353
359
 
354
- ### 現在の翻訳のエクスポート
360
+ ### 現在の説明のエクスポート
361
+
362
+ `--export-descriptions` フラグを指定してバイナリを実行することで、現在の説明(オーバーライドを含む)をエクスポートできます。このフラグは以前 `--export-translations` という名前でした。旧名も当面は動作しますが、非推奨の警告を出力し、将来のリリースで削除されます。
355
363
 
356
- `--export-translations` フラグを指定してバイナリを実行することで、現在のデフォルト翻訳(オーバーライドを含む)をエクスポートできます。
364
+ ツール一覧の構築時に解決されるすべてのキーと現在の値が、行ったカスタマイズを含めて標準出力に出力されます。ツール説明・パラメータ説明はすべて含まれるため、キー名を調べる用途にはこれを使ってください。
357
365
 
358
- これにより、行ったカスタマイズを含むすべてのツール説明が標準出力に出力されます。
366
+ バリデーションエラーのメッセージは含まれません。これらのキーは、実際に呼び出しが弾かれたときにはじめて解決されるためです。オーバーライド自体は同じ規則で可能ですが、キー名はソースを読んで調べる必要があります。
359
367
 
360
368
  例:
361
369
 
362
370
  ```bash
363
- docker run -i --rm ghcr.io/nulab/backlog-mcp-server node build/index.js --export-translations
371
+ docker run -i --rm ghcr.io/nulab/backlog-mcp-server node build/index.js --export-descriptions
364
372
  ```
365
373
 
366
374
  または
367
375
 
368
376
  ```bash
369
- npx github:nulab/backlog-mcp-server --export-translations
377
+ npx github:nulab/backlog-mcp-server --export-descriptions
370
378
  ```
371
379
 
372
380
  ### 環境変数の使用
@@ -537,7 +545,7 @@ pnpm test
537
545
 
538
546
  サーバーはいくつかのコマンドラインオプションをサポートしています:
539
547
 
540
- - `--export-translations`: すべての翻訳キーと値をエクスポート
548
+ - `--export-descriptions`: ツール一覧の構築時に解決される説明キーと値をエクスポート。旧名は `--export-translations` で、非推奨エイリアスとして当面動作しますが、将来のリリースで削除されます
541
549
  - `--optimize-response`: GraphQLスタイルのフィールド選択を有効にする
542
550
  - `--max-tokens=NUMBER`: レスポンスの最大トークン制限を設定
543
551
  - `--prefix=STRING`: すべてのツール名に付加するオプションの文字列プレフィックス(デフォルト:"")
package/README.md CHANGED
@@ -418,10 +418,14 @@ Create a new pull request from branch "feature/new-feature" to "main" in the rep
418
418
  Show me all items I'm watching
419
419
  ```
420
420
 
421
- ### i18n / Overriding Descriptions
421
+ ### Overriding Tool Descriptions
422
422
 
423
423
  You can override the descriptions of tools by creating a `.backlog-mcp-serverrc.json` file in your **home directory**.
424
424
 
425
+ 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.
426
+
427
+ 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.
428
+
425
429
  The file should contain a JSON object with the tool names as keys and the new descriptions as values.
426
430
  For example:
427
431
 
@@ -436,7 +440,9 @@ When the server starts, it determines the final description for each tool based
436
440
 
437
441
  1. Environment variables (e.g., `BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION`)
438
442
  2. Entries in `.backlog-mcp-serverrc.json` - Supported configuration file formats: .json, .yaml, .yml
439
- 3. Built-in fallback values (English)
443
+ 3. Built-in defaults
444
+
445
+ Empty or non-string values are ignored at every level, and the built-in default is used instead.
440
446
 
441
447
  Sample config:
442
448
 
@@ -466,22 +472,24 @@ Sample config:
466
472
  }
467
473
  ```
468
474
 
469
- ### Exporting Current Translations
475
+ ### Exporting Current Descriptions
476
+
477
+ 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.
470
478
 
471
- You can export the current default translations (including any overrides) by running the binary with the --export-translations flag.
479
+ 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.
472
480
 
473
- This will print all tool descriptions to stdout, including any customizations you have made.
481
+ 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.
474
482
 
475
483
  Example:
476
484
 
477
485
  ```bash
478
- docker run -i --rm ghcr.io/nulab/backlog-mcp-server node build/index.js --export-translations
486
+ docker run -i --rm ghcr.io/nulab/backlog-mcp-server node build/index.js --export-descriptions
479
487
  ```
480
488
 
481
489
  or
482
490
 
483
491
  ```bash
484
- npx github:nulab/backlog-mcp-server --export-translations
492
+ npx github:nulab/backlog-mcp-server --export-descriptions
485
493
  ```
486
494
 
487
495
  ### Using Environment Variables
@@ -654,7 +662,7 @@ The server supports several command line options:
654
662
  - `--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.
655
663
  - `--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.
656
664
  - `--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.
657
- - `--export-translations`: Export all translation keys and values
665
+ - `--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
658
666
  - `--optimize-response`: Enable GraphQL-style field selection
659
667
  - `--max-tokens=NUMBER`: Set maximum token limit for responses
660
668
  - `--prefix=STRING`: Optional string prefix to prepend to all tool names (default: "")
@@ -1,5 +1,5 @@
1
1
  import type { Backlog } from 'backlog-js';
2
- import type { TranslationHelper } from './createTranslationHelper.js';
2
+ import type { DescriptionHelper } from './createDescriptionHelper.js';
3
3
  import type { MCPOptions } from './types/mcp.js';
4
4
  import type { ToolsetGroup } from './types/toolsets.js';
5
5
  import type { BacklogClientRegistry } from './utils/backlogClientRegistry.js';
@@ -9,7 +9,7 @@ export type CreateBacklogMcpServerConfig = {
9
9
  useFields: boolean;
10
10
  backlog: Backlog;
11
11
  clientRegistry: BacklogClientRegistry;
12
- transHelper: TranslationHelper;
12
+ descriptionHelper: DescriptionHelper;
13
13
  enabledToolsets: string[];
14
14
  mcpOption: MCPOptions;
15
15
  dynamicToolsets: boolean;
@@ -26,4 +26,4 @@ export type CreateBacklogMcpServerConfig = {
26
26
  * Builds a fresh MCP server instance with all Backlog tools registered.
27
27
  * Used once per stdio connection; one instance per HTTP request for Streamable HTTP.
28
28
  */
29
- export declare function createBacklogMcpServer({ version, useFields, backlog, clientRegistry, transHelper, enabledToolsets, mcpOption, dynamicToolsets, toolsetGroup: sharedToolsetGroup, }: CreateBacklogMcpServerConfig): BacklogMCPServer;
29
+ export declare function createBacklogMcpServer({ version, useFields, backlog, clientRegistry, descriptionHelper, enabledToolsets, mcpOption, dynamicToolsets, toolsetGroup: sharedToolsetGroup, }: CreateBacklogMcpServerConfig): BacklogMCPServer;
@@ -17,24 +17,24 @@ const TOOL_LIST_CACHE_HINT = {
17
17
  * Builds a fresh MCP server instance with all Backlog tools registered.
18
18
  * Used once per stdio connection; one instance per HTTP request for Streamable HTTP.
19
19
  */
20
- export function createBacklogMcpServer({ version, useFields, backlog, clientRegistry, transHelper, enabledToolsets, mcpOption, dynamicToolsets, toolsetGroup: sharedToolsetGroup, }) {
20
+ export function createBacklogMcpServer({ version, useFields, backlog, clientRegistry, descriptionHelper, enabledToolsets, mcpOption, dynamicToolsets, toolsetGroup: sharedToolsetGroup, }) {
21
21
  const server = wrapServerWithToolRegistry(new McpServer({
22
22
  name: 'backlog',
23
23
  title: useFields ? 'backlog (field selection enabled)' : 'backlog',
24
24
  version,
25
25
  }, dynamicToolsets ? undefined : { cacheHints: TOOL_LIST_CACHE_HINT }));
26
26
  const toolsetGroup = sharedToolsetGroup ??
27
- buildToolsetGroup(backlog, transHelper, enabledToolsets);
27
+ buildToolsetGroup(backlog, descriptionHelper, enabledToolsets);
28
28
  registerTools(server, toolsetGroup, mcpOption);
29
29
  // `list_organizations` only has something to report when more than one space
30
30
  // is configured; the `organization` parameter its description points at is
31
31
  // published under the same condition.
32
32
  if (mcpOption.useOrganization) {
33
- registerDynamicTools(server, organizationTools(clientRegistry, transHelper), mcpOption.prefix);
33
+ registerDynamicTools(server, organizationTools(clientRegistry, descriptionHelper), mcpOption.prefix);
34
34
  }
35
35
  if (dynamicToolsets) {
36
36
  const registrar = createToolRegistrar(server, toolsetGroup, mcpOption);
37
- const dynamicToolsetGroup = dynamicTools(registrar, transHelper, toolsetGroup);
37
+ const dynamicToolsetGroup = dynamicTools(registrar, descriptionHelper, toolsetGroup);
38
38
  registerDynamicTools(server, dynamicToolsetGroup, mcpOption.prefix);
39
39
  }
40
40
  return server;
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Resolves the strings every tool definition passes through `t()`. Almost all of
3
+ * them are tool and parameter descriptions, read by the model when it picks a
4
+ * tool and fills in arguments. A few are validation error messages — `deleteVersion`
5
+ * and `resolveIdOrField` throw them — which do surface, as the text of a failed
6
+ * tool result.
7
+ *
8
+ * This module intentionally imports nothing. Every tool in `src/tools/` depends on
9
+ * it, so anything imported here is reachable from the tool layer — and the tool
10
+ * layer is meant to run on non-Node runtimes too. Discovering and reading the
11
+ * override file needs a filesystem and a home directory, so that part lives in
12
+ * `loadDescriptionOverrides` and the CLI passes the result in.
13
+ */
14
+ export interface DescriptionHelper {
15
+ t: (key: string, fallback: string) => string;
16
+ dump: () => Record<string, string>;
17
+ }
18
+ export declare function createDescriptionHelper(overrides?: Record<string, string>): DescriptionHelper;
@@ -1,4 +1,4 @@
1
- export function createTranslationHelper(overrides = {}) {
1
+ export function createDescriptionHelper(overrides = {}) {
2
2
  const usedKeys = {};
3
3
  function toEnvKey(key) {
4
4
  return `BACKLOG_MCP_${key}`;
package/build/index.js CHANGED
@@ -7,8 +7,8 @@ import yargs from 'yargs';
7
7
  import { hideBin } from 'yargs/helpers';
8
8
  import { getBacklogOAuthConfig } from './auth/backlogOAuthConfig.js';
9
9
  import { createTokenStore } from './auth/tokenStore.js';
10
- import { createTranslationHelper } from './createTranslationHelper.js';
11
- import { loadTranslationOverrides } from './loadTranslationOverrides.js';
10
+ import { createDescriptionHelper } from './createDescriptionHelper.js';
11
+ import { loadDescriptionOverrides } from './loadDescriptionOverrides.js';
12
12
  import { createBacklogMcpServer } from './createBacklogMcpServer.js';
13
13
  import { runHttpMcpServer } from './httpMcpServer.js';
14
14
  import { createBacklogClientRegistry, createOAuthBacklogClientRegistry, } from './utils/backlogClientRegistry.js';
@@ -98,9 +98,14 @@ const argv = yargs(hideBin(process.argv))
98
98
  describe: 'Optional string prefix to prepend to all generated outputs',
99
99
  default: env.get('PREFIX').default('').asString(),
100
100
  })
101
- .option('export-translations', {
101
+ .option('export-descriptions', {
102
102
  type: 'boolean',
103
- describe: 'Export translations and exit',
103
+ // Deprecated alias, to be removed in a future release. Kept because the old name is
104
+ // documented with docker and npx examples, and dropping it outright would
105
+ // not fail loudly: yargs ignores unknown flags, so the process would fall
106
+ // through to starting a server and the caller would see a hang.
107
+ alias: 'export-translations',
108
+ describe: 'Export tool and parameter descriptions and exit',
104
109
  default: false,
105
110
  })
106
111
  .option('enable-toolsets', {
@@ -121,6 +126,13 @@ Available toolsets:
121
126
  default: env.get('ENABLE_DYNAMIC_TOOLSETS').default('false').asBool(),
122
127
  })
123
128
  .parseSync();
129
+ // The alias resolves both spellings to the same argv key, so which one was typed
130
+ // is only visible in the raw arguments. Written straight to stderr rather than
131
+ // through `logger`, which drops anything below `error` in production — and stdout
132
+ // carries the JSON-RPC stream, so a notice there would corrupt the protocol.
133
+ if (hideBin(process.argv).some((arg) => arg.split('=')[0] === '--export-translations')) {
134
+ process.stderr.write('--export-translations is deprecated and will be removed in a future release. Use --export-descriptions.\n');
135
+ }
124
136
  const clientRegistry = oauthConfig
125
137
  ? createOAuthBacklogClientRegistry(oauthConfig.backlogDomain)
126
138
  : createBacklogClientRegistry();
@@ -132,7 +144,7 @@ if (tokenStore) {
132
144
  cleanupTimer.unref();
133
145
  }
134
146
  const useFields = argv.optimizeResponse;
135
- const transHelper = createTranslationHelper(loadTranslationOverrides());
147
+ const descriptionHelper = createDescriptionHelper(loadDescriptionOverrides());
136
148
  const maxTokens = argv.maxTokens;
137
149
  const prefix = argv.prefix;
138
150
  const enabledToolsets = argv.dynamicToolsets
@@ -149,7 +161,7 @@ const mcpOption = {
149
161
  // each request — so a per-server group would lose the enablement immediately.
150
162
  // Sharing it makes toolset state process-wide, which is the only scope left now
151
163
  // that the protocol has no sessions.
152
- const sharedToolsetGroup = buildToolsetGroup(backlog, transHelper, enabledToolsets);
164
+ const sharedToolsetGroup = buildToolsetGroup(backlog, descriptionHelper, enabledToolsets);
153
165
  // Factory: creates a fresh MCP server with all tools registered.
154
166
  // Used once per stdio connection; one fresh instance per HTTP request.
155
167
  const createServer = () => createBacklogMcpServer({
@@ -157,14 +169,14 @@ const createServer = () => createBacklogMcpServer({
157
169
  useFields,
158
170
  backlog,
159
171
  clientRegistry,
160
- transHelper,
172
+ descriptionHelper,
161
173
  enabledToolsets,
162
174
  mcpOption,
163
175
  dynamicToolsets: argv.dynamicToolsets,
164
176
  toolsetGroup: sharedToolsetGroup,
165
177
  });
166
- if (argv.exportTranslations) {
167
- // Translation keys are only recorded once a tool asks for them, so build a
178
+ if (argv.exportDescriptions) {
179
+ // Description keys are only recorded once a tool asks for them, so build a
168
180
  // server with every toolset enabled before dumping. Without this the dump is
169
181
  // empty, because no tool has been created yet at this point.
170
182
  createBacklogMcpServer({
@@ -172,12 +184,12 @@ if (argv.exportTranslations) {
172
184
  useFields,
173
185
  backlog,
174
186
  clientRegistry,
175
- transHelper,
187
+ descriptionHelper,
176
188
  enabledToolsets: ['all'],
177
189
  mcpOption,
178
190
  dynamicToolsets: true,
179
191
  });
180
- const data = transHelper.dump();
192
+ const data = descriptionHelper.dump();
181
193
  // eslint-disable-next-line no-console
182
194
  console.log(JSON.stringify(data, null, 2));
183
195
  process.exit(0);
package/build/lib.d.ts CHANGED
@@ -7,19 +7,19 @@
7
7
  * This module exposes the pieces needed to build a server, and nothing that runs
8
8
  * on import.
9
9
  *
10
- * Nothing reachable from here may touch a Node built-in. `loadTranslationOverrides`
10
+ * Nothing reachable from here may touch a Node built-in. `loadDescriptionOverrides`
11
11
  * is the counter-example worth remembering: it reads the override file from disk,
12
12
  * so it belongs to the CLI and is deliberately absent below. Consumers on other
13
- * runtimes pass their own overrides to `createTranslationHelper`.
13
+ * runtimes pass their own overrides to `createDescriptionHelper`.
14
14
  */
15
15
  export { allTools } from './tools/tools.js';
16
16
  export { composeToolHandler } from './handlers/builders/composeToolHandler.js';
17
- export { createTranslationHelper } from './createTranslationHelper.js';
17
+ export { createDescriptionHelper } from './createDescriptionHelper.js';
18
18
  export { backlogErrorHandler } from './backlog/backlogErrorHandler.js';
19
19
  export { buildToolSchema } from './types/tool.js';
20
20
  export { isErrorLike } from './types/result.js';
21
21
  export type { ComposeOptions } from './handlers/builders/composeToolHandler.js';
22
- export type { TranslationHelper } from './createTranslationHelper.js';
22
+ export type { DescriptionHelper } from './createDescriptionHelper.js';
23
23
  export type { ToolDefinition, DynamicToolDefinition, ToolRegistrar, } from './types/tool.js';
24
24
  export type { Toolset, ToolsetGroup, DynamicToolset, DynamicToolsetGroup, } from './types/toolsets.js';
25
25
  export type { ErrorLike, SafeResult } from './types/result.js';
package/build/lib.js CHANGED
@@ -7,14 +7,14 @@
7
7
  * This module exposes the pieces needed to build a server, and nothing that runs
8
8
  * on import.
9
9
  *
10
- * Nothing reachable from here may touch a Node built-in. `loadTranslationOverrides`
10
+ * Nothing reachable from here may touch a Node built-in. `loadDescriptionOverrides`
11
11
  * is the counter-example worth remembering: it reads the override file from disk,
12
12
  * so it belongs to the CLI and is deliberately absent below. Consumers on other
13
- * runtimes pass their own overrides to `createTranslationHelper`.
13
+ * runtimes pass their own overrides to `createDescriptionHelper`.
14
14
  */
15
15
  export { allTools } from './tools/tools.js';
16
16
  export { composeToolHandler } from './handlers/builders/composeToolHandler.js';
17
- export { createTranslationHelper } from './createTranslationHelper.js';
17
+ export { createDescriptionHelper } from './createDescriptionHelper.js';
18
18
  export { backlogErrorHandler } from './backlog/backlogErrorHandler.js';
19
19
  export { buildToolSchema } from './types/tool.js';
20
20
  export { isErrorLike } from './types/result.js';
@@ -2,16 +2,16 @@
2
2
  * Reads description overrides from a `.backlog-mcp-serverrc` file (`.json`,
3
3
  * `.yaml` or `.yml`) in the user's home directory.
4
4
  *
5
- * Node-only, and kept separate from `createTranslationHelper` for that reason:
5
+ * Node-only, and kept separate from `createDescriptionHelper` for that reason:
6
6
  * cosmiconfig walks the filesystem and the default search path is the home
7
7
  * directory. The CLI calls this and hands the result to the helper.
8
8
  *
9
9
  * The file is user-authored, so its contents are unknown: anything that is not a
10
- * string is dropped here rather than passed on. Every override ends up in a tool
10
+ * string is dropped here rather than passed on. Most overrides end up in a tool
11
11
  * description, and a number or an array there would produce an invalid
12
12
  * `tools/list` payload.
13
13
  */
14
- export declare function loadTranslationOverrides(options?: {
14
+ export declare function loadDescriptionOverrides(options?: {
15
15
  configName?: string;
16
16
  searchDir?: string;
17
17
  }): Record<string, string>;
@@ -4,16 +4,16 @@ import os from 'os';
4
4
  * Reads description overrides from a `.backlog-mcp-serverrc` file (`.json`,
5
5
  * `.yaml` or `.yml`) in the user's home directory.
6
6
  *
7
- * Node-only, and kept separate from `createTranslationHelper` for that reason:
7
+ * Node-only, and kept separate from `createDescriptionHelper` for that reason:
8
8
  * cosmiconfig walks the filesystem and the default search path is the home
9
9
  * directory. The CLI calls this and hands the result to the helper.
10
10
  *
11
11
  * The file is user-authored, so its contents are unknown: anything that is not a
12
- * string is dropped here rather than passed on. Every override ends up in a tool
12
+ * string is dropped here rather than passed on. Most overrides end up in a tool
13
13
  * description, and a number or an array there would produce an invalid
14
14
  * `tools/list` payload.
15
15
  */
16
- export function loadTranslationOverrides(options) {
16
+ export function loadDescriptionOverrides(options) {
17
17
  const explorer = cosmiconfigSync(options?.configName ?? 'backlog-mcp-server');
18
18
  const searchPath = options?.searchDir ?? os.homedir();
19
19
  const config = explorer.search(searchPath)?.config;
@@ -1,9 +1,9 @@
1
1
  import { Backlog } from 'backlog-js';
2
2
  import { z } from 'zod';
3
- import { TranslationHelper } from '../createTranslationHelper.js';
3
+ import { DescriptionHelper } from '../createDescriptionHelper.js';
4
4
  import { DocumentItemSchema } from '../types/zod/backlogOutputDefinition.js';
5
5
  import { ToolDefinition } from '../types/tool.js';
6
- declare const addDocumentSchema: (t: TranslationHelper["t"]) => {
6
+ declare const addDocumentSchema: (t: DescriptionHelper["t"]) => {
7
7
  projectId: z.ZodNumber;
8
8
  title: z.ZodOptional<z.ZodString>;
9
9
  content: z.ZodOptional<z.ZodString>;
@@ -11,5 +11,5 @@ declare const addDocumentSchema: (t: TranslationHelper["t"]) => {
11
11
  parentId: z.ZodOptional<z.ZodString>;
12
12
  addLast: z.ZodOptional<z.ZodBoolean>;
13
13
  };
14
- export declare const addDocumentTool: (backlog: Backlog, { t }: TranslationHelper) => ToolDefinition<ReturnType<typeof addDocumentSchema>, (typeof DocumentItemSchema)["shape"]>;
14
+ export declare const addDocumentTool: (backlog: Backlog, { t }: DescriptionHelper) => ToolDefinition<ReturnType<typeof addDocumentSchema>, (typeof DocumentItemSchema)["shape"]>;
15
15
  export {};
@@ -1,9 +1,9 @@
1
1
  import { Backlog } from 'backlog-js';
2
2
  import { z } from 'zod';
3
- import { TranslationHelper } from '../createTranslationHelper.js';
3
+ import { DescriptionHelper } from '../createDescriptionHelper.js';
4
4
  import { IssueSchema } from '../types/zod/backlogOutputDefinition.js';
5
5
  import { ToolDefinition } from '../types/tool.js';
6
- declare const addIssueSchema: (t: TranslationHelper["t"]) => {
6
+ declare const addIssueSchema: (t: DescriptionHelper["t"]) => {
7
7
  projectId: z.ZodNumber;
8
8
  summary: z.ZodString;
9
9
  issueTypeId: z.ZodNumber;
@@ -26,5 +26,5 @@ declare const addIssueSchema: (t: TranslationHelper["t"]) => {
26
26
  otherValue: z.ZodOptional<z.ZodString>;
27
27
  }, z.core.$strip>>>;
28
28
  };
29
- export declare const addIssueTool: (backlog: Backlog, { t }: TranslationHelper) => ToolDefinition<ReturnType<typeof addIssueSchema>, (typeof IssueSchema)["shape"]>;
29
+ export declare const addIssueTool: (backlog: Backlog, { t }: DescriptionHelper) => ToolDefinition<ReturnType<typeof addIssueSchema>, (typeof IssueSchema)["shape"]>;
30
30
  export {};
@@ -1,14 +1,14 @@
1
1
  import { z } from 'zod';
2
2
  import { Backlog } from 'backlog-js';
3
3
  import { ToolDefinition } from '../types/tool.js';
4
- import { TranslationHelper } from '../createTranslationHelper.js';
4
+ import { DescriptionHelper } from '../createDescriptionHelper.js';
5
5
  import { IssueCommentSchema } from '../types/zod/backlogOutputDefinition.js';
6
- declare const addIssueCommentSchema: (t: TranslationHelper["t"]) => {
6
+ declare const addIssueCommentSchema: (t: DescriptionHelper["t"]) => {
7
7
  issueId: z.ZodOptional<z.ZodNumber>;
8
8
  issueKey: z.ZodOptional<z.ZodString>;
9
9
  content: z.ZodString;
10
10
  notifiedUserId: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
11
11
  attachmentId: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
12
12
  };
13
- export declare const addIssueCommentTool: (backlog: Backlog, { t }: TranslationHelper) => ToolDefinition<ReturnType<typeof addIssueCommentSchema>, (typeof IssueCommentSchema)["shape"]>;
13
+ export declare const addIssueCommentTool: (backlog: Backlog, { t }: DescriptionHelper) => ToolDefinition<ReturnType<typeof addIssueCommentSchema>, (typeof IssueCommentSchema)["shape"]>;
14
14
  export {};
@@ -1,9 +1,9 @@
1
1
  import { z } from 'zod';
2
2
  import { Backlog } from 'backlog-js';
3
3
  import { ToolDefinition } from '../types/tool.js';
4
- import { TranslationHelper } from '../createTranslationHelper.js';
4
+ import { DescriptionHelper } from '../createDescriptionHelper.js';
5
5
  import { ProjectSchema } from '../types/zod/backlogOutputDefinition.js';
6
- declare const addProjectSchema: (t: TranslationHelper["t"]) => {
6
+ declare const addProjectSchema: (t: DescriptionHelper["t"]) => {
7
7
  name: z.ZodString;
8
8
  key: z.ZodString;
9
9
  chartEnabled: z.ZodOptional<z.ZodBoolean>;
@@ -14,5 +14,5 @@ declare const addProjectSchema: (t: TranslationHelper["t"]) => {
14
14
  markdown: "markdown";
15
15
  }>>;
16
16
  };
17
- export declare const addProjectTool: (backlog: Backlog, { t }: TranslationHelper) => ToolDefinition<ReturnType<typeof addProjectSchema>, (typeof ProjectSchema)["shape"]>;
17
+ export declare const addProjectTool: (backlog: Backlog, { t }: DescriptionHelper) => ToolDefinition<ReturnType<typeof addProjectSchema>, (typeof ProjectSchema)["shape"]>;
18
18
  export {};
@@ -1,9 +1,9 @@
1
1
  import { z } from 'zod';
2
2
  import { Backlog } from 'backlog-js';
3
3
  import { ToolDefinition } from '../types/tool.js';
4
- import { TranslationHelper } from '../createTranslationHelper.js';
4
+ import { DescriptionHelper } from '../createDescriptionHelper.js';
5
5
  import { PullRequestSchema } from '../types/zod/backlogOutputDefinition.js';
6
- declare const addPullRequestSchema: (t: TranslationHelper["t"]) => {
6
+ declare const addPullRequestSchema: (t: DescriptionHelper["t"]) => {
7
7
  projectId: z.ZodOptional<z.ZodNumber>;
8
8
  projectKey: z.ZodOptional<z.ZodString>;
9
9
  repoId: z.ZodOptional<z.ZodNumber>;
@@ -16,5 +16,5 @@ declare const addPullRequestSchema: (t: TranslationHelper["t"]) => {
16
16
  assigneeId: z.ZodOptional<z.ZodNumber>;
17
17
  notifiedUserId: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
18
18
  };
19
- export declare const addPullRequestTool: (backlog: Backlog, { t }: TranslationHelper) => ToolDefinition<ReturnType<typeof addPullRequestSchema>, (typeof PullRequestSchema)["shape"]>;
19
+ export declare const addPullRequestTool: (backlog: Backlog, { t }: DescriptionHelper) => ToolDefinition<ReturnType<typeof addPullRequestSchema>, (typeof PullRequestSchema)["shape"]>;
20
20
  export {};
@@ -1,9 +1,9 @@
1
1
  import { z } from 'zod';
2
2
  import { Backlog } from 'backlog-js';
3
3
  import { ToolDefinition } from '../types/tool.js';
4
- import { TranslationHelper } from '../createTranslationHelper.js';
4
+ import { DescriptionHelper } from '../createDescriptionHelper.js';
5
5
  import { PullRequestCommentSchema } from '../types/zod/backlogOutputDefinition.js';
6
- declare const addPullRequestCommentSchema: (t: TranslationHelper["t"]) => {
6
+ declare const addPullRequestCommentSchema: (t: DescriptionHelper["t"]) => {
7
7
  projectId: z.ZodOptional<z.ZodNumber>;
8
8
  projectKey: z.ZodOptional<z.ZodString>;
9
9
  repoId: z.ZodOptional<z.ZodNumber>;
@@ -12,5 +12,5 @@ declare const addPullRequestCommentSchema: (t: TranslationHelper["t"]) => {
12
12
  content: z.ZodString;
13
13
  notifiedUserId: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
14
14
  };
15
- export declare const addPullRequestCommentTool: (backlog: Backlog, { t }: TranslationHelper) => ToolDefinition<ReturnType<typeof addPullRequestCommentSchema>, (typeof PullRequestCommentSchema)["shape"]>;
15
+ export declare const addPullRequestCommentTool: (backlog: Backlog, { t }: DescriptionHelper) => ToolDefinition<ReturnType<typeof addPullRequestCommentSchema>, (typeof PullRequestCommentSchema)["shape"]>;
16
16
  export {};
@@ -1,12 +1,12 @@
1
1
  import { z } from 'zod';
2
2
  import { Backlog } from 'backlog-js';
3
3
  import { ToolDefinition } from '../types/tool.js';
4
- import { TranslationHelper } from '../createTranslationHelper.js';
4
+ import { DescriptionHelper } from '../createDescriptionHelper.js';
5
5
  import { RelatedIssueSchema } from '../types/zod/backlogOutputDefinition.js';
6
- declare const addRelatedIssueSchema: (t: TranslationHelper["t"]) => {
6
+ declare const addRelatedIssueSchema: (t: DescriptionHelper["t"]) => {
7
7
  issueId: z.ZodOptional<z.ZodNumber>;
8
8
  issueKey: z.ZodOptional<z.ZodString>;
9
9
  targetIssueId: z.ZodNumber;
10
10
  };
11
- export declare const addRelatedIssueTool: (backlog: Backlog, { t }: TranslationHelper) => ToolDefinition<ReturnType<typeof addRelatedIssueSchema>, (typeof RelatedIssueSchema)["shape"]>;
11
+ export declare const addRelatedIssueTool: (backlog: Backlog, { t }: DescriptionHelper) => ToolDefinition<ReturnType<typeof addRelatedIssueSchema>, (typeof RelatedIssueSchema)["shape"]>;
12
12
  export {};
@@ -1,9 +1,9 @@
1
1
  import { z } from 'zod';
2
2
  import { Backlog } from 'backlog-js';
3
3
  import { ToolDefinition } from '../types/tool.js';
4
- import { TranslationHelper } from '../createTranslationHelper.js';
4
+ import { DescriptionHelper } from '../createDescriptionHelper.js';
5
5
  import { VersionSchema } from '../types/zod/backlogOutputDefinition.js';
6
- declare const addVersionMilestoneSchema: (t: TranslationHelper["t"]) => {
6
+ declare const addVersionMilestoneSchema: (t: DescriptionHelper["t"]) => {
7
7
  projectId: z.ZodOptional<z.ZodNumber>;
8
8
  projectKey: z.ZodOptional<z.ZodString>;
9
9
  name: z.ZodString;
@@ -11,5 +11,5 @@ declare const addVersionMilestoneSchema: (t: TranslationHelper["t"]) => {
11
11
  startDate: z.ZodOptional<z.ZodString>;
12
12
  releaseDueDate: z.ZodOptional<z.ZodString>;
13
13
  };
14
- export declare const addVersionMilestoneTool: (backlog: Backlog, { t }: TranslationHelper) => ToolDefinition<ReturnType<typeof addVersionMilestoneSchema>, (typeof VersionSchema)["shape"]>;
14
+ export declare const addVersionMilestoneTool: (backlog: Backlog, { t }: DescriptionHelper) => ToolDefinition<ReturnType<typeof addVersionMilestoneSchema>, (typeof VersionSchema)["shape"]>;
15
15
  export {};
@@ -1,11 +1,11 @@
1
1
  import { z } from 'zod';
2
2
  import { Backlog } from 'backlog-js';
3
3
  import { ToolDefinition } from '../types/tool.js';
4
- import { TranslationHelper } from '../createTranslationHelper.js';
4
+ import { DescriptionHelper } from '../createDescriptionHelper.js';
5
5
  import { WatchingListItemSchema } from '../types/zod/backlogOutputDefinition.js';
6
- declare const addWatchingSchema: (t: TranslationHelper["t"]) => {
6
+ declare const addWatchingSchema: (t: DescriptionHelper["t"]) => {
7
7
  issueIdOrKey: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
8
8
  note: z.ZodDefault<z.ZodOptional<z.ZodString>>;
9
9
  };
10
- export declare const addWatchingTool: (backlog: Backlog, { t }: TranslationHelper) => ToolDefinition<ReturnType<typeof addWatchingSchema>, (typeof WatchingListItemSchema)["shape"]>;
10
+ export declare const addWatchingTool: (backlog: Backlog, { t }: DescriptionHelper) => ToolDefinition<ReturnType<typeof addWatchingSchema>, (typeof WatchingListItemSchema)["shape"]>;
11
11
  export {};
@@ -1,13 +1,13 @@
1
1
  import { z } from 'zod';
2
2
  import { Backlog } from 'backlog-js';
3
3
  import { ToolDefinition } from '../types/tool.js';
4
- import { TranslationHelper } from '../createTranslationHelper.js';
4
+ import { DescriptionHelper } from '../createDescriptionHelper.js';
5
5
  import { WikiSchema } from '../types/zod/backlogOutputDefinition.js';
6
- declare const addWikiSchema: (t: TranslationHelper["t"]) => {
6
+ declare const addWikiSchema: (t: DescriptionHelper["t"]) => {
7
7
  projectId: z.ZodNumber;
8
8
  name: z.ZodString;
9
9
  content: z.ZodString;
10
10
  mailNotify: z.ZodOptional<z.ZodBoolean>;
11
11
  };
12
- export declare const addWikiTool: (backlog: Backlog, { t }: TranslationHelper) => ToolDefinition<ReturnType<typeof addWikiSchema>, (typeof WikiSchema)["shape"]>;
12
+ export declare const addWikiTool: (backlog: Backlog, { t }: DescriptionHelper) => ToolDefinition<ReturnType<typeof addWikiSchema>, (typeof WikiSchema)["shape"]>;
13
13
  export {};
@@ -1,9 +1,9 @@
1
1
  import { z } from 'zod';
2
2
  import { Backlog } from 'backlog-js';
3
3
  import { ToolDefinition } from '../types/tool.js';
4
- import { TranslationHelper } from '../createTranslationHelper.js';
4
+ import { DescriptionHelper } from '../createDescriptionHelper.js';
5
5
  import { IssueCountSchema } from '../types/zod/backlogOutputDefinition.js';
6
- declare const countIssuesSchema: (t: TranslationHelper["t"]) => {
6
+ declare const countIssuesSchema: (t: DescriptionHelper["t"]) => {
7
7
  projectId: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
8
8
  issueTypeId: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
9
9
  categoryId: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
@@ -44,5 +44,5 @@ declare const countIssuesSchema: (t: TranslationHelper["t"]) => {
44
44
  value: z.ZodUnion<readonly [z.ZodNumber, z.ZodArray<z.ZodNumber>]>;
45
45
  }, z.core.$strip>], "type">>>;
46
46
  };
47
- export declare const countIssuesTool: (backlog: Backlog, { t }: TranslationHelper) => ToolDefinition<ReturnType<typeof countIssuesSchema>, (typeof IssueCountSchema)["shape"]>;
47
+ export declare const countIssuesTool: (backlog: Backlog, { t }: DescriptionHelper) => ToolDefinition<ReturnType<typeof countIssuesSchema>, (typeof IssueCountSchema)["shape"]>;
48
48
  export {};
@@ -1,11 +1,11 @@
1
1
  import { z } from 'zod';
2
2
  import { Backlog } from 'backlog-js';
3
3
  import { ToolDefinition } from '../types/tool.js';
4
- import { TranslationHelper } from '../createTranslationHelper.js';
4
+ import { DescriptionHelper } from '../createDescriptionHelper.js';
5
5
  import { IssueSchema } from '../types/zod/backlogOutputDefinition.js';
6
- declare const deleteIssueSchema: (t: TranslationHelper["t"]) => {
6
+ declare const deleteIssueSchema: (t: DescriptionHelper["t"]) => {
7
7
  issueId: z.ZodOptional<z.ZodNumber>;
8
8
  issueKey: z.ZodOptional<z.ZodString>;
9
9
  };
10
- export declare const deleteIssueTool: (backlog: Backlog, { t }: TranslationHelper) => ToolDefinition<ReturnType<typeof deleteIssueSchema>, (typeof IssueSchema)["shape"]>;
10
+ export declare const deleteIssueTool: (backlog: Backlog, { t }: DescriptionHelper) => ToolDefinition<ReturnType<typeof deleteIssueSchema>, (typeof IssueSchema)["shape"]>;
11
11
  export {};