bitbucket-server-mcp 1.4.0__tar.gz

bitbucket_server_mcp-1.4.0/.dockerignore

@@ -0,0 +1,12 @@
+.git/
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.env
+tests/

bitbucket_server_mcp-1.4.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,67 @@
+name: Bug Report
+description: Report a bug in Bitbucket Server MCP
+labels: ["bug"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the bug
+      description: A clear and concise description of what the bug is.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Steps to reproduce the behaviour.
+      placeholder: |
+        1. Configure MCP with '...'
+        2. Call tool '...' with arguments '...'
+        3. See error
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behaviour
+      description: What you expected to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behaviour
+      description: What actually happened. Include error messages if applicable.
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: "Output of: pip show bitbucket-server-mcp | grep Version"
+      placeholder: "1.3.1"
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      description: "Output of: python --version"
+      placeholder: "3.12.0"
+    validations:
+      required: true
+  - type: input
+    id: mcp-host
+    attributes:
+      label: MCP host
+      description: Which MCP client are you using?
+      placeholder: "Claude Code, GitHub Copilot, etc."
+    validations:
+      required: false
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Any other context, logs, or screenshots.
+    validations:
+      required: false

bitbucket_server_mcp-1.4.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,33 @@
+name: Feature Request
+description: Suggest a new tool or enhancement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or use case
+      description: What problem does this solve? What are you trying to do?
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: Describe the tool or feature you'd like to see.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any alternative solutions or workarounds you've considered.
+    validations:
+      required: false
+  - type: input
+    id: api-endpoint
+    attributes:
+      label: Bitbucket API endpoint
+      description: If this maps to a specific Bitbucket REST API endpoint, link it here.
+      placeholder: "https://developer.atlassian.com/server/bitbucket/rest/..."
+    validations:
+      required: false

bitbucket_server_mcp-1.4.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,21 @@
+## What
+
+Brief summary of the change.
+
+## Why
+
+Motivation or issue being addressed.
+
+## How
+
+High-level approach (especially for non-obvious changes).
+
+## Checklist
+
+- [ ] Tests pass (`uv run pytest -v`)
+- [ ] Lint passes (`uv run ruff check src/ tests/`)
+- [ ] New tools have tests (happy path, validation, error handling)
+- [ ] All new tool arguments are validated in `validation.py`
+- [ ] README.md tool count and inventory updated (if tools added)
+- [ ] No deletion operations added
+- [ ] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) format

bitbucket_server_mcp-1.4.0/.github/workflows/ci.yml

