Bitbucket Server MCP

Instructions

Implementation Reference

• src/index.ts:1164-1212 (handler)

  Core handler function that implements the browse_repository tool by calling Bitbucket's /browse API endpoint to list files and directories in a repository path, with support for branch specification and pagination.

  private async browseRepository(options: { project: string; repository: string; path?: string; branch?: string; limit?: number }) {
    const { project, repository, path = '', branch, limit = 50 } = options;
    
    if (!project || !repository) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Project and repository are required'
      );
    }
  
    const params: Record<string, string | number> = {
      limit
    };
  
    if (branch) {
      params.at = branch;
    }
  
    const browsePath = path ? `/${path}` : '';
    const response = await this.api.get(
      `/projects/${project}/repos/${repository}/browse${browsePath}`,
      { params }
    );
  
    const children = response.data.children || {};
    const browseResults = {
      project,
      repository,
      path: path || 'root',
      branch: branch || response.data.revision || 'default',
      isLastPage: children.isLastPage || false,
      size: children.size || 0,
      showing: children.values?.length || 0,
      items: children.values?.map((item: { 
        path: { name: string; toString: string }; 
        type: string; 
        size?: number 
      }) => ({
        name: item.path.name,
        path: item.path.toString,
        type: item.type,
        size: item.size
      })) || []
    };
  
    return {
      content: [{ type: 'text', text: JSON.stringify(browseResults, null, 2) }]
    };
  }

• src/index.ts:382-392 (schema)

  Input schema/JSON Schema definition for the browse_repository tool parameters, specifying types, descriptions, and required fields.

  inputSchema: {
    type: 'object',
    properties: {
      project: { type: 'string', description: 'Bitbucket project key. If omitted, uses BITBUCKET_DEFAULT_PROJECT environment variable.' },
      repository: { type: 'string', description: 'Repository slug to browse.' },
      path: { type: 'string', description: 'Directory path to browse (empty or "/" for root directory).' },
      branch: { type: 'string', description: 'Branch or commit hash to browse (defaults to main/master branch if not specified).' },
      limit: { type: 'number', description: 'Maximum number of items to return (default: 50).' }
    },
    required: ['repository']
  }

• src/index.ts:379-393 (registration)

  Tool registration in the ListToolsRequestSchema handler, defining name, description, and input schema for browse_repository.

  {
    name: 'browse_repository',
    description: 'Browse and list files and directories in a Bitbucket repository. Use this to explore repository structure, find files, or navigate directories.',
    inputSchema: {
      type: 'object',
      properties: {
        project: { type: 'string', description: 'Bitbucket project key. If omitted, uses BITBUCKET_DEFAULT_PROJECT environment variable.' },
        repository: { type: 'string', description: 'Repository slug to browse.' },
        path: { type: 'string', description: 'Directory path to browse (empty or "/" for root directory).' },
        branch: { type: 'string', description: 'Branch or commit hash to browse (defaults to main/master branch if not specified).' },
        limit: { type: 'number', description: 'Maximum number of items to return (default: 50).' }
      },
      required: ['repository']
    }
  }

• src/index.ts:569-577 (registration)

  Dispatch case in the central CallToolRequestSchema switch statement that routes calls to the browseRepository handler.

  case 'browse_repository': {
    return await this.browseRepository({
      project: getProject(args.project as string),
      repository: args.repository as string,
      path: args.path as string,
      branch: args.branch as string,
      limit: args.limit as number
    });
  }

• src/index.ts:162-162 (registration)

  Inclusion of browse_repository in the readOnlyTools list, allowing it in read-only mode.

  const readOnlyTools = ['list_projects', 'list_repositories', 'get_pull_request', 'get_diff', 'get_reviews', 'get_activities', 'get_comments', 'search', 'get_file_content', 'browse_repository'];