@atlassian-dc-mcp/common 0.12.2 → 0.14.0

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.14.0](https://github.com/b1ff/atlassian-dc-mcp/compare/v0.13.0...v0.14.0) (2026-03-23)
+
+**Note:** Version bump only for package @atlassian-dc-mcp/common
+
+
+
+
+
+# [0.13.0](https://github.com/b1ff/atlassian-dc-mcp/compare/v0.12.2...v0.13.0) (2026-03-21)
+
+
+### Features
+
+* add ability to specify external config file to MCP, to provide configuration to MCP without specifying credentials in the file ([c97d380](https://github.com/b1ff/atlassian-dc-mcp/commit/c97d38004ebc7e233ea276a36c2e233536d2d0ca))
+
+
+
+
+
 ## [0.12.2](https://github.com/b1ff/atlassian-dc-mcp/compare/v0.12.1...v0.12.2) (2026-03-21)
 
 **Note:** Version bump only for package @atlassian-dc-mcp/common

package/build/__tests__/runtime-config.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=runtime-config.test.d.ts.map

package/build/__tests__/runtime-config.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-config.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/runtime-config.test.ts"],"names":[],"mappings":""}

package/build/__tests__/runtime-config.test.js

@@ -0,0 +1,83 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+describe('runtime config loader', () => {
+    const originalEnv = process.env;
+    let tempDir;
+    beforeEach(() => {
+        jest.resetModules();
+        process.env = { ...originalEnv };
+        delete process.env.ATLASSIAN_DC_MCP_CONFIG_FILE;
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'atlassian-dc-mcp-config-'));
+    });
+    afterEach(() => {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+    afterAll(() => {
+        process.env = originalEnv;
+    });
+    it('loads an explicit shared config file', async () => {
+        const sharedConfigPath = path.join(tempDir, 'shared.env');
+        fs.writeFileSync(sharedConfigPath, 'JIRA_HOST=file-host\nJIRA_API_TOKEN=file-token\n');
+        process.env.ATLASSIAN_DC_MCP_CONFIG_FILE = sharedConfigPath;
+        const { getProductRuntimeConfig, initializeRuntimeConfig } = await import('../runtime-config.js');
+        initializeRuntimeConfig({ cwd: tempDir });
+        expect(getProductRuntimeConfig('jira')).toEqual({
+            host: 'file-host',
+            apiBasePath: undefined,
+            token: 'file-token',
+            defaultPageSize: 25,
+        });
+    });
+    it('throws when the explicit shared config file is missing', async () => {
+        process.env.ATLASSIAN_DC_MCP_CONFIG_FILE = path.join(tempDir, 'missing.env');
+        const { initializeRuntimeConfig } = await import('../runtime-config.js');
+        expect(() => initializeRuntimeConfig({ cwd: tempDir })).toThrow(`ATLASSIAN_DC_MCP_CONFIG_FILE points to a missing file: ${path.join(tempDir, 'missing.env')}`);
+    });
+    it('requires an absolute shared config file path', async () => {
+        process.env.ATLASSIAN_DC_MCP_CONFIG_FILE = 'relative/shared.env';
+        const { initializeRuntimeConfig } = await import('../runtime-config.js');
+        expect(() => initializeRuntimeConfig({ cwd: tempDir })).toThrow('ATLASSIAN_DC_MCP_CONFIG_FILE must be an absolute path: relative/shared.env');
+    });
+    it('keeps environment variables higher priority than file values', async () => {
+        const sharedConfigPath = path.join(tempDir, 'shared.env');
+        fs.writeFileSync(sharedConfigPath, 'JIRA_HOST=file-host\nJIRA_API_TOKEN=file-token\nJIRA_DEFAULT_PAGE_SIZE=50\n');
+        process.env.ATLASSIAN_DC_MCP_CONFIG_FILE = sharedConfigPath;
+        process.env.JIRA_API_TOKEN = 'env-token';
+        process.env.JIRA_DEFAULT_PAGE_SIZE = '10';
+        const { getProductRuntimeConfig, initializeRuntimeConfig } = await import('../runtime-config.js');
+        initializeRuntimeConfig({ cwd: tempDir });
+        expect(getProductRuntimeConfig('jira')).toEqual({
+            host: 'file-host',
+            apiBasePath: undefined,
+            token: 'env-token',
+            defaultPageSize: 10,
+        });
+    });
+    it('falls back to the cwd .env file when no explicit shared file is configured', async () => {
+        fs.writeFileSync(path.join(tempDir, '.env'), 'CONFLUENCE_HOST=cwd-host\nCONFLUENCE_API_TOKEN=cwd-token\nCONFLUENCE_DEFAULT_PAGE_SIZE=30\n');
+        const { getProductRuntimeConfig, initializeRuntimeConfig } = await import('../runtime-config.js');
+        initializeRuntimeConfig({ cwd: tempDir });
+        expect(getProductRuntimeConfig('confluence')).toEqual({
+            host: 'cwd-host',
+            apiBasePath: undefined,
+            token: 'cwd-token',
+            defaultPageSize: 30,
+        });
+    });
+    it('refreshes the cached file when its mtime changes', async () => {
+        const sharedConfigPath = path.join(tempDir, 'shared.env');
+        fs.writeFileSync(sharedConfigPath, 'BITBUCKET_HOST=file-host\nBITBUCKET_API_TOKEN=token-a\n');
+        const initialTime = new Date('2026-01-01T00:00:00.000Z');
+        fs.utimesSync(sharedConfigPath, initialTime, initialTime);
+        process.env.ATLASSIAN_DC_MCP_CONFIG_FILE = sharedConfigPath;
+        const { getProductRuntimeConfig, initializeRuntimeConfig } = await import('../runtime-config.js');
+        initializeRuntimeConfig({ cwd: tempDir });
+        expect(getProductRuntimeConfig('bitbucket').token).toBe('token-a');
+        fs.writeFileSync(sharedConfigPath, 'BITBUCKET_HOST=file-host\nBITBUCKET_API_TOKEN=token-b\n');
+        const updatedTime = new Date('2026-01-01T00:00:01.000Z');
+        fs.utimesSync(sharedConfigPath, updatedTime, updatedTime);
+        expect(getProductRuntimeConfig('bitbucket').token).toBe('token-b');
+    });
+});
+//# sourceMappingURL=runtime-config.test.js.map

package/build/__tests__/runtime-config.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-config.test.js","sourceRoot":"","sources":["../../src/__tests__/runtime-config.test.ts"],"names":[],"mappings":"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"}

package/build/index.d.ts

@@ -1,6 +1,6 @@
-import 'dotenv/config';
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export * from './api-error-handler.js';
+export * from './runtime-config.js';
 export declare const formatToolResponse: (result: unknown) => {
     content: {
         type: "text";

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGpE,cAAc,wBAAwB,CAAA;AAGtC,eAAO,MAAM,kBAAkB,GAAI,QAAQ,OAAO;;;;;CAKhD,CAAC;AAGH,eAAO,MAAM,WAAW,GAAI,OAAO,KAAK,UAGvC,CAAC;AAGF,wBAAgB,eAAe,CAAC,OAAO,EAAE;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,aAKA;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,SAAS,sBAkCpD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGpE,cAAc,wBAAwB,CAAA;AACtC,cAAc,qBAAqB,CAAC;AAGpC,eAAO,MAAM,kBAAkB,GAAI,QAAQ,OAAO;;;;;CAKhD,CAAC;AAGH,eAAO,MAAM,WAAW,GAAI,OAAO,KAAK,UAGvC,CAAC;AAGF,wBAAgB,eAAe,CAAC,OAAO,EAAE;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,aAKA;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,SAAS,sBAkCpD"}

package/build/index.js

@@ -1,7 +1,7 @@
-import 'dotenv/config';
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 export * from './api-error-handler.js';
+export * from './runtime-config.js';
 // Helper function to format tool responses
 export const formatToolResponse = (result) => ({
     content: [{

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,cAAc,wBAAwB,CAAA;AAEtC,2CAA2C;AAC3C,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,MAAe,EAAE,EAAE,CAAC,CAAC;IACtD,OAAO,EAAE,CAAC;YACR,IAAI,EAAE,MAAe;YACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;SAC7B,CAAC;CACH,CAAC,CAAC;AAEH,uBAAuB;AACvB,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAY,EAAE,EAAE;IAC1C,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;IACtC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC;AAEF,sCAAsC;AACtC,MAAM,UAAU,eAAe,CAAC,OAG/B;IACC,OAAO,IAAI,SAAS,CAAC;QACnB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAiB;IACnD,0DAA0D;IAC1D,yBAAyB;IACzB,iDAAiD;IACjD,EAAE;IACF,wCAAwC;IACxC,0DAA0D;IAC1D,qCAAqC;IACrC,MAAM;IACN,EAAE;IACF,8CAA8C;IAC9C,kDAAkD;IAClD,MAAM;IACN,EAAE;IACF,mDAAmD;IACnD,sCAAsC;IACtC,2CAA2C;IAC3C,kDAAkD;IAClD,2CAA2C;IAC3C,4CAA4C;IAC5C,mBAAmB;IACnB,uBAAuB;IACvB,gBAAgB;IAChB,QAAQ;IACR,EAAE;IACF,uDAAuD;IACvD,qBAAqB;IACrB,QAAQ;IACR,MAAM;IAGN,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,cAAc,wBAAwB,CAAA;AACtC,cAAc,qBAAqB,CAAC;AAEpC,2CAA2C;AAC3C,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,MAAe,EAAE,EAAE,CAAC,CAAC;IACtD,OAAO,EAAE,CAAC;YACR,IAAI,EAAE,MAAe;YACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;SAC7B,CAAC;CACH,CAAC,CAAC;AAEH,uBAAuB;AACvB,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAY,EAAE,EAAE;IAC1C,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;IACtC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC;AAEF,sCAAsC;AACtC,MAAM,UAAU,eAAe,CAAC,OAG/B;IACC,OAAO,IAAI,SAAS,CAAC;QACnB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAiB;IACnD,0DAA0D;IAC1D,yBAAyB;IACzB,iDAAiD;IACjD,EAAE;IACF,wCAAwC;IACxC,0DAA0D;IAC1D,qCAAqC;IACrC,MAAM;IACN,EAAE;IACF,8CAA8C;IAC9C,kDAAkD;IAClD,MAAM;IACN,EAAE;IACF,mDAAmD;IACnD,sCAAsC;IACtC,2CAA2C;IAC3C,kDAAkD;IAClD,2CAA2C;IAC3C,4CAA4C;IAC5C,mBAAmB;IACnB,uBAAuB;IACvB,gBAAgB;IAChB,QAAQ;IACR,EAAE;IACF,uDAAuD;IACvD,qBAAqB;IACrB,QAAQ;IACR,MAAM;IAGN,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/build/runtime-config.d.ts

@@ -0,0 +1,14 @@
+export declare const ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR = "ATLASSIAN_DC_MCP_CONFIG_FILE";
+export type AtlassianProduct = 'jira' | 'confluence' | 'bitbucket';
+export type ProductRuntimeConfig = {
+    host?: string;
+    apiBasePath?: string;
+    token?: string;
+    defaultPageSize: number;
+};
+export declare function initializeRuntimeConfig(options?: {
+    cwd?: string;
+}): void;
+export declare function getProductRuntimeConfig(product: AtlassianProduct): ProductRuntimeConfig;
+export declare function validateProductRuntimeConfig(product: AtlassianProduct): string[];
+//# sourceMappingURL=runtime-config.d.ts.map

package/build/runtime-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-config.d.ts","sourceRoot":"","sources":["../src/runtime-config.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,oCAAoC,iCAAiC,CAAC;AAEnF,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,YAAY,GAAG,WAAW,CAAC;AAoBnE,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;CACzB,CAAC;AA+GF,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,QAGjE;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,gBAAgB,GAAG,oBAAoB,CAUvF;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAchF"}

package/build/runtime-config.js

@@ -0,0 +1,123 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import dotenv from 'dotenv';
+const FALLBACK_PAGE_SIZE = 25;
+export const ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR = 'ATLASSIAN_DC_MCP_CONFIG_FILE';
+const PRODUCT_METADATA = {
+    jira: {
+        hostKey: 'JIRA_HOST',
+        apiBasePathKey: 'JIRA_API_BASE_PATH',
+        tokenKey: 'JIRA_API_TOKEN',
+        defaultPageSizeKey: 'JIRA_DEFAULT_PAGE_SIZE',
+    },
+    confluence: {
+        hostKey: 'CONFLUENCE_HOST',
+        apiBasePathKey: 'CONFLUENCE_API_BASE_PATH',
+        tokenKey: 'CONFLUENCE_API_TOKEN',
+        defaultPageSizeKey: 'CONFLUENCE_DEFAULT_PAGE_SIZE',
+    },
+    bitbucket: {
+        hostKey: 'BITBUCKET_HOST',
+        apiBasePathKey: 'BITBUCKET_API_BASE_PATH',
+        tokenKey: 'BITBUCKET_API_TOKEN',
+        defaultPageSizeKey: 'BITBUCKET_DEFAULT_PAGE_SIZE',
+    },
+};
+const runtimeConfigState = {
+    cwd: process.cwd(),
+};
+function parsePositiveInteger(value) {
+    if (!value) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (!/^\d+$/.test(trimmed)) {
+        return undefined;
+    }
+    const parsed = Number.parseInt(trimmed, 10);
+    return parsed > 0 ? parsed : undefined;
+}
+function getNonEmptyValue(value) {
+    if (!value) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function getExplicitConfigFilePath() {
+    const filePath = getNonEmptyValue(process.env[ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR]);
+    if (!filePath) {
+        return undefined;
+    }
+    if (!path.isAbsolute(filePath)) {
+        throw new Error(`${ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR} must be an absolute path: ${filePath}`);
+    }
+    return filePath;
+}
+function clearCachedFileIfNeeded(filePath) {
+    if (runtimeConfigState.cachedFile?.filePath === filePath) {
+        runtimeConfigState.cachedFile = undefined;
+    }
+}
+function getParsedFileEnvironment() {
+    const explicitFilePath = getExplicitConfigFilePath();
+    const filePath = explicitFilePath ?? path.join(runtimeConfigState.cwd, '.env');
+    let stats;
+    try {
+        stats = fs.statSync(filePath);
+    }
+    catch (error) {
+        clearCachedFileIfNeeded(filePath);
+        if (error.code === 'ENOENT' && !explicitFilePath) {
+            return {};
+        }
+        if (error.code === 'ENOENT' && explicitFilePath) {
+            throw new Error(`${ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR} points to a missing file: ${filePath}`);
+        }
+        throw error;
+    }
+    const cachedFile = runtimeConfigState.cachedFile;
+    if (cachedFile && cachedFile.filePath === filePath && cachedFile.mtimeMs === stats.mtimeMs) {
+        return cachedFile.values;
+    }
+    const values = dotenv.parse(fs.readFileSync(filePath));
+    runtimeConfigState.cachedFile = {
+        filePath,
+        mtimeMs: stats.mtimeMs,
+        values,
+    };
+    return values;
+}
+function getMergedEnvironment() {
+    return {
+        ...getParsedFileEnvironment(),
+        ...process.env,
+    };
+}
+export function initializeRuntimeConfig(options) {
+    runtimeConfigState.cwd = options?.cwd ?? process.cwd();
+    getParsedFileEnvironment();
+}
+export function getProductRuntimeConfig(product) {
+    const environment = getMergedEnvironment();
+    const metadata = PRODUCT_METADATA[product];
+    return {
+        host: getNonEmptyValue(environment[metadata.hostKey]),
+        apiBasePath: getNonEmptyValue(environment[metadata.apiBasePathKey]),
+        token: getNonEmptyValue(environment[metadata.tokenKey]),
+        defaultPageSize: parsePositiveInteger(environment[metadata.defaultPageSizeKey]) ?? FALLBACK_PAGE_SIZE,
+    };
+}
+export function validateProductRuntimeConfig(product) {
+    const metadata = PRODUCT_METADATA[product];
+    const config = getProductRuntimeConfig(product);
+    const missing = [];
+    if (!config.token) {
+        missing.push(metadata.tokenKey);
+    }
+    if (!config.host && !config.apiBasePath) {
+        missing.push(`${metadata.hostKey} or ${metadata.apiBasePathKey}`);
+    }
+    return missing;
+}
+//# sourceMappingURL=runtime-config.js.map

package/build/runtime-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-config.js","sourceRoot":"","sources":["../src/runtime-config.ts"],"names":[],"mappings":"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"}

package/jest.config.js

@@ -0,0 +1,19 @@
+export default {
+  preset: 'ts-jest/presets/default-esm',
+  extensionsToTreatAsEsm: ['.ts'],
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+  transform: {
+    '^.+\\.ts$': ['ts-jest', {
+      useESM: true,
+    }],
+  },
+  testEnvironment: 'node',
+  testMatch: ['**/__tests__/**/*.test.ts'],
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.d.ts',
+    '!src/**/index.ts',
+  ],
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlassian-dc-mcp/common",
-  "version": "0.12.2",
+  "version": "0.14.0",
   "main": "build/index.js",
   "type": "module",
   "private": false,
@@ -22,5 +22,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "6488590c1832714d510cc4a4f5f3d9e8e38f3b09"
+  "gitHead": "cddfcbf3cb1404e69957277fd988c28e08700fae"
 }

package/src/__tests__/runtime-config.test.ts

@@ -0,0 +1,116 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+describe('runtime config loader', () => {
+  const originalEnv = process.env;
+  let tempDir: string;
+
+  beforeEach(() => {
+    jest.resetModules();
+    process.env = { ...originalEnv };
+    delete process.env.ATLASSIAN_DC_MCP_CONFIG_FILE;
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'atlassian-dc-mcp-config-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  afterAll(() => {
+    process.env = originalEnv;
+  });
+
+  it('loads an explicit shared config file', async () => {
+    const sharedConfigPath = path.join(tempDir, 'shared.env');
+    fs.writeFileSync(sharedConfigPath, 'JIRA_HOST=file-host\nJIRA_API_TOKEN=file-token\n');
+    process.env.ATLASSIAN_DC_MCP_CONFIG_FILE = sharedConfigPath;
+
+    const { getProductRuntimeConfig, initializeRuntimeConfig } = await import('../runtime-config.js');
+
+    initializeRuntimeConfig({ cwd: tempDir });
+
+    expect(getProductRuntimeConfig('jira')).toEqual({
+      host: 'file-host',
+      apiBasePath: undefined,
+      token: 'file-token',
+      defaultPageSize: 25,
+    });
+  });
+
+  it('throws when the explicit shared config file is missing', async () => {
+    process.env.ATLASSIAN_DC_MCP_CONFIG_FILE = path.join(tempDir, 'missing.env');
+
+    const { initializeRuntimeConfig } = await import('../runtime-config.js');
+
+    expect(() => initializeRuntimeConfig({ cwd: tempDir })).toThrow(
+      `ATLASSIAN_DC_MCP_CONFIG_FILE points to a missing file: ${path.join(tempDir, 'missing.env')}`,
+    );
+  });
+
+  it('requires an absolute shared config file path', async () => {
+    process.env.ATLASSIAN_DC_MCP_CONFIG_FILE = 'relative/shared.env';
+
+    const { initializeRuntimeConfig } = await import('../runtime-config.js');
+
+    expect(() => initializeRuntimeConfig({ cwd: tempDir })).toThrow(
+      'ATLASSIAN_DC_MCP_CONFIG_FILE must be an absolute path: relative/shared.env',
+    );
+  });
+
+  it('keeps environment variables higher priority than file values', async () => {
+    const sharedConfigPath = path.join(tempDir, 'shared.env');
+    fs.writeFileSync(sharedConfigPath, 'JIRA_HOST=file-host\nJIRA_API_TOKEN=file-token\nJIRA_DEFAULT_PAGE_SIZE=50\n');
+    process.env.ATLASSIAN_DC_MCP_CONFIG_FILE = sharedConfigPath;
+    process.env.JIRA_API_TOKEN = 'env-token';
+    process.env.JIRA_DEFAULT_PAGE_SIZE = '10';
+
+    const { getProductRuntimeConfig, initializeRuntimeConfig } = await import('../runtime-config.js');
+
+    initializeRuntimeConfig({ cwd: tempDir });
+
+    expect(getProductRuntimeConfig('jira')).toEqual({
+      host: 'file-host',
+      apiBasePath: undefined,
+      token: 'env-token',
+      defaultPageSize: 10,
+    });
+  });
+
+  it('falls back to the cwd .env file when no explicit shared file is configured', async () => {
+    fs.writeFileSync(
+      path.join(tempDir, '.env'),
+      'CONFLUENCE_HOST=cwd-host\nCONFLUENCE_API_TOKEN=cwd-token\nCONFLUENCE_DEFAULT_PAGE_SIZE=30\n',
+    );
+
+    const { getProductRuntimeConfig, initializeRuntimeConfig } = await import('../runtime-config.js');
+
+    initializeRuntimeConfig({ cwd: tempDir });
+
+    expect(getProductRuntimeConfig('confluence')).toEqual({
+      host: 'cwd-host',
+      apiBasePath: undefined,
+      token: 'cwd-token',
+      defaultPageSize: 30,
+    });
+  });
+
+  it('refreshes the cached file when its mtime changes', async () => {
+    const sharedConfigPath = path.join(tempDir, 'shared.env');
+    fs.writeFileSync(sharedConfigPath, 'BITBUCKET_HOST=file-host\nBITBUCKET_API_TOKEN=token-a\n');
+    const initialTime = new Date('2026-01-01T00:00:00.000Z');
+    fs.utimesSync(sharedConfigPath, initialTime, initialTime);
+    process.env.ATLASSIAN_DC_MCP_CONFIG_FILE = sharedConfigPath;
+
+    const { getProductRuntimeConfig, initializeRuntimeConfig } = await import('../runtime-config.js');
+
+    initializeRuntimeConfig({ cwd: tempDir });
+    expect(getProductRuntimeConfig('bitbucket').token).toBe('token-a');
+
+    fs.writeFileSync(sharedConfigPath, 'BITBUCKET_HOST=file-host\nBITBUCKET_API_TOKEN=token-b\n');
+    const updatedTime = new Date('2026-01-01T00:00:01.000Z');
+    fs.utimesSync(sharedConfigPath, updatedTime, updatedTime);
+
+    expect(getProductRuntimeConfig('bitbucket').token).toBe('token-b');
+  });
+});

package/src/index.ts

@@ -1,8 +1,8 @@
-import 'dotenv/config';
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 export * from './api-error-handler.js'
+export * from './runtime-config.js';
 
 // Helper function to format tool responses
 export const formatToolResponse = (result: unknown) => ({

package/src/runtime-config.ts

@@ -0,0 +1,176 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import dotenv from 'dotenv';
+
+const FALLBACK_PAGE_SIZE = 25;
+
+export const ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR = 'ATLASSIAN_DC_MCP_CONFIG_FILE';
+
+export type AtlassianProduct = 'jira' | 'confluence' | 'bitbucket';
+
+type ProductMetadata = {
+  hostKey: string;
+  apiBasePathKey: string;
+  tokenKey: string;
+  defaultPageSizeKey: string;
+};
+
+type ParsedEnvironment = Record<string, string>;
+
+type RuntimeConfigState = {
+  cwd: string;
+  cachedFile?: {
+    filePath: string;
+    mtimeMs: number;
+    values: ParsedEnvironment;
+  };
+};
+
+export type ProductRuntimeConfig = {
+  host?: string;
+  apiBasePath?: string;
+  token?: string;
+  defaultPageSize: number;
+};
+
+const PRODUCT_METADATA: Record<AtlassianProduct, ProductMetadata> = {
+  jira: {
+    hostKey: 'JIRA_HOST',
+    apiBasePathKey: 'JIRA_API_BASE_PATH',
+    tokenKey: 'JIRA_API_TOKEN',
+    defaultPageSizeKey: 'JIRA_DEFAULT_PAGE_SIZE',
+  },
+  confluence: {
+    hostKey: 'CONFLUENCE_HOST',
+    apiBasePathKey: 'CONFLUENCE_API_BASE_PATH',
+    tokenKey: 'CONFLUENCE_API_TOKEN',
+    defaultPageSizeKey: 'CONFLUENCE_DEFAULT_PAGE_SIZE',
+  },
+  bitbucket: {
+    hostKey: 'BITBUCKET_HOST',
+    apiBasePathKey: 'BITBUCKET_API_BASE_PATH',
+    tokenKey: 'BITBUCKET_API_TOKEN',
+    defaultPageSizeKey: 'BITBUCKET_DEFAULT_PAGE_SIZE',
+  },
+};
+
+const runtimeConfigState: RuntimeConfigState = {
+  cwd: process.cwd(),
+};
+
+function parsePositiveInteger(value: string | undefined): number | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  const trimmed = value.trim();
+  if (!/^\d+$/.test(trimmed)) {
+    return undefined;
+  }
+
+  const parsed = Number.parseInt(trimmed, 10);
+  return parsed > 0 ? parsed : undefined;
+}
+
+function getNonEmptyValue(value: string | undefined): string | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function getExplicitConfigFilePath(): string | undefined {
+  const filePath = getNonEmptyValue(process.env[ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR]);
+  if (!filePath) {
+    return undefined;
+  }
+
+  if (!path.isAbsolute(filePath)) {
+    throw new Error(`${ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR} must be an absolute path: ${filePath}`);
+  }
+
+  return filePath;
+}
+
+function clearCachedFileIfNeeded(filePath: string) {
+  if (runtimeConfigState.cachedFile?.filePath === filePath) {
+    runtimeConfigState.cachedFile = undefined;
+  }
+}
+
+function getParsedFileEnvironment(): ParsedEnvironment {
+  const explicitFilePath = getExplicitConfigFilePath();
+  const filePath = explicitFilePath ?? path.join(runtimeConfigState.cwd, '.env');
+
+  let stats: fs.Stats;
+  try {
+    stats = fs.statSync(filePath);
+  } catch (error) {
+    clearCachedFileIfNeeded(filePath);
+
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT' && !explicitFilePath) {
+      return {};
+    }
+
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT' && explicitFilePath) {
+      throw new Error(`${ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR} points to a missing file: ${filePath}`);
+    }
+
+    throw error;
+  }
+
+  const cachedFile = runtimeConfigState.cachedFile;
+  if (cachedFile && cachedFile.filePath === filePath && cachedFile.mtimeMs === stats.mtimeMs) {
+    return cachedFile.values;
+  }
+
+  const values = dotenv.parse(fs.readFileSync(filePath));
+  runtimeConfigState.cachedFile = {
+    filePath,
+    mtimeMs: stats.mtimeMs,
+    values,
+  };
+  return values;
+}
+
+function getMergedEnvironment(): NodeJS.ProcessEnv {
+  return {
+    ...getParsedFileEnvironment(),
+    ...process.env,
+  };
+}
+
+export function initializeRuntimeConfig(options?: { cwd?: string }) {
+  runtimeConfigState.cwd = options?.cwd ?? process.cwd();
+  getParsedFileEnvironment();
+}
+
+export function getProductRuntimeConfig(product: AtlassianProduct): ProductRuntimeConfig {
+  const environment = getMergedEnvironment();
+  const metadata = PRODUCT_METADATA[product];
+
+  return {
+    host: getNonEmptyValue(environment[metadata.hostKey]),
+    apiBasePath: getNonEmptyValue(environment[metadata.apiBasePathKey]),
+    token: getNonEmptyValue(environment[metadata.tokenKey]),
+    defaultPageSize: parsePositiveInteger(environment[metadata.defaultPageSizeKey]) ?? FALLBACK_PAGE_SIZE,
+  };
+}
+
+export function validateProductRuntimeConfig(product: AtlassianProduct): string[] {
+  const metadata = PRODUCT_METADATA[product];
+  const config = getProductRuntimeConfig(product);
+  const missing: string[] = [];
+
+  if (!config.token) {
+    missing.push(metadata.tokenKey);
+  }
+
+  if (!config.host && !config.apiBasePath) {
+    missing.push(`${metadata.hostKey} or ${metadata.apiBasePathKey}`);
+  }
+
+  return missing;
+}