mcp-server-bitbucket 0.11.0 → 0.19.0

package/src/settings.ts

@@ -1,30 +1,65 @@
 /**
  * Settings management for Bitbucket MCP Server
- * 
+ *
  * Configuration via environment variables:
  * - BITBUCKET_WORKSPACE: Bitbucket workspace slug (required)
- * - BITBUCKET_EMAIL: Account email for Basic Auth (required)
- * - BITBUCKET_API_TOKEN: Repository access token (required)
+ * - BITBUCKET_EMAIL: Account email for Basic Auth (required for basic auth)
+ * - BITBUCKET_API_TOKEN: Atlassian API token / access token (required)
+ * - BITBUCKET_OAUTH_TOKEN: Access token used with `Authorization: Bearer` (optional)
+ * - BITBUCKET_AUTH_TYPE: Force auth mode - 'basic' or 'bearer' (optional, auto-detected)
  * - API_TIMEOUT: Request timeout in seconds (default: 30, max: 300)
  * - MAX_RETRIES: Max retry attempts for rate limiting (default: 3, max: 10)
  * - OUTPUT_FORMAT: Output format - 'json' or 'toon' (default: json)
+ *
+ * Auth modes:
+ * - basic: Atlassian API tokens (ATATT...) authenticate as `email:token`.
+ * - bearer: Workspace/project/repository access tokens (ATCTT...) only work as
+ *   `Authorization: Bearer <token>`; Basic auth returns 401 for them.
  */
 
 import { z } from 'zod';
 
+export type AuthType = 'basic' | 'bearer';
+
 const settingsSchema = z.object({
   bitbucketWorkspace: z.string().min(1, 'BITBUCKET_WORKSPACE is required'),
-  bitbucketEmail: z.string().min(1, 'BITBUCKET_EMAIL is required'),
-  bitbucketApiToken: z.string().min(1, 'BITBUCKET_API_TOKEN is required'),
+  bitbucketEmail: z.string().default(''),
+  bitbucketApiToken: z.string().min(1, 'BITBUCKET_API_TOKEN (or BITBUCKET_OAUTH_TOKEN) is required'),
+  bitbucketAuthType: z.enum(['basic', 'bearer']),
   apiTimeout: z.number().min(1).max(300).default(30),
   maxRetries: z.number().min(0).max(10).default(3),
   outputFormat: z.enum(['json', 'toon']).default('json'),
-});
+}).refine(
+  (s) => s.bitbucketAuthType !== 'basic' || s.bitbucketEmail.length > 0,
+  { message: 'BITBUCKET_EMAIL is required when using basic auth', path: ['bitbucketEmail'] }
+);
 
 export type Settings = z.infer<typeof settingsSchema>;
 
 let cachedSettings: Settings | null = null;
 
