backlog-mcp-server 0.11.0 → 0.12.0

package/README.ja.md

@@ -139,6 +139,56 @@ npm run dev
 }
 ```
 
+### OAuth 2.0 認証（リモートMCP）
+
+MCPサーバーをネットワーク経由で公開する場合、OAuth 2.0認証を有効にすることで、共有APIキーではなく各ユーザーが自分のBacklogアカウントで認証できます。
+
+サーバーは [MCP Third-Party Authorization Flow](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) を実装しており、MCPクライアント向けのOAuth認可サーバーとBacklog向けのOAuthクライアントの両方として動作します。
+
+#### 前提条件
+
+1. Backlogスペースにてアプリケーションを登録します：
+   - Backlogスペース → 個人設定 → アプリケーションの登録
+   - **リダイレクトURI** を `<MCP_SERVER_BASE_URL>/callback`（例：`https://mcp.example.com/callback`）に設定
+   - **Client ID** と **Client Secret** をメモ
+
+2. 以下の環境変数を設定します（`BACKLOG_DOMAIN` に加えて）：
+
+| 変数 | 説明 |
+| ---- | ---- |
+| `BACKLOG_OAUTH_CLIENT_ID` | Backlogアプリケーションの OAuth Client ID |
+| `BACKLOG_OAUTH_CLIENT_SECRET` | Backlogアプリケーションの OAuth Client Secret |
+| `MCP_SERVER_BASE_URL` | MCPサーバーの公開URL（例：`https://mcp.example.com`） |
+
+> **注意:** OAuth有効時は `BACKLOG_API_KEY` は**不要**です。各ユーザーが自分のBacklogアカウントで認証します。
+
+#### 使用例
+
+```bash
+BACKLOG_DOMAIN=your-space.backlog.com \
+BACKLOG_OAUTH_CLIENT_ID=your-client-id \
+BACKLOG_OAUTH_CLIENT_SECRET=your-client-secret \
+MCP_SERVER_BASE_URL=https://mcp.example.com \
+node build/index.js --transport http --http-host 0.0.0.0 --http-port 3333
+```
+
+OAuth有効時、サーバーは以下のOAuthエンドポイントを自動的に公開します：
+
+| エンドポイント | 説明 |
+| ------------- | ---- |
+| `GET /.well-known/oauth-authorization-server` | OAuth認可サーバーメタデータ（[RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)） |
+| `GET /.well-known/oauth-protected-resource/mcp` | OAuthリソースメタデータ（[RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)） |
+| `POST /register` | 動的クライアント登録（[RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)） |
+| `GET /authorize` | 認可エンドポイント（Backlog OAuthへリダイレクト） |
+| `GET /callback` | Backlog OAuthコールバック |
+| `POST /token` | トークンエンドポイント（認可コード＆リフレッシュトークン） |
+
+MCP認可仕様に対応するMCPクライアントは、これらのエンドポイントを自動的に使用します。
+
+> **制約事項:**
+> - OAuthモードは現在、単一のBacklog組織のみをサポートしています。複数組織設定との併用はできません。
+> - クライアント登録やトークンはメモリ内に保持されるため、サーバー再起動時に失われます。
+
 ## ツール設定
 
 `--enable-toolsets` コマンドラインフラグまたは `ENABLE_TOOLSETS` 環境変数を使用して、特定の **ツールセット** を選択的に有効または無効にすることができます。これにより、AIエージェントが利用できるツールをより細かく制御し、コンテキストサイズを削減するのに役立ちます。

package/README.md

@@ -163,6 +163,56 @@ Environment variables (CLI flags override when both are set):
 | `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)
+
+When exposing the MCP server over a network, you can enable OAuth 2.0 authentication so that each user authenticates with their own Backlog account instead of sharing a single API key.
+
+The server implements the [MCP Third-Party Authorization Flow](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) by acting as both an OAuth authorization server (for MCP clients) and an OAuth client (for Backlog).
+
+#### Prerequisites
+
+1. Register an OAuth application in your Backlog space:
+   - Go to your Backlog space → Personal Settings → Register Application
+   - Set the **Redirect URI** to `<MCP_SERVER_BASE_URL>/callback` (e.g., `https://mcp.example.com/callback`)
+   - Note the **Client ID** and **Client Secret**
+
+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`) |
+
+> **Note:** `BACKLOG_API_KEY` is **not required** when OAuth is enabled — each user authenticates with their own Backlog account.
+
+#### Example
+
+```bash
+BACKLOG_DOMAIN=your-space.backlog.com \
+BACKLOG_OAUTH_CLIENT_ID=your-client-id \
+BACKLOG_OAUTH_CLIENT_SECRET=your-client-secret \
+MCP_SERVER_BASE_URL=https://mcp.example.com \
+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) |
+
+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.
+
 ## Tool Configuration
 
 You can selectively enable or disable specific **toolsets** using the `--enable-toolsets` command-line flag or the `ENABLE_TOOLSETS` environment variable. This allows better control over which tools are available to the AI agent and helps reduce context size.

package/build/auth/backlogAuthContext.js

@@ -0,0 +1,10 @@
+// Copyright (c) 2025 Nulab inc.
+// Licensed under the MIT License.
+import { AsyncLocalStorage } from 'node:async_hooks';
+const accessTokenStorage = new AsyncLocalStorage();
+export function runWithAccessToken(token, fn) {
+    return accessTokenStorage.run(token, fn);
+}
+export function getCurrentAccessToken() {
+    return accessTokenStorage.getStore();
+}

package/build/auth/backlogOAuthClient.js

