mcp-server-bitbucket 0.11.0

package/src/types.ts

@@ -0,0 +1,369 @@
+/**
+ * Type definitions for Bitbucket MCP Server
+ */
+
+// ==================== CONFIGURATION ====================
+
+export interface BitbucketConfig {
+  workspace: string;
+  email: string;
+  apiToken: string;
+  timeout?: number;
+  maxRetries?: number;
+}
+
+// ==================== API RESPONSE TYPES ====================
+
+export interface BitbucketUser {
+  display_name: string;
+  uuid: string;
+  account_id?: string;
+  links?: {
+    avatar?: { href: string };
+    html?: { href: string };
+  };
+}
+
+export interface BitbucketProject {
+  key: string;
+  name: string;
+  description?: string;
+  uuid?: string;
+  links?: {
+    html?: { href: string };
+  };
+}
+
+export interface CloneLink {
+  name: string;
+  href: string;
+}
+
+export interface BitbucketRepository {
+  uuid: string;
+  name: string;
+  full_name: string;
+  description?: string;
+  is_private: boolean;
+  project?: BitbucketProject;
+  mainbranch?: { name: string };
+  links?: {
+    clone?: CloneLink[];
+    html?: { href: string };
+  };
+  created_on?: string;
+  updated_on?: string;
+}
+
+export interface BitbucketBranch {
+  name: string;
+  target?: {
+    hash: string;
+    message?: string;
+    author?: {
+      raw?: string;
+      user?: BitbucketUser;
+    };
+    date?: string;
+  };
+}
+
+export interface BitbucketCommit {
+  hash: string;
+  message?: string;
+  author?: {
+    raw?: string;
+    user?: BitbucketUser;
+  };
+  date?: string;
+  parents?: { hash: string }[];
+}
+
+export interface BitbucketPullRequest {
+  id: number;
+  title: string;
+  description?: string;
+  state: 'OPEN' | 'MERGED' | 'DECLINED' | 'SUPERSEDED';
+  author?: BitbucketUser;
+  source?: {
+    branch?: { name: string };
+    commit?: { hash: string };
+  };
+  destination?: {
+    branch?: { name: string };
+    commit?: { hash: string };
+  };
+  reviewers?: BitbucketUser[];
+  participants?: {
+    user: BitbucketUser;
+    approved: boolean;
+    role: string;
+  }[];
+  close_source_branch?: boolean;
+  merge_commit?: { hash: string };
+  created_on?: string;
+  updated_on?: string;
+  links?: {
+    html?: { href: string };
+    diff?: { href: string };
+  };
+}
+
+export interface BitbucketPipeline {
+  uuid: string;
+  build_number?: number;
+  state?: {
+    name: string;
+    result?: { name: string };
+  };
+  target?: {
+    ref_name?: string;
+    ref_type?: string;
+  };
+  created_on?: string;
+  completed_on?: string;
+  duration_in_seconds?: number;
+}
+
+export interface BitbucketPipelineStep {
+  uuid: string;
+  name?: string;
+  state?: {
+    name: string;
+    result?: { name: string };
+  };
+  started_on?: string;
+  completed_on?: string;
+  duration_in_seconds?: number;
+}
+
+export interface BitbucketPipelineVariable {
+  uuid: string;
+  key: string;
+  value?: string;
+  secured: boolean;
+}
+
+// ==================== PIPELINE TRIGGER OPTIONS ====================
+
+export interface PipelineTriggerVariable {
+  key: string;
+  value: string;
+  secured?: boolean;
+}
+
+export interface TriggerPipelineOptions {
+  branch?: string;
+  commit?: string;
+  customPipeline?: string;
+  variables?: PipelineTriggerVariable[] | Record<string, string>;
+}
+
+export interface BitbucketEnvironment {
+  uuid: string;
+  name: string;
+  environment_type?: { name: string };
+  rank?: number;
+  restrictions?: unknown;
+  lock?: unknown;
+}
+
+export interface BitbucketDeployment {
+  uuid: string;
+  environment?: BitbucketEnvironment;
+  state?: {
+    name: string;
+    started_on?: string;
+    completed_on?: string;
+  };
+  release?: {
+    commit?: { hash: string };
+    pipeline?: { uuid: string };
+  };
+}
+
+export interface BitbucketWebhook {
+  uuid: string;
+  url: string;
+  description?: string;
+  events: string[];
+  active: boolean;
+  created_at?: string;
+}
+
+export interface BitbucketTag {
+  name: string;
+  message?: string;
+  target?: {
+    hash: string;
+    date?: string;
+  };
+  tagger?: {
+    raw?: string;
+    date?: string;
+  };
+}
+
+export interface BitbucketBranchRestriction {
+  id: number;
+  kind: string;
+  pattern?: string;
+  branch_match_kind?: string;
+  branch_type?: string;
+  value?: number;
+  users?: BitbucketUser[];
+  groups?: BitbucketGroup[];
+}
+
+export interface BitbucketGroup {
+  slug: string;
+  name: string;
+}
+
+export interface BitbucketComment {
+  id: number;
+  content?: {
+    raw?: string;
+    markup?: string;
+    html?: string;
+  };
+  user?: BitbucketUser;
+  created_on?: string;
+  updated_on?: string;
+  inline?: {
+    path?: string;
+    from?: number;
+    to?: number;
+  };
+}
+
+export interface BitbucketCommitStatus {
+  key: string;
+  state: 'SUCCESSFUL' | 'FAILED' | 'INPROGRESS' | 'STOPPED';
+  name?: string;
+  description?: string;
+  url?: string;
+  created_on?: string;
+  updated_on?: string;
+}
+
+export interface DirectoryEntry {
+  path: string;
+  type: 'commit_file' | 'commit_directory';
+  size?: number;
+}
+
+export interface UserPermission {
+  user: BitbucketUser;
+  permission: 'read' | 'write' | 'admin';
+}
+
+export interface GroupPermission {
+  group: BitbucketGroup;
+  permission: 'read' | 'write' | 'admin';
+}
+
+// ==================== PAGINATED RESPONSE ====================
+
+export interface PaginatedResponse<T> {
+  values: T[];
+  page?: number;
+  pagelen?: number;
+  size?: number;
+  next?: string;
+  previous?: string;
+}
+
+// ==================== TOOL RESPONSE TYPES ====================
+
+export interface RepositorySummary {
+  name: string;
+  full_name: string;
+  private: boolean;
+  project?: string;
+  description?: string;
+}
+
+export interface RepositoryDetail extends RepositorySummary {
+  clone_urls: {
+    https?: string;
+    ssh?: string;
+    html?: string;
+  };
+  main_branch?: string;
+  created?: string;
+  updated?: string;
+}
+
+export interface PullRequestSummary {
+  id: number;
+  title: string;
+  state: string;
+  author?: string;
+  source_branch?: string;
+  destination_branch?: string;
+  url?: string;
+}
+
+export interface PullRequestDetail extends PullRequestSummary {
+  description?: string;
+  reviewers?: string[];
+  approvals?: number;
+  created?: string;
+  updated?: string;
+}
+
+export interface PipelineSummary {
+  uuid: string;
+  build_number?: number;
+  state?: string;
+  result?: string;
+  branch?: string;
+  created?: string;
+}
+
+export interface PipelineDetail extends PipelineSummary {
+  duration?: number;
+  completed?: string;
+}
+
+export interface BranchSummary {
+  name: string;
+  commit?: string;
+  message?: string;
+  date?: string;
+}
+
+export interface CommitSummary {
+  hash: string;
+  message?: string;
+  author?: string;
+  date?: string;
+}
+
+export interface CommitDetail extends CommitSummary {
+  parents?: string[];
+}
+
+// ==================== ENUMS ====================
+
+export enum PRState {
+  OPEN = 'OPEN',
+  MERGED = 'MERGED',
+  DECLINED = 'DECLINED',
+  SUPERSEDED = 'SUPERSEDED',
+}
+
+export enum MergeStrategy {
+  MERGE_COMMIT = 'merge_commit',
+  SQUASH = 'squash',
+  FAST_FORWARD = 'fast_forward',
+}
+
+export enum CommitStatusState {
+  SUCCESSFUL = 'SUCCESSFUL',
+  FAILED = 'FAILED',
+  INPROGRESS = 'INPROGRESS',
+  STOPPED = 'STOPPED',
+}
+

