Atlassian Bitbucket Server MCP Gateway

This component functions as an MCP (Model Context Protocol) bridge, facilitating sophisticated control and interaction with the underlying Atlassian Bitbucket Server REST API, focusing heavily on pull request operations.

🚀 Core Enhancements

• 🔍 Comprehensive Code Search: Utilize the search utility for advanced querying across source code and file structures, supporting granular filtering by project or repository slug.
• 🗄️ File System Access: Tools like get_file_content and browse_repository enable inspection of file contents and directory listings.
• 🗣️ Discussion Aggregation: Efficiently retrieve and filter specific communication threads from Pull Requests using get_comments.
• 🗺️ Project Indexing: Map accessible Bitbucket environments via list_projects.
• 📂 Repository Mapping: Enumerate all available repositories across organizational scopes using list_repositories.
• ⚙️ Flexible Scoping: Configuration for the default project is now optional, allowing per-command overrides or reliance on the BITBUCKET_DEFAULT_PROJECT environment variable.
• 📚 Documentation Fidelity: Substantially updated documentation, incorporating usage tutorials and detailed setup guides.

Prerequisites

• Runtime environment must support Node.js version 16 or newer.

Deployment Instructions

Automated Setup (Smithery)

To provision this gateway automatically for use within Claude Desktop via Smithery:

bash npx -y @smithery/cli install @garc33/bitbucket-server-mcp-server --client claude

Local Compilation

bash npm install

Compilation Artifacts

bash npm run build

Utility Functions

The service exposes the subsequent functions for robust Bitbucket Server integration:

list_projects

Function: Gathers and presents metadata for all accessible organizational projects. Crucial for establishing correct context keys for subsequent API calls.

Scenarios: Identifying unknown project keys; auditing organizational structure; permission verification.

Arguments:

• limit: Maximum entries returned (default: 25; ceiling: 1000)
• start: Offset index for result set retrieval (default: 0)

list_repositories

Function: Enumerates repositories within a designated project or across the entire accessible scope, detailing essential metadata like clone URIs.

Scenarios: Locating repository identifiers; mapping codebases; bulk discovery.

Arguments:

• project: The key identifying the specific Bitbucket project (defaults to environment variable if omitted).
• limit: Result count ceiling (default: 25; ceiling: 1000)
• start: Pagination starting index (default: 0)

create_pull_request

Function: Initiates a new Pull Request workflow, bundling necessary source/target branch references and optional reviewer assignments.

Scenarios: Formal submission of feature branches; proposing integration of fixes; initiating review cycles.

Arguments:

• project: Project identifier (optional context lookup).
• repository (mandatory): Slug identifying the target repository.
• title (mandatory): Concise, descriptive summary for the PR.
• description: Detailed context, supporting Markdown formatting.
• sourceBranch (mandatory): The branch containing the proposed modifications.
• targetBranch (mandatory): The base branch receiving the changes.
• reviewers: Collection of usernames designated as reviewers.

get_pull_request

Function: Fetches the holistic state of a specific Pull Request, encompassing status, commit lists, and reviewer endorsements.

Scenarios: Verifying readiness for automated or manual merging; tracking current approval status.

Arguments:

• project: Project context (optional).
• repository (mandatory): Repository identifier.
• prId (mandatory): Unique identifier for the Pull Request.

merge_pull_request

Function: Executes the integration of an already approved Pull Request into its target branch, offering control over the merge methodology.

Scenarios: Finalizing code integration; deploying reviewed fixes; adhering to repository merge policies.

Arguments:

• project: Project context (optional).
• repository (mandatory): Repository identifier.
• prId (mandatory): Pull Request identifier.
• message: Custom commit message to record the merge event.
• strategy: Merge method selection:
• merge-commit (standard behavior): Preserves full commit history via a merge commit.
• squash: Condenses all PR commits into a single representative commit.
• fast-forward: Moves the branch pointer directly if history diverges minimally.

decline_pull_request

Function: Terminates the lifecycle of a Pull Request that is deemed unsuitable for integration, providing necessary context to the author.

Scenarios: Enforcing quality gates; redirecting development efforts; formal closure of irrelevant submissions.

Arguments:

• project: Project context (optional).
• repository (mandatory): Repository identifier.
• prId (mandatory): Pull Request identifier.
• message: Explanatory text detailing the grounds for rejection.

add_comment

Function: Inserts conversational input or formal feedback directly onto a Pull Request thread, supporting nested replies.

Scenarios: Delivering line-by-line code review critiques; posing implementation inquiries; documenting decision rationale.

Arguments:

• project: Project context (optional).
• repository (mandatory): Repository identifier.
• prId (mandatory): Pull Request identifier.
• text (mandatory): The body of the comment (Markdown syntax permitted).
• parentId: Identifier referencing a comment to which this is a direct reply.

get_diff

Function: Retrieves the complete patch set (diff) associated with a Pull Request, with specialized mechanisms for mitigating output volume from excessively large files.

Scenarios: Detailed code inspection; scoping impact assessment; verifying precise modifications.

Arguments:

• project: Project context (optional).
• repository (mandatory): Repository identifier.
• prId (mandatory): Pull Request identifier.
• contextLines: Number of surrounding lines to display near actual changes (default: 10).
• maxLinesPerFile: Hard limit on lines outputted per file (defaults to environment variable or unbounded if unset).

Large File Handling Logic: If a file chunk exceeds maxLinesPerFile: - Header metadata remains visible. - The first 60% of the allowed line budget is displayed. - A truncation summary, including file metrics, is inserted. - The final 40% of the allowed line budget is appended. - The user is informed how to retrieve the full content.

get_reviews

Function: Fetches the status and history of all reviews submitted against the target Pull Request.

Scenarios: Confirming necessary approvals have been secured; auditing reviewer participation.