+/**
+ * Resolve which auth mode to use.
+ *
+ * Explicit BITBUCKET_AUTH_TYPE wins. Otherwise bearer is used when an
+ * OAuth/access token is configured or when no email is available (an access
+ * token has no account to pair with), and basic otherwise.
+ */
+function resolveAuthType(
+  explicit: string,
+  oauthToken: string,
+  email: string
+): AuthType {
+  const normalized = explicit.trim().toLowerCase();
+  if (normalized === 'bearer' || normalized === 'basic') {
+    return normalized;
+  }
+  if (oauthToken.length > 0 || email.length === 0) {
+    return 'bearer';
+  }
+  return 'basic';
+}
+
 /**
  * Load and validate settings from environment variables.
  * Results are cached for subsequent calls.
@@ -34,17 +69,24 @@ export function getSettings(): Settings {
     return cachedSettings;
   }
 
+  const email = process.env.BITBUCKET_EMAIL || '';
+  const oauthToken = process.env.BITBUCKET_OAUTH_TOKEN || '';
+  const apiToken = process.env.BITBUCKET_API_TOKEN || '';
+  const authType = resolveAuthType(process.env.BITBUCKET_AUTH_TYPE || '', oauthToken, email);
+
   const rawSettings = {
     bitbucketWorkspace: process.env.BITBUCKET_WORKSPACE || '',
-    bitbucketEmail: process.env.BITBUCKET_EMAIL || '',
-    bitbucketApiToken: process.env.BITBUCKET_API_TOKEN || '',
+    bitbucketEmail: email,
+    // Bearer mode prefers the dedicated OAuth/access token when both are set
+    bitbucketApiToken: authType === 'bearer' ? (oauthToken || apiToken) : apiToken,
+    bitbucketAuthType: authType,
     apiTimeout: parseInt(process.env.API_TIMEOUT || '30', 10),
     maxRetries: parseInt(process.env.MAX_RETRIES || '3', 10),
     outputFormat: (process.env.OUTPUT_FORMAT || 'json') as 'json' | 'toon',
   };
 
   const result = settingsSchema.safeParse(rawSettings);
-  
+
   if (!result.success) {
     const errors = result.error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ');
     throw new Error(`Configuration error: ${errors}`);
@@ -60,4 +102,3 @@ export function getSettings(): Settings {
 export function resetSettings(): void {
   cachedSettings = null;
 }
-

package/src/tools/commits.ts

@@ -10,12 +10,15 @@ import { CommitStatusState } from '../types.js';
 export const definitions: Tool[] = [
   {
     name: 'list_commits',
-    description: 'List commits in a repository.',
+    description: 'List a page of commits. Use include/exclude for commits between revisions (include=head, exclude=base); continue with next_cursor until has_more is false.',
     inputSchema: {
       type: 'object',
       properties: {
         repo_slug: { type: 'string', description: 'Repository slug' },
-        branch: { type: 'string', description: 'Filter by branch name (optional)' },
+        branch: { type: 'string', description: 'Branch, tag or SHA to include (alias for include)' },
+        include: { type: 'array', items: { type: 'string' }, description: 'Include commits reachable from these branches, tags or SHAs' },
+        exclude: { type: 'array', items: { type: 'string' }, description: 'Exclude commits reachable from these revisions' },
+        cursor: { type: 'string', description: 'Opaque next_cursor from this tool; retains its page size and filters' },
         path: { type: 'string', description: 'Filter by file path - only commits that modified this path (optional)' },
         limit: { type: 'number', description: 'Maximum results (default: 20)', default: 20 },
       },
@@ -36,17 +39,43 @@ export const definitions: Tool[] = [
   },
   {
     name: 'compare_commits',
-    description: 'Compare two commits or branches and see files changed.',
+    description: 'Compare base to head (branches, tags or SHAs). Returns a page of changed files and line counts; follow next_cursor for all files.',
     inputSchema: {
       type: 'object',
       properties: {
         repo_slug: { type: 'string', description: 'Repository slug' },
         base: { type: 'string', description: 'Base commit hash or branch name' },
-        head: { type: 'string', description: 'Head commit hash or branch name' },
+        head: { type: 'string', description: 'Head commit hash, tag or branch name' },
+        path: { type: 'string', description: 'Optional file path filter' },
+        limit: { type: 'integer', minimum: 1, maximum: 100, default: 50 },
+        cursor: { type: 'string', description: 'Opaque next_cursor; retains page size and filters' },
       },
       required: ['repo_slug', 'base', 'head'],
     },
   },
+  {
+    name: 'get_commit_diff',
+    description: 'Get the raw Git-style diff from base to head. Continue large diffs with next_offset; pin revisions to commit hashes while paging. API-side diff limits still apply.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string' }, base: { type: 'string' }, head: { type: 'string' },
+        path: { type: 'string', description: 'Optional file path filter' },
+        offset: { type: 'integer', minimum: 0, default: 0 },
+        max_chars: { type: 'integer', minimum: 1, maximum: 100000, default: 20000 },
+      },
+      required: ['repo_slug', 'base', 'head'],
+    },
+  },
+  {
+    name: 'get_merge_base',
+    description: 'Get a best common ancestor of two branches, tags or commit hashes. Bitbucket returns one ancestor when multiple best ancestors exist.',
+    inputSchema: {
+      type: 'object',
+      properties: { repo_slug: { type: 'string' }, base: { type: 'string' }, head: { type: 'string' } },
+      required: ['repo_slug', 'base', 'head'],
+    },
+  },
   {
     name: 'get_commit_statuses',
     description: 'Get build/CI statuses for a commit.',
@@ -82,18 +111,18 @@ export const definitions: Tool[] = [
 export const handlers: Record<string, (args: Record<string, unknown>) => Promise<Record<string, unknown>>> = {
   list_commits: async (args) => {
     const client = getClient();
-    const commits = await client.listCommits(args.repo_slug as string, {
+    const page = await client.listCommitsPage(args.repo_slug as string, {
       branch: args.branch as string,
+      include: args.include as string[] | undefined,
+      exclude: args.exclude as string[] | undefined,
       path: args.path as string,
-      limit: validateLimit((args.limit as number) || 20),
+      cursor: args.cursor as string,
+      limit: validateLimit((args.limit as number) ?? 20),
     });
     return {
-      commits: commits.map(c => ({
-        hash: truncateHash(c.hash),
-        message: c.message,
-        author: c.author?.raw,
-        date: c.date,
-      })),
+      commits: page.values.map(c => ({ hash: truncateHash(c.hash), message: c.message, author: c.author?.raw, date: c.date })),
+      has_more: page.has_more,
+      next_cursor: page.next_cursor,
     };
   },
 
@@ -114,31 +143,34 @@ export const handlers: Record<string, (args: Record<string, unknown>) => Promise
 
   compare_commits: async (args) => {
     const client = getClient();
-    const result = await client.compareCommits(
-      args.repo_slug as string,
-      args.base as string,
-      args.head as string
-    );
-    if (!result) {
-      return { error: `Could not compare ${args.base}..${args.head}` };
-    }
-    const files = (result.values as Array<{
-      new?: { path?: string };
-      old?: { path?: string };
-      status?: string;
-      lines_added?: number;
-      lines_removed?: number;
-    }>) || [];
+    const page = await client.compareCommitsPage(args.repo_slug as string, args.base as string, args.head as string, {
+      path: args.path as string, limit: validateLimit((args.limit as number) ?? 50), cursor: args.cursor as string,
+    });
+    const files = page.values as Array<{ new?: { path?: string }; old?: { path?: string }; status?: string; lines_added?: number; lines_removed?: number }>;
     return {
-      files: files.slice(0, 50).map(f => ({
-        path: f.new?.path || f.old?.path,
-        status: f.status,
-        '+': f.lines_added || 0,
-        '-': f.lines_removed || 0,
-      })),
+      files: files.map(f => ({ path: f.new?.path || f.old?.path, status: f.status, '+': f.lines_added || 0, '-': f.lines_removed || 0 })),
+      has_more: page.has_more, next_cursor: page.next_cursor,
     };
   },
 
+  get_commit_diff: async (args) => {
+    const offset = args.offset === undefined ? 0 : Number(args.offset);
+    const maxChars = args.max_chars === undefined ? 20000 : Number(args.max_chars);
+    if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(maxChars) || maxChars < 1 || maxChars > 100000) {
+      return { success: false, error: 'offset must be a nonnegative integer; max_chars must be an integer between 1 and 100000' };
+    }
+    const diff = await getClient().getCommitDiff(args.repo_slug as string, args.base as string, args.head as string, { path: args.path as string });
+    if (diff === null) return notFoundResponse('Diff', `${args.base}..${args.head}`);
+    const end = Math.min(offset + maxChars, diff.length);
+    return { diff: diff.slice(offset, end), offset, next_offset: end < diff.length ? end : null, truncated: end < diff.length, total_chars: diff.length };
+  },
+
+  get_merge_base: async (args) => {
+    const result = await getClient().getMergeBase(args.repo_slug as string, args.base as string, args.head as string);
+    return result ? { hash: result.hash, message: result.message, author: result.author?.raw, date: result.date, parents: result.parents?.map(p => truncateHash(p.hash)) }
+      : notFoundResponse('Common ancestor', `${args.base}..${args.head}`);
+  },
+
   get_commit_statuses: async (args) => {
     const client = getClient();
     const statuses = await client.getCommitStatuses(args.repo_slug as string, args.commit as string, {

package/src/tools/index.ts

@@ -3,9 +3,6 @@
  */
 
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import { getClient } from '../client.js';
-import { validateLimit, notFoundResponse, truncateHash, sanitizeSearchTerm } from '../utils.js';
-import { PRState, MergeStrategy, CommitStatusState } from '../types.js';
 
 // Import tool handlers from separate files
 import * as repositoryTools from './repositories.js';

