mcp-server-bitbucket 0.11.0

package/src/tools/commits.ts

@@ -0,0 +1,186 @@
+/**
+ * Commit tools for Bitbucket MCP Server
+ */
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { getClient } from '../client.js';
+import { validateLimit, notFoundResponse, truncateHash } from '../utils.js';
+import { CommitStatusState } from '../types.js';
+
+export const definitions: Tool[] = [
+  {
+    name: 'list_commits',
+    description: 'List commits in a repository.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        branch: { type: 'string', description: 'Filter by branch name (optional)' },
+        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 },
+      },
+      required: ['repo_slug'],
+    },
+  },
+  {
+    name: 'get_commit',
+    description: 'Get detailed information about a specific commit.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        commit: { type: 'string', description: 'Commit hash (full or short)' },
+      },
+      required: ['repo_slug', 'commit'],
+    },
+  },
+  {
+    name: 'compare_commits',
+    description: 'Compare two commits or branches and see files changed.',
+    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' },
+      },
+      required: ['repo_slug', 'base', 'head'],
+    },
+  },
+  {
+    name: 'get_commit_statuses',
+    description: 'Get build/CI statuses for a commit.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        commit: { type: 'string', description: 'Commit hash' },
+        limit: { type: 'number', description: 'Maximum results (default: 20)', default: 20 },
+      },
+      required: ['repo_slug', 'commit'],
+    },
+  },
+  {
+    name: 'create_commit_status',
+    description: 'Create a build status for a commit. Use this to report CI/CD status from external systems.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        commit: { type: 'string', description: 'Commit hash' },
+        state: { type: 'string', description: 'Status state: SUCCESSFUL, FAILED, INPROGRESS, STOPPED' },
+        key: { type: 'string', description: 'Unique identifier for this status' },
+        url: { type: 'string', description: 'URL to the build details (optional)' },
+        name: { type: 'string', description: 'Display name for the status (optional)' },
+        description: { type: 'string', description: 'Status description (optional)' },
+      },
+      required: ['repo_slug', 'commit', 'state', 'key'],
+    },
+  },
+];
+
+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, {
+      branch: args.branch as string,
+      path: args.path 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,
+      })),
+    };
+  },
+
+  get_commit: async (args) => {
+    const client = getClient();
+    const result = await client.getCommit(args.repo_slug as string, args.commit as string);
+    if (!result) {
+      return notFoundResponse('Commit', args.commit as string);
+    }
+    return {
+      hash: result.hash,
+      message: result.message,
+      author: result.author?.raw,
+      date: result.date,
+      parents: result.parents?.map(p => truncateHash(p.hash)),
+    };
+  },
+
+  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;
+    }>) || [];
+    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,
+      })),
+    };
+  },
+
+  get_commit_statuses: async (args) => {
+    const client = getClient();
+    const statuses = await client.getCommitStatuses(args.repo_slug as string, args.commit as string, {
+      limit: validateLimit((args.limit as number) || 20),
+    });
+    return {
+      commit: truncateHash(args.commit as string),
+      statuses: statuses.map(s => ({
+        key: s.key,
+        state: s.state,
+        name: s.name,
+        description: s.description,
+        url: s.url,
+        created: s.created_on,
+      })),
+    };
+  },
+
+  create_commit_status: async (args) => {
+    const state = (args.state as string).toUpperCase();
+    const validStates = Object.values(CommitStatusState);
+    if (!validStates.includes(state as CommitStatusState)) {
+      return {
+        success: false,
+        error: `Invalid state '${args.state}'. Must be one of: ${validStates.join(', ')}`,
+      };
+    }
+
+    const client = getClient();
+    const result = await client.createCommitStatus(args.repo_slug as string, args.commit as string, {
+      state,
+      key: args.key as string,
+      url: args.url as string,
+      name: args.name as string,
+      description: args.description as string,
+    });
+    return {
+      key: result.key,
+      state: result.state,
+      name: result.name,
+      url: result.url,
+    };
+  },
+};
+

package/src/tools/deployments.ts

