Bitbucket MCP Server

Instructions

Implementation Reference

• src/handlers/search-handlers.ts:96-199 (handler)

  Main handler function executing the search_code tool: parses args, builds contextual search query, calls Bitbucket Server search API, formats and returns results.

  async handleSearchCode(args: any) {
    try {
      const { 
        workspace, 
        repository, 
        search_query, 
        search_context = 'any',
        file_pattern, 
        include_patterns = [],
        limit = 25, 
        start = 0 
      } = args;
  
      if (!workspace || !search_query) {
        throw new Error('Workspace and search_query are required');
      }
  
      // Only works for Bitbucket Server currently
      if (!this.apiClient.getIsServer()) {
        throw new Error('Code search is currently only supported for Bitbucket Server');
      }
  
      // Build the enhanced query string
      let query = `project:${workspace}`;
      if (repository) {
        query += ` repo:${repository}`;
      }
      if (file_pattern) {
        query += ` path:${file_pattern}`;
      }
      
      // Build smart search patterns
      const smartQuery = buildSmartQuery(search_query, search_context, include_patterns);
      query += ` ${smartQuery}`;
  
      // Prepare the request payload
      const payload: BitbucketServerSearchRequest = {
        query: query.trim(),
        entities: { 
          code: {
            start: start,
            limit: limit
          }
        }
      };
  
      // Make the API request (no query params needed, pagination is in payload)
      const response = await this.apiClient.makeRequest<BitbucketServerSearchResult>(
        'post',
        `/rest/search/latest/search?avatarSize=64`,
        payload
      );
  
      const searchResult = response;
  
      // Use simplified formatter for cleaner output
      const simplifiedOutput = formatCodeSearchOutput(searchResult);
  
      // Prepare pagination info
      const hasMore = searchResult.code?.isLastPage === false;
      const nextStart = hasMore ? (searchResult.code?.nextStart || start + limit) : undefined;
      const totalCount = searchResult.code?.count || 0;
  
      // Build a concise response with search context info
      let resultText = `Code search results for "${search_query}"`;
      if (search_context !== 'any') {
        resultText += ` (context: ${search_context})`;
      }
      resultText += ` in ${workspace}`;
      if (repository) {
        resultText += `/${repository}`;
      }
      
      // Show the actual search query used
      resultText += `\n\nSearch query: ${query.trim()}`;
      resultText += `\n\n${simplifiedOutput}`;
      
      if (totalCount > 0) {
        resultText += `\n\nTotal matches: ${totalCount}`;
        if (hasMore) {
          resultText += ` (showing ${start + 1}-${start + (searchResult.code?.values?.length || 0)})`;
        }
      }
  
      return {
        content: [{
          type: 'text',
          text: resultText
        }]
      };
    } catch (error: any) {
      const errorMessage = error.response?.data?.errors?.[0]?.message || error.message;
      return {
        content: [{
          type: 'text',
          text: JSON.stringify({
            error: `Failed to search code: ${errorMessage}`,
            details: error.response?.data
          }, null, 2)
        }],
        isError: true
      };
    }
  }

• src/tools/definitions.ts:618-661 (schema)

  Tool schema definition including input schema with properties, descriptions, enums, and required fields.

  {
    name: 'search_code',
    description: 'Search for code across Bitbucket repositories with enhanced context-aware search patterns (currently only supported for Bitbucket Server)',
    inputSchema: {
      type: 'object',
      properties: {
        workspace: {
          type: 'string',
          description: 'Bitbucket workspace/project key (e.g., "PROJ")',
        },
        repository: {
          type: 'string',
          description: 'Repository slug to search in (optional, searches all repos if not specified)',
        },
        search_query: {
          type: 'string',
          description: 'The search term or phrase to look for in code (e.g., "variable")',
        },
        search_context: {
          type: 'string',
          enum: ['assignment', 'declaration', 'usage', 'exact', 'any'],
          description: 'Context to search for: assignment (term=value), declaration (defining term), usage (calling/accessing term), exact (quoted match), or any (all patterns)',
        },
        file_pattern: {
          type: 'string',
          description: 'File path pattern to filter results (e.g., "*.java", "src/**/*.ts") (optional)',
        },
        include_patterns: {
          type: 'array',
          items: { type: 'string' },
          description: 'Additional custom search patterns to include (e.g., ["variable =", ".variable"]) (optional)',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of results to return (default: 25)',
        },
        start: {
          type: 'number',
          description: 'Start index for pagination (default: 0)',
        },
      },
      required: ['workspace', 'search_query'],
    },
  },

• src/index.ts:140-141 (registration)

  Registration of the search_code tool in the main request handler switch statement, delegating to SearchHandlers.handleSearchCode.

  case 'search_code':
    return this.searchHandlers.handleSearchCode(request.params.arguments);

• src/types/guards.ts:313-331 (schema)

  Type guard function for validating search_code tool arguments.

  export const isSearchCodeArgs = (
    args: any
  ): args is {
    workspace: string;
    repository?: string;
    search_query: string;
    file_pattern?: string;
    limit?: number;
    start?: number;
  } =>
    typeof args === 'object' &&
    args !== null &&
    typeof args.workspace === 'string' &&
    typeof args.search_query === 'string' &&
    (args.repository === undefined || typeof args.repository === 'string') &&
    (args.file_pattern === undefined || typeof args.file_pattern === 'string') &&
    (args.limit === undefined || typeof args.limit === 'number') &&
    (args.start === undefined || typeof args.start === 'number');

• src/handlers/search-handlers.ts:56-88 (helper)

  Helper function to build contextual search query patterns based on search term and context (e.g., assignment, declaration). Used by the handler.

  function buildSmartQuery(
    searchTerm: string, 
    searchContext: string = 'any',
    includePatterns: string[] = []
  ): string {
    const contextPatterns = buildContextualPatterns(searchTerm);
    
    let patterns: string[] = [];
    
    // Add patterns based on context
    if (searchContext in contextPatterns) {
      patterns = [...contextPatterns[searchContext as keyof SearchContext]];
    } else {
      patterns = [...contextPatterns.any];
    }
    
    // Add user-provided patterns
    if (includePatterns && includePatterns.length > 0) {
      patterns = [...patterns, ...includePatterns];
    }
    
    // Remove duplicates and join with OR
    const uniquePatterns = [...new Set(patterns)];
    
    // If only one pattern, return it without parentheses
    if (uniquePatterns.length === 1) {
      return uniquePatterns[0];
    }
    
    // Wrap each pattern in quotes for safety and join with OR
    const quotedPatterns = uniquePatterns.map(pattern => `"${pattern}"`);
    return `(${quotedPatterns.join(' OR ')})`;
  }