@@ -0,0 +1,89 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Lint with ruff
+        run: uv run ruff check src/ tests/
+
+      - name: Format check with ruff
+        run: uv run ruff format --check src/ tests/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Run tests
+        run: uv run pytest -v --tb=short
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: uv pip install --system build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Verify package
+        run: |
+          uv pip install --system twine
+          twine check dist/*
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7

bitbucket_server_mcp-1.4.0/.github/workflows/release.yml

@@ -0,0 +1,101 @@
+name: Release
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+    branches: [master]
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    # Only run when CI succeeds and not on release commits (avoid infinite loops)
+    if: >-
+      github.event.workflow_run.conclusion == 'success' &&
+      !startsWith(github.event.workflow_run.head_commit.message, 'chore(release):')
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/bitbucket-server-mcp
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install python-semantic-release build
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      # PSR determines version from conventional commits:
+      #   feat: -> minor bump (1.x.0)
+      #   fix:/perf: -> patch bump (1.0.x)
+      #   BREAKING CHANGE: -> major bump (x.0.0)
+      - name: Python Semantic Release — Determine version
+        id: semver
+        run: |
+          OUTPUT=$(semantic-release version --print 2>/dev/null) || true
+          echo "new_version=$OUTPUT" >> "$GITHUB_OUTPUT"
+          if [ -z "$OUTPUT" ]; then
+            echo "released=false" >> "$GITHUB_OUTPUT"
+            echo "No new release needed."
+          else
+            echo "released=true" >> "$GITHUB_OUTPUT"
+            echo "New version: $OUTPUT"
+          fi
+
+      - name: Python Semantic Release — Apply version & tag
+        if: steps.semver.outputs.released == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          semantic-release version --no-push
+
+      - name: Build package
+        if: steps.semver.outputs.released == 'true'
+        run: python -m build
+
+      - name: Verify package
+        if: steps.semver.outputs.released == 'true'
+        run: |
+          pip install twine
+          twine check dist/*
+
+      - name: Publish to PyPI
+        if: steps.semver.outputs.released == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # Uses trusted publishing (OIDC) — no API token needed
+          # Configure at: https://pypi.org/manage/project/bitbucket-server-mcp/settings/publishing/
+          print-hash: true
+
+      - name: Create GitHub Release
+        if: steps.semver.outputs.released == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          semantic-release publish --no-upload
+
+      - name: Summary
+        if: steps.semver.outputs.released == 'true'
+        run: |
+          echo "## Release v${{ steps.semver.outputs.new_version }}" >> $GITHUB_STEP_SUMMARY
+          echo "- Published to PyPI" >> $GITHUB_STEP_SUMMARY
+          echo "- GitHub Release created" >> $GITHUB_STEP_SUMMARY
+          echo "- Install: \`pip install bitbucket-server-mcp==${{ steps.semver.outputs.new_version }}\`" >> $GITHUB_STEP_SUMMARY

bitbucket_server_mcp-1.4.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg
+.env

bitbucket_server_mcp-1.4.0/AGENTS.md

@@ -0,0 +1,130 @@
+# AGENTS.md — Bitbucket Server MCP
+
+## Project Overview
+
+MCP server for Atlassian Bitbucket Server / Data Center (Enterprise) REST API. Provides 54 tools for managing projects, repositories, branches, files, commits, pull requests, and code search. No deletion operations by design.
+
+## Tech Stack
+
+- **Language**: Python 3.10+
+- **Framework**: MCP SDK (`mcp[cli]`) with `FastMCP`
+- **HTTP Client**: `httpx` (async)
+- **Build**: Hatchling
+- **Package Manager**: `uv`
+- **Linting**: `ruff`
+- **Tests**: `pytest` + `pytest-asyncio` + `respx` (HTTP mocking)
+- **CI/CD**: GitHub Actions (CI + semantic release to PyPI)
+- **Versioning**: [Python Semantic Release](https://python-semantic-release.readthedocs.io/) (automated)
+
+## Project Structure
+
+```
+src/bitbucket_mcp/
+  server.py          # Entry point — env var config, wires client + tools, starts MCP stdio
+  client.py          # BitbucketClient — all HTTP goes through here (auth, error handling, pagination)
+  validation.py      # Input validation — every tool argument is validated/clamped here
+  tools/
+    projects.py      # list_projects, get_project
+    repositories.py  # list_repositories, get_repository, create_repository
+    branches.py      # list_branches, get_default_branch, create_branch, list_tags
+    files.py         # browse_files, get_file_content, list_files
+    commits.py       # list_commits, get_commit, get_commit_diff, get_commit_changes
+    pull_requests.py # All PR tools (CRUD, diff, commits, activities, comments, tasks, approvals, watch)
+    dashboard.py     # list_dashboard_pull_requests, list_inbox_pull_requests
+    search.py        # search_code, find_file
+    users.py         # find_user
+    attachments.py   # get_attachment, get_attachment_metadata, save_attachment_metadata
+tests/
+  conftest.py        # Shared fixtures (mcp, client, respx mocks)
+  test_*.py          # One test file per tool module + client + validation
+```
+
+## Architecture Patterns
+
+- **Tool registration**: Each `tools/*.py` module exposes `register_tools(mcp, client)`. Tools are closures over the shared `mcp` and `client` objects — no global state.
+- **HTTP abstraction**: Tool modules never construct `httpx` requests directly. All HTTP goes through `BitbucketClient` methods (`get`, `post`, `put`, `get_raw`, `search`, `get_paged`).
+- **Validation layer**: All untrusted input from MCP tool arguments passes through `validation.py` before reaching the HTTP client. Validators raise `ValidationError`; clamp functions silently coerce out-of-range values.
+- **Error handling**: Tools catch `BitbucketAPIError` and `ValidationError`, returning error strings to the MCP caller. 5xx errors are sanitised to avoid leaking server internals.
+
+## Commands
+
+```bash
+uv sync                              # Install dependencies
+uv run bitbucket-server-mcp           # Run the server (requires BITBUCKET_URL + BITBUCKET_TOKEN)
+uv run pytest -v                     # Run all tests
+uv run pytest tests/test_projects.py -v  # Run a single test file
+uv run ruff check src/ tests/        # Lint
+uv run ruff format src/ tests/       # Format
+```
+
+## Rules
+
+### Versioning and Changelog (AUTOMATED)
+
+Versioning is handled automatically by [Python Semantic Release (PSR)](https://python-semantic-release.readthedocs.io/). **Do NOT manually bump versions or edit CHANGELOG.md.**
+
+PSR analyses conventional commit messages on `master` and automatically:
+- Bumps version in `pyproject.toml` and `src/bitbucket_mcp/__init__.py`
+- Updates `CHANGELOG.md`
+- Creates a git tag and GitHub Release
+- Publishes to PyPI
+
+Version bumps are determined by commit type:
+- `feat:` → **minor** (e.g., 1.3.0 → 1.4.0)
+- `fix:` / `perf:` → **patch** (e.g., 1.3.0 → 1.3.1)
+- `BREAKING CHANGE:` or `!` → **major** (e.g., 1.3.0 → 2.0.0)
+- `docs:`, `chore:`, `refactor:`, `test:`, `ci:` → no release
+
+### Commit Messages
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) format:
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+Types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `ci`, `perf`, `style`, `build`
+
+Examples:
+- `feat: add delete_branch tool`
+- `fix(client): handle 429 rate limit responses`
+- `feat!: require Python 3.14+ (BREAKING CHANGE)`
+
+### Adding a New Tool
+
+1. Create or edit the appropriate `src/bitbucket_mcp/tools/<domain>.py`
+2. Add input validation to `validation.py` if new parameter types are introduced
+3. Register the tool via `register_tools()` using the `@mcp.tool()` decorator
+4. If adding a new tool module, wire it up in `server.py`
+5. Add tests in `tests/test_<domain>.py` using `respx` to mock HTTP
+6. Update the tool count and table in `README.md`
+
+### Adding a New Bitbucket API Endpoint
+
+1. Add the HTTP method to `BitbucketClient` in `client.py` if a new verb/path pattern is needed
+2. Follow the existing pattern: tool modules call `client.get()` / `client.post()` etc., never `httpx` directly
+
+### Code Style
+
+- All modules use `from __future__ import annotations`
+- Tool functions return `str` (JSON-serialised or error message)
+- Validation happens at the tool level before calling the client
+- Keep tools self-contained — each tool function should be readable on its own
+
+### Testing
+
+- Every tool module has a corresponding `tests/test_<module>.py`
+- Use `respx` to mock HTTP responses — never hit a real Bitbucket Server in tests
+- Shared fixtures live in `tests/conftest.py`
+- Run `uv run pytest -v` before pushing; all tests must pass
+
+### Security
+
+- No deletion operations — this is a deliberate design constraint
+- Path traversal protection in `validate_path()`
+- 5xx responses are sanitised before returning to MCP callers
+- Never log or expose the `BITBUCKET_TOKEN`

bitbucket_server_mcp-1.4.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.3.1] - 2026-03-20
+
+### Added
+
+- MIT license file
+- `license` field in `pyproject.toml`
+
+### Fixed
+
+- Corrected `test_http_allowed` to `test_http_rejected` to match HTTPS-only enforcement
+
+## [1.3.0] - 2026-03-20
+
+### Changed
+
+- Enforce HTTPS-only in `validate_base_url()` — `http://` URLs are now rejected at startup
+- Updated `SECURITY.md` to reflect HTTPS enforcement and resolved HTTP risk
+
+## [1.2.0] - 2026-03-20
+
+### Added
+
+- Docker support for running the MCP server in a container
+- `Dockerfile` and `.dockerignore` for building the server image
+- Docker build/run instructions in README
+- Docker-based integration examples for Claude Code and GitHub Copilot
+
+### Changed
+
+- Removed manual running section from README in favor of Docker-based instructions
+
+## [1.1.1] - 2025-06-04
+
+### Added
+
+- `SECURITY.md` — comprehensive security analysis covering threat model, input validation, injection prevention, and residual risks
+- `CONTRIBUTING.md` — contributor guide with PR guidelines, code style, testing patterns, and security rules
+
+## [1.0.0] - 2025-06-03
+
+### Added
+
+- MCP server for Atlassian Bitbucket Server / Data Center (Enterprise) REST API
+- 28 tools covering projects, repositories, branches, files, commits, pull requests, and code search
+- HTTP access token authentication via `BITBUCKET_URL` and `BITBUCKET_TOKEN` environment variables
+- Pagination support (`start`/`limit`) on all list operations
+- Input validation for required parameters
+- **Projects**: `list_projects`, `get_project`
+- **Repositories**: `list_repositories`, `get_repository`, `create_repository`
+- **Branches & Tags**: `list_branches`, `get_default_branch`, `create_branch`, `list_tags`
+- **Files & Content**: `browse_files`, `get_file_content`, `list_files`
+- **Commits**: `list_commits`, `get_commit`, `get_commit_diff`, `get_commit_changes`
+- **Pull Requests**: `list_pull_requests`, `get_pull_request`, `create_pull_request`, `update_pull_request`, `merge_pull_request`, `decline_pull_request`, `get_pull_request_diff`, `list_pull_request_commits`, `get_pull_request_activities`, `list_pull_request_comments`, `add_pull_request_comment`
+- **Search**: `search_code` (requires Elasticsearch on the Bitbucket Server instance)
+- No deletion operations by design
+- Claude Code integration support via MCP settings

bitbucket_server_mcp-1.4.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,83 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at **manpreetshuann@gmail.com**. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations