@atercates/bitbucket-mcp 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,296 @@
+/**
+ * Represents a hyperlink in Bitbucket API responses
+ */
+export interface BitbucketLink {
+    href: string;
+    name?: string;
+}
+/**
+ * Represents a Bitbucket account (user or team)
+ */
+export interface BitbucketAccount {
+    uuid: string;
+    display_name: string;
+    account_id: string;
+    nickname?: string;
+    type: "user" | "team";
+    links: Record<string, BitbucketLink[]>;
+}
+/**
+ * Represents a Bitbucket workspace
+ */
+export interface BitbucketWorkspace {
+    uuid: string;
+    name: string;
+    slug: string;
+    type: "workspace";
+    links: Record<string, BitbucketLink[]>;
+}
+/**
+ * Represents a Bitbucket project
+ */
+export interface BitbucketProject {
+    uuid: string;
+    key: string;
+    name: string;
+    description?: string;
+    is_private: boolean;
+    type: "project";
+    links: Record<string, BitbucketLink[]>;
+}
+/**
+ * Represents a Bitbucket branch reference
+ */
+export interface BitbucketBranch {
+    name: string;
+    type: "branch";
+}
+/**
+ * Represents a Bitbucket repository
+ */
+export interface BitbucketRepository {
+    uuid: string;
+    name: string;
+    full_name: string;
+    description: string;
+    is_private: boolean;
+    created_on: string;
+    updated_on: string;
+    size: number;
+    language: string;
+    has_issues: boolean;
+    has_wiki: boolean;
+    fork_policy: string;
+    owner: BitbucketAccount;
+    workspace: BitbucketWorkspace;
+    project: BitbucketProject;
+    mainbranch?: BitbucketBranch;
+    website?: string;
+    scm: string;
+    links: Record<string, BitbucketLink[]>;
+}
+/**
+ * Represents a branch reference in a pull request
+ */
+export interface BitbucketBranchReference {
+    branch: {
+        name: string;
+    };
+    commit: {
+        hash: string;
+    };
+    repository: BitbucketRepository;
+}
+/**
+ * Represents a participant in a pull request
+ */
+export interface BitbucketParticipant {
+    user: BitbucketAccount;
+    role: "PARTICIPANT" | "REVIEWER";
+    approved: boolean;
+    state?: "approved" | "changes_requested" | null;
+    participated_on: string;
+}
+/**
+ * Represents a Bitbucket pull request
+ */
+export interface BitbucketPullRequest {
+    id: number;
+    title: string;
+    description: string;
+    state: "OPEN" | "MERGED" | "DECLINED" | "SUPERSEDED";
+    author: BitbucketAccount;
+    source: BitbucketBranchReference;
+    destination: BitbucketBranchReference;
+    created_on: string;
+    updated_on: string;
+    closed_on?: string;
+    comment_count: number;
+    task_count: number;
+    close_source_branch: boolean;
+    reviewers: BitbucketAccount[];
+    participants: BitbucketParticipant[];
+    links: Record<string, BitbucketLink[]>;
+    summary?: {
+        raw: string;
+        markup: string;
+        html: string;
+    };
+}
+/**
+ * Represents inline comment positioning information
+ */
+export interface InlineCommentInline {
+    path: string;
+    from?: number;
+    to?: number;
+}
+/**
+ * Represents a Bitbucket branching model
+ */
+export interface BitbucketBranchingModel {
+    type: "branching_model";
+    development: {
+        name: string;
+        branch?: BitbucketBranch;
+        use_mainbranch: boolean;
+    };
+    production?: {
+        name: string;
+        branch?: BitbucketBranch;
+        use_mainbranch: boolean;
+    };
+    branch_types: Array<{
+        kind: string;
+        prefix: string;
+    }>;
+    links: Record<string, BitbucketLink[]>;
+}
+/**
+ * Represents a Bitbucket branching model settings
+ */
+export interface BitbucketBranchingModelSettings {
+    type: "branching_model_settings";
+    development: {
+        name: string;
+        use_mainbranch: boolean;
+        is_valid?: boolean;
+    };
+    production: {
+        name: string;
+        use_mainbranch: boolean;
+        enabled: boolean;
+        is_valid?: boolean;
+    };
+    branch_types: Array<{
+        kind: string;
+        prefix: string;
+        enabled: boolean;
+    }>;
+    links: Record<string, BitbucketLink[]>;
+}
+/**
+ * Represents a Bitbucket project branching model
+ */
+export interface BitbucketProjectBranchingModel {
+    type: "project_branching_model";
+    development: {
+        name: string;
+        use_mainbranch: boolean;
+    };
+    production?: {
+        name: string;
+        use_mainbranch: boolean;
+    };
+    branch_types: Array<{
+        kind: string;
+        prefix: string;
+    }>;
+    links: Record<string, BitbucketLink[]>;
+}
+/**
+ * Represents the configuration for a Bitbucket client
+ */
+export interface BitbucketConfig {
+    baseUrl: string;
+    token?: string;
+    username?: string;
+    password?: string;
+    defaultWorkspace?: string;
+    allowDangerousCommands?: boolean;
+}
+/**
+ * Represents a pipeline target
+ */
+export interface BitbucketPipelineTarget {
+    type: string;
+    ref_type?: string;
+    ref_name?: string;
+    commit?: {
+        type: "commit";
+        hash: string;
+    };
+    selector?: {
+        type: string;
+        pattern: string;
+    };
+}
+/**
+ * Represents a pipeline trigger
+ */
+export interface BitbucketPipelineTrigger {
+    type: string;
+    name?: string;
+}
+/**
+ * Represents a pipeline state
+ */
+export interface BitbucketPipelineState {
+    type: string;
+    name: "PENDING" | "IN_PROGRESS" | "SUCCESSFUL" | "FAILED" | "ERROR" | "STOPPED";
+    result?: {
+        type: string;
+        name: "SUCCESSFUL" | "FAILED" | "ERROR" | "STOPPED";
+    };
+}
+/**
+ * Represents a pipeline variable
+ */
+export interface BitbucketPipelineVariable {
+    type: "pipeline_variable";
+    key: string;
+    value: string;
+    secured?: boolean;
+}
+/**
+ * Represents a pipeline configuration source
+ */
+export interface BitbucketPipelineConfigurationSource {
+    source: string;
+    uri: string;
+}
+/**
+ * Represents a pipeline command
+ */
+export interface BitbucketPipelineCommand {
+    name?: string;
+    command: string;
+}
+/**
+ * Represents a pipeline step
+ */
+export interface BitbucketPipelineStep {
+    uuid: string;
+    type: "pipeline_step";
+    name?: string;
+    started_on?: string;
+    completed_on?: string;
+    state: BitbucketPipelineState;
+    image?: {
+        name: string;
+        username?: string;
+        password?: string;
+        email?: string;
+    };
+    setup_commands?: BitbucketPipelineCommand[];
+    script_commands?: BitbucketPipelineCommand[];
+}
+/**
+ * Represents a Bitbucket pipeline
+ */
+export interface BitbucketPipeline {
+    uuid: string;
+    type: "pipeline";
+    build_number: number;
+    creator: BitbucketAccount;
+    repository: BitbucketRepository;
+    target: BitbucketPipelineTarget;
+    trigger: BitbucketPipelineTrigger;
+    state: BitbucketPipelineState;
+    created_on: string;
+    completed_on?: string;
+    build_seconds_used?: number;
+    variables?: BitbucketPipelineVariable[];
+    configuration_sources?: BitbucketPipelineConfigurationSource[];
+    links: Record<string, BitbucketLink[]>;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+// =========== TYPE DEFINITIONS ===========
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,2CAA2C"}

package/dist/utils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Wraps data in MCP tool response format with JSON content
+ */
+export declare function jsonResponse(data: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/**
+ * Wraps text in MCP tool response format
+ */
+export declare function textResponse(text: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};

package/dist/utils.js

@@ -0,0 +1,17 @@
+/**
+ * Wraps data in MCP tool response format with JSON content
+ */
+export function jsonResponse(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+/**
+ * Wraps text in MCP tool response format
+ */
+export function textResponse(text) {
+    return {
+        content: [{ type: "text", text }],
+    };
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,IAAa;IACxC,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;KAC1E,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,CAAC;KAC3C,CAAC;AACJ,CAAC"}

package/docs/README.md

@@ -0,0 +1,216 @@
+# Bitbucket MCP Server Documentation
+
+Welcome to the Bitbucket MCP (Model Context Protocol) Server documentation. This server provides AI assistants and other MCP clients with programmatic access to Bitbucket Cloud and Server APIs.
+
+## Quick Links
+
+- **[Getting Started Guide](guides/GETTING_STARTED.md)** - Installation and configuration
+- **[Tools Reference](TOOLS.md)** - Complete list of all available tools
+- **[Architecture](architecture/ARCHITECTURE.md)** - Technical design and structure
+- **[Project Structure](guides/PROJECT_STRUCTURE.md)** - Explanation of files and directories
+- **[Environment Variables](guides/ENVIRONMENT_VARIABLES.md)** - Configuration reference
+- **[NPM Deployment](guides/NPM_DEPLOYMENT.md)** - Publishing to NPM
+- **[GitHub Actions Setup](guides/GITHUB_ACTIONS_SETUP.md)** - Automatic CI/CD configuration
+
+## What is Bitbucket MCP?
+
+The Bitbucket MCP server is a standardized interface that allows AI assistants (like Claude, integrated in Cursor) to interact with Bitbucket repositories programmatically. It enables:
+
+- **Repository Management**: List, create, and manage repositories
+- **Pull Request Operations**: Create, approve, merge, and manage PRs
+- **Code Review**: Add comments, tasks, and request changes on PRs
+- **Branch Management**: Create, list, and delete branches and tags
+- **Pipeline Control**: Trigger and monitor CI/CD pipelines
+- **Source Code Access**: Read file content from repositories
+- **Commit History**: Query commits and changes
+
+## Key Features
+
+✨ **Modular Architecture** - Organized by feature domain for easy maintenance and extension
+
+🔒 **Secure** - Token-based authentication with fine-grained permission control
+
+📝 **Well-Documented** - Comprehensive API reference and architecture guide
+
+🧪 **Tested** - Full unit test suite with 100% tool coverage
+
+⚡ **Fast** - Efficient pagination and minimal dependencies
+
+🛡️ **Safe** - Dangerous operations (deletes) require explicit enablement
+
+## Quick Start
+
+1. **Install:**
+   ```bash
+   npm install -g bitbucket-mcp
+   # or
+   npx -y bitbucket-mcp@latest
+   ```
+
+2. **Configure:**
+   ```bash
+   export BITBUCKET_TOKEN="your_app_password"
+   export BITBUCKET_WORKSPACE="my-workspace"
+   ```
+
+3. **Run:**
+   ```bash
+   bitbucket-mcp
+   ```
+
+4. **Connect:** Configure your MCP client (Claude, Cursor) to use this server
+
+For detailed setup instructions, see [Getting Started Guide](guides/GETTING_STARTED.md).
+
+## Core Concepts
+
+### MCP (Model Context Protocol)
+
+MCP is a standardized protocol that allows AI models to interact with external tools and data sources. This server implements the MCP specification to expose Bitbucket operations as "tools" that AI assistants can call.
+
+### Handler Modules
+
+The server is organized into feature-based handler modules:
+
+| Module | Purpose |
+|--------|---------|
+| `repositories` | Repository operations |
+| `pull-requests` | PR creation, approval, merging |
+| `pr-comments` | PR comments and discussions |
+| `pr-tasks` | PR tasks (TODO items) |
+| `pr-content` | PR diffs and commits |
+| `refs` | Branches and tags |
+| `commits` | Commit history and details |
+| `pipelines` | CI/CD pipeline management |
+| `source` | Source code file access |
+| `users` | User and workspace information |
+| `branching-model` | Branching strategy configuration |
+
+### Authentication
+
+The server supports two authentication methods:
+
+1. **Token Authentication** (Recommended)
+   ```bash
+   BITBUCKET_TOKEN=your_app_password
+   ```
+
+2. **Basic Authentication**
+   ```bash
+   BITBUCKET_USERNAME=your_email@example.com
+   BITBUCKET_PASSWORD=your_app_password
+   ```
+
+### Workspace Resolution
+
+Workspaces can be specified in multiple ways:
+
+1. **Default workspace** (via `BITBUCKET_WORKSPACE` env var)
+2. **Per-call** (via `workspace` parameter in tool arguments)
+3. **Auto-detection** (from API responses)
+
+## Available Tools
+
+The server exposes 59 tools across 11 categories. See [TOOLS.md](TOOLS.md) for complete reference.
+
+**Quick Examples:**
+
+- `listRepositories` - List repos in a workspace
+- `createPullRequest` - Create a new PR
+- `approvePullRequest` - Approve a PR
+- `mergePullRequest` - Merge a PR
+- `listBranches` - List repository branches
+- `runPipeline` - Trigger a pipeline run
+- `getFileContent` - Read file from repository
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────┐
+│     MCP Client (Cursor, Claude, etc)    │
+└──────────────┬──────────────────────────┘
+               │
+               ▼
+┌──────────────────────────────────────────┐
+│   Bitbucket MCP Server                  │
+├──────────────────────────────────────────┤
+│  • Tool Registration                     │
+│  • Request Routing                       │
+│  • Authentication                        │
+└──────────────┬───────────────────────────┘
+               │
+        ┌──────▼──────────────────────────┐
+        │   Handler Modules               │
+        │   (repositories, PRs, etc)      │
+        └──────┬───────────────────────────┘
+               │
+    ┌──────────┴──────────────┐
+    ▼                         ▼
+┌──────────────────┐  ┌──────────────────┐
+│ BitbucketClient  │  │    Logger        │
+│ (API Wrapper)    │  │ (File-based)     │
+└────────┬─────────┘  └──────────────────┘
+         │
+         ▼
+    ┌─────────────────┐
+    │ Bitbucket API   │
+    │ (Cloud/Server)  │
+    └─────────────────┘
+```
+
+For more details, see [Architecture](architecture/ARCHITECTURE.md).
+
+## Environment Variables
+
+### Required
+
+- `BITBUCKET_TOKEN` - App password for authentication (recommended)
+- OR `BITBUCKET_USERNAME` + `BITBUCKET_PASSWORD` - Basic auth credentials
+
+### Optional
+
+- `BITBUCKET_URL` - API base URL (default: `https://api.bitbucket.org/2.0`)
+- `BITBUCKET_WORKSPACE` - Default workspace name
+- `BITBUCKET_ALLOW_DANGEROUS` - Enable delete operations (default: false)
+- `BITBUCKET_LOG_DISABLE` - Disable file logging (default: false)
+- `BITBUCKET_LOG_FILE` - Custom log file path
+- `BITBUCKET_LOG_DIR` - Custom log directory
+- `BITBUCKET_LOG_PER_CWD` - Create per-directory logs (default: false)
+
+## Getting Help
+
+- 📖 Check [TOOLS.md](TOOLS.md) for tool-specific documentation
+- 🏗️ Review [Architecture](architecture/ARCHITECTURE.md) for technical details
+- 📁 See [Project Structure](guides/PROJECT_STRUCTURE.md) for file organization
+- 🚀 See [Getting Started](guides/GETTING_STARTED.md) for setup help
+- ⚙️ Check [Environment Variables](guides/ENVIRONMENT_VARIABLES.md) for config options
+- 📦 See [NPM Deployment](guides/NPM_DEPLOYMENT.md) for publishing
+- ⚡ See [GitHub Actions Setup](guides/GITHUB_ACTIONS_SETUP.md) for CI/CD automation
+- 🐛 Check logs in your platform's log directory (see Getting Started guide)
+
+## Contributing
+
+Contributions are welcome! To add new features:
+
+1. Create a new handler module in `src/handlers/`
+2. Implement the `HandlerModule` interface
+3. Register it in `src/handlers/index.ts`
+4. Add tests in `__tests__/handlers/`
+5. Submit a pull request
+
+For detailed contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT License - See LICENSE file for details.
+
+## Support
+
+- Report issues on GitHub
+- Check existing issues for solutions
+- Review logs for error details (enable with `BITBUCKET_LOG_DISABLE=false`)
+
+---
+
+**Last Updated:** 2024
+**Version:** 5.0.0+