mcp-server-bitbucket 0.11.0

package/src/tools/repositories.ts

@@ -0,0 +1,208 @@
+/**
+ * Repository tools for Bitbucket MCP Server
+ */
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { getClient } from '../client.js';
+import { validateLimit, notFoundResponse, sanitizeSearchTerm } from '../utils.js';
+
+export const definitions: Tool[] = [
+  {
+    name: 'get_repository',
+    description: 'Get information about a Bitbucket repository.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: {
+          type: 'string',
+          description: 'Repository slug (e.g., "anzsic_classifier")',
+        },
+      },
+      required: ['repo_slug'],
+    },
+  },
+  {
+    name: 'create_repository',
+    description: 'Create a new Bitbucket repository.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: {
+          type: 'string',
+          description: 'Repository slug (lowercase, no spaces)',
+        },
+        project_key: {
+          type: 'string',
+          description: 'Project key to create repo under (optional)',
+        },
+        is_private: {
+          type: 'boolean',
+          description: 'Whether repository is private (default: true)',
+          default: true,
+        },
+        description: {
+          type: 'string',
+          description: 'Repository description',
+          default: '',
+        },
+      },
+      required: ['repo_slug'],
+    },
+  },
+  {
+    name: 'delete_repository',
+    description: 'Delete a Bitbucket repository. WARNING: This action is irreversible!',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: {
+          type: 'string',
+          description: 'Repository slug to delete',
+        },
+      },
+      required: ['repo_slug'],
+    },
+  },
+  {
+    name: 'list_repositories',
+    description: 'List and search repositories in the workspace.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_key: {
+          type: 'string',
+          description: 'Filter by project key (optional)',
+        },
+        search: {
+          type: 'string',
+          description: 'Simple search term for repository name (optional). Uses fuzzy matching.',
+        },
+        query: {
+          type: 'string',
+          description: 'Advanced Bitbucket query syntax (optional). Examples: name ~ "api", is_private = false',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of results (default: 50, max: 100)',
+          default: 50,
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'update_repository',
+    description: 'Update repository settings (project, visibility, description, name).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: {
+          type: 'string',
+          description: 'Repository slug',
+        },
+        project_key: {
+          type: 'string',
+          description: 'Move to different project (optional)',
+        },
+        is_private: {
+          type: 'boolean',
+          description: 'Change visibility (optional)',
+        },
+        description: {
+          type: 'string',
+          description: 'Update description (optional)',
+        },
+        name: {
+          type: 'string',
+          description: 'Rename repository (optional)',
+        },
+      },
+      required: ['repo_slug'],
+    },
+  },
+];
+
+export const handlers: Record<string, (args: Record<string, unknown>) => Promise<Record<string, unknown>>> = {
+  get_repository: async (args) => {
+    const client = getClient();
+    const result = await client.getRepository(args.repo_slug as string);
+    if (!result) {
+      return notFoundResponse('Repository', args.repo_slug as string);
+    }
+    return {
+      name: result.name,
+      full_name: result.full_name,
+      private: result.is_private,
+      project: result.project?.key,
+      description: result.description || '',
+      main_branch: result.mainbranch?.name,
+      clone_urls: client.extractCloneUrls(result),
+      created: result.created_on,
+      updated: result.updated_on,
+    };
+  },
+
+  create_repository: async (args) => {
+    const client = getClient();
+    const result = await client.createRepository(args.repo_slug as string, {
+      projectKey: args.project_key as string | undefined,
+      isPrivate: args.is_private as boolean | undefined,
+      description: args.description as string | undefined,
+    });
+    return {
+      name: result.name,
+      full_name: result.full_name,
+      clone_urls: client.extractCloneUrls(result),
+    };
+  },
+
+  delete_repository: async (args) => {
+    const client = getClient();
+    await client.deleteRepository(args.repo_slug as string);
+    return {};
+  },
+
+  list_repositories: async (args) => {
+    const client = getClient();
+    let effectiveQuery = args.query as string | undefined;
+    
+    if (args.search && !args.query) {
+      const safeSearch = sanitizeSearchTerm(args.search as string);
+      effectiveQuery = `name ~ "${safeSearch}"`;
+    }
+
+    const repos = await client.listRepositories({
+      projectKey: args.project_key as string | undefined,
+      query: effectiveQuery,
+      limit: validateLimit((args.limit as number) || 50),
+    });
+
+    return {
+      repositories: repos.map(r => ({
+        name: r.name,
+        full_name: r.full_name,
+        private: r.is_private,
+        project: r.project?.key,
+        description: r.description || '',
+      })),
+    };
+  },
+
+  update_repository: async (args) => {
+    const client = getClient();
+    const result = await client.updateRepository(args.repo_slug as string, {
+      projectKey: args.project_key as string | undefined,
+      isPrivate: args.is_private as boolean | undefined,
+      description: args.description as string | undefined,
+      name: args.name as string | undefined,
+    });
+    return {
+      name: result.name,
+      full_name: result.full_name,
+      project: result.project?.key,
+      private: result.is_private,
+      description: result.description || '',
+    };
+  },
+};
+

package/src/tools/restrictions.ts