@@ -0,0 +1,100 @@
+/**
+ * Deployment 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_environments',
+    description: 'List deployment environments for a repository.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        limit: { type: 'number', description: 'Maximum results (default: 20)', default: 20 },
+      },
+      required: ['repo_slug'],
+    },
+  },
+  {
+    name: 'get_environment',
+    description: 'Get details about a specific deployment environment.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        environment_uuid: { type: 'string', description: 'Environment UUID' },
+      },
+      required: ['repo_slug', 'environment_uuid'],
+    },
+  },
+  {
+    name: 'list_deployment_history',
+    description: 'Get deployment history for a specific environment.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        environment_uuid: { type: 'string', description: 'Environment UUID' },
+        limit: { type: 'number', description: 'Maximum results (default: 20)', default: 20 },
+      },
+      required: ['repo_slug', 'environment_uuid'],
+    },
+  },
+];
+
+export const handlers: Record<string, (args: Record<string, unknown>) => Promise<Record<string, unknown>>> = {
+  list_environments: async (args) => {
+    const client = getClient();
+    const environments = await client.listEnvironments(args.repo_slug as string, {
+      limit: validateLimit((args.limit as number) || 20),
+    });
+    return {
+      environments: environments.map(e => ({
+        uuid: e.uuid,
+        name: e.name,
+        type: e.environment_type?.name,
+        rank: e.rank,
+      })),
+    };
+  },
+
+  get_environment: async (args) => {
+    const client = getClient();
+    const result = await client.getEnvironment(args.repo_slug as string, args.environment_uuid as string);
+    if (!result) {
+      return notFoundResponse('Environment', args.environment_uuid as string);
+    }
+    return {
+      uuid: result.uuid,
+      name: result.name,
+      environment_type: result.environment_type?.name,
+      rank: result.rank,
+      restrictions: result.restrictions,
+      lock: result.lock,
+    };
+  },
+
+  list_deployment_history: async (args) => {
+    const client = getClient();
+    const deployments = await client.listDeploymentHistory(
+      args.repo_slug as string,
+      args.environment_uuid as string,
+      { limit: validateLimit((args.limit as number) || 20) }
+    );
+    return {
+      deployments: deployments.map(d => ({
+        uuid: d.uuid,
+        state: d.state?.name,
+        started: d.state?.started_on,
+        completed: d.state?.completed_on,
+        commit: d.release?.commit?.hash?.substring(0, 7),
+        pipeline_uuid: d.release?.pipeline?.uuid,
+      })),
+    };
+  },
+};
+

package/src/tools/index.ts

@@ -0,0 +1,112 @@
+/**
+ * Tool definitions and handlers for Bitbucket MCP Server
+ */
+
+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';
+import * as pullRequestTools from './pull-requests.js';
+import * as pipelineTools from './pipelines.js';
+import * as branchTools from './branches.js';
+import * as commitTools from './commits.js';
+import * as deploymentTools from './deployments.js';
+import * as webhookTools from './webhooks.js';
+import * as tagTools from './tags.js';
+import * as restrictionTools from './restrictions.js';
+import * as sourceTools from './source.js';
+import * as permissionTools from './permissions.js';
+import * as projectTools from './projects.js';
+
+/**
+ * All tool definitions for the MCP server
+ */
+export const toolDefinitions: Tool[] = [
+  // Repository tools
+  ...repositoryTools.definitions,
+  // Pull request tools
+  ...pullRequestTools.definitions,
+  // Pipeline tools
+  ...pipelineTools.definitions,
+  // Branch tools
+  ...branchTools.definitions,
+  // Commit tools
+  ...commitTools.definitions,
+  // Deployment tools
+  ...deploymentTools.definitions,
+  // Webhook tools
+  ...webhookTools.definitions,
+  // Tag tools
+  ...tagTools.definitions,
+  // Branch restriction tools
+  ...restrictionTools.definitions,
+  // Source browsing tools
+  ...sourceTools.definitions,
+  // Permission tools
+  ...permissionTools.definitions,
+  // Project tools
+  ...projectTools.definitions,
+];
+
+/**
+ * Handle tool calls by routing to the appropriate handler
+ */
+export async function handleToolCall(
+  name: string,
+  args: Record<string, unknown>
+): Promise<Record<string, unknown>> {
+  // Repository tools
+  if (name in repositoryTools.handlers) {
+    return await repositoryTools.handlers[name as keyof typeof repositoryTools.handlers](args);
+  }
+  // Pull request tools
+  if (name in pullRequestTools.handlers) {
+    return await pullRequestTools.handlers[name as keyof typeof pullRequestTools.handlers](args);
+  }
+  // Pipeline tools
+  if (name in pipelineTools.handlers) {
+    return await pipelineTools.handlers[name as keyof typeof pipelineTools.handlers](args);
+  }
+  // Branch tools
+  if (name in branchTools.handlers) {
+    return await branchTools.handlers[name as keyof typeof branchTools.handlers](args);
+  }
+  // Commit tools
+  if (name in commitTools.handlers) {
+    return await commitTools.handlers[name as keyof typeof commitTools.handlers](args);
+  }
+  // Deployment tools
+  if (name in deploymentTools.handlers) {
+    return await deploymentTools.handlers[name as keyof typeof deploymentTools.handlers](args);
+  }
+  // Webhook tools
+  if (name in webhookTools.handlers) {
+    return await webhookTools.handlers[name as keyof typeof webhookTools.handlers](args);
+  }
+  // Tag tools
+  if (name in tagTools.handlers) {
+    return await tagTools.handlers[name as keyof typeof tagTools.handlers](args);
+  }
+  // Branch restriction tools
+  if (name in restrictionTools.handlers) {
+    return await restrictionTools.handlers[name as keyof typeof restrictionTools.handlers](args);
+  }
+  // Source browsing tools
+  if (name in sourceTools.handlers) {
+    return await sourceTools.handlers[name as keyof typeof sourceTools.handlers](args);
+  }
+  // Permission tools
+  if (name in permissionTools.handlers) {
+    return await permissionTools.handlers[name as keyof typeof permissionTools.handlers](args);
+  }
+  // Project tools
+  if (name in projectTools.handlers) {
+    return await projectTools.handlers[name as keyof typeof projectTools.handlers](args);
+  }
+
+  throw new Error(`Unknown tool: ${name}`);
+}
+

