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'];