backlog-mcp-server 0.9.0 → 0.10.0

package/README.ja.md

@@ -507,6 +507,93 @@ npm test
 node build/index.js --optimize-response --max-tokens=100000 --prefix="backlog_" --enable-toolsets space,issue
 ```
 
+## 複数組織対応
+
+このサーバーは、1つのMCPサーバーインスタンスから複数のBacklog組織にアクセスできるよう設定できます。
+
+### 設定
+
+組織ごとに環境変数のペアを定義し、デフォルト組織を設定します。
+
+```bash
+BACKLOG_DEFAULT_ORG=COMPANY_A
+BACKLOG_ORG_COMPANY_A_DOMAIN=company-a.backlog.com
+BACKLOG_ORG_COMPANY_A_API_KEY=your-company-a-api-key
+BACKLOG_ORG_COMPANY_B_DOMAIN=company-b.backlog.com
+BACKLOG_ORG_COMPANY_B_API_KEY=your-company-b-api-key
+```
+
+これらの変数は、ローカルの`.env`、シェル環境変数、またはMCPクライアント設定の`env`ブロックのいずれからでも利用できます。
+
+MCP設定例：
+
+```json
+{
+  "mcpServers": {
+    "backlog": {
+      "env": {
+        "BACKLOG_DEFAULT_ORG": "COMPANY_A",
+        "BACKLOG_ORG_COMPANY_A_DOMAIN": "company-a.backlog.com",
+        "BACKLOG_ORG_COMPANY_A_API_KEY": "your-company-a-api-key",
+        "BACKLOG_ORG_COMPANY_B_DOMAIN": "company-b.backlog.com",
+        "BACKLOG_ORG_COMPANY_B_API_KEY": "your-company-b-api-key"
+      }
+    }
+  }
+}
+```
+
+複数組織用の環境変数が設定されていない場合、サーバーは従来どおり単一組織用の設定にフォールバックします。
+
+```bash
+BACKLOG_DOMAIN=your-domain.backlog.com
+BACKLOG_API_KEY=your-api-key
+```
+
+### ツールの使い方
+
+通常のツールはすべて、任意の`organization`入力フィールドを受け付けます。指定した場合、そのBacklog組織に対してツールが実行されます。
+
+例：
+
+```json
+{
+  "organization": "COMPANY_B",
+  "projectKey": "PROJECT"
+}
+```
+
+`organization`を省略した場合：
+
+- `BACKLOG_DEFAULT_ORG`で指定した組織が使われます
+- 複数組織用の環境変数が存在するのに`BACKLOG_DEFAULT_ORG`が未設定の場合、サーバーは起動時に失敗します
+
+### 組織一覧の確認
+
+サーバーは `list_organizations` ツールを提供しており、設定済みの組織名、ドメイン、デフォルト組織かどうかを返します。
+
+レスポンス例：
+
+```json
+[
+  {
+    "name": "COMPANY_A",
+    "domain": "company-a.backlog.com",
+    "isDefault": true
+  },
+  {
+    "name": "COMPANY_B",
+    "domain": "company-b.backlog.com",
+    "isDefault": false
+  }
+]
+```
+
+### 注意
+
+- 複数組織モードでは、各組織に対して `BACKLOG_ORG_<NAME>_DOMAIN` と `BACKLOG_ORG_<NAME>_API_KEY` の両方を定義する必要があります
+- `<NAME>` の部分が、`organization`入力や `list_organizations` に表示される組織名になります
+
 ## ライセンス
 
 このプロジェクトは [MITライセンス](./LICENSE) のもとでライセンスされています。

package/README.md

@@ -587,6 +587,89 @@ Example:
 node build/index.js --optimize-response --max-tokens=100000 --prefix="backlog_" --enable-toolsets space,issue
 ```
 
