@atlassian-dc-mcp/bitbucket 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.17.0](https://github.com/b1ff/atlassian-dc-mcp/compare/v0.16.0...v0.17.0) (2026-04-23)
+
+
+### Features
+
+* add interactive setup CLI with secure credential storage ([f317903](https://github.com/b1ff/atlassian-dc-mcp/commit/f317903a9975b66442f54e520a5a1656a69d1a1b))
+
+
+
+
+
 # [0.16.0](https://github.com/b1ff/atlassian-dc-mcp/compare/v0.15.0...v0.16.0) (2026-04-14)
 
 

package/README.md

@@ -2,6 +2,35 @@
 
 This package provides a Machine Comprehension Protocol (MCP) server for interacting with Atlassian Bitbucket Data Center edition.
 
+## Interactive Setup
+
+The easiest way to configure this server is the built-in `setup` subcommand:
+
+```bash
+npx @atlassian-dc-mcp/bitbucket setup
+```
+
+It prompts for host, API base path, default page size, and API token, then stores them in the most secure place available:
+
+- **macOS** — token in the login Keychain (service `atlassian-dc-mcp`, account `bitbucket-token`); host / base path / page size in `~/.atlassian-dc-mcp/bitbucket.env` (mode `0600`).
+- **Linux** — everything in `~/.atlassian-dc-mcp/bitbucket.env` with POSIX mode `0600` (read/write for your user only).
+- **Windows** — everything in `%USERPROFILE%\.atlassian-dc-mcp\bitbucket.env`. Node passes the mode bits but Windows ignores them, so the file inherits the ACL of your user profile directory (typically readable only by your user, SYSTEM, and Administrators).
+
+After setup, you can launch the server without any environment variables:
+
+```json
+{
+  "mcpServers": {
+    "atlassian-bitbucket-dc": {
+      "command": "npx",
+      "args": ["-y", "@atlassian-dc-mcp/bitbucket"]
+    }
+  }
+}
+```
+
+Environment variables still override stored values — see [Configuration sources](#configuration-sources) below.
+
 ## Claude Desktop Configuration
 
 To use this MCP connector with Claude Desktop, add the following to your Claude Desktop configuration:
@@ -94,7 +123,7 @@ Alternatively, you can use `BITBUCKET_API_BASE_PATH` instead of `BITBUCKET_HOST`
    BITBUCKET_DEFAULT_PAGE_SIZE=25
    ```
 
-   Direct environment variables override values loaded from `ATLASSIAN_DC_MCP_CONFIG_FILE`.
+   See [Configuration sources](#configuration-sources) for the full precedence chain.
 
    To create a personal access token:
   - In Bitbucket, select your profile picture at the bottom left
@@ -103,6 +132,19 @@ Alternatively, you can use `BITBUCKET_API_BASE_PATH` instead of `BITBUCKET_HOST`
   - Set appropriate permissions for the token
   - Copy the token and store it securely (you won't be able to see it again)
 
+## Configuration sources
+
+Each key is resolved by walking these sources in priority order and taking the first non-empty value:
+
+| Priority | Source | Reads | Written by `setup` |
+|---------:|--------|-------|--------------------|
+| 100 | `process.env` (`BITBUCKET_HOST`, `BITBUCKET_API_BASE_PATH`, `BITBUCKET_API_TOKEN`, `BITBUCKET_DEFAULT_PAGE_SIZE`) | all keys | — |
+| 80  | env file — `ATLASSIAN_DC_MCP_CONFIG_FILE` (absolute path) or `./.env` | all keys | — |
+| 60  | home file — `~/.atlassian-dc-mcp/bitbucket.env` on macOS/Linux, `%USERPROFILE%\.atlassian-dc-mcp\bitbucket.env` on Windows (mode `0600` on POSIX; Windows inherits the user-profile ACL) | all keys | host, apiBasePath, defaultPageSize (always); token (non-darwin or keychain fallback) |
+| 40  | macOS Keychain — service `atlassian-dc-mcp`, account `bitbucket-token` | token only | token (darwin only) |
+
+`setup` always writes non-secret fields to the home file and tries the keychain first for the token. If a higher-priority source shadows the value being saved, `setup` prints a warning so you can unset the env var.
+
 ## Usage
 
 Or for development with auto-reload:

package/bin/run.js

@@ -1,2 +1,7 @@
 #!/usr/bin/env node
-import '../build/index.js';
+const sub = process.argv[2];
+if (sub === 'setup') {
+  await import('../build/setup.js');
+} else {
+  await import('../build/index.js');
+}

package/build/__tests__/setup.test.d.ts

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

package/build/__tests__/setup.test.d.ts.map

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

package/build/__tests__/setup.test.js

@@ -0,0 +1,11 @@
+import fs from 'node:fs';
+import path from 'node:path';
+describe('bitbucket setup shim', () => {
+    it('calls runSetup with BITBUCKET_PRODUCT', () => {
+        const setupSource = fs.readFileSync(path.join(process.cwd(), 'src', 'setup.ts'), 'utf8');
+        expect(setupSource).toMatch(/runSetup\(\s*BITBUCKET_PRODUCT\s*\)/);
+        expect(setupSource).toMatch(/from\s+['"]@atlassian-dc-mcp\/common['"]/);
+        expect(setupSource).toMatch(/import\s+\{\s*BITBUCKET_PRODUCT\s*\}\s+from\s+['"]\.\/config\.js['"]/);
+    });
+});
+//# sourceMappingURL=setup.test.js.map

package/build/__tests__/setup.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.test.js","sourceRoot":"","sources":["../../src/__tests__/setup.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,QAAQ,CAAC,sBAAsB,EAAE,GAAG,EAAE;IACpC,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;QAC/C,MAAM,WAAW,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,CAAC;QACzF,MAAM,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,qCAAqC,CAAC,CAAC;QACnE,MAAM,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,0CAA0C,CAAC,CAAC;QACxE,MAAM,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,sEAAsE,CAAC,CAAC;IACtG,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/build/config.d.ts

@@ -1,3 +1,5 @@
+import { type ProductDefinition } from '@atlassian-dc-mcp/common';
+export declare const BITBUCKET_PRODUCT: ProductDefinition;
 export declare function getBitbucketRuntimeConfig(): import("@atlassian-dc-mcp/common").ProductRuntimeConfig;
 export declare function getDefaultPageSize(): number;
 export declare function getMissingConfig(): string[];

package/build/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,wBAAgB,yBAAyB,4DAExC;AAED,wBAAgB,kBAAkB,WAEjC;AAED,wBAAgB,gBAAgB,aAE/B"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAElC,eAAO,MAAM,iBAAiB,EAAE,iBAS/B,CAAC;AAEF,wBAAgB,yBAAyB,4DAExC;AAED,wBAAgB,kBAAkB,WAEjC;AAED,wBAAgB,gBAAgB,aAE/B"}

package/build/config.js

@@ -1,11 +1,21 @@
-import { getProductRuntimeConfig, validateProductRuntimeConfig } from '@atlassian-dc-mcp/common';
+import { getProductRuntimeConfig, validateProductRuntimeConfig, } from '@atlassian-dc-mcp/common';
+export const BITBUCKET_PRODUCT = {
+    id: 'bitbucket',
+    envVars: {
+        host: 'BITBUCKET_HOST',
+        apiBasePath: 'BITBUCKET_API_BASE_PATH',
+        token: 'BITBUCKET_API_TOKEN',
+        defaultPageSize: 'BITBUCKET_DEFAULT_PAGE_SIZE',
+    },
+    defaultApiBasePath: '/rest/api/1.0',
+};
 export function getBitbucketRuntimeConfig() {
-    return getProductRuntimeConfig('bitbucket');
+    return getProductRuntimeConfig(BITBUCKET_PRODUCT);
 }
 export function getDefaultPageSize() {
     return getBitbucketRuntimeConfig().defaultPageSize;
 }
 export function getMissingConfig() {
-    return validateProductRuntimeConfig('bitbucket');
+    return validateProductRuntimeConfig(BITBUCKET_PRODUCT);
 }
 //# sourceMappingURL=config.js.map

package/build/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AAEjG,MAAM,UAAU,yBAAyB;IACvC,OAAO,uBAAuB,CAAC,WAAW,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,OAAO,yBAAyB,EAAE,CAAC,eAAe,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,4BAA4B,CAAC,WAAW,CAAC,CAAC;AACnD,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,4BAA4B,GAE7B,MAAM,0BAA0B,CAAC;AAElC,MAAM,CAAC,MAAM,iBAAiB,GAAsB;IAClD,EAAE,EAAE,WAAW;IACf,OAAO,EAAE;QACP,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,yBAAyB;QACtC,KAAK,EAAE,qBAAqB;QAC5B,eAAe,EAAE,6BAA6B;KAC/C;IACD,kBAAkB,EAAE,eAAe;CACpC,CAAC;AAEF,MAAM,UAAU,yBAAyB;IACvC,OAAO,uBAAuB,CAAC,iBAAiB,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,OAAO,yBAAyB,EAAE,CAAC,eAAe,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,4BAA4B,CAAC,iBAAiB,CAAC,CAAC;AACzD,CAAC"}

package/build/setup.d.ts

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

package/build/setup.d.ts.map

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

package/build/setup.js

@@ -0,0 +1,4 @@
+import { runSetup } from '@atlassian-dc-mcp/common';
+import { BITBUCKET_PRODUCT } from './config.js';
+await runSetup(BITBUCKET_PRODUCT);
+//# sourceMappingURL=setup.js.map

package/build/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,QAAQ,CAAC,iBAAiB,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlassian-dc-mcp/bitbucket",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "main": "build/index.js",
   "type": "module",
   "bin": "./bin/run.js",
@@ -31,7 +31,7 @@
     "test": "jest"
   },
   "dependencies": {
-    "@atlassian-dc-mcp/common": "^0.16.0",
+    "@atlassian-dc-mcp/common": "^0.17.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "dotenv": "^16.4.7",
     "zod": "^3.24.2"
@@ -48,5 +48,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "eb8394fc8317b2d986b03de9853edf47aa77566a"
+  "gitHead": "3f2e386c4f08b0ff6781dde37ce6e54f6dcb8d51"
 }

package/src/__tests__/setup.test.ts

@@ -0,0 +1,11 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+describe('bitbucket setup shim', () => {
+  it('calls runSetup with BITBUCKET_PRODUCT', () => {
+    const setupSource = fs.readFileSync(path.join(process.cwd(), 'src', 'setup.ts'), 'utf8');
+    expect(setupSource).toMatch(/runSetup\(\s*BITBUCKET_PRODUCT\s*\)/);
+    expect(setupSource).toMatch(/from\s+['"]@atlassian-dc-mcp\/common['"]/);
+    expect(setupSource).toMatch(/import\s+\{\s*BITBUCKET_PRODUCT\s*\}\s+from\s+['"]\.\/config\.js['"]/);
+  });
+});

package/src/config.ts

@@ -1,7 +1,22 @@
-import { getProductRuntimeConfig, validateProductRuntimeConfig } from '@atlassian-dc-mcp/common';
+import {
+  getProductRuntimeConfig,
+  validateProductRuntimeConfig,
+  type ProductDefinition,
+} from '@atlassian-dc-mcp/common';
+
+export const BITBUCKET_PRODUCT: ProductDefinition = {
+  id: 'bitbucket',
+  envVars: {
+    host: 'BITBUCKET_HOST',
+    apiBasePath: 'BITBUCKET_API_BASE_PATH',
+    token: 'BITBUCKET_API_TOKEN',
+    defaultPageSize: 'BITBUCKET_DEFAULT_PAGE_SIZE',
+  },
+  defaultApiBasePath: '/rest/api/1.0',
+};
 
 export function getBitbucketRuntimeConfig() {
-  return getProductRuntimeConfig('bitbucket');
+  return getProductRuntimeConfig(BITBUCKET_PRODUCT);
 }
 
 export function getDefaultPageSize() {
@@ -9,5 +24,5 @@ export function getDefaultPageSize() {
 }
 
 export function getMissingConfig() {
-  return validateProductRuntimeConfig('bitbucket');
+  return validateProductRuntimeConfig(BITBUCKET_PRODUCT);
 }

package/src/setup.ts

@@ -0,0 +1,4 @@
+import { runSetup } from '@atlassian-dc-mcp/common';
+import { BITBUCKET_PRODUCT } from './config.js';
+
+await runSetup(BITBUCKET_PRODUCT);