backlog-mcp-server 0.7.0 → 0.8.0

package/README.ja.md

@@ -42,11 +42,14 @@ Backlog API とやり取りするための Model Context Protocol（MCP）サー
       "command": "docker",
       "args": [
         "run",
-        "--pull", "always",
+        "--pull",
+        "always",
         "-i",
         "--rm",
-        "-e", "BACKLOG_DOMAIN",
-        "-e", "BACKLOG_API_KEY",
+        "-e",
+        "BACKLOG_DOMAIN",
+        "-e",
+        "BACKLOG_API_KEY",
         "ghcr.io/nulab/backlog-mcp-server"
       ],
       "env": {
@@ -79,9 +82,7 @@ docker pull ghcr.io/nulab/backlog-mcp-server:latest
   "mcpServers": {
     "backlog": {
       "command": "npx",
-      "args": [
-        "backlog-mcp-server"
-      ],
+      "args": ["backlog-mcp-server"],
       "env": {
         "BACKLOG_DOMAIN": "your-domain.backlog.com",
         "BACKLOG_API_KEY": "your-api-key"
@@ -96,6 +97,7 @@ docker pull ghcr.io/nulab/backlog-mcp-server:latest
 ### オプション3: 手動セットアップ (Node.js)
 
 1. クローンしてインストール：
+
    ```bash
    git clone https://github.com/nulab/backlog-mcp-server.git
    cd backlog-mcp-server
@@ -103,23 +105,39 @@ docker pull ghcr.io/nulab/backlog-mcp-server:latest
    npm run build
    ```
 
-2. MCPとして使用するJSONを設定します：
-  ```json
-  {
-    "mcpServers": {
-      "backlog": {
-        "command": "node",
-        "args": [
-          "your-repository-location/build/index.js"
-        ],
-        "env": {
-          "BACKLOG_DOMAIN": "your-domain.backlog.com",
-          "BACKLOG_API_KEY": "your-api-key"
-        }
+2. テンプレートから `.env` を作成し、必須の環境変数を設定します：
+
+```bash
+cp .env.example .env
+```
+
+`.env` に以下を設定してください：
+
+- `BACKLOG_DOMAIN=your-domain.backlog.com`
+- `BACKLOG_API_KEY=your-api-key`
+
+3. ローカルで起動します：
+
+```bash
+npm run dev
+```
+
+4. MCPとして使用するJSONを設定します：
+
+```json
+{
+  "mcpServers": {
+    "backlog": {
+      "command": "node",
+      "args": ["your-repository-location/build/index.js"],
+      "env": {
+        "BACKLOG_DOMAIN": "your-domain.backlog.com",
+        "BACKLOG_API_KEY": "your-api-key"
       }
     }
   }
-  ```
+}
+```
 
 ## ツール設定
 
@@ -129,15 +147,15 @@ docker pull ghcr.io/nulab/backlog-mcp-server:latest
 
 次のツールセットが利用可能です（`"all"` が使用されるとデフォルトで有効になります）：
 
-| ツールセット    | 説明                                                                 |
-|-----------------|--------------------------------------------------------------------------------------|
-| `space`         | Backlogスペース設定と一般情報を管理するためのツール                                  |
-| `project`       | プロジェクト、カテゴリ、カスタムフィールド、課題タイプを管理するためのツール             |
-| `issue`         | 課題とそのコメント、発生バージョン/マイルストーンを管理するためのツール                                             |
-| `wiki`          | Wikiページを管理するためのツール                                                     |
-| `git`           | Gitリポジトリとプルリクエストを管理するためのツール                                    |
-| `notifications` | ユーザー通知を管理するためのツール                                                   |
-| `document`      | ドキュメントおよびドキュメントツリーを参照するためのツール      |
+| ツールセット    | 説明                                                                         |
+| --------------- | ---------------------------------------------------------------------------- |
+| `space`         | Backlogスペース設定と一般情報を管理するためのツール                          |
+| `project`       | プロジェクト、カテゴリ、カスタムフィールド、課題タイプを管理するためのツール |
+| `issue`         | 課題とそのコメント、発生バージョン/マイルストーンを管理するためのツール      |
+| `wiki`          | Wikiページを管理するためのツール                                             |
+| `git`           | Gitリポジトリとプルリクエストを管理するためのツール                          |
+| `notifications` | ユーザー通知を管理するためのツール                                           |
+| `document`      | ドキュメントおよびドキュメントツリーを参照するためのツール                   |
 
 ### ツールセットの指定
 
@@ -190,29 +208,41 @@ CLI経由での有効化：
 MCPサーバーがAIエージェントで設定されると、会話で直接ツールを使用できます。以下にいくつかの例を示します：
 
 - プロジェクトの一覧表示
+
 ```
 私のBacklogプロジェクトをすべてリストアップしてください。
 ```
+
 - 新しい課題の作成
+
 ```
 PROJECT-KEYプロジェクトに「ログインページのエラーを修正」というタイトルの高優先度のバグ課題を作成してください。
 ```
+
 - プロジェクト詳細の取得
+
 ```
 PROJECT-KEYプロジェクトの詳細を表示してください。
 ```
+
 - Gitリポジトリの操作
+
 ```
 PROJECT-KEYプロジェクト内のすべてのGitリポジトリをリストアップしてください。
 ```
+
 - プルリクエストの管理
+
 ```
 PROJECT-KEYプロジェクトの「repo-name」リポジトリ内のすべてのオープンなプルリクエストを表示してください。
 ```
+
 ```
 PROJECT-KEYプロジェクトの「repo-name」リポジトリで、ブランチ「feature/new-feature」から「main」への新しいプルリクエストを作成してください。
 ```
+
 - ウォッチアイテム
+
 ```
 私がウォッチしているすべてのアイテムを表示してください。
 ```
@@ -248,9 +278,12 @@ PROJECT-KEYプロジェクトの「repo-name」リポジトリで、ブランチ
         "run",
         "-i",
         "--rm",
-        "-e", "BACKLOG_DOMAIN",
-        "-e", "BACKLOG_API_KEY",
-        "-v", "/yourcurrentdir/.backlog-mcp-serverrc.json:/root/.backlog-mcp-serverrc.json:ro",
+        "-e",
+        "BACKLOG_DOMAIN",
+        "-e",
+        "BACKLOG_API_KEY",
+        "-v",
+        "/yourcurrentdir/.backlog-mcp-serverrc.json:/root/.backlog-mcp-serverrc.json:ro",
         "ghcr.io/nulab/backlog-mcp-server"
       ],
       "env": {
@@ -281,6 +314,7 @@ npx github:nulab/backlog-mcp-server --export-translations
 ```
 
 ### 日本語翻訳テンプレートの使用
+
 サンプルの日本語設定ファイルは次の場所に提供されています：
 
 ```bash
@@ -292,6 +326,7 @@ translationConfig/.backlog-mcp-serverrc.json.example
 その後、必要に応じてファイルを編集して説明をカスタマイズできます。
 
 ### 環境変数の使用
+
 または、環境変数を介してツールの説明をオーバーライドすることもできます。
 
 環境変数名は、ツールキーに基づいており、`BACKLOG_MCP_` がプレフィックスとして付き、大文字で記述されます。
@@ -308,9 +343,12 @@ translationConfig/.backlog-mcp-serverrc.json.example
         "run",
         "-i",
         "--rm",
-        "-e", "BACKLOG_DOMAIN",
-        "-e", "BACKLOG_API_KEY",
-        "-e", "BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION",
+        "-e",
+        "BACKLOG_DOMAIN",
+        "-e",
+        "BACKLOG_API_KEY",
+        "-e",
+        "BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION",
         "ghcr.io/nulab/backlog-mcp-server"
       ],
       "env": {
@@ -372,6 +410,7 @@ get_project(projectIdOrKey: "PROJECT-KEY", fields: "{ name key description }")
 ```
 
 利点：
+
 - 必要なフィールドのみを要求することでレスポンスサイズを削減
 - 特定のデータポイントに焦点を当てる
 - 大規模なレスポンスのパフォーマンスを向上
@@ -379,6 +418,7 @@ get_project(projectIdOrKey: "PROJECT-KEY", fields: "{ name key description }")
 #### トークン制限
 
 大規模なレスポンスは、トークン制限を超えないように自動的に制限されます：
+
 - デフォルト制限：50,000トークン
 - `MAX_TOKENS` 環境変数で設定可能
 - 制限を超えるレスポンスはメッセージと共に切り捨てられます
@@ -390,6 +430,7 @@ MAX_TOKENS=10000
 ```
 
 レスポンスが制限を超えた場合、警告と共に切り捨てられます。
+
 > 注：これはベストエフォートの緩和策であり、保証された強制ではありません。
 
 ### 完全なカスタム設定例
@@ -405,12 +446,18 @@ MAX_TOKENS=10000
         "run",
         "-i",
         "--rm",
-        "-e", "BACKLOG_DOMAIN",
-        "-e", "BACKLOG_API_KEY",
-        "-e", "MAX_TOKENS",
-        "-e", "OPTIMIZE_RESPONSE",
-        "-e", "PREFIX",
-        "-e", "ENABLE_TOOLSETS",
+        "-e",
+        "BACKLOG_DOMAIN",
+        "-e",
+        "BACKLOG_API_KEY",
+        "-e",
+        "MAX_TOKENS",
+        "-e",
+        "OPTIMIZE_RESPONSE",
+        "-e",
+        "PREFIX",
+        "-e",
+        "ENABLE_TOOLSETS",
         "ghcr.io/nulab/backlog-mcp-server"
       ],
       "env": {
@@ -455,6 +502,7 @@ npm test
   利用可能なツールセット：`space`、`project`、`issue`、`wiki`、`git`、`notifications`。
 
 例：
+
 ```bash
 node build/index.js --optimize-response --max-tokens=100000 --prefix="backlog_" --enable-toolsets space,issue
 ```

package/README.md

@@ -4,7 +4,7 @@
 ![Build](https://github.com/nulab/backlog-mcp-server/actions/workflows/ci.yml/badge.svg)
 ![Last Commit](https://img.shields.io/github/last-commit/nulab/backlog-mcp-server.svg)
 
-[📘 日本語でのご利用ガイド](./README.ja.md) 
+[📘 日本語でのご利用ガイド](./README.ja.md)
 
 A Model Context Protocol (MCP) server for interacting with the Backlog API. This server provides tools for managing projects, issues, wiki pages, and more in Backlog through AI agents like Claude Desktop / Cline / Cursor etc.
 
@@ -42,11 +42,14 @@ The easiest way to use this MCP server is through MCP configurations:
       "command": "docker",
       "args": [
         "run",
-        "--pull", "always",
+        "--pull",
+        "always",
         "-i",
         "--rm",
-        "-e", "BACKLOG_DOMAIN",
-        "-e", "BACKLOG_API_KEY",
+        "-e",
+        "BACKLOG_DOMAIN",
+        "-e",
+        "BACKLOG_API_KEY",
         "ghcr.io/nulab/backlog-mcp-server"
       ],
       "env": {
@@ -79,9 +82,7 @@ You can also run the server directly using `npx` without cloning the repository.
   "mcpServers": {
     "backlog": {
       "command": "npx",
-      "args": [
-        "backlog-mcp-server"
-      ],
+      "args": ["backlog-mcp-server"],
       "env": {
         "BACKLOG_DOMAIN": "your-domain.backlog.com",
         "BACKLOG_API_KEY": "your-api-key"
@@ -96,6 +97,7 @@ Replace `your-domain.backlog.com` with your Backlog domain and `your-api-key` wi
 ### Option 3: Manual Setup (Node.js)
 
 1. Clone and install:
+
    ```bash
    git clone https://github.com/nulab/backlog-mcp-server.git
    cd backlog-mcp-server
@@ -103,23 +105,39 @@ Replace `your-domain.backlog.com` with your Backlog domain and `your-api-key` wi
    npm run build
    ```
 
-2. Set your json to use as MCP
-  ```json
-  {
-    "mcpServers": {
-      "backlog": {
-        "command": "node",
-        "args": [
-          "your-repository-location/build/index.js"
-        ],
-        "env": {
-          "BACKLOG_DOMAIN": "your-domain.backlog.com",
-          "BACKLOG_API_KEY": "your-api-key"
-        }
+2. Create `.env` from template and set required variables:
+
+```bash
+cp .env.example .env
+```
+
+Set the following values in `.env`:
+
+- `BACKLOG_DOMAIN=your-domain.backlog.com`
+- `BACKLOG_API_KEY=your-api-key`
+
+3. Run locally:
+
+```bash
+npm run dev
+```
+
+4. Set your json to use as MCP
+
+```json
+{
+  "mcpServers": {
+    "backlog": {
+      "command": "node",
+      "args": ["your-repository-location/build/index.js"],
+      "env": {
+        "BACKLOG_DOMAIN": "your-domain.backlog.com",
+        "BACKLOG_API_KEY": "your-api-key"
       }
     }
   }
-  ```
+}
+```
 
 ## Tool Configuration
 
@@ -129,15 +147,15 @@ You can selectively enable or disable specific **toolsets** using the `--enable-
 
 The following toolsets are available (enabled by default when `"all"` is used):
 
-| Toolset         | Description                                                                          |
-|-----------------|--------------------------------------------------------------------------------------|
-| `space`         | Tools for managing Backlog space settings and general information                   |
-| `project`       | Tools for managing projects, categories, custom fields, and issue types              |
-| `issue`         | Tools for managing issues and their comments, version milestones                    |
-| `wiki`          | Tools for managing wiki pages                                                        |
-| `git`           | Tools for managing Git repositories and pull requests                                |
-| `notifications` | Tools for managing user notifications                                                |
-| `document`      | Tools for viewing documents and document trees                   |
+| Toolset         | Description                                                             |
+| --------------- | ----------------------------------------------------------------------- |
+| `space`         | Tools for managing Backlog space settings and general information       |
+| `project`       | Tools for managing projects, categories, custom fields, and issue types |
+| `issue`         | Tools for managing issues and their comments, version milestones        |
+| `wiki`          | Tools for managing wiki pages                                           |
+| `git`           | Tools for managing Git repositories and pull requests                   |
+| `notifications` | Tools for managing user notifications                                   |
+| `document`      | Tools for viewing documents and document trees                          |
 
 ### Specifying Toolsets
 
@@ -182,13 +200,17 @@ With dynamic toolsets enabled, the LLM will be able to list and activate toolset
 ## Available Tools
 
 ### Toolset: `space`
+
 Tools for managing Backlog space settings and general information.
+
 - `get_space`: Returns information about the Backlog space.
 - `get_users`: Returns list of users in the Backlog space.
 - `get_myself`: Returns information about the authenticated user.
 
 ### Toolset: `project`
+
 Tools for managing projects, categories, custom fields, and issue types.
+
 - `get_project_list`: Returns list of projects.
 - `add_project`: Creates a new project.
 - `get_project`: Returns information about a specific project.
@@ -196,7 +218,9 @@ Tools for managing projects, categories, custom fields, and issue types.
 - `delete_project`: Deletes a project.
 
 ### Toolset: `issue`
+
 Tools for managing issues, their comments, and related items like priorities, categories, custom fields, issue types, resolutions, and watching lists.
+
 - `get_issue`: Returns information about a specific issue.
 - `get_issues`: Returns list of issues.
 - `count_issues`: Returns count of issues.
@@ -222,14 +246,18 @@ Tools for managing issues, their comments, and related items like priorities, ca
 - `delete_version_milestone`: Deletes a version milestone.
 
 ### Toolset: `wiki`
+
 Tools for managing wiki pages.
+
 - `get_wiki_pages`: Returns list of Wiki pages.
 - `get_wikis_count`: Returns count of wiki pages in a project.
 - `get_wiki`: Returns information about a specific wiki page.
 - `add_wiki`: Creates a new wiki page.
 
 ### Toolset: `git`
+
 Tools for managing Git repositories and pull requests.
+
 - `get_git_repositories`: Returns list of Git repositories for a project.
 - `get_git_repository`: Returns information about a specific Git repository.
 - `get_pull_requests`: Returns list of pull requests for a repository.
@@ -242,14 +270,18 @@ Tools for managing Git repositories and pull requests.
 - `update_pull_request_comment`: Updates a comment on a pull request.
 
 ### Toolset: `notifications`
+
 Tools for managing user notifications.
+
 - `get_notifications`: Returns list of notifications.
 - `get_notifications_count`: Returns count of notifications.
 - `reset_unread_notification_count`: Resets unread notification count.
 - `mark_notification_as_read`: Marks a notification as read.
 
 ### Toolset: `document`
+
 Tools for managing documents and document trees in Backlog projects.
+
 - `get_document_tree`: Returns the hierarchical tree of documents for a project, including folders and ne
 - `get_documents`: Returns a flat list of documents in a project or folder.
 - `get_document`: Returns detailed information about a specific document, including metadata, content, an
@@ -259,31 +291,43 @@ Tools for managing documents and document trees in Backlog projects.
 Once the MCP server is configured in AI agents, you can use the tools directly in your conversations. Here are some examples:
 
 - Listing Projects
+
 ```
 Could you list all my Backlog projects?
 ```
+
 - Creating a New Issue
+
 ```
 Create a new bug issue in the PROJECT-KEY project with high priority titled "Fix login page error"
 ```
+
 - Getting Project Details
+
 ```
 Show me the details of the PROJECT-KEY project
 ```
+
 - Working with Git Repositories
+
 ```
 List all Git repositories in the PROJECT-KEY project
 ```
+
 - Managing Pull Requests
+
 ```
 Show me all open pull requests in the repository "repo-name" of PROJECT-KEY project
 ```
+
 ```
 Create a new pull request from branch "feature/new-feature" to "main" in the repository "repo-name" of PROJECT-KEY project
 ```
+
 - Watching Items
+
 ```
-Show me all items I'm watching 
+Show me all items I'm watching
 ```
 
 ### i18n / Overriding Descriptions
@@ -306,7 +350,7 @@ When the server starts, it determines the final description for each tool based
 2. Entries in `.backlog-mcp-serverrc.json` - Supported configuration file formats: .json, .yaml, .yml
 3. Built-in fallback values (English)
 
-Sample config: 
+Sample config:
 
 ```json
 {
@@ -317,9 +361,12 @@ Sample config:
         "run",
         "-i",
         "--rm",
-        "-e", "BACKLOG_DOMAIN",
-        "-e", "BACKLOG_API_KEY",
-        "-v", "/yourcurrentdir/.backlog-mcp-serverrc.json:/root/.backlog-mcp-serverrc.json:ro",
+        "-e",
+        "BACKLOG_DOMAIN",
+        "-e",
+        "BACKLOG_API_KEY",
+        "-v",
+        "/yourcurrentdir/.backlog-mcp-serverrc.json:/root/.backlog-mcp-serverrc.json:ro",
         "ghcr.io/nulab/backlog-mcp-server"
       ],
       "env": {
@@ -343,13 +390,14 @@ Example:
 docker run -i --rm ghcr.io/nulab/backlog-mcp-server node build/index.js --export-translations
 ```
 
-or 
+or
 
 ```bash
 npx github:nulab/backlog-mcp-server --export-translations
 ```
 
 ### Using a Japanese Translation Template
+
 A sample Japanese configuration file is provided at:
 
 ```bash
@@ -361,9 +409,10 @@ To use it, copy it to your home directory as .backlog-mcp-serverrc.json:
 You can then edit the file to customize the descriptions as needed.
 
 ### Using Environment Variables
+
 Alternatively, you can override tool descriptions via environment variables.
 
-The environment variable names are based on the tool keys, prefixed with BACKLOG_MCP_ and written in uppercase.
+The environment variable names are based on the tool keys, prefixed with BACKLOG*MCP* and written in uppercase.
 
 Example:
 To override the TOOL_ADD_ISSUE_COMMENT_DESCRIPTION:
@@ -441,6 +490,7 @@ get_project(projectIdOrKey: "PROJECT-KEY", fields: "{ name key description }")
 ```
 
 Benefits:
+
 - Reduce response size by requesting only needed fields
 - Focus on specific data points
 - Improve performance for large responses
@@ -448,6 +498,7 @@ Benefits:
 #### Token Limiting
 
 Large responses are automatically limited to prevent exceeding token limits:
+
 - Default limit: 50,000 tokens
 - Configurable via `MAX_TOKENS` environment variable
 - Responses exceeding the limit are truncated with a message
@@ -459,6 +510,7 @@ MAX_TOKENS=10000
 ```
 
 If a response exceeds the limit, it will be truncated with a warning.
+
 > Note: This is a best-effort mitigation, not a guaranteed enforcement.
 
 ### Full Custom Configuration Example
@@ -474,12 +526,18 @@ This section demonstrates advanced configuration using multiple environment vari
         "run",
         "-i",
         "--rm",
-        "-e", "BACKLOG_DOMAIN",
-        "-e", "BACKLOG_API_KEY",
-        "-e", "MAX_TOKENS",
-        "-e", "OPTIMIZE_RESPONSE",
-        "-e", "PREFIX",
-        "-e", "ENABLE_TOOLSETS",
+        "-e",
+        "BACKLOG_DOMAIN",
+        "-e",
+        "BACKLOG_API_KEY",
+        "-e",
+        "MAX_TOKENS",
+        "-e",
+        "OPTIMIZE_RESPONSE",
+        "-e",
+        "PREFIX",
+        "-e",
+        "ENABLE_TOOLSETS",
         "ghcr.io/nulab/backlog-mcp-server"
       ],
       "env": {
@@ -524,6 +582,7 @@ The server supports several command line options:
   Available toolsets: `space`, `project`, `issue`, `wiki`, `git`, `notifications`.
 
 Example:
+
 ```bash
 node build/index.js --optimize-response --max-tokens=100000 --prefix="backlog_" --enable-toolsets space,issue
 ```

package/package.json

@@ -1,20 +1,27 @@
 {
   "name": "backlog-mcp-server",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "bin": {
     "backlog-mcp-server": "./build/index.js"
   },
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nulab/backlog-mcp-server.git"
+  },
   "scripts": {
     "dev": "tsx src/index.ts",
     "build": "tsc && chmod 755 build/index.js",
-    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
-    "test:coverage": "NODE_OPTIONS=--experimental-vm-modules jest --coverage",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --ext .ts --fix",
     "format": "prettier --check \"**/*.{ts,tsx}\"",
-    "format:fix": "prettier --write \"**/*.{ts,tsx}\""
+    "format:fix": "prettier --write \"**/*.{ts,tsx}\"",
+    "typecheck": "tsc --noEmit",
+    "typecheck:all": "tsc --noEmit --project tsconfig.test.json"
   },
   "files": [
     "build"
@@ -33,22 +40,20 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.24.0",
-    "tsx": "^4.20.6",
     "@release-it/conventional-changelog": "^10.0.2",
-    "@types/jest": "^29.5.14",
     "@types/node": "^22.14.1",
     "@types/yargs": "^17.0.33",
     "@typescript-eslint/eslint-plugin": "^8.30.1",
     "@typescript-eslint/parser": "^8.30.1",
     "@typescript-eslint/utils": "^8.30.1",
+    "@vitest/coverage-v8": "^4.0.0",
     "eslint": "^9.24.0",
     "eslint-config-prettier": "^10.1.2",
     "eslint-plugin-prettier": "^5.2.6",
-    "jest": "^29.7.0",
     "prettier": "^3.5.3",
     "release-it": "^19.0.0",
-    "ts-jest": "^29.3.2",
-    "ts-node": "^10.9.2",
-    "typescript": "^5.8.3"
+    "tsx": "^4.20.6",
+    "typescript": "^5.8.3",
+    "vitest": "^4.0.0"
   }
 }

package/build/backlog/backlogErrorHandler.js

@@ -1,8 +0,0 @@
-import { parseBacklogAPIError } from './parseBacklogAPIError.js';
-export const backlogErrorHandler = (err) => {
-    const parsed = parseBacklogAPIError(err);
-    return {
-        kind: 'error',
-        message: parsed.message,
-    };
-};