package/src/tools/pipelines.ts

@@ -146,6 +146,29 @@ export const definitions: Tool[] = [
       required: ['repo_slug', 'variable_uuid'],
     },
   },
+  {
+    name: 'get_pipeline_config',
+    description: 'Get pipeline configuration for a repository (check if pipelines are enabled).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+      },
+      required: ['repo_slug'],
+    },
+  },
+  {
+    name: 'update_pipeline_config',
+    description: 'Update pipeline configuration for a repository (enable or disable pipelines).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        enabled: { type: 'boolean', description: 'Enable or disable pipelines' },
+      },
+      required: ['repo_slug', 'enabled'],
+    },
+  },
 ];
 
 export const handlers: Record<string, (args: Record<string, unknown>) => Promise<Record<string, unknown>>> = {
@@ -297,5 +320,23 @@ export const handlers: Record<string, (args: Record<string, unknown>) => Promise
     await client.deletePipelineVariable(args.repo_slug as string, args.variable_uuid as string);
     return {};
   },
+
+  get_pipeline_config: async (args) => {
+    const client = getClient();
+    const result = await client.getPipelineConfig(args.repo_slug as string);
+    return {
+      enabled: result.enabled,
+    };
+  },
+
+  update_pipeline_config: async (args) => {
+    const client = getClient();
+    const result = await client.updatePipelineConfig(args.repo_slug as string, {
+      enabled: args.enabled as boolean,
+    });
+    return {
+      enabled: result.enabled,
+    };
+  },
 };
 

package/src/tools/source.ts

@@ -20,6 +20,19 @@ export const definitions: Tool[] = [
       required: ['repo_slug', 'path'],
     },
   },
