Bitbucket Server MCP

Instructions

Implementation Reference

• src/index.ts:1123-1162 (handler)

  The core handler function that implements the get_file_content tool logic. It fetches the content of a specific file from a Bitbucket repository using the /browse endpoint, supports pagination with limit and start parameters, validates inputs, and returns formatted JSON with file metadata and lines.

  private async getFileContent(options: FileContentOptions) {
    const { project, repository, filePath, branch, limit = 100, start = 0 } = options;
    
    if (!project || !repository || !filePath) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Project, repository, and filePath are required'
      );
    }
  
    const params: Record<string, string | number> = {
      limit: Math.min(limit, 1000),
      start
    };
  
    if (branch) {
      params.at = branch;
    }
  
    const response = await this.api.get(
      `/projects/${project}/repos/${repository}/browse/${filePath}`,
      { params }
    );
  
    const fileContent = {
      project,
      repository,
      filePath,
      branch: branch || 'default',
      isLastPage: response.data.isLastPage,
      size: response.data.size,
      showing: response.data.lines?.length || 0,
      startLine: start,
      lines: response.data.lines?.map((line: { text: string }) => line.text) || []
    };
  
    return {
      content: [{ type: 'text', text: JSON.stringify(fileContent, null, 2) }]
    };
  }

• src/index.ts:86-91 (schema)

  TypeScript interface defining the input parameters for the get_file_content tool, used for type checking the options passed to the handler.

  interface FileContentOptions extends ListOptions {
    project?: string;
    repository?: string;
    filePath: string;
    branch?: string;
  }

• src/index.ts:366-376 (schema)

  JSON schema defining the input parameters and validation rules for the get_file_content tool, provided in ListTools response.

  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 containing the file.' },
      filePath: { type: 'string', description: 'Path to the file in the repository (e.g., "src/main.py", "README.md", "config/settings.json").' },
      branch: { type: 'string', description: 'Branch or commit hash to read from (defaults to main/master branch if not specified).' },
      limit: { type: 'number', description: 'Maximum number of lines to return per request (default: 100, max: 1000).' },
      start: { type: 'number', description: 'Starting line number for pagination (0-based, default: 0).' }
    },
    required: ['repository', 'filePath']

• src/index.ts:363-378 (registration)

  Tool registration entry in the tools list returned by ListToolsRequestSchema handler, including name, description, and input schema.

  {
    name: 'get_file_content',
    description: 'Retrieve the content of a specific file from a Bitbucket repository with pagination support. Use this to read source code, configuration files, documentation, or any text-based files. For large files, use start parameter to paginate through content.',
    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 containing the file.' },
        filePath: { type: 'string', description: 'Path to the file in the repository (e.g., "src/main.py", "README.md", "config/settings.json").' },
        branch: { type: 'string', description: 'Branch or commit hash to read from (defaults to main/master branch if not specified).' },
        limit: { type: 'number', description: 'Maximum number of lines to return per request (default: 100, max: 1000).' },
        start: { type: 'number', description: 'Starting line number for pagination (0-based, default: 0).' }
      },
      required: ['repository', 'filePath']
    }
  },

• src/index.ts:558-567 (registration)

  Dispatch case in the CallToolRequestSchema handler's switch statement that routes calls to the getFileContent method, including parameter extraction and project fallback.

  case 'get_file_content': {
    return await this.getFileContent({
      project: getProject(args.project as string),
      repository: args.repository as string,
      filePath: args.filePath as string,
      branch: args.branch as string,
      limit: args.limit as number,
      start: args.start as number
    });
  }