Bitbucket Cloud MCP Server

Instructions

Implementation Reference

• src/tools/index.ts:674-689 (registration)

  Registration of the 'list_issues' tool in the toolDefinitions array for MCP, including name, description, and JSON schema for inputs.

  {
    name: 'list_issues',
    description: 'List issues in a repository with optional filtering.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        workspace: { type: 'string', description: 'The workspace slug' },
        repo_slug: { type: 'string', description: 'The repository slug' },
        q: { type: 'string', description: 'Query string for filtering' },
        sort: { type: 'string', description: 'Sort field' },
        page: { type: 'number', description: 'Page number' },
        pagelen: { type: 'number', description: 'Results per page' },
      },
      required: ['workspace', 'repo_slug'],
    },
  },

• src/tools/index.ts:199-206 (schema)

  Zod schema definition for validating inputs to the list_issues tool.

  list_issues: z.object({
    workspace: z.string().describe('The workspace slug'),
    repo_slug: z.string().describe('The repository slug'),
    q: z.string().optional().describe('Query string for filtering'),
    sort: z.string().optional().describe('Sort field'),
    page: z.number().optional().describe('Page number'),
    pagelen: z.number().optional().describe('Results per page'),
  }),

• src/tools/index.ts:1026-1029 (handler)

  ToolHandler switch case that handles the 'list_issues' tool call: parses arguments with Zod schema and delegates to IssuesAPI.list method.

  case 'list_issues': {
    const params = toolSchemas.list_issues.parse(args);
    return this.issues.list(params);
  }

• src/api/issues.ts:15-21 (handler)

  Core implementation of listing issues: makes a GET request to Bitbucket API endpoint /repositories/{workspace}/{repo_slug}/issues with query parameters.

  async list(params: ListIssuesParams): Promise<PaginatedResponse<BitbucketIssue>> {
    const { workspace, repo_slug, ...queryParams } = params;
    return this.client.get<PaginatedResponse<BitbucketIssue>>(
      `/repositories/${workspace}/${repo_slug}/issues`,
      queryParams as Record<string, string | number | undefined>
    );
  }

• src/types/index.ts:330-337 (schema)

  TypeScript interface defining the parameters for listing issues, used in IssuesAPI.list.

  export interface ListIssuesParams {
    workspace: string;
    repo_slug: string;
    q?: string;
    sort?: string;
    page?: number;
    pagelen?: number;
  }