+  {
+    name: 'get_file_history',
+    description: 'List file-history paths and full commit hashes at a branch, tag or SHA. Use get_commit for author, message and date. Follow next_cursor for older changes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string' }, path: { type: 'string' }, ref: { type: 'string', default: 'main' },
+        limit: { type: 'integer', minimum: 1, maximum: 100, default: 20 },
+        cursor: { type: 'string', description: 'Opaque next_cursor; retains page size and filters' },
+      },
+      required: ['repo_slug', 'path'],
+    },
+  },
   {
     name: 'list_directory',
     description: 'List contents of a directory in a repository. Browse repository structure without cloning.',
@@ -54,6 +67,16 @@ export const handlers: Record<string, (args: Record<string, unknown>) => Promise
     };
   },
 
+  get_file_history: async (args) => {
+    const page = await getClient().getFileHistory(args.repo_slug as string, args.path as string, (args.ref as string) || 'main', {
+      limit: validateLimit((args.limit as number) ?? 20), cursor: args.cursor as string,
+    });
+    return {
+      history: page.values.map(entry => ({ path: entry.path, commit: { hash: entry.commit.hash } })),
+      has_more: page.has_more, next_cursor: page.next_cursor,
+    };
+  },
+
   list_directory: async (args) => {
     const client = getClient();
     const ref = (args.ref as string) || 'main';

package/src/tools/tags.ts

@@ -4,21 +4,29 @@
 
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import { getClient } from '../client.js';
-import { validateLimit, truncateHash } from '../utils.js';
+import { validateLimit, truncateHash, notFoundResponse } from '../utils.js';
 
 export const definitions: Tool[] = [
   {
     name: 'list_tags',
-    description: 'List tags in a repository.',
+    description: 'List a page of tags, optionally filtered with Bitbucket query syntax and sorted (name uses natural version order). Follow next_cursor for all tags.',
     inputSchema: {
       type: 'object',
       properties: {
         repo_slug: { type: 'string', description: 'Repository slug' },
-        limit: { type: 'number', description: 'Maximum results (default: 50)', default: 50 },
+        limit: { type: 'integer', minimum: 1, maximum: 100, default: 50 },
+        query: { type: 'string', description: 'Bitbucket filter, e.g. name ~ \"v2\" or target.hash = \"full-sha\"' },
+        sort: { type: 'string', description: 'Sort field, e.g. name, -name, -target.date', default: '-target.date' },
+        cursor: { type: 'string', description: 'Opaque next_cursor; retains page size and filters' },
       },
       required: ['repo_slug'],
     },
   },
+  {
+    name: 'get_tag',
+    description: 'Get a specific tag and its target commit without scanning tag pages.',
+    inputSchema: { type: 'object', properties: { repo_slug: { type: 'string' }, tag_name: { type: 'string' } }, required: ['repo_slug', 'tag_name'] },
+  },
   {
     name: 'create_tag',
     description: 'Create a new tag in a repository.',
@@ -50,20 +58,27 @@ export const definitions: Tool[] = [
 export const handlers: Record<string, (args: Record<string, unknown>) => Promise<Record<string, unknown>>> = {
   list_tags: async (args) => {
     const client = getClient();
-    const tags = await client.listTags(args.repo_slug as string, {
-      limit: validateLimit((args.limit as number) || 50),
+    const page = await client.listTagsPage(args.repo_slug as string, {
+      limit: validateLimit((args.limit as number) ?? 50),
+      query: args.query as string, sort: args.sort as string, cursor: args.cursor as string,
     });
     return {
-      tags: tags.map(t => ({
+      tags: page.values.map(t => ({
         name: t.name,
         target: truncateHash(t.target?.hash),
         message: t.message,
         date: t.target?.date,
         tagger: t.tagger?.raw,
       })),
+      has_more: page.has_more, next_cursor: page.next_cursor,
     };
   },
 
+  get_tag: async (args) => {
+    const tag = await getClient().getTag(args.repo_slug as string, args.tag_name as string);
+    return tag ? { name: tag.name, target: tag.target?.hash, message: tag.message, date: tag.date, tagger: tag.tagger?.raw } : notFoundResponse('Tag', args.tag_name as string);
+  },
+
   create_tag: async (args) => {
     const client = getClient();
     const result = await client.createTag(

package/src/types.ts

@@ -144,6 +144,15 @@ export interface BitbucketPipelineVariable {
   secured: boolean;
 }
 
+export interface BitbucketPipelineConfig {
+  enabled: boolean;
+  type?: string;
+  repository?: {
+    uuid?: string;
+    full_name?: string;
+  };
+}
+
 // ==================== PIPELINE TRIGGER OPTIONS ====================
 
 export interface PipelineTriggerVariable {