backlog-mcp-server 0.13.5 → 0.15.0

package/README.ja.md

@@ -154,11 +154,11 @@ MCPサーバーをネットワーク経由で公開する場合、OAuth 2.0認
 
 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`） |
+| 変数                          | 説明                                                  |
+| ----------------------------- | ----------------------------------------------------- |
+| `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アカウントで認証します。
 
@@ -169,23 +169,27 @@ 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
+node build/index.js --transport http --http-host 0.0.0.0 --http-port 3333 \
+  --http-allowed-hosts mcp.example.com
 ```
 
+`0.0.0.0` にバインドする場合、`--http-allowed-hosts` は実質必須です。指定しないとDNSリバインディング保護が一切効かず、起動時に警告がログ出力されます。
+
 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` | トークンエンドポイント（認可コード＆リフレッシュトークン） |
+| エンドポイント                                  | 説明                                                                                     |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `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組織のみをサポートしています。複数組織設定との併用はできません。
 > - クライアント登録やトークンはメモリ内に保持されるため、サーバー再起動時に失われます。
 
@@ -247,6 +251,8 @@ CLI経由での有効化：
 
 動的ツールセットを有効にすると、LLMはツールインターフェースを介してオンデマンドでツールセットを一覧表示およびアクティブ化できるようになります。
 
+> **HTTPでのスコープ:** MCP `2026-07-28` にはプロトコルセッションがないため、アクティブ化したツールセットはクライアント単位ではなく**サーバープロセス単位**で保持されます。HTTPトランスポートでは接続中の全クライアントが1つのツールセット状態を共有し、プロセス再起動でリセットされます。共有されるのはツールの*可視性*のみで、認可は共有されません（各呼び出しは呼び出し元自身の認証情報で認証されます）。
+
 ## 利用可能なツール
 
 以下のような Backlog 機能に対応するツールを提供しています：

package/README.md

@@ -149,20 +149,22 @@ pnpm run build
 MCP_TRANSPORT=http MCP_HTTP_PORT=3333 node build/index.js
 ```
 
-- **Endpoint:** `POST`, `GET`, and `DELETE` on `http://<host>:<port><path>` (default path `/mcp`).
-- **Session:** After `initialize`, clients must send the `mcp-session-id` header on later requests (as returned by the server).
-- **Security:** Default bind is `127.0.0.1`. Do not expose the HTTP port to untrusted networks without authentication and TLS; it allows full use of your Backlog API key via MCP tools.
+- **Endpoint:** `POST` (and `GET` for server-initiated streams) on `http://<host>:<port><path>` (default path `/mcp`).
+- **Protocol:** MCP `2026-07-28`. The protocol is stateless: there is no `initialize` handshake and no `mcp-session-id` header. Clients send their metadata in `_meta` on every request and discover capabilities via `server/discover`. Streamable HTTP also requires the `Mcp-Method` header (and `Mcp-Name` on `tools/call`).
+- **Backward compatibility:** Clients on `2025-11-25` and earlier are still served over the same endpoint, statelessly. Because no session is kept, the 2025 session operations (`GET` / `DELETE` with an `mcp-session-id`) answer `405`.
+- **Security:** Default bind is `127.0.0.1`. On a bare loopback bind, `Host` and `Origin` are both validated against the localhost set (DNS rebinding protection). Behind a reverse proxy, set `--http-allowed-hosts` to the public hostname; that turns off the localhost `Origin` default, since a browser client's `Origin` is its own site and never this server's hostname. Add `--http-allowed-origins` to restrict which client origins may reach the server. Do not expose the HTTP port to untrusted networks without authentication and TLS; it allows full use of your Backlog API key via MCP tools.
 
 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                                    |
-| `MCP_HTTP_ALLOWED_HOSTS` | Comma-separated allowed `Host` values when binding to `0.0.0.0` (DNS rebinding protection) |
+| 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 (applies to `2026-07-28` clients only)                                                                                                   |
+| `MCP_HTTP_ALLOWED_HOSTS`   | Comma-separated allowed `Host` hostnames (port-agnostic). Required when binding to `0.0.0.0`; also the escape hatch for a loopback bind behind a proxy (DNS rebinding protection) |
+| `MCP_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                   |
 
 ### OAuth 2.0 Authentication (Remote MCP)
 
@@ -194,9 +196,12 @@ 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
+node build/index.js --transport http --http-host 0.0.0.0 --http-port 3333 \
+  --http-allowed-hosts mcp.example.com
 ```
 
+`--http-allowed-hosts` is required in practice when binding to `0.0.0.0`: without it there is no DNS rebinding protection, and the server logs a warning at startup.
+
 The server automatically exposes the following OAuth endpoints when OAuth is enabled:
 
 | Endpoint                                        | Description                                                                                     |
@@ -273,6 +278,8 @@ Or via environment variable::
 
 With dynamic toolsets enabled, the LLM will be able to list and activate toolsets on demand via tool interface.
 