@@ -0,0 +1,94 @@
+/**
+ * Branch Restriction tools for Bitbucket MCP Server
+ */
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { getClient } from '../client.js';
+import { validateLimit } from '../utils.js';
+
+export const definitions: Tool[] = [
+  {
+    name: 'list_branch_restrictions',
+    description: 'List branch restrictions (protection rules) in a repository.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        limit: { type: 'number', description: 'Maximum results (default: 50)', default: 50 },
+      },
+      required: ['repo_slug'],
+    },
+  },
+  {
+    name: 'create_branch_restriction',
+    description: 'Create a branch restriction (protection rule).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        kind: {
+          type: 'string',
+          description: 'Type of restriction: push, force, delete, restrict_merges, require_passing_builds_to_merge, require_approvals_to_merge, etc.',
+        },
+        pattern: { type: 'string', description: 'Branch pattern (e.g., "main", "release/*"). Required for glob match.', default: '' },
+        branch_match_kind: { type: 'string', description: 'How to match branches: "glob" or "branching_model"', default: 'glob' },
+        branch_type: { type: 'string', description: 'Branch type when using branching_model: development, production, feature, etc.', default: '' },
+        value: { type: 'number', description: 'Numeric value (e.g., number of required approvals)', default: 0 },
+      },
+      required: ['repo_slug', 'kind'],
+    },
+  },
+  {
+    name: 'delete_branch_restriction',
+    description: 'Delete a branch restriction.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        restriction_id: { type: 'number', description: 'Restriction ID' },
+      },
+      required: ['repo_slug', 'restriction_id'],
+    },
+  },
+];
+
+export const handlers: Record<string, (args: Record<string, unknown>) => Promise<Record<string, unknown>>> = {
+  list_branch_restrictions: async (args) => {
+    const client = getClient();
+    const restrictions = await client.listBranchRestrictions(args.repo_slug as string, {
+      limit: validateLimit((args.limit as number) || 50),
+    });
+    return {
+      restrictions: restrictions.map(r => ({
+        id: r.id,
+        kind: r.kind,
+        pattern: r.pattern,
+        branch_match_kind: r.branch_match_kind,
+        branch_type: r.branch_type,
+        value: r.value,
+      })),
+    };
+  },
+
+  create_branch_restriction: async (args) => {
+    const client = getClient();
+    const result = await client.createBranchRestriction(args.repo_slug as string, {
+      kind: args.kind as string,
+      pattern: args.pattern as string,
+      branchMatchKind: args.branch_match_kind as string || 'glob',
+      branchType: args.branch_type as string || undefined,
+      value: args.value as number || undefined,
+    });
+    return {
+      id: result.id,
+      kind: result.kind,
+    };
+  },
+
+  delete_branch_restriction: async (args) => {
+    const client = getClient();
+    await client.deleteBranchRestriction(args.repo_slug as string, args.restriction_id as number);
+    return {};
+  },
+};
+

package/src/tools/source.ts

@@ -0,0 +1,78 @@
+/**
+ * Source (File Browsing) tools for Bitbucket MCP Server
+ */
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { getClient } from '../client.js';
+import { validateLimit } from '../utils.js';
+
+export const definitions: Tool[] = [
+  {
+    name: 'get_file_content',
+    description: 'Get the content of a file from a repository. Read file contents without cloning.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        path: { type: 'string', description: 'File path (e.g., "src/main.py", "README.md")' },
+        ref: { type: 'string', description: 'Branch, tag, or commit hash (default: "main")', default: 'main' },
+      },
+      required: ['repo_slug', 'path'],
+    },
+  },
+  {
+    name: 'list_directory',
+    description: 'List contents of a directory in a repository. Browse repository structure without cloning.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        path: { type: 'string', description: 'Directory path (empty string for root)', default: '' },
+        ref: { type: 'string', description: 'Branch, tag, or commit hash (default: "main")', default: 'main' },
+        limit: { type: 'number', description: 'Maximum entries (default: 100)', default: 100 },
+      },
+      required: ['repo_slug'],
+    },
+  },
+];
+
+export const handlers: Record<string, (args: Record<string, unknown>) => Promise<Record<string, unknown>>> = {
+  get_file_content: async (args) => {
+    const client = getClient();
+    const ref = (args.ref as string) || 'main';
+    const content = await client.getFileContent(args.repo_slug as string, args.path as string, ref);
+    
+    if (content === null) {
+      return { error: `File '${args.path}' not found at ref '${ref}'` };
+    }
+
+    return {
+      path: args.path,
+      ref,
+      content,
+      size: content.length,
+    };
+  },
+
+  list_directory: async (args) => {
+    const client = getClient();
+    const ref = (args.ref as string) || 'main';
+    const path = (args.path as string) || '';
+    
+    const entries = await client.listDirectory(args.repo_slug as string, path, {
+      ref,
+      limit: validateLimit((args.limit as number) || 100),
+    });
+
+    return {
+      path: path || '/',
+      ref,
+      entries: entries.map(e => ({
+        path: e.path,
+        type: e.type === 'commit_directory' ? 'directory' : 'file',
+        size: e.size,
+      })),
+    };
+  },
+};
+