package/src/utils.ts

@@ -0,0 +1,83 @@
+/**
+ * Utility functions for Bitbucket MCP Server
+ */
+
+/**
+ * Ensure a UUID has braces around it (Bitbucket API requirement)
+ */
+export function ensureUuidBraces(uuid: string): string {
+  if (!uuid) return uuid;
+  if (uuid.startsWith('{') && uuid.endsWith('}')) {
+    return uuid;
+  }
+  return `{${uuid}}`;
+}
+
+/**
+ * Remove braces from a UUID
+ */
+export function removeUuidBraces(uuid: string): string {
+  if (!uuid) return uuid;
+  return uuid.replace(/^{|}$/g, '');
+}
+
+/**
+ * Truncate a hash to short form (7 characters)
+ */
+export function truncateHash(hash: string | undefined | null): string {
+  if (!hash) return '';
+  return hash.substring(0, 7);
+}
+
+/**
+ * Sanitize a search term to prevent BQL injection
+ */
+export function sanitizeSearchTerm(term: string): string {
+  // Remove or escape special characters that could be used for BQL injection
+  return term.replace(/["\\]/g, '').trim();
+}
+
+/**
+ * Validate and clamp a limit parameter
+ */
+export function validateLimit(limit: number, maxLimit: number = 100): number {
+  if (limit < 1) return 1;
+  if (limit > maxLimit) return maxLimit;
+  return limit;
+}
+
+/**
+ * Create a "not found" response object
+ */
+export function notFoundResponse(type: string, identifier: string): Record<string, unknown> {
+  return {
+    error: `${type} '${identifier}' not found`,
+    found: false,
+  };
+}
+
+/**
+ * Format a timestamp string, truncating to date only if needed
+ */
+export function formatTimestamp(timestamp: string | undefined | null): string | null {
+  if (!timestamp) return null;
+  // Return ISO format truncated to seconds
+  return timestamp.split('.')[0];
+}
+
+/**
+ * Extract a URL from Bitbucket links structure
+ */
+export function extractUrl(links: Record<string, unknown> | undefined, key: string = 'html'): string {
+  if (!links) return '';
+  const link = links[key] as { href?: string } | undefined;
+  return link?.href || '';
+}
+
+/**
+ * Sleep for a specified duration (for rate limiting retries)
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}
+