backlog-mcp-server 0.14.0 → 0.15.1

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 機能に対応するツールを提供しています：
@@ -590,7 +596,9 @@ BACKLOG_API_KEY=your-api-key
 
 ### ツールの使い方
 
-通常のツールはすべて、任意の`organization`入力フィールドを受け付けます。指定した場合、そのBacklog組織に対してツールが実行されます。
+マルチ組織用の環境変数が設定されている場合、通常のツールはすべて任意の`organization`入力フィールドを受け付けます。指定した場合、そのBacklog組織に対してツールが実行されます。
+
+単一組織モードでは、ルーティング先が1つしかないためこのフィールドは公開されません。これにより`tools/list`のレスポンスから約8KBのスキーマが削減されます。
 
 例：
 
@@ -608,7 +616,7 @@ BACKLOG_API_KEY=your-api-key
 
 ### 組織一覧の確認
 
-サーバーは `list_organizations` ツールを提供しており、設定済みの組織名、ドメイン、デフォルト組織かどうかを返します。
+マルチ組織モードでは、サーバーは `list_organizations` ツールを提供しており、設定済みの組織名、ドメイン、デフォルト組織かどうかを返します。単一組織モードでは登録されません。
 
 レスポンス例：
 

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`
@@ -644,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
@@ -707,7 +715,9 @@ BACKLOG_API_KEY=your-api-key
 
 ### Tool Usage
 
-All normal tools accept an optional `organization` input field. When provided, the tool call is routed to that Backlog organization.
+When multi-organization env vars are configured, all normal tools accept an optional `organization` input field. When provided, the tool call is routed to that Backlog organization.
+
+In single-organization mode the field is not published, since there would be only one organization to route to. Omitting it keeps roughly 8 KB of tool schema out of every `tools/list` response.
 
 Examples:
 
@@ -725,7 +735,7 @@ If `organization` is omitted:
 
 ### Organization Discovery
 
-The server provides a `list_organizations` tool that returns the configured organization names, their domains, and which one is the default.
+In multi-organization mode the server provides a `list_organizations` tool that returns the configured organization names, their domains, and which one is the default. It is not registered in single-organization mode.
 
 Example response:
 

package/build/auth/backlogAuthContext.d.ts

@@ -0,0 +1,2 @@
+export declare function runWithAccessToken<T>(token: string | undefined, fn: () => Promise<T>): Promise<T>;
+export declare function getCurrentAccessToken(): string | undefined;

package/build/auth/backlogOAuthClient.d.ts

@@ -0,0 +1,10 @@
+import type { BacklogOAuthConfig } from './backlogOAuthConfig.js';
+import type { BacklogTokenData } from './tokenStore.js';
+export declare function buildBacklogAuthorizationUrl(config: BacklogOAuthConfig, redirectUri: string, state: string): string;
+export declare function exchangeBacklogCode(config: BacklogOAuthConfig, code: string, redirectUri: string): Promise<BacklogTokenData>;
+export declare function refreshBacklogToken(config: BacklogOAuthConfig, refreshToken: string): Promise<BacklogTokenData>;
+export declare function verifyBacklogToken(domain: string, accessToken: string): Promise<{
+    id: number;
+    userId: string;
+    name: string;
+}>;

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/backlogOAuthConfig.d.ts

@@ -0,0 +1,9 @@
+export type BacklogOAuthConfig = {
+    clientId: string;
+    clientSecret: string;
+    backlogDomain: string;
+    serverBaseUrl: string;
+};
+type Environment = Record<string, string | undefined>;
+export declare function getBacklogOAuthConfig(env?: Environment): BacklogOAuthConfig | undefined;
+export {};

package/build/auth/bearerAuthMiddleware.d.ts

@@ -0,0 +1,4 @@
+import type { MiddlewareHandler } from 'hono';
+import type { BacklogOAuthConfig } from './backlogOAuthConfig.js';
+import type { TokenStore } from './tokenStore.js';
+export declare function createBearerAuthMiddleware(store: TokenStore, config: BacklogOAuthConfig, mcpPath: string): MiddlewareHandler;

package/build/auth/oauthRoutes.d.ts

@@ -0,0 +1,4 @@
+import { Hono } from 'hono';
+import type { BacklogOAuthConfig } from './backlogOAuthConfig.js';
+import type { TokenStore } from './tokenStore.js';
+export declare function createOAuthRoutes(config: BacklogOAuthConfig, store: TokenStore, mcpPath: string): Hono;

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/auth/tokenStore.d.ts

@@ -0,0 +1,62 @@
+import type { AuthInfo } from '@modelcontextprotocol/server';
+export type BacklogTokenData = {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    refresh_token: string;
+};
+export type OAuthClientInfo = {
+    client_id: string;
+    client_secret?: string;
+    client_id_issued_at: number;
+    client_secret_expires_at: number;
+    redirect_uris: string[];
+    client_name?: string;
+    token_endpoint_auth_method?: string;
+    grant_types?: string[];
+    response_types?: string[];
+};
+type PendingAuthorization = {
+    mcpClientId: string;
+    codeChallenge: string;
+    redirectUri: string;
+    resource?: string;
+    scopes: string[];
+    state?: string;
+    createdAt: number;
+};
+type AuthCodeEntry = {
+    mcpClientId: string;
+    backlogTokens: BacklogTokenData;
+    codeChallenge: string;
+    redirectUri: string;
+    resource?: string;
+    expiresAt: number;
+};
+export type McpTokenEntry = {
+    backlogAccessToken: string;
+    clientId: string;
+    expiresAt: number;
+};
+type McpRefreshEntry = {
+    backlogRefreshToken: string;
+    clientId: string;
+    expiresAt: number;
+};
+export type TokenStore = ReturnType<typeof createTokenStore>;
+export declare function createTokenStore(): {
+    storePendingAuth(backlogState: string, pending: PendingAuthorization): void;
+    consumePendingAuth(backlogState: string): PendingAuthorization | undefined;
+    storeAuthCode(code: string, entry: AuthCodeEntry): void;
+    consumeAuthCode(code: string): AuthCodeEntry | undefined;
+    getClient(clientId: string): OAuthClientInfo | undefined;
+    registerClient(client: OAuthClientInfo): boolean;
+    getCachedVerification(token: string): AuthInfo | undefined;
+    cacheVerification(token: string, authInfo: AuthInfo, ttlMs: number): void;
+    storeMcpToken(mcpToken: string, entry: McpTokenEntry): void;
+    getMcpToken(mcpToken: string): McpTokenEntry | undefined;
+    storeMcpRefreshToken(mcpRefreshToken: string, entry: McpRefreshEntry): void;
+    consumeMcpRefreshToken(mcpRefreshToken: string): McpRefreshEntry | undefined;
+    cleanup(): void;
+};
+export {};

package/build/backlog/backlogErrorHandler.d.ts

@@ -0,0 +1,2 @@
+import { ErrorLike } from '../types/result.js';
+export declare const backlogErrorHandler: (err: unknown) => ErrorLike;

package/build/backlog/customFields.d.ts

@@ -0,0 +1,29 @@
+export type CustomFieldInput = {
+    id: number;
+    value?: string | number | string[] | number[];
+    otherValue?: string;
+};
+export type CustomFieldFilterInput = {
+    id: number;
+    type: 'text';
+    value: string;
+} | {
+    id: number;
+    type: 'numeric';
+    min?: number;
+    max?: number;
+} | {
+    id: number;
+    type: 'date';
+    min?: string;
+    max?: string;
+} | {
+    id: number;
+    type: 'list';
+    value: number | number[];
+};
+/**
+ * Converts Backlog-style customFields array into proper payload format
+ */
+export declare function customFieldsToPayload(customFields: CustomFieldInput[] | undefined): Record<string, string | number | string[] | number[] | undefined>;
+export declare function customFieldFiltersToPayload(customFields: CustomFieldFilterInput[] | undefined): Record<string, string | number | number[] | undefined>;

package/build/backlog/parseBacklogAPIError.d.ts

@@ -0,0 +1,8 @@
+export type ParsedBacklogAPIError = {
+    type: 'BacklogAuthError' | 'BacklogApiError' | 'UnexpectedError' | 'UnknownError';
+    message: string;
+    status?: number;
+    code?: number;
+    url?: string;
+};
+export declare function parseBacklogAPIError(err: unknown): ParsedBacklogAPIError;

package/build/createBacklogMcpServer.d.ts

@@ -0,0 +1,29 @@
+import type { Backlog } from 'backlog-js';
+import type { TranslationHelper } from './createTranslationHelper.js';
+import type { MCPOptions } from './types/mcp.js';
+import type { ToolsetGroup } from './types/toolsets.js';
+import type { BacklogClientRegistry } from './utils/backlogClientRegistry.js';
+import { type BacklogMCPServer } from './utils/wrapServerWithToolRegistry.js';
+export type CreateBacklogMcpServerConfig = {
+    version: string;
+    useFields: boolean;
+    backlog: Backlog;
+    clientRegistry: BacklogClientRegistry;
+    transHelper: TranslationHelper;
+    enabledToolsets: string[];
+    mcpOption: MCPOptions;
+    dynamicToolsets: boolean;
+    /**
+     * A toolset group to register from, instead of building one from
+     * `enabledToolsets`. Callers that produce many servers from one factory pass
+     * a single shared group: `enable_toolset` mutates it, and under the stateless
+     * HTTP model — one server per request — a group built per server would throw
+     * that mutation away the moment the request ends.
+     */
+    toolsetGroup?: ToolsetGroup;
+};
+/**
+ * Builds a fresh MCP server instance with all Backlog tools registered.
+ * Used once per stdio connection; one instance per HTTP request for Streamable HTTP.
+ */
+export declare function createBacklogMcpServer({ version, useFields, backlog, clientRegistry, transHelper, enabledToolsets, mcpOption, dynamicToolsets, toolsetGroup: sharedToolsetGroup, }: CreateBacklogMcpServerConfig): BacklogMCPServer;

package/build/createBacklogMcpServer.js

@@ -1,25 +1,37 @@
 // 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);
+    // `list_organizations` only has something to report when more than one space
+    // is configured; the `organization` parameter its description points at is
+    // published under the same condition.
+    if (mcpOption.useOrganization) {
+        registerDynamicTools(server, organizationTools(clientRegistry, transHelper), mcpOption.prefix);
+    }
     if (dynamicToolsets) {
         const registrar = createToolRegistrar(server, toolsetGroup, mcpOption);
         const dynamicToolsetGroup = dynamicTools(registrar, transHelper, toolsetGroup);

package/build/createTranslationHelper.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Resolves the schema strings every tool definition passes through `t()`: tool
+ * descriptions and parameter descriptions. These are read by the model when it
+ * picks a tool and fills in arguments; they never reach the end user.
+ *
+ * This module intentionally imports nothing. Every tool in `src/tools/` depends on
+ * it, so anything imported here is reachable from the tool layer — and the tool
+ * layer is meant to run on non-Node runtimes too. Discovering and reading the
+ * override file needs a filesystem and a home directory, so that part lives in
+ * `loadTranslationOverrides` and the CLI passes the result in.
+ */
+export interface TranslationHelper {
+    t: (key: string, fallback: string) => string;
+    dump: () => Record<string, string>;
+}
+export declare function createTranslationHelper(overrides?: Record<string, string>): TranslationHelper;

package/build/createTranslationHelper.js

@@ -1,13 +1,5 @@
-import { cosmiconfigSync } from 'cosmiconfig';
-import os from 'os';
-export function createTranslationHelper(options) {
+export function createTranslationHelper(overrides = {}) {
     const usedKeys = {};
-    const configName = options?.configName ?? 'backlog-mcp-server';
-    // Load config file
-    const explorer = cosmiconfigSync(configName);
-    const searchPath = options?.searchDir ?? os.homedir();
-    const configResult = explorer.search(searchPath);
-    const config = configResult?.config || {};
     function toEnvKey(key) {
         return `BACKLOG_MCP_${key}`;
     }
@@ -16,8 +8,12 @@ export function createTranslationHelper(options) {
         if (usedKeys[upperKey]) {
             return usedKeys[upperKey];
         }
-        // Priority：ENV → config → fallback
-        const value = process.env[toEnvKey(upperKey)] || config[upperKey] || fallback;
+        // Runtimes without a Node compatibility layer have no `process`, and a
+        // partial shim can have `process` without `env`.
+        const env = typeof process === 'undefined' ? undefined : process.env;
+        const fromEnv = env?.[toEnvKey(upperKey)];
+        // Priority：ENV → overrides → fallback
+        const value = fromEnv || overrides[upperKey] || fallback;
         usedKeys[upperKey] = value;
         return value;
     }

package/build/handlers/builders/composeToolHandler.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { ErrorLike } from '../../types/result.js';
+import { ToolDefinition } from '../../types/tool.js';
+export interface ComposeOptions {
+    useFields: boolean;
+    errorHandler?: (err: unknown) => ErrorLike;
+    maxTokens: number;
+    /**
+     * Whether to advertise `organization`. Defaults to false: with a single
+     * Backlog space the parameter has exactly one legal value, and repeating it
+     * across every tool costs the client ~8 KB of schema for nothing.
+     */
+    useOrganization?: boolean;
+}
+type ComposedInput = {
+    fields?: string;
+    organization?: string;
+} & Record<string, unknown>;
+/**
+ * Builds the schema and handler a tool is registered with.
+ *
+ * The returned schema is a fresh object: the tool definition is never mutated.
+ * That matters under the stateless HTTP model, where one toolset group is shared
+ * by every per-request server — an in-place extension would be re-applied on
+ * every request, against a definition other requests are reading concurrently.
+ */
+export declare function composeToolHandler(tool: ToolDefinition<any, any>, options: ComposeOptions): {
+    schema: z.ZodObject<any, z.core.$strip>;
+    handler: (input: ComposedInput, extra: import("@modelcontextprotocol/server").ServerContext) => Promise<import("@modelcontextprotocol/server").CallToolResult>;
+};
+export {};