@atercates/bitbucket-mcp 1.0.0

package/docs/guides/GETTING_STARTED.md

@@ -0,0 +1,267 @@
+# Getting Started with Bitbucket MCP
+
+This guide will help you set up and use the Bitbucket MCP server.
+
+## Prerequisites
+
+- Node.js 18+ 
+- Bitbucket Cloud account with API access
+- An MCP client (Claude, Cursor, etc.)
+
+## Installation
+
+### Option 1: From NPM (Recommended)
+
+```bash
+npm install -g bitbucket-mcp
+# or
+pnpm add -g bitbucket-mcp
+```
+
+Then run:
+```bash
+bitbucket-mcp
+```
+
+### Option 2: NPX
+
+```bash
+npx -y bitbucket-mcp@latest
+```
+
+### Option 3: Local Development
+
+```bash
+git clone https://github.com/atercates/bitbucket-mcp.git
+cd bitbucket-mcp
+pnpm install
+pnpm build
+pnpm start
+```
+
+## Configuration
+
+The server uses environment variables for configuration. Create a `.env` file or set these in your shell:
+
+### Required
+```bash
+# One of these authentication methods:
+
+# Option 1: Token Authentication (Recommended)
+BITBUCKET_TOKEN=your_app_password_here
+
+# Option 2: Basic Authentication
+BITBUCKET_USERNAME=your_email@example.com
+BITBUCKET_PASSWORD=your_app_password_here
+```
+
+### Optional
+```bash
+# API Configuration
+BITBUCKET_URL=https://api.bitbucket.org/2.0  # Default URL
+BITBUCKET_WORKSPACE=my-workspace              # Default workspace (auto-detected if not set)
+
+# Security
+BITBUCKET_ALLOW_DANGEROUS=true                # Allow delete operations (default: false)
+
+# Logging
+BITBUCKET_LOG_DISABLE=false                   # Disable file logging
+BITBUCKET_LOG_FILE=/path/to/custom.log        # Custom log file path
+BITBUCKET_LOG_DIR=/path/to/logs               # Custom log directory
+BITBUCKET_LOG_PER_CWD=true                    # Create per-directory logs
+```
+
+## Getting Bitbucket Credentials
+
+### Create an App Password
+
+1. Go to https://bitbucket.org/account/settings/app-passwords/
+2. Click "Create app password"
+3. Give it a name (e.g., "MCP Server")
+4. Select required permissions:
+   - Pipelines: Read
+   - Repositories: Read, Write (for PR operations)
+   - Pull requests: Read, Write (for PR operations)
+5. Copy the generated password
+6. Set `BITBUCKET_TOKEN` to this password
+
+### Find Your Workspace
+
+1. Go to your Bitbucket workspace
+2. The workspace name is in the URL: `https://bitbucket.org/{workspace}`
+3. Or set `BITBUCKET_WORKSPACE` environment variable
+
+## Using with Claude/Cursor
+
+Add to your MCP configuration file (`.mcp.json` or similar):
+
+```json
+{
+  "mcpServers": {
+    "bitbucket": {
+      "command": "bitbucket-mcp",
+      "env": {
+        "BITBUCKET_TOKEN": "${BITBUCKET_TOKEN}",
+        "BITBUCKET_WORKSPACE": "my-workspace"
+      }
+    }
+  }
+}
+```
+
+Or with npx:
+
+```json
+{
+  "mcpServers": {
+    "bitbucket": {
+      "command": "npx",
+      "args": ["-y", "bitbucket-mcp@latest"],
+      "env": {
+        "BITBUCKET_TOKEN": "${BITBUCKET_TOKEN}",
+        "BITBUCKET_WORKSPACE": "my-workspace"
+      }
+    }
+  }
+}
+```
+
+## Basic Operations
+
+### List Repositories
+
+```
+Tool: listRepositories
+Args: {
+  "workspace": "my-workspace",
+  "pagelen": 20
+}
+```
+
+### Create a Pull Request
+
+```
+Tool: createPullRequest
+Args: {
+  "workspace": "my-workspace",
+  "repo_slug": "my-repo",
+  "title": "Add new feature",
+  "description": "This PR adds support for X",
+  "sourceBranch": "feature/new-feature",
+  "targetBranch": "main",
+  "reviewers": ["uuid1", "uuid2"]
+}
+```
+
+### Approve a Pull Request
+
+```
+Tool: approvePullRequest
+Args: {
+  "workspace": "my-workspace",
+  "repo_slug": "my-repo",
+  "pull_request_id": "123"
+}
+```
+
+### List Branches
+
+```
+Tool: listBranches
+Args: {
+  "workspace": "my-workspace",
+  "repo_slug": "my-repo"
+}
+```
+
+### Run a Pipeline
+
+```
+Tool: runPipeline
+Args: {
+  "workspace": "my-workspace",
+  "repo_slug": "my-repo",
+  "target": {
+    "ref_type": "branch",
+    "ref_name": "main"
+  }
+}
+```
+
+## Debugging
+
+### View Logs
+
+Logs are stored in platform-specific directories:
+
+**macOS:**
+```bash
+tail -f ~/Library/Logs/bitbucket-mcp/bitbucket.log
+```
+
+**Linux:**
+```bash
+tail -f ~/.local/state/bitbucket-mcp/bitbucket.log
+```
+
+**Windows:**
+```bash
+Get-Content -Path "$env:LOCALAPPDATA\bitbucket-mcp\bitbucket.log" -Tail 50 -Wait
+```
+
+### Enable Verbose Logging
+
+```bash
+BITBUCKET_LOG_DISABLE=false bitbucket-mcp
+```
+
+### Test Connection
+
+```bash
+curl -X GET https://api.bitbucket.org/2.0/user \
+  -u username:app_password
+```
+
+## Troubleshooting
+
+### "Invalid credentials" error
+- Verify `BITBUCKET_TOKEN` or `BITBUCKET_USERNAME`/`BITBUCKET_PASSWORD` are correct
+- Check that app password has required permissions
+- Ensure workspace name is correct
+
+### "Workspace not found"
+- Set `BITBUCKET_WORKSPACE` explicitly
+- Or provide `workspace` parameter in every tool call
+- Check workspace name is correct (case-sensitive)
+
+### "Dangerous operation not allowed"
+- Set `BITBUCKET_ALLOW_DANGEROUS=true` to enable delete operations
+- This is intentionally restrictive for safety
+
+### Pagination issues
+- Use `pagelen` parameter to control page size (1-100)
+- Use `all: true` to fetch all results automatically
+- Check rate limits with `x-ratelimit-*` headers in logs
+
+## FAQ
+
+**Q: Can I use this with Bitbucket Server (self-hosted)?**
+A: Yes! Set `BITBUCKET_URL` to your server URL:
+```bash
+BITBUCKET_URL=https://bitbucket.mycompany.com/rest/api/2.0
+```
+
+**Q: How do I use with multiple workspaces?**
+A: Provide `workspace` parameter in each tool call, or run multiple instances with different `BITBUCKET_WORKSPACE` values.
+
+**Q: Is it safe to enable dangerous operations?**
+A: Yes, but be careful. These operations (delete branch/tag) cannot be undone. Only enable in trusted environments.
+
+**Q: How do I contribute?**
+A: See [CONTRIBUTING.md](../CONTRIBUTING.md) in the docs.
+
+## Next Steps
+
+- Read [TOOLS.md](../TOOLS.md) for complete tool reference
+- Check [ARCHITECTURE.md](./architecture/ARCHITECTURE.md) for technical details
+- See [examples/](./examples/) for common use cases