get_activities

Function: Retrieves the comprehensive chronological sequence of events related to a PR, including commits, status updates, and all discussions.

Scenarios: Reconstructing the entire evolution of a PR; tracing status changes.

Arguments: - project: Project context (optional). - repository (mandatory): Repository identifier. - prId (mandatory): Pull Request identifier.

get_comments

Function: Isolates and returns only the conversational comments from the PR activity log, filtering out system events like commits or review status changes.

Scenarios: Focused analysis of team discussions; extracting direct feedback.

Arguments: - project: Project context (optional). - repository (mandatory): Repository identifier. - prId (mandatory): Pull Request identifier.

search

Function: Executes complex searches against repository contents and metadata via the specialized Bitbucket search endpoint. Constraint: Search operations are limited to the repository's default branch index.

Scenarios: Locating specific function definitions; finding configuration files by name; pattern matching across multiple projects.

Arguments: - query (mandatory): The search expression. - project: Scope the search to a single project key. - repository: Scope the search to a single repository slug. - type: Query enforcement flag: "file" (enforces exact filename matching) or "code" (default content search). - limit: Result pagination cap (default: 25; ceiling: 100). - start: Offset index (default: 0).

Syntax Examples: - "configuration.yaml" - Exact file name match. - error handling ext:java - Finding error logic in Java files. - service_v2 project:BETA - Searching within the BETA project context.

get_file_content

Function: Fetches the textual content of a specific artifact within a repository, supporting chunked retrieval for very large files.

Scenarios: Source code inspection; viewing documentation; retrieving configuration artifacts.

Arguments: - project: Project context (optional). - repository (mandatory): Repository identifier. - filePath (mandatory): The precise path to the file from the repository root. - branch: The specific SHA, tag, or branch name to query (defaults to primary branch). - limit: Maximum lines to fetch per sequential API call (default: 100; ceiling: 1000). - start: The initial line number to begin extraction (default: 0).

browse_repository

Function: Allows recursive traversal of a repository's directory structure, listing contained files and subdirectories.

Scenarios: Mapping out directory architecture; locating files prior to content retrieval.

Arguments: - project: Project context (optional). - repository (mandatory): Repository identifier. - path: The directory path to enumerate (defaults to the root /). - branch: The reference point for browsing (defaults to primary branch). - limit: Maximum number of entries (files/directories) to list per request (default: 50).

Illustrative Command Sequences

Environment Indexing

bash

Retrieve all accessible projects

list_projects

Check repositories within the 'INFRA' project scope

list_repositories --project "INFRA"

Artifact Investigation

bash

Search for all files named 'index.ts'

search --query "index.ts" --type "file" --limit 5

Examine the contents of a configuration file

get_file_content --repository "auth-service" --filePath "config/secrets.yaml" --branch "release/v2.1"

Traverse the components directory

browse_repository --repository "frontend-app" --path "src/ui/components"

Pull Request Lifecycle Management

bash

Submit code for review

create_pull_request --repository "core-api" --title "Refactor: Optimize DB calls" --sourceBranch "perf/db-opt" --targetBranch "staging" --reviewers ["user_a", "user_b"]

Inspect discussion history only

get_comments --repository "core-api" --prId 45

Finalize the merge using the fast-forward strategy

merge_pull_request --repository "core-api" --prId 45 --strategy "fast-forward" --message "Merged PR #45: Optimized database interaction."

Operational Dependencies

• @modelcontextprotocol/sdk: Core framework for MCP communication.
• axios: HTTP request abstraction layer.
• winston: Standardized logging utility for diagnostics.

Configuration Schema

The service requires configuration parameters established within the hosting environment's MCP settings.

{ "mcpServers": { "bitbucket": { "command": "node", "args": ["/path/to/bitbucket-server/build/index.js"], "env": { "BITBUCKET_URL": "https://your-bitbucket-instance.com", // Authentication (One Mandatory Path): // Path A: OAuth/Token "BITBUCKET_TOKEN": "your-secure-api-token", // Path B: Basic Auth "BITBUCKET_USERNAME": "api_user", "BITBUCKET_PASSWORD": "api_password", // Optional Context: "BITBUCKET_DEFAULT_PROJECT": "DEFAULT_ORG_KEY" } } } }

Environment Variables Reference

• BITBUCKET_URL (Required): The root endpoint for the Bitbucket Server installation.
• Authentication Block (One required):
• BITBUCKET_TOKEN: Preferred method using a Personal Access Token.
• BITBUCKET_USERNAME & BITBUCKET_PASSWORD: Credentials for Basic Authentication.
• BITBUCKET_DEFAULT_PROJECT (Optional): Sets the organizational scope if no explicit project parameter is passed to a tool.
• BITBUCKET_DIFF_MAX_LINES_PER_FILE (Optional): Controls output size by setting a ceiling on lines per file in diff retrievals. Overridden by get_diff parameters.
• BITBUCKET_READ_ONLY (Optional): If set to true, write-enabled utilities are disabled.

Read-Only Security Posture

This gateway supports a restricted operational mode to ensure data safety during auditing or informational retrieval tasks. Setting BITBUCKET_READ_ONLY=true enforces this constraint.

Permitted Operations (Read-Only Active): - list_projects, list_repositories - get_pull_request, get_diff, get_reviews, get_activities, get_comments - search, get_file_content, browse_repository

Prohibited Operations (Read-Only Active): - create_pull_request, merge_pull_request, decline_pull_request - add_comment

Behavioral Note: In read-only mode, any attempt to invoke a write operation will result in an immediate operational failure notification, ensuring configuration integrity.

Diagnostic Logging

The service utilizes Winston for comprehensive logging, persisting operational events and errors to the designated bitbucket.log file for monitoring and debugging.