backlog-mcp-server 0.12.0 → 0.13.0

package/README.ja.md

@@ -101,8 +101,8 @@ docker pull ghcr.io/nulab/backlog-mcp-server:latest
    ```bash
    git clone https://github.com/nulab/backlog-mcp-server.git
    cd backlog-mcp-server
-   npm install
-   npm run build
+   pnpm install
+   pnpm run build
    ```
 
 2. テンプレートから `.env` を作成し、必須の環境変数を設定します：
@@ -119,7 +119,7 @@ cp .env.example .env
 3. ローカルで起動します：
 
 ```bash
-npm run dev
+pnpm run dev
 ```
 
 4. MCPとして使用するJSONを設定します：
@@ -529,7 +529,7 @@ MAX_TOKENS=10000
 ### テストの実行
 
 ```bash
-npm test
+pnpm test
 ```
 
 ### 新しいツールの追加

package/README.md

@@ -101,8 +101,8 @@ Replace `your-domain.backlog.com` with your Backlog domain and `your-api-key` wi
    ```bash
    git clone https://github.com/nulab/backlog-mcp-server.git
    cd backlog-mcp-server
-   npm install
-   npm run build
+   pnpm install
+   pnpm run build
    ```
 
 2. Create `.env` from template and set required variables:
@@ -119,7 +119,7 @@ Set the following values in `.env`:
 3. Run locally:
 
 ```bash
-npm run dev
+pnpm run dev
 ```
 
 4. Set your json to use as MCP
@@ -144,7 +144,7 @@ npm run dev
 By default the server uses **stdio**. To run the [MCP Streamable HTTP](https://modelcontextprotocol.io/) transport instead (JSON-RPC over HTTP, same tools as stdio), start with `--transport http` or set `MCP_TRANSPORT=http`.
 
 ```bash
-npm run build
+pnpm run build
 MCP_TRANSPORT=http MCP_HTTP_PORT=3333 node build/index.js
 ```
 
@@ -154,13 +154,13 @@ MCP_TRANSPORT=http MCP_HTTP_PORT=3333 node build/index.js
 
 Environment variables (CLI flags override when both are set):
 
-| Variable | Description |
-| -------- | ----------- |
-| `MCP_TRANSPORT` | `stdio` (default) or `http` |
-| `MCP_HTTP_HOST` | Bind address (default `127.0.0.1`) |
-| `MCP_HTTP_PORT` | Port (default `3333`) |
-| `MCP_HTTP_PATH` | URL path (default `/mcp`) |
-| `MCP_HTTP_JSON_RESPONSE` | `true` to prefer JSON responses over SSE when supported |
+| Variable                 | Description                                                                                |
+| ------------------------ | ------------------------------------------------------------------------------------------ |
+| `MCP_TRANSPORT`          | `stdio` (default) or `http`                                                                |
+| `MCP_HTTP_HOST`          | Bind address (default `127.0.0.1`)                                                         |
+| `MCP_HTTP_PORT`          | Port (default `3333`)                                                                      |
+| `MCP_HTTP_PATH`          | URL path (default `/mcp`)                                                                  |
+| `MCP_HTTP_JSON_RESPONSE` | `true` to prefer JSON responses over SSE when supported                                    |
 | `MCP_HTTP_ALLOWED_HOSTS` | Comma-separated allowed `Host` values when binding to `0.0.0.0` (DNS rebinding protection) |
 
 ### OAuth 2.0 Authentication (Remote MCP)
@@ -178,11 +178,11 @@ The server implements the [MCP Third-Party Authorization Flow](https://modelcont
 
 2. Set the following environment variables (in addition to `BACKLOG_DOMAIN`):
 
-| Variable | Description |
-| -------- | ----------- |
-| `BACKLOG_OAUTH_CLIENT_ID` | OAuth Client ID from your Backlog application |
-| `BACKLOG_OAUTH_CLIENT_SECRET` | OAuth Client Secret from your Backlog application |
-| `MCP_SERVER_BASE_URL` | Public URL of your MCP server (e.g., `https://mcp.example.com`) |
+| Variable                      | Description                                                     |
+| ----------------------------- | --------------------------------------------------------------- |
+| `BACKLOG_OAUTH_CLIENT_ID`     | OAuth Client ID from your Backlog application                   |
+| `BACKLOG_OAUTH_CLIENT_SECRET` | OAuth Client Secret from your Backlog application               |
+| `MCP_SERVER_BASE_URL`         | Public URL of your MCP server (e.g., `https://mcp.example.com`) |
 
 > **Note:** `BACKLOG_API_KEY` is **not required** when OAuth is enabled — each user authenticates with their own Backlog account.
 
@@ -198,18 +198,19 @@ node build/index.js --transport http --http-host 0.0.0.0 --http-port 3333
 
 The server automatically exposes the following OAuth endpoints when OAuth is enabled:
 
-| Endpoint | Description |
-| -------- | ----------- |
-| `GET /.well-known/oauth-authorization-server` | OAuth Authorization Server Metadata ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)) |
-| `GET /.well-known/oauth-protected-resource/mcp` | OAuth Protected Resource Metadata ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)) |
-| `POST /register` | Dynamic Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) |
-| `GET /authorize` | Authorization endpoint (redirects to Backlog OAuth) |
-| `GET /callback` | Backlog OAuth callback |
-| `POST /token` | Token endpoint (authorization code & refresh token) |
+| Endpoint                                        | Description                                                                                     |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `GET /.well-known/oauth-authorization-server`   | OAuth Authorization Server Metadata ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)) |
+| `GET /.well-known/oauth-protected-resource/mcp` | OAuth Protected Resource Metadata ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728))   |
+| `POST /register`                                | Dynamic Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591))         |
+| `GET /authorize`                                | Authorization endpoint (redirects to Backlog OAuth)                                             |
+| `GET /callback`                                 | Backlog OAuth callback                                                                          |
+| `POST /token`                                   | Token endpoint (authorization code & refresh token)                                             |
 
 MCP clients that support the MCP authorization specification will use these endpoints automatically.
 
 > **Limitations:**