@@ -0,0 +1,57 @@
+// Copyright (c) 2025 Nulab inc.
+// Licensed under the MIT License.
+export function buildBacklogAuthorizationUrl(config, redirectUri, state) {
+    const params = new URLSearchParams({
+        response_type: 'code',
+        client_id: config.clientId,
+        redirect_uri: redirectUri,
+        state,
+    });
+    return `https://${config.backlogDomain}/OAuth2AccessRequest.action?${params.toString()}`;
+}
+export async function exchangeBacklogCode(config, code, redirectUri) {
+    const params = new URLSearchParams({
+        grant_type: 'authorization_code',
+        code,
+        client_id: config.clientId,
+        client_secret: config.clientSecret,
+        redirect_uri: redirectUri,
+    });
+    const response = await fetch(`https://${config.backlogDomain}/api/v2/oauth2/token`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: params.toString(),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Backlog token exchange failed (${response.status}): ${text}`);
+    }
+    return (await response.json());
+}
+export async function refreshBacklogToken(config, refreshToken) {
+    const params = new URLSearchParams({
+        grant_type: 'refresh_token',
+        client_id: config.clientId,
+        client_secret: config.clientSecret,
+        refresh_token: refreshToken,
+    });
+    const response = await fetch(`https://${config.backlogDomain}/api/v2/oauth2/token`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: params.toString(),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Backlog token refresh failed (${response.status}): ${text}`);
+    }
+    return (await response.json());
+}
+export async function verifyBacklogToken(domain, accessToken) {
+    const response = await fetch(`https://${domain}/api/v2/users/myself`, {
+        headers: { Authorization: `Bearer ${accessToken}` },
+    });
+    if (!response.ok) {
+        throw new Error(`Backlog token verification failed (${response.status})`);
+    }
+    return (await response.json());
+}

package/build/auth/backlogOAuthConfig.js

@@ -0,0 +1,25 @@
+// Copyright (c) 2025 Nulab inc.
+// Licensed under the MIT License.
+export function getBacklogOAuthConfig(env = process.env) {
+    const clientId = env.BACKLOG_OAUTH_CLIENT_ID;
+    if (!clientId)
+        return undefined;
+    const clientSecret = env.BACKLOG_OAUTH_CLIENT_SECRET;
+    if (!clientSecret) {
+        throw new Error('BACKLOG_OAUTH_CLIENT_SECRET is required when BACKLOG_OAUTH_CLIENT_ID is set.');
+    }
+    const backlogDomain = env.BACKLOG_DOMAIN;
+    if (!backlogDomain) {
+        throw new Error('BACKLOG_DOMAIN is required when BACKLOG_OAUTH_CLIENT_ID is set.');
+    }
+    const serverBaseUrl = env.MCP_SERVER_BASE_URL;
+    if (!serverBaseUrl) {
+        throw new Error('MCP_SERVER_BASE_URL is required when BACKLOG_OAUTH_CLIENT_ID is set.');
+    }
+    return {
+        clientId,
+        clientSecret,
+        backlogDomain,
+        serverBaseUrl: serverBaseUrl.replace(/\/+$/, ''),
+    };
+}

package/build/auth/bearerAuthMiddleware.js

@@ -0,0 +1,58 @@
+// Copyright (c) 2025 Nulab inc.
+// Licensed under the MIT License.
+import { verifyBacklogToken } from './backlogOAuthClient.js';
+import { logger } from '../utils/logger.js';
+const CACHE_TTL_MS = 5 * 60 * 1000;
+export function createBearerAuthMiddleware(store, config, mcpPath) {
+    const prmPath = mcpPath === '/' ? '' : mcpPath;
+    const resourceMetadataUrl = `${config.serverBaseUrl}/.well-known/oauth-protected-resource${prmPath}`;
+    return async (c, next) => {
+        const authHeader = c.req.header('authorization');
+        if (!authHeader) {
+            c.header('WWW-Authenticate', `Bearer resource_metadata="${resourceMetadataUrl}"`);
+            return c.json({
+                error: 'invalid_token',
+                error_description: 'Missing Authorization header',
+            }, 401);
+        }
+        const [type, mcpToken] = authHeader.split(' ');
+        if (type?.toLowerCase() !== 'bearer' || !mcpToken) {
+            c.header('WWW-Authenticate', `Bearer error="invalid_token", error_description="Invalid Authorization header format", resource_metadata="${resourceMetadataUrl}"`);
+            return c.json({ error: 'invalid_token', error_description: 'Expected Bearer token' }, 401);
+        }
+        const tokenEntry = store.getMcpToken(mcpToken);
+        if (!tokenEntry) {
+            c.header('WWW-Authenticate', `Bearer error="invalid_token", error_description="Unknown or expired token", resource_metadata="${resourceMetadataUrl}"`);
+            return c.json({
+                error: 'invalid_token',
+                error_description: 'Unknown or expired token',
+            }, 401);
+        }
+        const cached = store.getCachedVerification(mcpToken);
+        if (cached) {
+            c.set('authInfo', cached);
+            await next();
+            return;
+        }
+        try {
+            const user = await verifyBacklogToken(config.backlogDomain, tokenEntry.backlogAccessToken);
+            const authInfo = {
+                token: tokenEntry.backlogAccessToken,
+                clientId: String(user.id),
+                scopes: [],
+                expiresAt: Math.floor(Date.now() / 1000) + CACHE_TTL_MS / 1000,
+            };
+            store.cacheVerification(mcpToken, authInfo, CACHE_TTL_MS);
+            c.set('authInfo', authInfo);
+            await next();
+        }
+        catch (err) {
+            logger.warn({ err }, 'Bearer token verification failed');
+            c.header('WWW-Authenticate', `Bearer error="invalid_token", error_description="Token verification failed", resource_metadata="${resourceMetadataUrl}"`);
+            return c.json({
+                error: 'invalid_token',
+                error_description: 'Token verification failed',
+            }, 401);
+        }
+    };
+}