+## Multi-Organization Support
+
+This server can be configured to access multiple Backlog organizations from a single MCP server instance.
+
+### Configuration
+
+Configure one env pair per organization and set a default organization:
+
+```bash
+BACKLOG_DEFAULT_ORG=COMPANY_A
+BACKLOG_ORG_COMPANY_A_DOMAIN=company-a.backlog.com
+BACKLOG_ORG_COMPANY_A_API_KEY=your-company-a-api-key
+BACKLOG_ORG_COMPANY_B_DOMAIN=company-b.backlog.com
+BACKLOG_ORG_COMPANY_B_API_KEY=your-company-b-api-key
+```
+
+This works whether the variables come from a local `.env`, your shell environment, or an MCP client config `env` block.
+
+Example MCP config:
+
+```json
+{
+  "env": {
+    "BACKLOG_DEFAULT_ORG": "COMPANY_A",
+    "BACKLOG_ORG_COMPANY_A_DOMAIN": "company-a.backlog.com",
+    "BACKLOG_ORG_COMPANY_A_API_KEY": "your-company-a-api-key",
+    "BACKLOG_ORG_COMPANY_B_DOMAIN": "company-b.backlog.com",
+    "BACKLOG_ORG_COMPANY_B_API_KEY": "your-company-b-api-key"
+  }
+}
+```
+
+If no multi-organization env vars are set, the server falls back to the existing single-organization configuration:
+
+```bash
+BACKLOG_DOMAIN=your-domain.backlog.com
+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.
+
+Examples:
+
+```json
+{
+  "organization": "COMPANY_B",
+  "projectKey": "PROJECT"
+}
+```
+
+If `organization` is omitted:
+
+- the organization named by `BACKLOG_DEFAULT_ORG` is used
+- if multi-organization env vars are present and `BACKLOG_DEFAULT_ORG` is missing, the server fails at startup
+
+### Organization Discovery
+
+The server provides a `list_organizations` tool that returns the configured organization names, their domains, and which one is the default.
+
+Example response:
+
+```json
+[
+  {
+    "name": "COMPANY_A",
+    "domain": "company-a.backlog.com",
+    "isDefault": true
+  },
+  {
+    "name": "COMPANY_B",
+    "domain": "company-b.backlog.com",
+    "isDefault": false
+  }
+]
+```
+
+### Notes
+
+- For multi-org mode, every organization must define both `BACKLOG_ORG_<NAME>_DOMAIN` and `BACKLOG_ORG_<NAME>_API_KEY`.
+- The `<NAME>` part is the organization name exposed through the `organization` tool input and `list_organizations`.
+
 ## License
 
 This project is licensed under the [MIT License](./LICENSE).

package/build/handlers/builders/composeToolHandler.js

@@ -1,6 +1,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { wrapWithErrorHandling } from '../transformers/wrapWithErrorHandling.js';
 import { wrapWithFieldPicking } from '../transformers/wrapWithFieldPicking.js';
+import { wrapWithOrganizationContext } from '../transformers/wrapWithOrganizationContext.js';
 import { wrapWithTokenLimit } from '../transformers/wrapWithTokenLimit.js';
 import { wrapWithToolResult } from '../transformers/wrapWithToolResult.js';
 import { z } from 'zod';
@@ -8,19 +9,26 @@ import { generateFieldsDescription } from '../../utils/generateFieldsDescription
 export function composeToolHandler(tool, options) {
     const { useFields, errorHandler, maxTokens } = options;
     // Step 1: Add `fields` to schema if needed
-    if (useFields) {
-        const fieldDesc = generateFieldsDescription(tool.outputSchema, tool.importantFields ?? [], tool.name);
-        tool.schema = extendSchema(tool.schema, fieldDesc);
-    }
+    const fieldDesc = useFields
+        ? generateFieldsDescription(tool.outputSchema, tool.importantFields ?? [], tool.name)
+        : undefined;
+    tool.schema = extendSchema(tool.schema, fieldDesc);
     // Step 2: Compose
-    let handler = wrapWithErrorHandling(tool.handler, errorHandler);
+    let handler = wrapWithErrorHandling(wrapWithOrganizationContext(tool.handler), errorHandler);
     if (useFields) {
         handler = wrapWithFieldPicking(handler);
     }
     return wrapWithToolResult(wrapWithTokenLimit(handler, maxTokens));
 }
 function extendSchema(schema, desc) {
-    return schema.extend({
-        fields: z.string().describe(desc),
-    });
+    const extension = {
+        organization: z
+            .string()
+            .optional()
+            .describe('Optional organization name. Use list_organizations to inspect available organizations.'),
+    };
+    if (desc) {
+        extension.fields = z.string().describe(desc);
+    }
+    return schema.extend(extension);
 }

package/build/handlers/transformers/wrapWithOrganizationContext.js

@@ -0,0 +1,7 @@
+import { runWithOrganization } from '../../utils/backlogOrganizationContext.js';
+export function wrapWithOrganizationContext(fn) {
+    return async (input) => {
+        const { organization, ...rest } = input;
+        return runWithOrganization(organization, () => fn(rest));
+    };
+}

package/build/index.js

@@ -3,14 +3,15 @@
 // Licensed under the MIT License.
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import * as backlogjs from 'backlog-js';
 import dotenv from 'dotenv';
 import { default as env } from 'env-var';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import { createTranslationHelper } from './createTranslationHelper.js';
 import { registerDynamicTools, registerTools } from './registerTools.js';
+import { organizationTools } from './tools/dynamicTools/organizations.js';
 import { dynamicTools } from './tools/dynamicTools/toolsets.js';
+import { createBacklogClientRegistry } from './utils/backlogClientRegistry.js';
 import { logger } from './utils/logger.js';
 import { createToolRegistrar } from './utils/toolRegistrar.js';
 import { buildToolsetGroup } from './utils/toolsetUtils.js';
@@ -18,9 +19,6 @@ import { wrapServerWithToolRegistry } from './utils/wrapServerWithToolRegistry.j
 import packageJson from '../package.json' with { type: 'json' };
 const { version } = packageJson;
 dotenv.config();
-const domain = env.get('BACKLOG_DOMAIN').required().asString();
-const apiKey = env.get('BACKLOG_API_KEY').required().asString();
-const backlog = new backlogjs.Backlog({ host: domain, apiKey: apiKey });
 const argv = yargs(hideBin(process.argv))
     .option('max-tokens', {
     type: 'number',
@@ -60,6 +58,8 @@ Available toolsets:
     default: env.get('ENABLE_DYNAMIC_TOOLSETS').default('false').asBool(),
 })
     .parseSync();
+const clientRegistry = createBacklogClientRegistry();
+const backlog = clientRegistry.createScopedClient();
 const useFields = argv.optimizeResponse;
 const server = wrapServerWithToolRegistry(new McpServer({
     name: 'backlog',
@@ -78,6 +78,7 @@ const mcpOption = { useFields: useFields, maxTokens, prefix };
 const toolsetGroup = buildToolsetGroup(backlog, transHelper, enabledToolsets);
 // Register all tools
 registerTools(server, toolsetGroup, mcpOption);
+registerDynamicTools(server, organizationTools(clientRegistry, transHelper), prefix);
 // Register dynamic tool management tools if enabled
 if (argv.dynamicToolsets) {
     const registrar = createToolRegistrar(server, toolsetGroup, mcpOption);

package/build/tools/dynamicTools/organizations.js

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+export function organizationTools(registry, { t }) {
+    return {
+        toolsets: [
+            {
+                name: 'organization_metadata',
+                description: 'Tools for inspecting configured Backlog organizations.',
+                enabled: true,
+                tools: [listOrganizationsTool(registry, t)],
+            },
+        ],
+    };
+}
+export function listOrganizationsTool(registry, t) {
+    return {
+        name: 'list_organizations',
+        description: t('TOOL_LIST_ORGANIZATIONS_DESCRIPTION', 'List configured Backlog organizations and identify the default organization.'),
+        schema: z.object({}),
+        handler: async () => {
+            const organizations = registry.listOrganizations().map(toToolOutput);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(organizations, null, 2),
+                    },
+                ],
+            };
+        },
+    };
+}
+function toToolOutput(organization) {
+    return {
+        name: organization.name,
+        domain: organization.domain,
+        isDefault: organization.isDefault,
+    };
+}

package/build/tools/dynamicTools/toolsets.js

@@ -24,7 +24,7 @@ const enableToolsetSchema = buildToolSchema((t) => ({
 export const enableToolsetTool = (toolRegistrar, { t }) => {
     return {
         name: 'enable_toolset',
-        description: t('TOOL_ENABLE_TOOLSET_DESCRIPTION', 'Enable one of the sets of tools the GitHub MCP server provides, use get_toolset_tools and list_available_toolsets first to see what this will enable'),
+        description: t('TOOL_ENABLE_TOOLSET_DESCRIPTION', 'Enable one of the Backlog MCP server toolsets. Use get_toolset_tools and list_available_toolsets first to inspect what this will enable.'),
         schema: z.object(enableToolsetSchema(t)),
         handler: async ({ toolset }) => {
             const msg = await toolRegistrar.enableToolsetAndRefresh(toolset);

package/build/tools/tools.js

@@ -55,7 +55,6 @@ import { addVersionMilestoneTool } from './addVersionMilestone.js';
 import { updateVersionMilestoneTool } from './updateVersionMilestone.js';
 import { deleteVersionTool } from './deleteVersion.js';
 import { addDocumentTool } from './addDocument.js';
-import { deleteDocumentTool } from './deleteDocument.js';
 export const allTools = (backlog, helper) => {
     return {
         toolsets: [
@@ -152,7 +151,6 @@ export const allTools = (backlog, helper) => {
                     getDocumentTreeTool(backlog, helper),
                     getDocumentTool(backlog, helper),
                     addDocumentTool(backlog, helper),
-                    deleteDocumentTool(backlog, helper),
                 ],
             },
             {

package/build/utils/backlogClientRegistry.js

@@ -0,0 +1,132 @@
+import { Backlog } from 'backlog-js';
+import { getCurrentOrganization } from './backlogOrganizationContext.js';
+export function createBacklogClientRegistry(input = {}) {
+    const env = input.env ?? process.env;
+    const multiOrgRegistry = createMultiOrganizationRegistryFromEnv(env);
+    if (multiOrgRegistry) {
+        return multiOrgRegistry;
+    }
+    const domain = env.BACKLOG_DOMAIN;
+    const apiKey = env.BACKLOG_API_KEY;
+    if (!domain || !apiKey) {
+        throw new Error('Configure either BACKLOG_ORG_<NAME>_DOMAIN and BACKLOG_ORG_<NAME>_API_KEY with BACKLOG_DEFAULT_ORG, or both BACKLOG_DOMAIN and BACKLOG_API_KEY.');
+    }
+    const defaultName = 'default';
+    const client = new Backlog({ host: domain, apiKey });
+    const info = {
+        name: defaultName,
+        domain,
+        isDefault: true,
+    };
+    return {
+        resolveClient: (organization) => {
+            if (organization && organization !== defaultName) {
+                throw new Error(`Unknown organization '${organization}'. Use list_organizations to inspect available organizations.`);
+            }
+            return client;
+        },
+        createScopedClient: () => createBacklogClientProxy(() => {
+            const organization = getCurrentOrganization();
+            if (organization && organization !== defaultName) {
+                throw new Error(`Unknown organization '${organization}'. Use list_organizations to inspect available organizations.`);
+            }
+            return client;
+        }),
+        listOrganizations: () => [info],
+        getDefaultOrganization: () => defaultName,
+    };
+}
+function createMultiOrganizationRegistryFromEnv(env) {
+    const organizations = new Map();
+    let hasMultiOrgKeys = false;
+    for (const [key, value] of Object.entries(env)) {
+        const match = /^BACKLOG_ORG_(.+)_(DOMAIN|API_KEY)$/.exec(key);
+        if (!match) {
+            continue;
+        }
+        hasMultiOrgKeys = true;
+        const [, organization, field] = match;
+        const config = organizations.get(organization) ?? {};
+        if (field === 'DOMAIN') {
+            config.domain = value;
+        }
+        else {
+            config.apiKey = value;
+        }
+        organizations.set(organization, config);
+    }
+    if (!hasMultiOrgKeys) {
+        return undefined;
+    }
+    const invalidOrganizations = Array.from(organizations.entries())
+        .filter(([, config]) => !config.domain || !config.apiKey)
+        .map(([organization, config]) => {
+        const missing = [];
+        if (!config.domain)
+            missing.push(`BACKLOG_ORG_${organization}_DOMAIN`);
+        if (!config.apiKey)
+            missing.push(`BACKLOG_ORG_${organization}_API_KEY`);
+        return `${organization} (missing: ${missing.join(', ')})`;
+    })
+        .sort();
+    if (invalidOrganizations.length > 0) {
+        throw new Error(`Incomplete multi-organization configuration. ${invalidOrganizations.join('; ')}`);
+    }
+    if (organizations.size === 0) {
+        throw new Error('No valid multi-organization configuration was found. Define BACKLOG_ORG_<NAME>_DOMAIN and BACKLOG_ORG_<NAME>_API_KEY pairs.');
+    }
+    const defaultOrganization = env.BACKLOG_DEFAULT_ORG;
+    if (!defaultOrganization) {
+        throw new Error('BACKLOG_DEFAULT_ORG is required when using BACKLOG_ORG_<NAME>_DOMAIN and BACKLOG_ORG_<NAME>_API_KEY.');
+    }
+    const clients = new Map();
+    // At this point, all organizations have been validated to have both domain and apiKey
+    const validatedOrganizations = organizations;
+    const organizationInfo = Array.from(validatedOrganizations.entries()).map(([name, config]) => {
+        clients.set(name, new Backlog({
+            host: config.domain,
+            apiKey: config.apiKey,
+        }));
+        return {
+            name,
+            domain: config.domain,
+            isDefault: name === defaultOrganization,
+        };
+    });
+    if (!clients.has(defaultOrganization)) {
+        throw new Error(`BACKLOG_DEFAULT_ORG '${defaultOrganization}' does not match any configured organization. Use list_organizations to inspect available organizations.`);
+    }
+    return {
+        resolveClient: (organization) => {
+            const orgName = organization ?? defaultOrganization;
+            return resolveKnownClient(clients, orgName);
+        },
+        createScopedClient: () => createBacklogClientProxy(() => {
+            const organization = getCurrentOrganization();
+            return organization === undefined
+                ? resolveKnownClient(clients, defaultOrganization)
+                : resolveKnownClient(clients, organization);
+        }),
+        listOrganizations: () => organizationInfo,
+        getDefaultOrganization: () => defaultOrganization,
+    };
+}
+function resolveKnownClient(clients, organization) {
+    const client = clients.get(organization);
+    if (!client) {
+        throw new Error(`Unknown organization '${organization}'. Use list_organizations to inspect available organizations.`);
+    }
+    return client;
+}
+function createBacklogClientProxy(resolveClient) {
+    return new Proxy({}, {
+        get(_target, prop) {
+            const client = resolveClient();
+            const value = Reflect.get(client, prop);
+            if (typeof value === 'function') {
+                return value.bind(client);
+            }
+            return value;
+        },
+    });
+}

package/build/utils/backlogOrganizationContext.js

@@ -0,0 +1,8 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+const organizationStorage = new AsyncLocalStorage();
+export function runWithOrganization(organization, fn) {
+    return organizationStorage.run(organization, fn);
+}
+export function getCurrentOrganization() {
+    return organizationStorage.getStore();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backlog-mcp-server",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "bin": {
     "backlog-mcp-server": "./build/index.js"
@@ -27,7 +27,7 @@
     "build"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.24.0",
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "backlog-js": "^0.16.0",
     "cosmiconfig": "^9.0.0",
     "dotenv": "^16.5.0",

package/build/tools/deleteDocument.js

@@ -1,19 +0,0 @@
-import { z } from 'zod';
-import { DocumentItemSchema } from '../types/zod/backlogOutputDefinition.js';
-import { buildToolSchema } from '../types/tool.js';
-const deleteDocumentSchema = buildToolSchema((t) => ({
-    documentId: z
-        .string()
-        .describe(t('TOOL_DELETE_DOCUMENT_DOCUMENT_ID', 'Document ID')),
-}));
-export const deleteDocumentTool = (backlog, { t }) => {
-    return {
-        name: 'delete_document',
-        description: t('TOOL_DELETE_DOCUMENT_DESCRIPTION', 'Permanently deletes a document. This is irreversible (hard delete) and the document cannot be recovered. Unlike the Backlog UI trash feature, this operation does not move the document to trash.'),
-        schema: z.object(deleteDocumentSchema(t)),
-        outputSchema: DocumentItemSchema,
-        handler: async ({ documentId }) => {
-            return backlog.deleteDocument(documentId);
-        },
-    };
-};