package/src/tools/tags.ts

@@ -0,0 +1,88 @@
+/**
+ * Tag tools for Bitbucket MCP Server
+ */
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { getClient } from '../client.js';
+import { validateLimit, truncateHash } from '../utils.js';
+
+export const definitions: Tool[] = [
+  {
+    name: 'list_tags',
+    description: 'List tags in a repository.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        limit: { type: 'number', description: 'Maximum results (default: 50)', default: 50 },
+      },
+      required: ['repo_slug'],
+    },
+  },
+  {
+    name: 'create_tag',
+    description: 'Create a new tag in a repository.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        name: { type: 'string', description: 'Tag name (e.g., "v1.0.0")' },
+        target: { type: 'string', description: 'Commit hash or branch name to tag' },
+        message: { type: 'string', description: 'Optional tag message (for annotated tags)', default: '' },
+      },
+      required: ['repo_slug', 'name', 'target'],
+    },
+  },
+  {
+    name: 'delete_tag',
+    description: 'Delete a tag from a repository.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        tag_name: { type: 'string', description: 'Tag name to delete' },
+      },
+      required: ['repo_slug', 'tag_name'],
+    },
+  },
+];
+
+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),
+    });
+    return {
+      tags: tags.map(t => ({
+        name: t.name,
+        target: truncateHash(t.target?.hash),
+        message: t.message,
+        date: t.target?.date,
+        tagger: t.tagger?.raw,
+      })),
+    };
+  },
+
+  create_tag: async (args) => {
+    const client = getClient();
+    const result = await client.createTag(
+      args.repo_slug as string,
+      args.name as string,
+      args.target as string,
+      args.message as string || undefined
+    );
+    return {
+      name: result.name,
+      target: truncateHash(result.target?.hash),
+      message: result.message || '',
+    };
+  },
+
+  delete_tag: async (args) => {
+    const client = getClient();
+    await client.deleteTag(args.repo_slug as string, args.tag_name as string);
+    return {};
+  },
+};
+

package/src/tools/webhooks.ts

@@ -0,0 +1,121 @@
+/**
+ * Webhook tools for Bitbucket MCP Server
+ */
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { getClient } from '../client.js';
+import { validateLimit, notFoundResponse } from '../utils.js';
+
+export const definitions: Tool[] = [
+  {
+    name: 'list_webhooks',
+    description: 'List webhooks configured for a repository.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        limit: { type: 'number', description: 'Maximum results (default: 50)', default: 50 },
+      },
+      required: ['repo_slug'],
+    },
+  },
+  {
+    name: 'create_webhook',
+    description: 'Create a webhook for a repository.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        url: { type: 'string', description: 'URL to call when events occur' },
+        events: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'List of events (e.g., repo:push, pullrequest:created, pullrequest:merged)',
+        },
+        description: { type: 'string', description: 'Webhook description (optional)', default: '' },
+        active: { type: 'boolean', description: 'Whether webhook is active (default: true)', default: true },
+      },
+      required: ['repo_slug', 'url', 'events'],
+    },
+  },
+  {
+    name: 'get_webhook',
+    description: 'Get details about a specific webhook.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        webhook_uuid: { type: 'string', description: 'Webhook UUID' },
+      },
+      required: ['repo_slug', 'webhook_uuid'],
+    },
+  },
+  {
+    name: 'delete_webhook',
+    description: 'Delete a webhook.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        webhook_uuid: { type: 'string', description: 'Webhook UUID' },
+      },
+      required: ['repo_slug', 'webhook_uuid'],
+    },
+  },
+];
+
+export const handlers: Record<string, (args: Record<string, unknown>) => Promise<Record<string, unknown>>> = {
+  list_webhooks: async (args) => {
+    const client = getClient();
+    const webhooks = await client.listWebhooks(args.repo_slug as string, {
+      limit: validateLimit((args.limit as number) || 50),
+    });
+    return {
+      webhooks: webhooks.map(w => ({
+        uuid: w.uuid,
+        url: w.url,
+        description: w.description,
+        events: w.events,
+        active: w.active,
+      })),
+    };
+  },
+
+  create_webhook: async (args) => {
+    const client = getClient();
+    const result = await client.createWebhook(args.repo_slug as string, {
+      url: args.url as string,
+      events: args.events as string[],
+      description: args.description as string,
+      active: args.active as boolean ?? true,
+    });
+    return {
+      uuid: result.uuid,
+      url: result.url,
+      events: result.events,
+      active: result.active,
+    };
+  },
+
+  get_webhook: async (args) => {
+    const client = getClient();
+    const result = await client.getWebhook(args.repo_slug as string, args.webhook_uuid as string);
+    if (!result) {
+      return notFoundResponse('Webhook', args.webhook_uuid as string);
+    }
+    return {
+      uuid: result.uuid,
+      url: result.url,
+      description: result.description,
+      events: result.events,
+      active: result.active,
+    };
+  },
+
+  delete_webhook: async (args) => {
+    const client = getClient();
+    await client.deleteWebhook(args.repo_slug as string, args.webhook_uuid as string);
+    return {};
+  },
+};
+