commit 29496cb94426687cd04308d887f84c30ba04d4ed
Author: Nicolas FRADIN <fradinni@gmail.com>
Date:   Tue May 19 16:24:55 2026 +0200

    Initial commit

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ff0e8f9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,162 @@
+# Bitbucket MCP Server
+
+MCP (Model Context Protocol) server for AI agents to interact with **Bitbucket Cloud Pull Requests**.
+
+## Features
+
+- ✅ List pull requests in repositories
+- ✅ Get detailed PR information
+- ✅ Get PR activities/events
+- ✅ Get PR changes (files modified)
+- ✅ Get PR comments and individual comments
+- ✅ Get PR commits
+- ✅ Get PR diff and patch
+- ✅ Get PR participants and reviewers
+- ✅ Get PR status/state
+- ✅ Get PR tasks
+- ✅ Flexible credential configuration (env var or .env file)
+- ✅ Rate limiting protection
+- ✅ Error handling and retry logic
+
+## Installation
+
+```bash
+npm install
+```
+
+## Configuration
+
+### Credentials Sources (Priority Order)
+
+1. **Environment Variables** (highest priority):
+   ```bash
+   export BITBUCKET_MCP_EMAIL=your_email@example.com
+   export BITBUCKET_MCP_TOKEN=your_token_here
+   ```
+
+2. **.env file** in project root:
+   ```
+   BITBUCKET_MCP_EMAIL=your_email@example.com
+   BITBUCKET_MCP_TOKEN=your_token_here
+   ```
+
+3. **Interactive prompt** (development fallback)
+
+### Getting Your Access Token
+
+1. Go to [Bitbucket Applications](https://bitbucket.org/account/applications/)
+2. Click "New application" or select existing
+3. Set callback URL to `http://localhost:8080` (or any placeholder)
+4. Copy the **Access token**
+
+**Note:** Bitbucket uses Basic Authentication with your email as username and the access token as password.
+
+## Usage
+
+### Start the Server
+
+```bash
+npm start
+# Or for development:
+npm run dev
+```
+
+The server will output:
+```
+✅ Bitbucket MCP Server started
+   Name: bitbucket-pullrequests v1.0.0
+   Token source: environment variable
+```
+
+### Available Tools
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `list_pull_requests` | List PRs in a repository | workspace, repository, state (optional), author (optional) |
+| `get_pull_request` | Get PR details | workspace, repository, pullRequestId |
+| `get_pull_request_activities` | Get PR activities/events | workspace, repository, pullRequestId, limit (optional), start (optional) |
+| `get_pull_request_changes` | Get files changed in PR | workspace, repository, pullRequestId, limit (optional), start (optional) |
+| `get_pull_request_comments` | Get all PR comments | workspace, repository, pullRequestId, limit (optional), start (optional) |
+| `get_pull_request_comment` | Get a specific PR comment | workspace, repository, pullRequestId, commentId |
+| `get_pull_request_commits` | Get commits in PR | workspace, repository, pullRequestId, limit (optional), start (optional) |
+| `get_pull_request_diff` | Get PR diff | workspace, repository, pullRequestId, path (optional), context (optional) |
+| `get_pull_request_patch` | Get PR patch | workspace, repository, pullRequestId |
+| `get_pull_request_participants` | Get PR participants | workspace, repository, pullRequestId |
+| `get_pull_request_reviewers` | Get PR reviewers | workspace, repository, pullRequestId |
+| `get_pull_request_status` | Get PR status/state | workspace, repository, pullRequestId |
+| `get_pull_request_tasks` | Get PR tasks | workspace, repository, pullRequestId |
+| `get_pull_request_task_count` | Get PR task count | workspace, repository, pullRequestId |
+| `get_full_pull_request` | Get full PR details | workspace, repository, pullRequestId |
+
+### Example MCP Call
+
+```json
+{
+  "name": "list_pull_requests",
+  "arguments": {
+    "workspace": "my-workspace",
+    "repository": "my-repo",
+    "state": "open"
+  }
+}
+```
+
+## API Reference
+
+### list_pull_requests(workspace, repository, options?)
+
+List pull requests in a repository.
+
+**Options:**
+- `state`: 'open' | 'closed' | 'all' (default: open)
+- `author`: Filter by author username
+
+**Returns:** Array of pull request objects with metadata.
+
+### get_pull_request(workspace, repository, pullRequestId)
+
+Get detailed information about a specific pull request.
+
+**Returns:** Complete PR object including title, description, source/destination branches, reviewers, etc.
+
+### merge_pull_request(workspace, repository, pullRequestId, options?)
+
+Merge a pull request into the target branch.
+
+**Options:**
+- `mergeStrategy`: 'merge' | 'squash' | 'fastforward' (default: merge)
+- `deleteSourceBranch`: boolean (default: false)
+
+### create_pull_request(workspace, repository, title, description, sourceBranch, destinationBranch)
+
+Create a new pull request.
+
+**Returns:** Created PR object with ID and URL.
+
+## Error Handling
+
+The server handles the following errors:
+
+| Error | Cause |
+|-------|-------|
+| `AuthenticationFailed` | Invalid or expired token |
+| `RateLimited` | API rate limit exceeded (429) |
+| `RepositoryNotFound` | Workspace/repo doesn't exist |
+| `PRNotFound` | Pull request ID invalid |
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run in development mode with hot reload
+npm run dev
+
+# Build for production
+npm run build
+```
+
+## License
+
+MIT