+> **Scope over HTTP:** MCP `2026-07-28` has no protocol sessions, so an activated toolset is remembered per **server process**, not per client. On the HTTP transport every connected client shares one toolset state, and it resets when the process restarts. Tool _visibility_ is shared; authorization is not — every call is still authenticated with the caller's own credentials.
+
 ## Available Tools
 
 ### Toolset: `space`
@@ -307,6 +314,9 @@ Tools for managing issues, their comments, and related items like priorities, ca
 - `get_issue_comments`: Returns list of comments for an issue.
 - `add_issue_comment`: Adds a comment to an issue.
 - `update_issue_comment`: Updates a comment on an issue.
+- `get_related_issues`: Returns list of issues related to a specific issue.
+- `add_related_issue`: Relates an issue to another issue.
+- `remove_related_issue`: Removes the relation between an issue and a related issue.
 - `get_priorities`: Returns list of priorities.
 - `get_categories`: Returns list of categories for a project.
 - `get_custom_fields`: Returns list of custom fields for a project.
@@ -641,8 +651,9 @@ The server supports several command line options:
 
 - `--transport stdio|http`: MCP transport (default: stdio). Use `http` for Streamable HTTP.
 - `--http-host`, `--http-port`, `--http-path`: HTTP bind address, port, and path (defaults: `127.0.0.1`, `3333`, `/mcp`).
-- `--http-json-response`: Prefer JSON responses over SSE when the transport supports it.
-- `--http-allowed-hosts`: Comma-separated allowed `Host` headers when binding to all interfaces.
+- `--http-json-response`: Prefer JSON responses over SSE. Applies to `2026-07-28` clients only; the backward-compatible `2025-11-25` path is served with the SDK's default response shaping.
+- `--http-allowed-hosts`: Comma-separated allowed `Host` hostnames (port-agnostic). Needed when binding to all interfaces, or on a loopback bind behind a reverse proxy.
+- `--http-allowed-origins`: Comma-separated allowed `Origin` hostnames for browser-based clients. Defaults to the localhost set on a bare loopback bind, and to no `Origin` check otherwise.
 - `--export-translations`: Export all translation keys and values
 - `--optimize-response`: Enable GraphQL-style field selection
 - `--max-tokens=NUMBER`: Set maximum token limit for responses

package/build/auth/backlogOAuthClient.js

@@ -26,7 +26,7 @@ export async function exchangeBacklogCode(config, code, redirectUri) {
         const text = await response.text();
         throw new Error(`Backlog token exchange failed (${response.status}): ${text}`);
     }