package/src/tools/permissions.ts

@@ -0,0 +1,205 @@
+/**
+ * Permission 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[] = [
+  // User permissions
+  {
+    name: 'list_user_permissions',
+    description: 'List user permissions 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: 'get_user_permission',
+    description: "Get a specific user's permission for a repository.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        selected_user: { type: 'string', description: "User's account_id or UUID" },
+      },
+      required: ['repo_slug', 'selected_user'],
+    },
+  },
+  {
+    name: 'update_user_permission',
+    description: "Update or add a user's permission for a repository.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        selected_user: { type: 'string', description: "User's account_id or UUID" },
+        permission: { type: 'string', description: 'Permission level: "read", "write", or "admin"' },
+      },
+      required: ['repo_slug', 'selected_user', 'permission'],
+    },
+  },
+  {
+    name: 'delete_user_permission',
+    description: "Remove a user's explicit permission from a repository.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        selected_user: { type: 'string', description: "User's account_id or UUID" },
+      },
+      required: ['repo_slug', 'selected_user'],
+    },
+  },
+  // Group permissions
+  {
+    name: 'list_group_permissions',
+    description: 'List group permissions 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: 'get_group_permission',
+    description: "Get a specific group's permission for a repository.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        group_slug: { type: 'string', description: 'Group slug' },
+      },
+      required: ['repo_slug', 'group_slug'],
+    },
+  },
+  {
+    name: 'update_group_permission',
+    description: "Update or add a group's permission for a repository.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        group_slug: { type: 'string', description: 'Group slug' },
+        permission: { type: 'string', description: 'Permission level: "read", "write", or "admin"' },
+      },
+      required: ['repo_slug', 'group_slug', 'permission'],
+    },
+  },
+  {
+    name: 'delete_group_permission',
+    description: "Remove a group's explicit permission from a repository.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        repo_slug: { type: 'string', description: 'Repository slug' },
+        group_slug: { type: 'string', description: 'Group slug' },
+      },
+      required: ['repo_slug', 'group_slug'],
+    },
+  },
+];
+
+export const handlers: Record<string, (args: Record<string, unknown>) => Promise<Record<string, unknown>>> = {
+  list_user_permissions: async (args) => {
+    const client = getClient();
+    const permissions = await client.listUserPermissions(args.repo_slug as string, {
+      limit: validateLimit((args.limit as number) || 50),
+    });
+    return {
+      users: permissions.map(p => ({
+        user: p.user?.display_name,
+        account_id: p.user?.account_id,
+        permission: p.permission,
+      })),
+    };
+  },
+
+  get_user_permission: async (args) => {
+    const client = getClient();
+    const result = await client.getUserPermission(args.repo_slug as string, args.selected_user as string);
+    if (!result) {
+      return notFoundResponse('User permission', args.selected_user as string);
+    }
+    return {
+      user: result.user?.display_name,
+      account_id: result.user?.account_id,
+      permission: result.permission,
+    };
+  },
+
+  update_user_permission: async (args) => {
+    const client = getClient();
+    const result = await client.updateUserPermission(
+      args.repo_slug as string,
+      args.selected_user as string,
+      args.permission as string
+    );
+    return {
+      user: result.user?.display_name,
+      permission: result.permission,
+    };
+  },
+
+  delete_user_permission: async (args) => {
+    const client = getClient();
+    await client.deleteUserPermission(args.repo_slug as string, args.selected_user as string);
+    return {};
+  },
+
+  list_group_permissions: async (args) => {
+    const client = getClient();
+    const permissions = await client.listGroupPermissions(args.repo_slug as string, {
+      limit: validateLimit((args.limit as number) || 50),
+    });
+    return {
+      groups: permissions.map(p => ({
+        group: p.group?.name,
+        slug: p.group?.slug,
+        permission: p.permission,
+      })),
+    };
+  },
+
+  get_group_permission: async (args) => {
+    const client = getClient();
+    const result = await client.getGroupPermission(args.repo_slug as string, args.group_slug as string);
+    if (!result) {
+      return notFoundResponse('Group permission', args.group_slug as string);
+    }
+    return {
+      group: result.group?.name,
+      slug: result.group?.slug,
+      permission: result.permission,
+    };
+  },
+
+  update_group_permission: async (args) => {
+    const client = getClient();
+    const result = await client.updateGroupPermission(
+      args.repo_slug as string,
+      args.group_slug as string,
+      args.permission as string
+    );
+    return {
+      group: result.group?.name,
+      permission: result.permission,
+    };
+  },
+
+  delete_group_permission: async (args) => {
+    const client = getClient();
+    await client.deleteGroupPermission(args.repo_slug as string, args.group_slug as string);
+    return {};
+  },
+};
+