+>
 > - OAuth mode currently supports a single Backlog organization. It is not compatible with the multi-organization configuration.
 > - Client registrations and tokens are stored in memory and will be lost on server restart.
 
@@ -288,6 +289,7 @@ 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.
+- `get_project_users`: Returns list of users in a specific project.
 - `update_project`: Updates an existing project.
 - `delete_project`: Deletes a project.
 
@@ -633,7 +635,7 @@ This section demonstrates advanced configuration using multiple environment vari
 ### Running Tests
 
 ```bash
-npm test
+pnpm test
 ```
 
 ### Adding New Tools

package/build/index.js

@@ -2,7 +2,6 @@
 // Copyright (c) 2025 Nulab inc.
 // Licensed under the MIT License.
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import dotenv from 'dotenv';
 import { default as env } from 'env-var';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
@@ -20,11 +19,11 @@ const { version } = packageJson;
 // as an error event on stdout/stderr streams — both must be handled.
 process.on('SIGPIPE', () => { });
 process.stdout.on('error', (err) => {
-    if (err.code !== 'EPIPE')
+    if (!('code' in err) || err.code !== 'EPIPE')
         throw err;
 });
 process.stderr.on('error', (err) => {
-    if (err.code !== 'EPIPE')
+    if (!('code' in err) || err.code !== 'EPIPE')
         throw err;
 });
 process.on('uncaughtException', (error) => {
@@ -35,7 +34,12 @@ process.on('unhandledRejection', (reason) => {
     logger.error({ err: reason }, 'Unhandled rejection');
     process.exit(1);
 });
-dotenv.config();
+try {
+    process.loadEnvFile();
+}
+catch {
+    // .env file is optional
+}
 const oauthConfig = getBacklogOAuthConfig();
 const argv = yargs(hideBin(process.argv))
     .option('transport', {

package/build/tools/getProjectUsers.js

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import { buildToolSchema } from '../types/tool.js';
+import { UserSchema } from '../types/zod/backlogOutputDefinition.js';
+import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
+const getProjectUsersSchema = buildToolSchema((t) => ({
+    projectId: z
+        .number()
+        .optional()
+        .describe(t('TOOL_GET_PROJECT_USERS_PROJECT_ID', 'The numeric ID of the project (e.g., 12345)')),
+    projectKey: z
+        .string()
+        .optional()
+        .describe(t('TOOL_GET_PROJECT_USERS_PROJECT_KEY', "The key of the project (e.g., 'PROJECT')")),
+}));
+export const getProjectUsersTool = (backlog, { t }) => {
+    return {
+        name: 'get_project_users',
+        description: t('TOOL_GET_PROJECT_USERS_DESCRIPTION', 'Returns list of users in a specific project'),
+        schema: z.object(getProjectUsersSchema(t)),
+        outputSchema: UserSchema,
+        importantFields: ['userId', 'name', 'roleType', 'lang'],
+        handler: async ({ projectId, projectKey }) => {
+            const result = resolveIdOrKey('project', { id: projectId, key: projectKey }, t);
+            if (!result.ok) {
+                throw result.error;
+            }
+            return backlog.getProjectUsers(result.value);
+        },
+    };
+};

package/build/tools/tools.js

@@ -22,6 +22,7 @@ import { getNotificationsCountTool } from './getNotificationsCount.js';
 import { getPrioritiesTool } from './getPriorities.js';
 import { getProjectTool } from './getProject.js';
 import { getProjectListTool } from './getProjectList.js';
+import { getProjectUsersTool } from './getProjectUsers.js';
 import { getPullRequestTool } from './getPullRequest.js';
 import { getPullRequestCommentsTool } from './getPullRequestComments.js';
 import { getPullRequestsTool } from './getPullRequests.js';
@@ -79,6 +80,7 @@ export const allTools = (backlog, helper) => {
                     getProjectListTool(backlog, helper),
                     addProjectTool(backlog, helper),
                     getProjectTool(backlog, helper),
+                    getProjectUsersTool(backlog, helper),
                     updateProjectTool(backlog, helper),
                     deleteProjectTool(backlog, helper),
                 ],

package/package.json

@@ -1,16 +1,61 @@
 {
   "name": "backlog-mcp-server",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "type": "module",
   "bin": {
     "backlog-mcp-server": "./build/index.js"
   },
+  "engines": {
+    "node": ">=22"
+  },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=22",
+      "onFail": "warn"
+    }
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nulab/backlog-mcp-server.git"
   },
+  "files": [
+    "build"
+  ],
+  "dependencies": {
+    "@hono/node-server": "^2.0.4",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "backlog-js": "^0.16.0",
+    "cosmiconfig": "^9.0.1",
+    "env-var": "^7.5.0",
+    "graphql": "^16.14.1",
+    "hono": "^4.12.25",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "yargs": "^18.0.0",
+    "zod": "^3.24.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@release-it/conventional-changelog": "^11.0.1",
+    "@types/node": "^25.9.2",
+    "@types/yargs": "^17.0.35",
+    "@typescript-eslint/eslint-plugin": "^8.60.1",
+    "@typescript-eslint/parser": "^8.60.1",
+    "@typescript-eslint/utils": "^8.60.1",
+    "@vitest/coverage-v8": "^4.1.8",
+    "eslint": "^10.4.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.6",
+    "prettier": "^3.8.3",
+    "release-it": "^20.2.0",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
   "scripts": {
+    "preinstall": "npx only-allow pnpm",
     "dev": "tsx src/index.ts",
     "build": "tsc && chmod 755 build/index.js",
     "test": "vitest run",
@@ -22,40 +67,5 @@
     "format:fix": "prettier --write \"**/*.{ts,tsx}\"",
     "typecheck": "tsc --noEmit",
     "typecheck:all": "tsc --noEmit --project tsconfig.test.json"
-  },
-  "files": [
-    "build"
-  ],
-  "dependencies": {
-    "@hono/node-server": "^1.19.14",
-    "@modelcontextprotocol/sdk": "^1.26.0",
-    "backlog-js": "^0.16.0",
-    "cosmiconfig": "^9.0.0",
-    "dotenv": "^16.5.0",
-    "env-var": "^7.5.0",
-    "graphql": "^16.11.0",
-    "hono": "^4.12.23",
-    "pino": "^9.9.0",
-    "pino-pretty": "^13.1.1",
-    "yargs": "^18.0.0",
-    "zod": "^3.24.3"
-  },
-  "devDependencies": {
-    "@eslint/js": "^9.24.0",
-    "@release-it/conventional-changelog": "^11.0.0",
-    "@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",
-    "prettier": "^3.5.3",
-    "release-it": "^20.0.1",
-    "tsx": "^4.20.6",
-    "typescript": "^5.8.3",
-    "vitest": "^4.0.0"
   }
-}
+}