Bitbucket Server MCP

Instructions

Implementation Reference

• src/index.ts:1016-1121 (handler)

  The primary handler function that implements the 'search' tool. It constructs the search query based on options, calls the Bitbucket search API, processes the results, and returns formatted output.
  private async search(options: SearchOptions) { const { query, project, repository, type, limit = 25, start = 0 } = options; if (!query) { throw new McpError( ErrorCode.InvalidParams, 'Query parameter is required' ); } // Build the search query with filters let searchQuery = query; // Add project filter if specified if (project) { searchQuery = `${searchQuery} project:${project}`; } // Add repository filter if specified (requires project) if (repository && project) { searchQuery = `${searchQuery} repo:${project}/${repository}`; } // Add file extension filter if type is specified if (type === 'file') { // For file searches, wrap query in quotes for exact filename matching if (!query.includes('ext:') && !query.startsWith('"')) { searchQuery = `"${query}"`; if (project) searchQuery += ` project:${project}`; if (repository && project) searchQuery += ` repo:${project}/${repository}`; } } else if (type === 'code' && !query.includes('ext:')) { // For code searches, add common extension filters if not specified // This can be enhanced based on user needs } const requestBody = { query: searchQuery, entities: { code: { start, limit: Math.min(limit, 100) } } }; try { // Use full URL for search API since it uses different base path const searchUrl = `${this.config.baseUrl}/rest/search/latest/search`; const response = await axios.post(searchUrl, requestBody, { headers: this.config.token ? { Authorization: `Bearer ${this.config.token}`, 'Content-Type': 'application/json' } : { 'Content-Type': 'application/json' }, auth: this.config.username && this.config.password ? { username: this.config.username, password: this.config.password } : undefined, }); const codeResults = response.data.code || {}; const searchResults = { query: searchQuery, originalQuery: query, project: project || 'global', repository: repository || 'all', type: type || 'code', scope: response.data.scope || {}, total: codeResults.count || 0, showing: codeResults.values?.length || 0, isLastPage: codeResults.isLastPage || true, nextStart: codeResults.nextStart || null, results: codeResults.values?.map((result: any) => ({ repository: result.repository, file: result.file, hitCount: result.hitCount || 0, pathMatches: result.pathMatches || [], hitContexts: result.hitContexts || [] })) || [] }; return { content: [{ type: 'text', text: JSON.stringify(searchResults, null, 2) }] }; } catch (error) { if (axios.isAxiosError(error)) { if (error.response?.status === 404) { throw new McpError( ErrorCode.InternalError, 'Search API endpoint not available on this Bitbucket instance' ); } // Handle specific search API errors const errorData = error.response?.data; if (errorData?.errors && errorData.errors.length > 0) { const firstError = errorData.errors[0]; throw new McpError( ErrorCode.InvalidParams, `Search error: ${firstError.message || 'Invalid search query'}` ); } } throw error; } }
• src/index.ts:346-361 (schema)

  The input schema definition for the 'search' tool, specifying parameters like query, project, repository, type, limit, and start.
  inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query string to look for in code or file names.' }, project: { type: 'string', description: 'Bitbucket project key to limit search scope. If omitted, searches across accessible projects.' }, repository: { type: 'string', description: 'Repository slug to limit search to a specific repository within the project.' }, type: { type: 'string', enum: ['code', 'file'], description: 'Query optimization: "file" wraps query in quotes for exact filename matching, "code" uses default search behavior. Both search file contents and filenames.' }, limit: { type: 'number', description: 'Number of results to return (default: 25, max: 100)' }, start: { type: 'number', description: 'Start index for pagination (default: 0)' } }, required: ['query'] }
• src/index.ts:344-362 (registration)

  The registration of the 'search' tool in the MCP tools list, including name, description, and input schema.
  name: 'search', description: 'Search for code or files across repositories. Use this to find specific code patterns, file names, or content within projects and repositories. Searches both file contents and filenames. Supports filtering by project, repository, and query optimization.', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query string to look for in code or file names.' }, project: { type: 'string', description: 'Bitbucket project key to limit search scope. If omitted, searches across accessible projects.' }, repository: { type: 'string', description: 'Repository slug to limit search to a specific repository within the project.' }, type: { type: 'string', enum: ['code', 'file'], description: 'Query optimization: "file" wraps query in quotes for exact filename matching, "code" uses default search behavior. Both search file contents and filenames.' }, limit: { type: 'number', description: 'Number of results to return (default: 25, max: 100)' }, start: { type: 'number', description: 'Start index for pagination (default: 0)' } }, required: ['query'] } },
• src/index.ts:547-556 (registration)

  The dispatch/registration case in the CallToolRequestSchema handler that routes 'search' calls to the search method.
  case 'search': { return await this.search({ query: args.query as string, project: args.project as string, repository: args.repository as string, type: args.type as 'code' | 'file', limit: args.limit as number, start: args.start as number }); }
• src/index.ts:79-84 (helper)

  TypeScript interface defining the options for the search function.
  interface SearchOptions extends ListOptions { project?: string; repository?: string; query: string; type?: 'code' | 'file'; }