bitbucket-mcp copilot-instructions.md

Bitbucket MCP Server - AI Coding Instructions

Architecture Overview

This is a Model Context Protocol (MCP) server providing read-only access to Bitbucket API v2.0. The architecture follows a modular pattern with clear separation of concerns:

• TypeScript interfaces - Strict typing for all Bitbucket API responses
• Zod schemas - Input validation using z.object() with descriptive field documentation
• Tool registration - Each tool uses zodToJsonSchema() for automatic schema generation
• Handler registry pattern - Modular domain-based handlers (replaces switch-case)
• Authentication system - Supports API tokens
• Branch handling - Uses ?at=branch for listings and /src/{ref}/{file} for file content
• Read-only by design - All operations are safe GET requests

Enhanced Features (2025-2026 Update)

Modular Architecture

• src/index.ts - Main MCP server entry point
• src/tools.ts - Tool definitions and handler registry routing
• src/handlers/ - Domain-specific tool handlers (repository, pullrequest, diff, etc.)
• src/handlers/index.ts - Central handler registry export
• src/handlers/types.ts - Shared handler interfaces
• src/config.ts - Configuration management with Zod validation
• src/errors.ts - Custom error classes with helpful suggestions
• src/api.ts - API layer with retry logic and dual response types
• src/types.ts - Comprehensive TypeScript interfaces
• src/schemas.ts - Centralized Zod schemas and API constants

Authentication & Security

• API Token Priority: Uses BITBUCKET_API_TOKEN + BITBUCKET_EMAIL
• Runtime Protection: Blocks non-GET requests at the makeRequest() level
• Configuration Validation: Type-safe environment variable parsing with error suggestions

Handler Registry Pattern (2025-2026)

Replaced large switch statements with modular, domain-based handlers:

// src/handlers/index.ts - Central registry
export const toolHandlers: Record<string, ToolHandler> = {
  bb_get_repository: handleGetRepository,
  bb_list_repositories: handleListRepositories,
  bb_get_pull_requests: handleGetPullRequests,
  // ... 38 total tools organized by domain
};

// src/tools.ts - Clean lookup pattern
export async function handleToolCall(request: CallToolRequest) {
  const { name, arguments: args } = request.params;
  const handler = toolHandlers[name];
  return handler ? await handler(args) : errorResponse;
}