package/build/auth/oauthRoutes.js

@@ -0,0 +1,336 @@
+// Copyright (c) 2025 Nulab inc.
+// Licensed under the MIT License.
+import { randomUUID, randomBytes, createHash } from 'node:crypto';
+import { Hono } from 'hono';
+import { buildBacklogAuthorizationUrl, exchangeBacklogCode, refreshBacklogToken, } from './backlogOAuthClient.js';
+import { logger } from '../utils/logger.js';
+const AUTH_CODE_TTL_MS = 10 * 60 * 1000;
+const REFRESH_TOKEN_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+const LOCALHOST_HOSTS = ['localhost', '127.0.0.1', '[::1]'];
+const SUPPORTED_AUTH_METHODS = ['client_secret_post', 'none'];
+function verifyPkce(codeVerifier, codeChallenge) {
+    const hash = createHash('sha256').update(codeVerifier).digest('base64url');
+    return hash === codeChallenge;
+}
+function oauthError(code, description) {
+    return { error: code, error_description: description };
+}
+function isValidRedirectUri(uri) {
+    try {
+        const parsed = new URL(uri);
+        if (parsed.protocol === 'https:')
+            return true;
+        if (parsed.protocol === 'http:' &&
+            LOCALHOST_HOSTS.includes(parsed.hostname))
+            return true;
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+export function createOAuthRoutes(config, store, mcpPath) {
+    const app = new Hono();
+    const { serverBaseUrl } = config;
+    const callbackUrl = `${serverBaseUrl}/callback`;
+    const resourceUri = `${serverBaseUrl}${mcpPath}`;
+    // RFC 8414 — OAuth Authorization Server Metadata
+    app.get('/.well-known/oauth-authorization-server', (c) => {
+        c.header('Cache-Control', 'public, max-age=3600');
+        return c.json({
+            issuer: serverBaseUrl,
+            authorization_endpoint: `${serverBaseUrl}/authorize`,
+            token_endpoint: `${serverBaseUrl}/token`,
+            registration_endpoint: `${serverBaseUrl}/register`,
+            response_types_supported: ['code'],
+            grant_types_supported: ['authorization_code', 'refresh_token'],
+            token_endpoint_auth_methods_supported: ['client_secret_post', 'none'],
+            code_challenge_methods_supported: ['S256'],
+        });
+    });
+    // RFC 9728 — OAuth Protected Resource Metadata
+    const prm = mcpPath === '/' ? '' : mcpPath;
+    app.get(`/.well-known/oauth-protected-resource${prm}`, (c) => {
+        c.header('Cache-Control', 'public, max-age=3600');
+        return c.json({
+            resource: resourceUri,
+            authorization_servers: [serverBaseUrl],
+        });
+    });
+    // Dynamic Client Registration (RFC 7591)
+    app.post('/register', async (c) => {
+        let body;
+        try {
+            body = (await c.req.json());
+        }
+        catch {
+            return c.json(oauthError('invalid_request', 'Invalid JSON body'), 400);
+        }
+        const redirectUris = body.redirect_uris;
+        if (!Array.isArray(redirectUris) ||
+            redirectUris.length === 0 ||
+            !redirectUris.every((u) => typeof u === 'string')) {
+            return c.json(oauthError('invalid_client_metadata', 'redirect_uris must be a non-empty array of strings'), 400);
+        }
+        for (const uri of redirectUris) {
+            if (!isValidRedirectUri(uri)) {
+                return c.json(oauthError('invalid_client_metadata', `redirect_uri must use https or http://localhost: ${uri}`), 400);
+            }
+        }
+        const authMethod = typeof body.token_endpoint_auth_method === 'string'
+            ? body.token_endpoint_auth_method
+            : 'client_secret_post';
+        if (!SUPPORTED_AUTH_METHODS.includes(authMethod)) {
+            return c.json(oauthError('invalid_client_metadata', `Unsupported token_endpoint_auth_method: ${authMethod}. Supported: ${SUPPORTED_AUTH_METHODS.join(', ')}`), 400);
+        }
+        const clientId = randomUUID();
+        const clientSecret = authMethod === 'none' ? undefined : randomBytes(32).toString('hex');
+        const now = Math.floor(Date.now() / 1000);
+        const client = {
+            client_id: clientId,
+            client_secret: clientSecret,
+            client_id_issued_at: now,
+            client_secret_expires_at: 0,
+            redirect_uris: redirectUris,
+            client_name: typeof body.client_name === 'string' ? body.client_name : undefined,
+            token_endpoint_auth_method: authMethod,
+            grant_types: ['authorization_code', 'refresh_token'],
+            response_types: ['code'],
+        };
+        if (!store.registerClient(client)) {
+            return c.json(oauthError('server_error', 'Maximum number of registered clients reached'), 503);
+        }
+        logger.info({ clientId }, 'Registered new OAuth client');
+        return c.json(client, 201);
+    });
+    // Authorization Endpoint
+    app.get('/authorize', async (c) => {
+        const params = Object.fromEntries(new URL(c.req.url).searchParams.entries());
+        const clientId = params.client_id;
+        const redirectUri = params.redirect_uri;
+        const responseType = params.response_type;
+        const codeChallenge = params.code_challenge;
+        const codeChallengeMethod = params.code_challenge_method;
+        const scope = params.scope;
+        const state = params.state;
+        const resource = params.resource;
+        // Phase 1: Validate client and redirect_uri (errors returned directly)
+        if (!clientId) {
+            return c.json(oauthError('invalid_request', 'Missing client_id'), 400);
+        }
+        const client = store.getClient(clientId);
+        if (!client) {
+            return c.json(oauthError('invalid_client', 'Unknown client_id'), 400);
+        }
+        if (!redirectUri) {
+            if (client.redirect_uris.length !== 1) {
+                return c.json(oauthError('invalid_request', 'redirect_uri is required'), 400);
+            }
+        }
+        else if (!client.redirect_uris.includes(redirectUri)) {
+            return c.json(oauthError('invalid_request', 'Unregistered redirect_uri'), 400);
+        }
+        const effectiveRedirectUri = redirectUri ?? client.redirect_uris[0];
+        // Phase 2: Validate other params (errors redirected)
+        if (responseType !== 'code') {
+            const url = new URL(effectiveRedirectUri);
+            url.searchParams.set('error', 'unsupported_response_type');
+            url.searchParams.set('error_description', 'Only response_type=code is supported');
+            if (state)
+                url.searchParams.set('state', state);
+            return c.redirect(url.href, 302);
+        }
+        if (!codeChallenge) {
+            const url = new URL(effectiveRedirectUri);
+            url.searchParams.set('error', 'invalid_request');
+            url.searchParams.set('error_description', 'code_challenge is required');
+            if (state)
+                url.searchParams.set('state', state);
+            return c.redirect(url.href, 302);
+        }
+        if (codeChallengeMethod && codeChallengeMethod !== 'S256') {
+            const url = new URL(effectiveRedirectUri);
+            url.searchParams.set('error', 'invalid_request');
+            url.searchParams.set('error_description', 'Only code_challenge_method=S256 is supported');
+            if (state)
+                url.searchParams.set('state', state);
+            return c.redirect(url.href, 302);
+        }
+        if (resource && resource !== resourceUri) {
+            const url = new URL(effectiveRedirectUri);
+            url.searchParams.set('error', 'invalid_target');
+            url.searchParams.set('error_description', 'Invalid resource parameter');
+            if (state)
+                url.searchParams.set('state', state);
+            return c.redirect(url.href, 302);
+        }
+        // Store pending authorization and redirect to Backlog
+        const backlogState = randomUUID();
+        store.storePendingAuth(backlogState, {
+            mcpClientId: clientId,
+            codeChallenge,
+            redirectUri: effectiveRedirectUri,
+            resource: resource ?? resourceUri,
+            scopes: scope ? scope.split(' ') : [],
+            state,
+            createdAt: Date.now(),
+        });
+        const backlogAuthUrl = buildBacklogAuthorizationUrl(config, callbackUrl, backlogState);
+        return c.redirect(backlogAuthUrl, 302);
+    });
+    // Backlog OAuth Callback
+    app.get('/callback', async (c) => {
+        const url = new URL(c.req.url);
+        const backlogCode = url.searchParams.get('code');
+        const backlogState = url.searchParams.get('state');
+        const backlogError = url.searchParams.get('error');
+        if (!backlogState) {
+            return c.text('Missing state parameter from Backlog', 400);
+        }
+        if (backlogError || !backlogCode) {
+            const pending = store.consumePendingAuth(backlogState);
+            if (!pending) {
+                return c.text('Unknown or expired authorization state. Please start the authorization flow again.', 400);
+            }
+            const errorUrl = new URL(pending.redirectUri);
+            errorUrl.searchParams.set('error', backlogError ?? 'access_denied');
+            errorUrl.searchParams.set('error_description', url.searchParams.get('error_description') ??
+                'Authorization was denied by the user');
+            if (pending.state)
+                errorUrl.searchParams.set('state', pending.state);
+            return c.redirect(errorUrl.href, 302);
+        }
+        const pending = store.consumePendingAuth(backlogState);
+        if (!pending) {
+            return c.text('Unknown or expired authorization state. Please start the authorization flow again.', 400);
+        }
+        let backlogTokens;
+        try {
+            backlogTokens = await exchangeBacklogCode(config, backlogCode, callbackUrl);
+        }
+        catch (err) {
+            logger.error({ err }, 'Failed to exchange Backlog authorization code');
+            const url = new URL(pending.redirectUri);
+            url.searchParams.set('error', 'server_error');
+            url.searchParams.set('error_description', 'Failed to exchange authorization code with Backlog');
+            if (pending.state)
+                url.searchParams.set('state', pending.state);
+            return c.redirect(url.href, 302);
+        }
+        const mcpCode = randomUUID();
+        store.storeAuthCode(mcpCode, {
+            mcpClientId: pending.mcpClientId,
+            backlogTokens,
+            codeChallenge: pending.codeChallenge,
+            redirectUri: pending.redirectUri,
+            resource: pending.resource,
+            expiresAt: Date.now() + AUTH_CODE_TTL_MS,
+        });
+        const redirectUrl = new URL(pending.redirectUri);
+        redirectUrl.searchParams.set('code', mcpCode);
+        if (pending.state)
+            redirectUrl.searchParams.set('state', pending.state);
+        return c.redirect(redirectUrl.href, 302);
+    });
+    // Token Endpoint
+    app.post('/token', async (c) => {
+        c.header('Cache-Control', 'no-store');
+        const body = (await c.req.parseBody());
+        const grantType = body.grant_type;
+        const clientId = body.client_id;
+        if (!clientId) {
+            return c.json(oauthError('invalid_request', 'Missing client_id'), 400);
+        }
+        const client = store.getClient(clientId);
+        if (!client) {
+            return c.json(oauthError('invalid_client', 'Unknown client_id'), 401);
+        }
+        if (client.client_secret && body.client_secret !== client.client_secret) {
+            return c.json(oauthError('invalid_client', 'Invalid client_secret'), 401);
+        }
+        if (grantType === 'authorization_code') {
+            const code = body.code;
+            const codeVerifier = body.code_verifier;
+            const redirectUri = body.redirect_uri;
+            const resource = body.resource;
+            if (!code) {
+                return c.json(oauthError('invalid_request', 'Missing code'), 400);
+            }
+            const entry = store.consumeAuthCode(code);
+            if (!entry) {
+                return c.json(oauthError('invalid_grant', 'Invalid or expired authorization code'), 400);
+            }
+            if (entry.mcpClientId !== clientId) {
+                return c.json(oauthError('invalid_grant', 'Authorization code was issued to a different client'), 400);
+            }
+            if (!redirectUri || redirectUri !== entry.redirectUri) {
+                return c.json(oauthError('invalid_grant', !redirectUri ? 'Missing redirect_uri' : 'redirect_uri mismatch'), 400);
+            }
+            if (resource && resource !== entry.resource) {
+                return c.json(oauthError('invalid_grant', 'resource mismatch'), 400);
+            }
+            if (!codeVerifier || !verifyPkce(codeVerifier, entry.codeChallenge)) {
+                return c.json(oauthError('invalid_grant', 'Invalid code_verifier'), 400);
+            }
+            const mcpAccessToken = randomBytes(32).toString('hex');
+            const mcpRefreshToken = randomBytes(32).toString('hex');
+            store.storeMcpToken(mcpAccessToken, {
+                backlogAccessToken: entry.backlogTokens.access_token,
+                clientId,
+                expiresAt: Date.now() + entry.backlogTokens.expires_in * 1000,
+            });
+            store.storeMcpRefreshToken(mcpRefreshToken, {
+                backlogRefreshToken: entry.backlogTokens.refresh_token,
+                clientId,
+                expiresAt: Date.now() + REFRESH_TOKEN_TTL_MS,
+            });
+            return c.json({
+                access_token: mcpAccessToken,
+                token_type: 'bearer',
+                expires_in: entry.backlogTokens.expires_in,
+                refresh_token: mcpRefreshToken,
+            });
+        }
+        if (grantType === 'refresh_token') {
+            const refreshToken = body.refresh_token;
+            if (!refreshToken) {
+                return c.json(oauthError('invalid_request', 'Missing refresh_token'), 400);
+            }
+            const refreshEntry = store.consumeMcpRefreshToken(refreshToken);
+            if (!refreshEntry) {
+                return c.json(oauthError('invalid_grant', 'Invalid or expired refresh token'), 400);
+            }
+            if (refreshEntry.clientId !== clientId) {
+                return c.json(oauthError('invalid_grant', 'Refresh token was issued to a different client'), 400);
+            }
+            try {
+                const tokens = await refreshBacklogToken(config, refreshEntry.backlogRefreshToken);
+                const mcpAccessToken = randomBytes(32).toString('hex');
+                const mcpRefreshToken = randomBytes(32).toString('hex');
+                store.storeMcpToken(mcpAccessToken, {
+                    backlogAccessToken: tokens.access_token,
+                    clientId,
+                    expiresAt: Date.now() + tokens.expires_in * 1000,
+                });
+                store.storeMcpRefreshToken(mcpRefreshToken, {
+                    backlogRefreshToken: tokens.refresh_token,
+                    clientId,
+                    expiresAt: Date.now() + REFRESH_TOKEN_TTL_MS,
+                });
+                return c.json({
+                    access_token: mcpAccessToken,
+                    token_type: 'bearer',
+                    expires_in: tokens.expires_in,
+                    refresh_token: mcpRefreshToken,
+                });
+            }
+            catch (err) {
+                logger.error({ err }, 'Failed to refresh Backlog token');
+                store.storeMcpRefreshToken(refreshToken, refreshEntry);
+                return c.json(oauthError('server_error', 'Failed to refresh upstream token'), 503);
+            }
+        }
+        return c.json(oauthError('unsupported_grant_type', `Unsupported grant_type: ${grantType}`), 400);
+    });
+    return app;
+}

package/build/auth/tokenStore.js

@@ -0,0 +1,129 @@
+// Copyright (c) 2025 Nulab inc.
+// Licensed under the MIT License.
+const PENDING_AUTH_TTL_MS = 10 * 60 * 1000;
+const CLIENT_TTL_MS = 90 * 24 * 60 * 60 * 1000; // 90 days
+const MAX_CLIENTS = 1000;
+export function createTokenStore() {
+    const pendingAuthorizations = new Map();
+    const authorizationCodes = new Map();
+    const clients = new Map();
+    const verificationCache = new Map();
+    const mcpAccessTokens = new Map();
+    const mcpRefreshTokens = new Map();
+    const evictOldestClient = () => {
+        const now = Math.floor(Date.now() / 1000);
+        for (const [id, client] of clients) {
+            if (now - client.client_id_issued_at > CLIENT_TTL_MS / 1000) {
+                clients.delete(id);
+                return;
+            }
+        }
+    };
+    return {
+        storePendingAuth(backlogState, pending) {
+            pendingAuthorizations.set(backlogState, pending);
+        },
+        consumePendingAuth(backlogState) {
+            const entry = pendingAuthorizations.get(backlogState);
+            if (!entry)
+                return undefined;
+            pendingAuthorizations.delete(backlogState);
+            if (Date.now() - entry.createdAt > PENDING_AUTH_TTL_MS)
+                return undefined;
+            return entry;
+        },
+        storeAuthCode(code, entry) {
+            authorizationCodes.set(code, entry);
+        },
+        consumeAuthCode(code) {
+            const entry = authorizationCodes.get(code);
+            if (!entry)
+                return undefined;
+            authorizationCodes.delete(code);
+            if (Date.now() > entry.expiresAt)
+                return undefined;
+            return entry;
+        },
+        getClient(clientId) {
+            return clients.get(clientId);
+        },
+        registerClient(client) {
+            if (clients.size >= MAX_CLIENTS) {
+                evictOldestClient();
+                if (clients.size >= MAX_CLIENTS)
+                    return false;
+            }
+            clients.set(client.client_id, client);
+            return true;
+        },
+        getCachedVerification(token) {
+            const cached = verificationCache.get(token);
+            if (!cached)
+                return undefined;
+            if (Date.now() > cached.expiresAt) {
+                verificationCache.delete(token);
+                return undefined;
+            }
+            return cached.authInfo;
+        },
+        cacheVerification(token, authInfo, ttlMs) {
+            verificationCache.set(token, {
+                authInfo,
+                expiresAt: Date.now() + ttlMs,
+            });
+        },
+        storeMcpToken(mcpToken, entry) {
+            mcpAccessTokens.set(mcpToken, entry);
+        },
+        getMcpToken(mcpToken) {
+            const entry = mcpAccessTokens.get(mcpToken);
+            if (!entry)
+                return undefined;
+            if (Date.now() > entry.expiresAt) {
+                mcpAccessTokens.delete(mcpToken);
+                return undefined;
+            }
+            return entry;
+        },
+        storeMcpRefreshToken(mcpRefreshToken, entry) {
+            mcpRefreshTokens.set(mcpRefreshToken, entry);
+        },
+        consumeMcpRefreshToken(mcpRefreshToken) {
+            const entry = mcpRefreshTokens.get(mcpRefreshToken);
+            if (!entry)
+                return undefined;
+            mcpRefreshTokens.delete(mcpRefreshToken);
+            if (Date.now() > entry.expiresAt)
+                return undefined;
+            return entry;
+        },
+        cleanup() {
+            const now = Date.now();
+            for (const [key, entry] of pendingAuthorizations) {
+                if (now - entry.createdAt > PENDING_AUTH_TTL_MS)
+                    pendingAuthorizations.delete(key);
+            }
+            for (const [key, entry] of authorizationCodes) {
+                if (now > entry.expiresAt)
+                    authorizationCodes.delete(key);
+            }
+            for (const [key, cached] of verificationCache) {
+                if (now > cached.expiresAt)
+                    verificationCache.delete(key);
+            }
+            for (const [key, entry] of mcpAccessTokens) {
+                if (now > entry.expiresAt)
+                    mcpAccessTokens.delete(key);
+            }
+            for (const [key, entry] of mcpRefreshTokens) {
+                if (now > entry.expiresAt)
+                    mcpRefreshTokens.delete(key);
+            }
+            const nowSec = Math.floor(now / 1000);
+            for (const [key, client] of clients) {
+                if (nowSec - client.client_id_issued_at > CLIENT_TTL_MS / 1000)
+                    clients.delete(key);
+            }
+        },
+    };
+}

package/build/handlers/builders/composeToolHandler.js

@@ -14,10 +14,8 @@ export function composeToolHandler(tool, options) {
         : undefined;
     tool.schema = extendSchema(tool.schema, fieldDesc);
     // Step 2: Compose
-    let handler = wrapWithErrorHandling(wrapWithOrganizationContext(tool.handler), errorHandler);
-    if (useFields) {
-        handler = wrapWithFieldPicking(handler);
-    }
+    const baseHandler = wrapWithErrorHandling(wrapWithOrganizationContext(tool.handler), errorHandler);
+    const handler = useFields ? wrapWithFieldPicking(baseHandler) : baseHandler;
     return wrapWithToolResult(wrapWithTokenLimit(handler, maxTokens));
 }
 function extendSchema(schema, desc) {

package/build/httpMcpServer.js

@@ -5,6 +5,7 @@ import { serve } from '@hono/node-server';
 import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
 import { Hono } from 'hono';
+import { runWithAccessToken } from './auth/backlogAuthContext.js';
 import { logger } from './utils/logger.js';
 const jsonRpcError = (code, message) => {
     return { jsonrpc: '2.0', error: { code, message }, id: null };
@@ -39,7 +40,7 @@ const checkHostHeader = (hostHeader, allowedHostnames) => {
         ? null
         : jsonRpcError(-32000, `Invalid Host: ${hostname}`);
 };
-const startNewSession = async (req, body, enableJsonResponse, transports, createServer) => {
+const startNewSession = async (req, body, enableJsonResponse, transports, createServer, authInfo) => {
     const transport = new WebStandardStreamableHTTPServerTransport({
         sessionIdGenerator: () => randomUUID(),
         enableJsonResponse,
@@ -53,10 +54,10 @@ const startNewSession = async (req, body, enableJsonResponse, transports, create
             delete transports[sid];
     };
     await createServer().connect(transport);
-    return transport.handleRequest(req, { parsedBody: body });
+    return transport.handleRequest(req, { parsedBody: body, authInfo });
 };
 export const runHttpMcpServer = async (options) => {
-    const { host, port, path: mcpPath, version, enableJsonResponse, allowedHosts, createServer, } = options;
+    const { host, port, path: mcpPath, version, enableJsonResponse, allowedHosts, createServer, oauthConfig, tokenStore, } = options;
     if ((host === '0.0.0.0' || host === '::') && !allowedHosts?.length) {
         logger.warn('Binding to all interfaces without --http-allowed-hosts. ' +
             'Set allowed Host values to prevent DNS rebinding attacks.');
@@ -64,18 +65,35 @@ export const runHttpMcpServer = async (options) => {
     const app = new Hono();
     const transports = {};
     const allowedHostnames = buildAllowedHostnames(host, allowedHosts);
+    const oauthEnabled = !!(oauthConfig && tokenStore);
+    if (allowedHostnames) {
+        app.use('*', async (c, next) => {
+            const hostError = checkHostHeader(c.req.raw.headers.get('host'), allowedHostnames);
+            if (hostError)
+                return c.json(hostError, 403);
+            await next();
+        });
+    }
     app.get('/health', (c) => c.json({ status: 'healthy', timestamp: new Date().toISOString(), version }));
+    if (oauthEnabled) {
+        const { createOAuthRoutes } = await import('./auth/oauthRoutes.js');
+        const { createBearerAuthMiddleware } = await import('./auth/bearerAuthMiddleware.js');
+        app.route('/', createOAuthRoutes(oauthConfig, tokenStore, mcpPath));
+        app.use(mcpPath, createBearerAuthMiddleware(tokenStore, oauthConfig, mcpPath));
+    }
     app.all(mcpPath, async (c) => {
         const req = c.req.raw;
-        if (allowedHostnames) {
-            const hostError = checkHostHeader(req.headers.get('host'), allowedHostnames);
-            if (hostError)
-                return c.json(hostError, 403);
-        }
+        const authInfo = oauthEnabled
+            ? c.get('authInfo')
+            : undefined;
+        const accessToken = authInfo?.token;
         const sessionId = req.headers.get('mcp-session-id');
         try {
             if (sessionId && transports[sessionId]) {
-                return transports[sessionId].handleRequest(req);
+                const handleExisting = () => transports[sessionId].handleRequest(req, { authInfo });
+                return accessToken
+                    ? runWithAccessToken(accessToken, handleExisting)
+                    : handleExisting();
             }
             if (sessionId) {
                 return c.json(jsonRpcError(-32000, 'Bad Request: Unknown or expired session ID. Send a new initialize request without mcp-session-id.'), 400);
@@ -92,7 +110,10 @@ export const runHttpMcpServer = async (options) => {
                 const err = jsonRpcError(-32000, 'Bad Request: No mcp-session-id header and body is not an initialize request.');
                 return c.json(Array.isArray(body) ? [err] : err, 400);
             }
-            return startNewSession(req, body, enableJsonResponse, transports, createServer);
+            const handleNew = () => startNewSession(req, body, enableJsonResponse, transports, createServer, authInfo);
+            return accessToken
+                ? runWithAccessToken(accessToken, handleNew)
+                : handleNew();
         }
         catch (error) {
             logger.error({ err: error }, 'Error handling MCP request');

package/build/index.js

@@ -6,10 +6,12 @@ import dotenv from 'dotenv';
 import { default as env } from 'env-var';
 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 { createBacklogMcpServer } from './createBacklogMcpServer.js';
 import { runHttpMcpServer } from './httpMcpServer.js';
-import { createBacklogClientRegistry } from './utils/backlogClientRegistry.js';
+import { createBacklogClientRegistry, createOAuthBacklogClientRegistry, } from './utils/backlogClientRegistry.js';
 import { logger } from './utils/logger.js';
 import packageJson from '../package.json' with { type: 'json' };
 const { version } = packageJson;
@@ -34,6 +36,7 @@ process.on('unhandledRejection', (reason) => {
     process.exit(1);
 });
 dotenv.config();
+const oauthConfig = getBacklogOAuthConfig();
 const argv = yargs(hideBin(process.argv))
     .option('transport', {
     type: 'string',
@@ -107,17 +110,23 @@ Available toolsets:
     default: env.get('ENABLE_DYNAMIC_TOOLSETS').default('false').asBool(),
 })
     .parseSync();
-const clientRegistry = createBacklogClientRegistry();
+const clientRegistry = oauthConfig
+    ? createOAuthBacklogClientRegistry(oauthConfig.backlogDomain)
+    : createBacklogClientRegistry();
 const backlog = clientRegistry.createScopedClient();
+const tokenStore = oauthConfig ? createTokenStore() : undefined;
+let cleanupTimer;
+if (tokenStore) {
+    cleanupTimer = setInterval(() => tokenStore.cleanup(), 5 * 60 * 1000);
+    cleanupTimer.unref();
+}
 const useFields = argv.optimizeResponse;
 const transHelper = createTranslationHelper();
 const maxTokens = argv.maxTokens;
 const prefix = argv.prefix;
-let enabledToolsets = argv.enableToolsets;
-// If dynamic toolsets are enabled, remove "all" to allow for selective enabling via commands
-if (argv.dynamicToolsets) {
-    enabledToolsets = enabledToolsets.filter((a) => a !== 'all');
-}
+const enabledToolsets = argv.dynamicToolsets
+    ? argv.enableToolsets.filter((a) => a !== 'all')
+    : argv.enableToolsets;
 const mcpOption = { useFields: useFields, maxTokens, prefix };
 // Factory: creates a fresh MCP server with all tools registered.
 // Used once for stdio; one fresh instance per HTTP session for Streamable HTTP.
@@ -144,6 +153,9 @@ function normalizeHttpPath(p) {
     return p;
 }
 async function main() {
+    if (oauthConfig && argv.transport === 'stdio') {
+        logger.warn('OAuth is configured but transport is stdio. OAuth is only available with HTTP transport.');
+    }
     if (argv.transport === 'http') {
         const httpPath = normalizeHttpPath(argv.httpPath);
         const allowedHostsRaw = argv.httpAllowedHosts;
@@ -161,6 +173,8 @@ async function main() {
             enableJsonResponse: argv.httpJsonResponse,
             allowedHosts,
             createServer,
+            oauthConfig,
+            tokenStore,
         });
         process.once('SIGINT', () => {
             void shutdown()
@@ -177,7 +191,10 @@ async function main() {
             host: argv.httpHost,
             port: argv.httpPort,
             path: httpPath,
-        }, 'Backlog MCP Server listening (Streamable HTTP)');
+            oauth: !!oauthConfig,
+        }, oauthConfig
+            ? 'Backlog MCP Server listening (Streamable HTTP + OAuth)'
+            : 'Backlog MCP Server listening (Streamable HTTP)');
         return;
     }
     const server = createServer();

package/build/tools/addIssue.js

@@ -67,9 +67,14 @@ const addIssueSchema = buildToolSchema((t) => ({
             .number()
             .describe(t('TOOL_ADD_ISSUE_CUSTOM_FIELD_ID', 'The ID of the custom field (e.g., 12345)')),
         value: z
-            .union([z.number(), z.array(z.number())])
+            .union([
+            z.string(),
+            z.number(),
+            z.array(z.string()),
+            z.array(z.number()),
+        ])
             .optional()
-            .describe('The ID(s) of the custom field item. For single-select fields, provide a number. For multi-select fields, provide an array of numbers representing the selected item IDs.'),
+            .describe(t('TOOL_ADD_ISSUE_CUSTOM_FIELD_VALUE', 'Value of the custom field. For text/date fields, provide a string. For numeric fields, provide a number. For list fields, provide an array of strings or numbers.')),
         otherValue: z
             .string()
             .optional()

package/build/tools/updateIssue.js

@@ -86,9 +86,14 @@ const updateIssueSchema = buildToolSchema((t) => ({
             .number()
             .describe(t('TOOL_UPDATE_ISSUE_CUSTOM_FIELD_ID', 'The ID of the custom field (e.g., 12345)')),
         value: z
-            .union([z.number(), z.array(z.number())])
+            .union([
+            z.string(),
+            z.number(),
+            z.array(z.string()),
+            z.array(z.number()),
+        ])
             .optional()
-            .describe('The ID(s) of the custom field item. For single-select fields, provide a number. For multi-select fields, provide an array of numbers representing the selected item IDs.'),
+            .describe(t('TOOL_UPDATE_ISSUE_CUSTOM_FIELD_VALUE', 'Value of the custom field. For text/date fields, provide a string. For numeric fields, provide a number. For list fields, provide an array of strings or numbers.')),
         otherValue: z
             .string()
             .optional()

package/build/utils/backlogClientRegistry.js

@@ -1,4 +1,5 @@
 import { Backlog } from 'backlog-js';
+import { getCurrentAccessToken } from '../auth/backlogAuthContext.js';
 import { getCurrentOrganization } from './backlogOrganizationContext.js';
 export function createBacklogClientRegistry(input = {}) {
     const env = input.env ?? process.env;
@@ -118,6 +119,27 @@ function resolveKnownClient(clients, organization) {
     }
     return client;
 }
+export function createOAuthBacklogClientRegistry(domain) {
+    const defaultName = 'default';
+    const info = {
+        name: defaultName,
+        domain,
+        isDefault: true,
+    };
+    const resolveOAuthClient = () => {
+        const token = getCurrentAccessToken();
+        if (!token) {
+            throw new Error('No OAuth access token in current request context');
+        }
+        return new Backlog({ host: domain, accessToken: token });
+    };
+    return {
+        resolveClient: () => resolveOAuthClient(),
+        createScopedClient: () => createBacklogClientProxy(resolveOAuthClient),
+        listOrganizations: () => [info],
+        getDefaultOrganization: () => defaultName,
+    };
+}
 function createBacklogClientProxy(resolveClient) {
     return new Proxy({}, {
         get(_target, prop) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backlog-mcp-server",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "type": "module",
   "bin": {
     "backlog-mcp-server": "./build/index.js"
@@ -34,7 +34,7 @@
     "dotenv": "^16.5.0",
     "env-var": "^7.5.0",
     "graphql": "^16.11.0",
-    "hono": "^4.12.12",
+    "hono": "^4.12.23",
     "pino": "^9.9.0",
     "pino-pretty": "^13.1.1",
     "yargs": "^18.0.0",
@@ -42,7 +42,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.24.0",
-    "@release-it/conventional-changelog": "^10.0.2",
+    "@release-it/conventional-changelog": "^11.0.0",
     "@types/node": "^22.14.1",
     "@types/yargs": "^17.0.33",
     "@typescript-eslint/eslint-plugin": "^8.30.1",
@@ -53,7 +53,7 @@
     "eslint-config-prettier": "^10.1.2",
     "eslint-plugin-prettier": "^5.2.6",
     "prettier": "^3.5.3",
-    "release-it": "^19.0.0",
+    "release-it": "^20.0.1",
     "tsx": "^4.20.6",
     "typescript": "^5.8.3",
     "vitest": "^4.0.0"