-    return (await response.json());
+    return await response.json();
 }
 export async function refreshBacklogToken(config, refreshToken) {
     const params = new URLSearchParams({
@@ -44,7 +44,7 @@ export async function refreshBacklogToken(config, refreshToken) {
         const text = await response.text();
         throw new Error(`Backlog token refresh failed (${response.status}): ${text}`);
     }
-    return (await response.json());
+    return await response.json();
 }
 export async function verifyBacklogToken(domain, accessToken) {
     const response = await fetch(`https://${domain}/api/v2/users/myself`, {
@@ -53,5 +53,5 @@ export async function verifyBacklogToken(domain, accessToken) {
     if (!response.ok) {
         throw new Error(`Backlog token verification failed (${response.status})`);
     }
-    return (await response.json());
+    return await response.json();
 }

package/build/auth/oauthRoutes.js

@@ -20,10 +20,7 @@ function isValidRedirectUri(uri) {
         const parsed = new URL(uri);
         if (parsed.protocol === 'https:')
             return true;
-        if (parsed.protocol === 'http:' &&
-            LOCALHOST_HOSTS.includes(parsed.hostname))
-            return true;
-        return false;
+        return (parsed.protocol === 'http:' && LOCALHOST_HOSTS.includes(parsed.hostname));
     }
     catch {
         return false;
@@ -46,6 +43,8 @@ export function createOAuthRoutes(config, store, mcpPath) {
             grant_types_supported: ['authorization_code', 'refresh_token'],
             token_endpoint_auth_methods_supported: ['client_secret_post', 'none'],
             code_challenge_methods_supported: ['S256'],
+            // RFC 9207 — every authorization response carries `iss`
+            authorization_response_iss_parameter_supported: true,
         });
     });
     // RFC 9728 — OAuth Protected Resource Metadata
@@ -61,7 +60,7 @@ export function createOAuthRoutes(config, store, mcpPath) {
     app.post('/register', async (c) => {
         let body;
         try {
-            body = (await c.req.json());
+            body = await c.req.json();
         }
         catch {
             return c.json(oauthError('invalid_request', 'Invalid JSON body'), 400);
@@ -136,6 +135,7 @@ export function createOAuthRoutes(config, store, mcpPath) {
             const url = new URL(effectiveRedirectUri);
             url.searchParams.set('error', 'unsupported_response_type');
             url.searchParams.set('error_description', 'Only response_type=code is supported');
+            url.searchParams.set('iss', serverBaseUrl);
             if (state)
                 url.searchParams.set('state', state);
             return c.redirect(url.href, 302);
@@ -144,6 +144,7 @@ export function createOAuthRoutes(config, store, mcpPath) {
             const url = new URL(effectiveRedirectUri);
             url.searchParams.set('error', 'invalid_request');
             url.searchParams.set('error_description', 'code_challenge is required');
+            url.searchParams.set('iss', serverBaseUrl);
             if (state)
                 url.searchParams.set('state', state);
             return c.redirect(url.href, 302);
@@ -152,6 +153,7 @@ export function createOAuthRoutes(config, store, mcpPath) {
             const url = new URL(effectiveRedirectUri);
             url.searchParams.set('error', 'invalid_request');
             url.searchParams.set('error_description', 'Only code_challenge_method=S256 is supported');
+            url.searchParams.set('iss', serverBaseUrl);
             if (state)
                 url.searchParams.set('state', state);
             return c.redirect(url.href, 302);
@@ -160,6 +162,7 @@ export function createOAuthRoutes(config, store, mcpPath) {
             const url = new URL(effectiveRedirectUri);
             url.searchParams.set('error', 'invalid_target');
             url.searchParams.set('error_description', 'Invalid resource parameter');
+            url.searchParams.set('iss', serverBaseUrl);
             if (state)
                 url.searchParams.set('state', state);
             return c.redirect(url.href, 302);
@@ -196,6 +199,7 @@ export function createOAuthRoutes(config, store, mcpPath) {
             errorUrl.searchParams.set('error', backlogError ?? 'access_denied');
             errorUrl.searchParams.set('error_description', url.searchParams.get('error_description') ??
                 'Authorization was denied by the user');
+            errorUrl.searchParams.set('iss', serverBaseUrl);
             if (pending.state)
                 errorUrl.searchParams.set('state', pending.state);
             return c.redirect(errorUrl.href, 302);
@@ -213,6 +217,7 @@ export function createOAuthRoutes(config, store, mcpPath) {
             const url = new URL(pending.redirectUri);
             url.searchParams.set('error', 'server_error');
             url.searchParams.set('error_description', 'Failed to exchange authorization code with Backlog');
+            url.searchParams.set('iss', serverBaseUrl);
             if (pending.state)
                 url.searchParams.set('state', pending.state);
             return c.redirect(url.href, 302);
@@ -228,6 +233,8 @@ export function createOAuthRoutes(config, store, mcpPath) {
         });
         const redirectUrl = new URL(pending.redirectUri);
         redirectUrl.searchParams.set('code', mcpCode);
+        // RFC 9207 — let the client confirm which AS answered
+        redirectUrl.searchParams.set('iss', serverBaseUrl);
         if (pending.state)
             redirectUrl.searchParams.set('state', pending.state);
         return c.redirect(redirectUrl.href, 302);

package/build/createBacklogMcpServer.js

@@ -1,23 +1,30 @@
 // Copyright (c) 2025 Nulab inc.
 // Licensed under the MIT License.
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer } from '@modelcontextprotocol/server';
 import { registerDynamicTools, registerTools } from './registerTools.js';
 import { organizationTools } from './tools/dynamicTools/organizations.js';
 import { dynamicTools } from './tools/dynamicTools/toolsets.js';
 import { createToolRegistrar } from './utils/toolRegistrar.js';
 import { buildToolsetGroup } from './utils/toolsetUtils.js';
 import { wrapServerWithToolRegistry, } from './utils/wrapServerWithToolRegistry.js';
+// The tool list is fixed for the process lifetime (it only depends on CLI flags
+// and environment), so clients may cache it. With dynamic toolsets the list can
+// grow at runtime, so no hint is published in that case.
+const TOOL_LIST_CACHE_HINT = {
+    'tools/list': { ttlMs: 5 * 60 * 1000, cacheScope: 'public' },
+};
 /**
  * Builds a fresh MCP server instance with all Backlog tools registered.
- * Used once for stdio; one instance per HTTP session for Streamable HTTP.
+ * Used once per stdio connection; one instance per HTTP request for Streamable HTTP.
  */
-export function createBacklogMcpServer({ version, useFields, backlog, clientRegistry, transHelper, enabledToolsets, mcpOption, dynamicToolsets, }) {
+export function createBacklogMcpServer({ version, useFields, backlog, clientRegistry, transHelper, enabledToolsets, mcpOption, dynamicToolsets, toolsetGroup: sharedToolsetGroup, }) {
     const server = wrapServerWithToolRegistry(new McpServer({
         name: 'backlog',
         title: useFields ? 'backlog (field selection enabled)' : 'backlog',
         version,
-    }));
-    const toolsetGroup = buildToolsetGroup(backlog, transHelper, enabledToolsets);
+    }, dynamicToolsets ? undefined : { cacheHints: TOOL_LIST_CACHE_HINT }));
+    const toolsetGroup = sharedToolsetGroup ??
+        buildToolsetGroup(backlog, transHelper, enabledToolsets);
     registerTools(server, toolsetGroup, mcpOption);
     registerDynamicTools(server, organizationTools(clientRegistry, transHelper), mcpOption.prefix);
     if (dynamicToolsets) {

package/build/handlers/builders/composeToolHandler.js

@@ -28,5 +28,8 @@ function extendSchema(schema, desc) {
     if (desc) {
         extension.fields = z.string().describe(desc);
     }
+    // zod v4 reworked the ZodObject shape generics, so `extend()`'s result no
+    // longer overlaps the declared return type enough for a direct cast. The
+    // shape is correct at runtime; route through `unknown` to keep the assertion.
     return schema.extend(extension);
 }

package/build/httpMcpServer.js

@@ -1,78 +1,40 @@
 // Copyright (c) 2025 Nulab inc.
 // Licensed under the MIT License.
-import { randomUUID } from 'node:crypto';
 import { serve } from '@hono/node-server';
-import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
-import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { hostHeaderValidation, localhostHostValidation, localhostOriginValidation, originValidation, } from '@modelcontextprotocol/hono';
+import { createMcpHandler } from '@modelcontextprotocol/server';
 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 };
-};
-const bodyContainsInitialize = (body) => {
-    return (Array.isArray(body) ? body : [body]).some(isInitializeRequest);
-};
-const buildAllowedHostnames = (host, allowedHosts) => {
-    if (allowedHosts?.length)
-        return allowedHosts;
-    const localhostHosts = ['127.0.0.1', 'localhost', '::1'];
-    return localhostHosts.includes(host)
-        ? ['localhost', '127.0.0.1', '[::1]']
-        : undefined;
-};
-const parseHostname = (hostHeader) => {
-    try {
-        return new URL(`http://${hostHeader}`).hostname;
-    }
-    catch {
-        return null;
-    }
-};
-const checkHostHeader = (hostHeader, allowedHostnames) => {
-    if (!hostHeader)
-        return jsonRpcError(-32000, 'Missing Host header');
-    const hostname = parseHostname(hostHeader);
-    if (hostname === null) {
-        return jsonRpcError(-32000, `Invalid Host header: ${hostHeader}`);
-    }
-    return allowedHostnames.includes(hostname)
-        ? null
-        : jsonRpcError(-32000, `Invalid Host: ${hostname}`);
-};
-const startNewSession = async (req, body, enableJsonResponse, transports, createServer, authInfo) => {
-    const transport = new WebStandardStreamableHTTPServerTransport({
-        sessionIdGenerator: () => randomUUID(),
-        enableJsonResponse,
-        onsessioninitialized: (sid) => {
-            transports[sid] = transport;
-        },
-    });
-    transport.onclose = () => {
-        const sid = transport.sessionId;
-        if (sid)
-            delete transports[sid];
-    };
-    await createServer().connect(transport);
-    return transport.handleRequest(req, { parsedBody: body, authInfo });
-};
+const LOCALHOST_BINDS = ['127.0.0.1', 'localhost', '::1'];
 export const runHttpMcpServer = async (options) => {
-    const { host, port, path: mcpPath, version, enableJsonResponse, allowedHosts, createServer, oauthConfig, tokenStore, } = options;
+    const { host, port, path: mcpPath, version, enableJsonResponse, allowedHosts, allowedOrigins, 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.');
     }
     const app = new Hono();
-    const transports = {};
-    const allowedHostnames = buildAllowedHostnames(host, allowedHosts);
+    const isLocalhostBind = LOCALHOST_BINDS.includes(host);
     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();
-        });
+    // DNS rebinding protection. `Host` is the actual defense: a rebinding page
+    // reaches us carrying its own hostname, which the allow list rejects.
+    if (allowedHosts?.length) {
+        app.use('*', hostHeaderValidation(allowedHosts));
+    }
+    else if (isLocalhostBind) {
+        app.use('*', localhostHostValidation());
+    }
+    // `Origin` is a separate axis and cannot be derived from the allow list: a
+    // browser client's Origin is its own site, never this server's hostname, so
+    // validating one against the other would reject every legitimate remote
+    // client. Default to the localhost set only for a bare loopback bind (the
+    // desktop case, where a drive-by page is the threat); a deployment that
+    // declares its hosts opts out unless it names its client origins too.
+    if (allowedOrigins?.length) {
+        app.use('*', originValidation(allowedOrigins));
+    }
+    else if (isLocalhostBind && !allowedHosts?.length) {
+        app.use('*', localhostOriginValidation());
     }
     app.get('/health', (c) => c.json({ status: 'healthy', timestamp: new Date().toISOString(), version }));
     if (oauthEnabled) {
@@ -81,43 +43,30 @@ export const runHttpMcpServer = async (options) => {
         app.route('/', createOAuthRoutes(oauthConfig, tokenStore, mcpPath));
         app.use(mcpPath, createBearerAuthMiddleware(tokenStore, oauthConfig, mcpPath));
     }
+    // MCP 2026-07-28 removed protocol sessions: every request is self-contained,
+    // so the handler builds a fresh server per request instead of keeping a
+    // transport map keyed by mcp-session-id. `legacy` defaults to 'stateless',
+    // which keeps 2025-era clients working over the same endpoint.
+    const mcpHandler = createMcpHandler(() => createServer(), {
+        responseMode: enableJsonResponse ? 'json' : 'auto',
+        onerror: (err) => logger.error({ err }, 'MCP handler error'),
+    });
     app.all(mcpPath, async (c) => {
-        const req = c.req.raw;
-        const authInfo = oauthEnabled
-            ? c.get('authInfo')
-            : undefined;
+        const authInfo = oauthEnabled ? c.get('authInfo') : undefined;
         const accessToken = authInfo?.token;
-        const sessionId = req.headers.get('mcp-session-id');
         try {
-            if (sessionId && transports[sessionId]) {
-                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);
-            }
-            if (req.method !== 'POST') {
-                return c.json(jsonRpcError(-32000, 'Bad Request: No mcp-session-id header.'), 400);
-            }
-            const parsed = await req.json().then((body) => ({ body }), () => null);
-            if (!parsed) {
-                return c.json(jsonRpcError(-32700, 'Parse error: Invalid JSON'), 400);
-            }
-            const { body } = parsed;
-            if (!bodyContainsInitialize(body)) {
-                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);
-            }
-            const handleNew = () => startNewSession(req, body, enableJsonResponse, transports, createServer, authInfo);
+            const dispatch = () => mcpHandler.fetch(c.req.raw, { authInfo });
             return accessToken
-                ? runWithAccessToken(accessToken, handleNew)
-                : handleNew();
+                ? await runWithAccessToken(accessToken, dispatch)
+                : await dispatch();
         }
         catch (error) {
             logger.error({ err: error }, 'Error handling MCP request');
-            return c.json(jsonRpcError(-32603, 'Internal server error'), 500);
+            return c.json({
+                jsonrpc: '2.0',
+                error: { code: -32603, message: 'Internal server error' },
+                id: null,
+            }, 500);
         }
     });
     const httpServer = await new Promise((resolve, reject) => {
@@ -125,14 +74,11 @@ export const runHttpMcpServer = async (options) => {
         srv.on('error', reject);
     });
     const shutdown = async () => {
-        for (const sid of Object.keys(transports)) {
-            try {
-                await transports[sid].close();
-            }
-            catch {
-                /* ignore */
-            }
-            delete transports[sid];
+        try {
+            await mcpHandler.close();
+        }
+        catch {
+            /* ignore */
         }
         httpServer.closeAllConnections();
         await new Promise((resolve) => httpServer.close(() => resolve()));

package/build/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // Copyright (c) 2025 Nulab inc.
 // Licensed under the MIT License.
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
 import { default as env } from 'env-var';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
@@ -12,6 +12,7 @@ import { createBacklogMcpServer } from './createBacklogMcpServer.js';
 import { runHttpMcpServer } from './httpMcpServer.js';
 import { createBacklogClientRegistry, createOAuthBacklogClientRegistry, } from './utils/backlogClientRegistry.js';
 import { logger } from './utils/logger.js';
+import { buildToolsetGroup } from './utils/toolsetUtils.js';
 import packageJson from '../package.json' with { type: 'json' };
 const { version } = packageJson;
 // Swallow SIGPIPE and stdout/stderr EPIPE so the process doesn't crash when a
@@ -75,6 +76,11 @@ const argv = yargs(hideBin(process.argv))
     type: 'string',
     describe: 'Comma-separated allowed Host header values when binding to all interfaces (recommended with 0.0.0.0)',
     default: env.get('MCP_HTTP_ALLOWED_HOSTS').default('').asString(),
+})
+    .option('http-allowed-origins', {
+    type: 'string',
+    describe: 'Comma-separated allowed Origin header hostnames for browser-based clients. Defaults to the localhost set on a loopback bind, and to no Origin check otherwise',
+    default: env.get('MCP_HTTP_ALLOWED_ORIGINS').default('').asString(),
 })
     .option('max-tokens', {
     type: 'number',
@@ -132,8 +138,14 @@ const enabledToolsets = argv.dynamicToolsets
     ? argv.enableToolsets.filter((a) => a !== 'all')
     : argv.enableToolsets;
 const mcpOption = { useFields: useFields, maxTokens, prefix };
+// Built once and shared by every server the factory produces. `enable_toolset`
+// mutates this group, and the stateless HTTP model discards its server after
+// each request — so a per-server group would lose the enablement immediately.
+// Sharing it makes toolset state process-wide, which is the only scope left now
+// that the protocol has no sessions.
+const sharedToolsetGroup = buildToolsetGroup(backlog, transHelper, enabledToolsets);
 // Factory: creates a fresh MCP server with all tools registered.
-// Used once for stdio; one fresh instance per HTTP session for Streamable HTTP.
+// Used once per stdio connection; one fresh instance per HTTP request.
 const createServer = () => createBacklogMcpServer({
     version,
     useFields,
@@ -143,6 +155,7 @@ const createServer = () => createBacklogMcpServer({
     enabledToolsets,
     mcpOption,
     dynamicToolsets: argv.dynamicToolsets,
+    toolsetGroup: sharedToolsetGroup,
 });
 if (argv.exportTranslations) {
     // Translation keys are only recorded once a tool asks for them, so build a
@@ -175,13 +188,14 @@ async function main() {
     }
     if (argv.transport === 'http') {
         const httpPath = normalizeHttpPath(argv.httpPath);
-        const allowedHostsRaw = argv.httpAllowedHosts;
-        const allowedHosts = allowedHostsRaw && allowedHostsRaw.trim().length > 0
-            ? allowedHostsRaw
+        const parseHostList = (raw) => raw && raw.trim().length > 0
+            ? raw
                 .split(',')
                 .map((h) => h.trim())
                 .filter(Boolean)
             : undefined;
+        const allowedHosts = parseHostList(argv.httpAllowedHosts);
+        const allowedOrigins = parseHostList(argv.httpAllowedOrigins);
         const { shutdown } = await runHttpMcpServer({
             host: argv.httpHost,
             port: argv.httpPort,
@@ -189,6 +203,7 @@ async function main() {
             version,
             enableJsonResponse: argv.httpJsonResponse,
             allowedHosts,
+            allowedOrigins,
             createServer,
             oauthConfig,
             tokenStore,
@@ -214,9 +229,11 @@ async function main() {
             : 'Backlog MCP Server listening (Streamable HTTP)');
         return;
     }
-    const server = createServer();
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
+    // serveStdio owns the era decision for the connection: it pins one instance
+    // from the factory, serving both 2026-07-28 and 2025-era clients.
+    serveStdio(createServer, {
+        onerror: (err) => logger.error({ err }, 'MCP stdio error'),
+    });
     logger.info('Backlog MCP Server running on stdio');
 }
 main().catch((error) => {

package/build/registerTools.js

@@ -31,7 +31,7 @@ function registerToolsets({ server, toolsetGroup, prefix, handlerStrategy, }) {
         for (const tool of toolset.tools) {
             const toolNameWithPrefix = `${prefix}${tool.name}`;
             const handler = handlerStrategy(tool);
-            server.registerOnce(toolNameWithPrefix, tool.description, tool.schema.shape, handler);
+            server.registerOnce(toolNameWithPrefix, tool.description, tool.schema, handler);
         }
     }
 }

package/build/tools/addRelatedIssue.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { buildToolSchema } from '../types/tool.js';
+import { RelatedIssueSchema } from '../types/zod/backlogOutputDefinition.js';
+import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
+const addRelatedIssueSchema = buildToolSchema((t) => ({
+    issueId: z
+        .number()
+        .optional()
+        .describe(t('TOOL_ADD_RELATED_ISSUE_ISSUE_ID', 'The numeric ID of the issue (e.g., 12345)')),
+    issueKey: z
+        .string()
+        .optional()
+        .describe(t('TOOL_ADD_RELATED_ISSUE_ISSUE_KEY', "The key of the issue (e.g., 'PROJ-123')")),
+    targetIssueId: z
+        .number()
+        .describe(t('TOOL_ADD_RELATED_ISSUE_TARGET_ISSUE_ID', 'The numeric ID of the issue to relate to (e.g., 12346)')),
+}));
+export const addRelatedIssueTool = (backlog, { t }) => {
+    return {
+        name: 'add_related_issue',
+        description: t('TOOL_ADD_RELATED_ISSUE_DESCRIPTION', 'Relates an issue to another issue'),
+        schema: z.object(addRelatedIssueSchema(t)),
+        outputSchema: RelatedIssueSchema,
+        handler: async ({ issueId, issueKey, targetIssueId }) => {
+            const result = resolveIdOrKey('issue', { id: issueId, key: issueKey }, t);
+            if (!result.ok) {
+                throw result.error;
+            }
+            return backlog.addRelatedIssue(result.value, { targetIssueId });
+        },
+    };
+};

package/build/tools/getRelatedIssues.js

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import { buildToolSchema } from '../types/tool.js';
+import { RelatedIssueSchema } from '../types/zod/backlogOutputDefinition.js';
+import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
+const getRelatedIssuesSchema = buildToolSchema((t) => ({
+    issueId: z
+        .number()
+        .optional()
+        .describe(t('TOOL_GET_RELATED_ISSUES_ISSUE_ID', 'The numeric ID of the issue (e.g., 12345)')),
+    issueKey: z
+        .string()
+        .optional()
+        .describe(t('TOOL_GET_RELATED_ISSUES_ISSUE_KEY', "The key of the issue (e.g., 'PROJ-123')")),
+}));
+export const getRelatedIssuesTool = (backlog, { t }) => {
+    return {
+        name: 'get_related_issues',
+        description: t('TOOL_GET_RELATED_ISSUES_DESCRIPTION', 'Returns list of issues related to a specific issue'),
+        schema: z.object(getRelatedIssuesSchema(t)),
+        importantFields: ['issueKey', 'summary', 'status', 'type'],
+        outputSchema: RelatedIssueSchema,
+        handler: async ({ issueId, issueKey }) => {
+            const result = resolveIdOrKey('issue', { id: issueId, key: issueKey }, t);
+            if (!result.ok) {
+                throw result.error;
+            }
+            return backlog.getRelatedIssues(result.value);
+        },
+    };
+};

package/build/tools/removeRelatedIssue.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { buildToolSchema } from '../types/tool.js';
+import { RelatedIssueSchema } from '../types/zod/backlogOutputDefinition.js';
+import { resolveIdOrKey } from '../utils/resolveIdOrKey.js';
+const removeRelatedIssueSchema = buildToolSchema((t) => ({
+    issueId: z
+        .number()
+        .optional()
+        .describe(t('TOOL_REMOVE_RELATED_ISSUE_ISSUE_ID', 'The numeric ID of the issue (e.g., 12345)')),
+    issueKey: z
+        .string()
+        .optional()
+        .describe(t('TOOL_REMOVE_RELATED_ISSUE_ISSUE_KEY', "The key of the issue (e.g., 'PROJ-123')")),
+    relatedIssueId: z
+        .number()
+        .describe(t('TOOL_REMOVE_RELATED_ISSUE_RELATED_ISSUE_ID', 'The numeric ID of the related issue to unlink (e.g., 12346)')),
+}));
+export const removeRelatedIssueTool = (backlog, { t }) => {
+    return {
+        name: 'remove_related_issue',
+        description: t('TOOL_REMOVE_RELATED_ISSUE_DESCRIPTION', 'Removes the relation between an issue and a related issue'),
+        schema: z.object(removeRelatedIssueSchema(t)),
+        outputSchema: RelatedIssueSchema,
+        handler: async ({ issueId, issueKey, relatedIssueId }) => {
+            const result = resolveIdOrKey('issue', { id: issueId, key: issueKey }, t);
+            if (!result.ok) {
+                throw result.error;
+            }
+            return backlog.removeRelatedIssue(result.value, relatedIssueId);
+        },
+    };
+};

package/build/tools/tools.js

@@ -15,6 +15,9 @@ import { getGitRepositoryTool } from './getGitRepository.js';
 import { getIssueTool } from './getIssue.js';
 import { getIssueCommentsTool } from './getIssueComments.js';
 import { getIssuesTool } from './getIssues.js';
+import { getRelatedIssuesTool } from './getRelatedIssues.js';
+import { addRelatedIssueTool } from './addRelatedIssue.js';
+import { removeRelatedIssueTool } from './removeRelatedIssue.js';
 import { getIssueTypesTool } from './getIssueTypes.js';
 import { getMyselfTool } from './getMyself.js';
 import { getNotificationsTool } from './getNotifications.js';
@@ -100,6 +103,9 @@ export const allTools = (backlog, helper) => {
                     getIssueCommentsTool(backlog, helper),
                     addIssueCommentTool(backlog, helper),
                     updateIssueCommentTool(backlog, helper),
+                    getRelatedIssuesTool(backlog, helper),
+                    addRelatedIssueTool(backlog, helper),
+                    removeRelatedIssueTool(backlog, helper),
                     getPrioritiesTool(backlog, helper),
                     getCategoriesTool(backlog, helper),
                     getCustomFieldsTool(backlog, helper),

package/build/tools/updateIssue.js

@@ -47,15 +47,15 @@ const updateIssueSchema = buildToolSchema((t) => ({
     categoryId: z
         .array(z.number())
         .optional()
-        .describe(t('TOOL_UPDATE_ISSUE_CATEGORY_ID', 'Category IDs')),
+        .describe(t('TOOL_UPDATE_ISSUE_CATEGORY_ID', 'Category IDs. Pass an empty array to clear all categories. Omit this field to leave the current categories unchanged.')),
     versionId: z
         .array(z.number())
         .optional()
-        .describe(t('TOOL_UPDATE_ISSUE_VERSION_ID', 'Version IDs')),
+        .describe(t('TOOL_UPDATE_ISSUE_VERSION_ID', 'Version IDs. Pass an empty array to clear all versions. Omit this field to leave the current versions unchanged.')),
     milestoneId: z
         .array(z.number())
         .optional()
-        .describe(t('TOOL_UPDATE_ISSUE_MILESTONE_ID', 'Milestone IDs')),
+        .describe(t('TOOL_UPDATE_ISSUE_MILESTONE_ID', 'Milestone IDs. Pass an empty array to clear all milestones. Omit this field to leave the current milestones unchanged.')),
     statusId: z
         .number()
         .optional()
@@ -106,6 +106,30 @@ const updateIssueSchema = buildToolSchema((t) => ({
         .optional()
         .describe(t('TOOL_UPDATE_ISSUE_CUSTOM_FIELDS', 'List of custom fields to set on the issue')),
 }));
+// Backlog API clears a stored array field (category/version/milestone) only when
+// the parameter is sent as `field[]=` (empty value). backlog-js serializes
+// params via qs with `arrayFormat: 'brackets'`, and an empty array `[]` produces
+// no query string at all, so the API silently ignores it. Converting `[]` to
+// `['']` makes qs emit `field[]=`, which the API interprets as "clear".
+//
+// Only these three are persistent, clearable array fields. notifiedUserId (a
+// one-off notification target) and attachmentId (attachments to add) are action
+// parameters, not stored state, so they are intentionally excluded.
+const CLEARABLE_ARRAY_FIELDS = [
+    'categoryId',
+    'versionId',
+    'milestoneId',
+];
+const clearEmptyArrayFields = (params) => {
+    const next = { ...params };
+    for (const field of CLEARABLE_ARRAY_FIELDS) {
+        const value = next[field];
+        if (Array.isArray(value) && value.length === 0) {
+            next[field] = [''];
+        }
+    }
+    return next;
+};
 export const updateIssueTool = (backlog, { t }) => {
     return {
         name: 'update_issue',
@@ -119,9 +143,12 @@ export const updateIssueTool = (backlog, { t }) => {
             }
             const customFieldPayload = customFieldsToPayload(customFields);
             const finalPayload = {
-                ...params,
+                ...clearEmptyArrayFields(params),
                 ...customFieldPayload,
             };
+            // The `['']` clear-sentinel is not representable in backlog-js's
+            // `number[]` param types, so cast at this single boundary. qs serializes
+            // it to `field[]=`, which the Backlog API accepts as "clear this field".
             return backlog.patchIssue(result.value, finalPayload);
         },
     };

package/build/types/zod/backlogOutputDefinition.js

@@ -211,6 +211,10 @@ export const IssueSchema = z.object({
     sharedFiles: z.array(SharedFileSchema),
     stars: z.array(StarSchema),
 });
+// An issue plus the relation type that links it to the issue it was fetched from.
+export const RelatedIssueSchema = IssueSchema.extend({
+    type: z.string(),
+});
 export const ProjectSchema = z.object({
     id: z.number(),
     projectKey: z.string(),
@@ -484,6 +488,9 @@ export const ActiveTrashTreeSchema = z.object({
     id: z.string(),
     children: z.array(DocumentTreeNodeSchema),
 });
+// No `: z.ZodRawShape` annotation here: it erases the concrete shape, so
+// `z.infer<typeof DocumentTreeFullSchemaZ>` collapses to Record<string, unknown>
+// and backlog-js's DocumentTree (no index signature) stops being assignable.
 export const DocumentTreeFullSchema = {
     projectId: z.number(),
     activeTree: ActiveTrashTreeSchema.optional(),

package/build/utils/generateFieldsDescription.js

@@ -36,6 +36,9 @@ function mapZodTypeToGraphQLType(zodType) {
         return 'Int!';
     if (zodType instanceof z.ZodBoolean)
         return 'Boolean!';
+    // zod v4 types `.unwrap()` as the core `$ZodType` rather than the classic
+    // `ZodType`, so the recursive call needs a cast. The runtime value is a
+    // classic schema either way - only the declared type narrowed.
     if (zodType instanceof z.ZodNullable)
         return mapZodTypeToGraphQLType(zodType.unwrap()).replace(/!$/, '');
     if (zodType instanceof z.ZodOptional)

package/build/utils/wrapServerWithToolRegistry.js

@@ -10,7 +10,7 @@ export function wrapServerWithToolRegistry(server) {
             return;
         }
         s.__registeredToolNames.add(name);
-        s.tool(name, description, schema, handler);
+        s.registerTool(name, { description, inputSchema: schema }, handler);
     };
     return s;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backlog-mcp-server",
-  "version": "0.13.5",
+  "version": "0.15.0",
   "type": "module",
   "bin": {
     "backlog-mcp-server": "./build/index.js"
@@ -25,8 +25,9 @@
   ],
   "dependencies": {
     "@hono/node-server": "^2.0.10",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "backlog-js": "^0.18.1",
+    "@modelcontextprotocol/hono": "^2.0.0",
+    "@modelcontextprotocol/server": "^2.0.0",
+    "backlog-js": "^0.19.1",
     "cosmiconfig": "^9.0.1",
     "env-var": "^7.5.0",
     "graphql": "^16.14.1",
@@ -34,7 +35,7 @@
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
     "yargs": "^18.0.0",
-    "zod": "^3.24.3"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",