Bitbucket MCP Server

Instructions

Implementation Reference

• src/handlers/file-handlers.ts:29-115 (handler)

  The core handler function that implements the list_directory_content tool. It validates arguments, queries the Bitbucket API (supporting both Cloud and Server), processes the directory listing, and returns a formatted JSON response with file/directory details.

  async handleListDirectoryContent(args: any) {
    if (!isListDirectoryContentArgs(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid arguments for list_directory_content'
      );
    }
  
    const { workspace, repository, path: dirPath = '', branch } = args;
  
    try {
      let apiPath: string;
      let params: any = {};
      let response: any;
  
      if (this.apiClient.getIsServer()) {
        // Bitbucket Server API
        apiPath = `/rest/api/1.0/projects/${workspace}/repos/${repository}/browse`;
        if (dirPath) {
          apiPath += `/${dirPath}`;
        }
        if (branch) {
          params.at = `refs/heads/${branch}`;
        }
        
        response = await this.apiClient.makeRequest<any>('get', apiPath, undefined, { params });
      } else {
        // Bitbucket Cloud API
        const branchOrDefault = branch || 'HEAD';
        apiPath = `/repositories/${workspace}/${repository}/src/${branchOrDefault}`;
        if (dirPath) {
          apiPath += `/${dirPath}`;
        }
        
        response = await this.apiClient.makeRequest<any>('get', apiPath);
      }
  
      // Format the response
      let contents: any[] = [];
      let actualBranch = branch;
  
      if (this.apiClient.getIsServer()) {
        // Bitbucket Server response
        const entries = response.children?.values || [];
        contents = entries.map((entry: BitbucketServerDirectoryEntry) => ({
          name: entry.path.name,
          type: entry.type === 'FILE' ? 'file' : 'directory',
          size: entry.size,
          path: dirPath ? `${dirPath}/${entry.path.name}` : entry.path.name
        }));
        
        // Get the actual branch from the response if available
        if (!branch && response.path?.components) {
          // Server returns default branch info in the response
          actualBranch = 'default';
        }
      } else {
        // Bitbucket Cloud response
        const entries = response.values || [];
        contents = entries.map((entry: BitbucketCloudDirectoryEntry) => ({
          name: entry.path.split('/').pop() || entry.path,
          type: entry.type === 'commit_file' ? 'file' : 'directory',
          size: entry.size,
          path: entry.path
        }));
        
        // Cloud returns the branch in the response
        actualBranch = branch || response.commit?.branch || 'main';
      }
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              path: dirPath || '/',
              branch: actualBranch,
              contents,
              total_items: contents.length
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      return this.apiClient.handleApiError(error, `listing directory '${dirPath}' in ${workspace}/${repository}`);
    }
  }

• src/tools/definitions.ts:466-491 (schema)

  Official tool definition including name, description, and input schema used for tool discovery and validation.

  {
    name: 'list_directory_content',
    description: 'List files and directories in a repository path',
    inputSchema: {
      type: 'object',
      properties: {
        workspace: {
          type: 'string',
          description: 'Bitbucket workspace/project key (e.g., "PROJ")',
        },
        repository: {
          type: 'string',
          description: 'Repository slug (e.g., "my-repo")',
        },
        path: {
          type: 'string',
          description: 'Directory path (optional, defaults to root, e.g., "src/components")',
        },
        branch: {
          type: 'string',
          description: 'Branch name (optional, defaults to default branch)',
        },
      },
      required: ['workspace', 'repository'],
    },
  },

• src/types/guards.ts:229-243 (schema)

  Type guard function used in the handler to validate and type-check input arguments for the list_directory_content tool.

  export const isListDirectoryContentArgs = (
    args: any
  ): args is {
    workspace: string;
    repository: string;
    path?: string;
    branch?: string;
  } =>
    typeof args === 'object' &&
    args !== null &&
    typeof args.workspace === 'string' &&
    typeof args.repository === 'string' &&
    (args.path === undefined || typeof args.path === 'string') &&
    (args.branch === undefined || typeof args.branch === 'string');

• src/index.ts:134-135 (registration)

  Registration and dispatch logic in the main MCP server that maps tool calls for 'list_directory_content' to the appropriate handler method.

  case 'list_directory_content':
    return this.fileHandlers.handleListDirectoryContent(request.params.arguments);