package/docs/guides/GITHUB_ACTIONS_SETUP.md

@@ -0,0 +1,148 @@
+# GitHub Actions Setup for Auto-Publishing to NPM
+
+This guide explains how to set up automatic publishing to NPM with every push to main.
+
+## What the Workflow Does
+
+The `auto-publish.yml` workflow:
+1. ✅ Runs on every push to `main` or `master`
+2. ✅ Lints, tests, and builds the code
+3. ✅ Detects if source code changed since last release
+4. ✅ Automatically bumps patch version (5.0.6 → 5.0.7)
+5. ✅ Publishes to NPM
+6. ✅ Creates a GitHub release
+7. ✅ Skips publishing if only docs changed
+
+## What You Need to Do
+
+### 1. Create an NPM Token
+
+1. Go to https://npmjs.com/settings/atercates/tokens/new
+2. Select **Granular Access Token**
+3. Configure:
+   - **Token Name**: `github-actions`
+   - **Expiration**: 1 year
+   - **Permissions**: 
+     - Read and write access to `bitbucket-mcp`
+4. Copy the token (you won't see it again)
+
+### 2. Add NPM_TOKEN to GitHub Secrets
+
+1. Go to your repository on GitHub
+2. Click **Settings** → **Secrets and variables** → **Actions**
+3. Click **New repository secret**
+   - **Name**: `NPM_TOKEN`
+   - **Value**: Paste your token from Step 1
+4. Click **Add secret**
+
+That's it! The workflow will automatically run on your next push to main.
+
+## GitHub Token (Automatic)
+
+The workflow uses `secrets.GITHUB_TOKEN` which is **automatically provided** by GitHub Actions. No manual setup needed.
+
+## How to Trigger a Release
+
+Simply push code to `main`:
+
+```bash
+git commit -m "feat: add new feature"
+git push origin main
+```
+
+The workflow will:
+- ✅ Run tests and lint checks
+- ✅ Auto-bump version (patch)
+- ✅ Publish to NPM
+- ✅ Create GitHub release
+
+To see the progress:
+1. Go to your repo on GitHub
+2. Click **Actions**
+3. Find **Build, Test & Auto-Publish**
+4. Watch the workflow run (takes 2-5 minutes)
+
+## Manual Version Control
+
+By default, the workflow bumps **patch** versions (5.0.6 → 5.0.7).
+
+To bump **minor** or **major** versions:
+1. Edit `package.json` manually
+   - `5.0.6` → `5.1.0` (minor)
+   - `5.0.6` → `6.0.0` (major)
+2. Commit and push to main
+3. Workflow will detect and publish
+
+## Troubleshooting
+
+### Workflow doesn't trigger
+- ✅ Check: Did you push to `main` or `master`?
+- ✅ Check: Did you change files in `src/`, `__tests__/`, or `package.json`?
+- ✅ If still not triggering: Go to **Actions** tab → **Build, Test & Auto-Publish** → **Run workflow** → Select branch
+
+### NPM publish fails
+**Cause**: `NPM_TOKEN` not set or expired
+**Fix**: Follow Step 1-2 above, ensure token is still valid
+
+**Cause**: Package name already published
+**Fix**: Check https://npmjs.com/package/bitbucket-mcp
+
+### Tests fail
+The workflow will fail and not publish. Fix errors locally:
+```bash
+pnpm lint
+pnpm test
+pnpm build
+```
+
+## What NOT to Do
+
+❌ Don't manually edit `server.json` version (auto-synced)
+❌ Don't manually tag releases (auto-created)
+❌ Don't commit directly with `git push --force`
+❌ Don't expose `NPM_TOKEN` in code or logs
+
+## Environment Variables for Users
+
+When users install the MCP server, they need these environment variables:
+
+```bash
+# Required (choose one)
+export BITBUCKET_TOKEN="app_password"           # Recommended
+# OR
+export BITBUCKET_USERNAME="user@example.com"
+export BITBUCKET_PASSWORD="app_password"
+
+# Optional
+export BITBUCKET_WORKSPACE="my-workspace"
+export BITBUCKET_ALLOW_DANGEROUS=true            # Enable deletes
+```
+
+See [ENVIRONMENT_VARIABLES.md](ENVIRONMENT_VARIABLES.md) for details.
+
+## Files Modified by the Workflow
+
+The workflow modifies these files automatically:
+- `package.json` - Version bumped
+- `server.json` - Version synced
+- Git history - New commit and tag created
+
+You don't need to manually update these.
+
+## Verify Setup is Working
+
+1. Make a small change to `src/` (e.g., update a comment)
+2. Commit and push: `git push origin main`
+3. Go to GitHub → **Actions** tab
+4. Watch **Build, Test & Auto-Publish** workflow
+5. When complete, check:
+   - NPM: https://npmjs.com/package/bitbucket-mcp
+   - GitHub: **Releases** tab (new release should appear)
+
+## Support
+
+For issues:
+- Check the Actions log on GitHub for error details
+- Verify `NPM_TOKEN` is set in Settings → Secrets
+- Ensure local build works: `pnpm build && pnpm test`
+

package/docs/guides/NPM_DEPLOYMENT.md

@@ -0,0 +1,266 @@
+# Deploying to NPM
+
+This guide explains how to deploy the Bitbucket MCP server to npm.
+
+## Prerequisites
+
+- npm account at https://www.npmjs.com/
+- Local npm authentication (`npm login`)
+- Git repository with version control
+- Access to bump version numbers
+
+## Setup
+
+### 1. Create NPM Account
+
+If you don't have an npm account:
+1. Go to https://www.npmjs.com/signup
+2. Create your account
+3. Verify your email
+
+### 2. Local npm Login
+
+```bash
+npm login
+```
+
+This will prompt for:
+- **Username**: Your npm username
+- **Password**: Your npm password
+- **Email**: Email associated with your account
+- **Two-Factor Authentication** (2FA): If enabled, provide your 2FA code
+
+Your credentials are saved to `~/.npmrc` (do not commit this file).
+
+### 3. Verify Ownership
+
+Ensure you own the `bitbucket-mcp` package on npm. If not, you'll need to:
+- Contact the current owner for permissions, or
+- Use a different package name
+
+## Deployment Process
+
+### Option 1: Automated Script (Recommended)
+
+Use the npm version scripts in `package.json`:
+
+```bash
+# Patch version bump (5.0.6 → 5.0.7)
+pnpm publish:patch
+
+# Minor version bump (5.0.6 → 5.1.0)
+pnpm publish:minor
+
+# Major version bump (5.0.6 → 6.0.0)
+pnpm publish:major
+
+# Alias for patch
+pnpm release
+```
+
+This will:
+1. Build the project
+2. Bump the version in package.json
+3. Commit the version change
+4. Tag the commit with git
+5. Publish to npm
+6. Push changes and tags to GitHub
+
+### Option 2: Manual Process
+
+If you prefer more control:
+
+```bash
+# 1. Build the project
+pnpm build
+
+# 2. Manually bump version (edit package.json)
+# Change: "version": "5.0.6" → "5.0.7"
+
+# 3. Commit the change
+git add package.json
+git commit -m "chore: bump version to 5.0.7"
+git tag v5.0.7
+
+# 4. Publish to npm
+pnpm publish
+
+# 5. Push changes to GitHub
+git push origin master --tags
+```
+
+## Environment Variables for CI/CD
+
+If deploying from CI/CD (GitHub Actions, GitLab CI, etc.), set:
+
+```bash
+# GitHub Actions example
+NPM_TOKEN=your_npm_access_token
+```
+
+Configure in your repository secrets or CI/CD provider.
+
+### Getting NPM Access Token
+
+1. Go to https://www.npmjs.com/settings/~/tokens
+2. Click "Generate New Token"
+3. Select token type:
+   - **Automation** - For CI/CD deployments (recommended)
+   - **Publish** - For publishing packages
+4. Copy the token
+5. Add to GitHub Secrets as `NPM_TOKEN`
+
+### GitHub Actions Workflow
+
+Example `.github/workflows/publish.yml`:
+
+```yaml
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - uses: pnpm/action-setup@v2
+        with:
+          version: 8
+      
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'pnpm'
+      
+      - run: pnpm install
+      - run: pnpm build
+      - run: pnpm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+## Pre-Deployment Checklist
+
+Before deploying, verify:
+
+- ✅ All tests pass: `pnpm test`
+- ✅ Linting is clean: `pnpm lint`
+- ✅ Code is formatted: `pnpm format`
+- ✅ Build succeeds: `pnpm build`
+- ✅ README is updated
+- ✅ CHANGELOG.md is updated
+- ✅ Version number is bumped correctly
+- ✅ No sensitive data in code
+- ✅ package.json has correct metadata
+- ✅ .npmignore is configured properly
+
+## Verification After Deployment
+
+After publishing:
+
+1. **Check npm package page:**
+   ```
+   https://www.npmjs.com/package/bitbucket-mcp
+   ```
+
+2. **Install and test locally:**
+   ```bash
+   npm install -g bitbucket-mcp
+   bitbucket-mcp --version
+   ```
+
+3. **Verify with npx:**
+   ```bash
+   npx -y bitbucket-mcp@latest
+   ```
+
+4. **Check GitHub release:**
+   - Tag is created
+   - Release notes are visible
+
+## Troubleshooting
+
+### "403 Forbidden" Error
+
+**Problem:** Cannot publish to npm
+
+**Solutions:**
+- Verify npm login: `npm whoami`
+- Check package name is available (or you own it)
+- Verify credentials in `~/.npmrc`
+- Check 2FA is configured correctly
+
+### "ENEEDAUTH" Error
+
+**Problem:** Not authenticated with npm
+
+**Solution:**
+```bash
+npm logout
+npm login
+```
+
+### "Version already published"
+
+**Problem:** Cannot publish duplicate version
+
+**Solution:**
+```bash
+# Bump version and try again
+pnpm publish:patch
+```
+
+### Package not appearing on npm
+
+**Problem:** Published but not visible
+
+**Solutions:**
+- Wait 2-5 minutes for npm CDN to sync
+- Clear npm cache: `npm cache clean --force`
+- Check https://www.npmjs.com/package/bitbucket-mcp for latest version
+- Verify you're logged in as correct user: `npm whoami`
+
+## Best Practices
+
+1. **Version Numbering** - Use semantic versioning (MAJOR.MINOR.PATCH)
+2. **Changelog** - Update CHANGELOG.md before each release
+3. **Tags** - Always use git tags matching version (v5.0.7)
+4. **Testing** - Run full test suite before publishing
+5. **2FA** - Enable 2FA on npm account for security
+6. **Access Tokens** - Use granular tokens in CI/CD
+7. **Documentation** - Keep README and docs up to date
+
+## Rolling Back a Release
+
+If you accidentally publish a bad version:
+
+```bash
+npm unpublish bitbucket-mcp@5.0.7
+```
+
+Then:
+1. Fix the issue
+2. Test thoroughly
+3. Bump to a new version
+4. Publish again
+
+Note: npm has restrictions on unpublishing after 72 hours.
+
+## Monitoring Package Health
+
+- **Package page:** https://www.npmjs.com/package/bitbucket-mcp
+- **Weekly downloads:** Visible on package page
+- **Issues:** GitHub Issues section
+- **Quality score:** npm calculates based on tests, docs, links, etc.
+
+## Contact
+
+For npm support:
+- npm Help: https://docs.npmjs.com/
+- npm Support: support@npmjs.com