@atercates/bitbucket-mcp 1.0.0

package/docs/architecture/ARCHITECTURE.md

@@ -0,0 +1,302 @@
+# Architecture Overview
+
+This document describes the architecture of the Bitbucket MCP server.
+
+## High-Level Overview
+
+The Bitbucket MCP server is a Model Context Protocol (MCP) implementation that provides programmatic access to Bitbucket Cloud and Server APIs. It's designed as a modular, maintainable system that separates concerns by feature domain.
+
+```
+┌─────────────────────────────────────────┐
+│     MCP Client (e.g., Cursor, Claude)   │
+└──────────────┬──────────────────────────┘
+               │ stdio/HTTP
+               ▼
+┌──────────────────────────────────────────┐
+│   BitbucketMcpServer (src/server.ts)    │
+│  - Tool Registration                     │
+│  - Request Routing                       │
+│  - MCP Protocol Handling                 │
+└──────────────┬───────────────────────────┘
+               │
+        ┌──────▼──────────────────────────┐
+        │   Handler Modules (/handlers/)  │
+        ├─────────────────────────────────┤
+        │ • repositories.ts               │
+        │ • pull-requests.ts              │
+        │ • pr-comments.ts                │
+        │ • pr-tasks.ts                   │
+        │ • pr-content.ts                 │
+        │ • pipelines.ts                  │
+        │ • refs.ts (branches/tags)       │
+        │ • commits.ts                    │
+        │ • source.ts                     │
+        │ • users.ts                      │
+        │ • branching-model.ts            │
+        └──────┬───────────────────────────┘
+               │
+    ┌──────────┴──────────────┐
+    ▼                         ▼
+┌──────────────────┐  ┌──────────────────┐
+│ BitbucketClient  │  │    Logger        │
+│ (src/client.ts)  │  │ (src/logger.ts)  │
+│                  │  │                  │
+│ • API wrapper    │  │ • File-based     │
+│ • Auth handling  │  │   logging        │
+│ • URL normaliz.  │  │ • Platform-aware │
+│ • Pagination    │  │                  │
+└────────┬─────────┘  └──────────────────┘
+         │
+         ▼
+    ┌─────────────────┐
+    │ Bitbucket API   │
+    │ (api.bitbucket) │
+    └─────────────────┘
+```
+
+## Core Components
+
+### 1. Entry Point (`src/index.ts`)
+- Minimal entry point that initializes the server
+- Starts stdio transport for MCP communication
+- Handles process lifecycle
+
+### 2. Server (`src/server.ts`)
+The core orchestrator that:
+- Manages MCP protocol events
+- Dynamically registers tools from handler modules
+- Routes tool calls to appropriate handlers
+- Handles errors and response formatting
+
+**Key Responsibilities:**
+- `initializeListTools()`: Collects tools from all modules
+- `handleCallTool()`: Routes calls to correct handler
+- Security checks for dangerous tools
+
+### 3. Handler Modules (`src/handlers/`)
+Each handler module follows the `HandlerModule` interface:
+
+```typescript
+interface HandlerModule {
+  tools: Tool[];
+  dangerousTools?: string[];
+  createHandlers: (client: BitbucketClient) => Record<string, Handler>;
+}
+```
+
+**Module Pattern:**
+- **tools**: Defines tool schemas (names, descriptions, input schemas)
+- **dangerousTools**: Lists tools requiring `BITBUCKET_ALLOW_DANGEROUS`
+- **createHandlers**: Factory function that returns handler implementations
+
+**Example Structure:**
+```
+repositories.ts
+  └─ tools: [
+       { name: "listRepositories", ... },
+       { name: "getRepository", ... },
+       { name: "createRepository", ... }
+     ]
+  └─ createHandlers: (client) => ({
+       listRepositories: async (args) => { ... },
+       getRepository: async (args) => { ... },
+       createRepository: async (args) => { ... }
+     })
+```
+
+### 4. BitbucketClient (`src/client.ts`)
+Encapsulates all Bitbucket API interactions:
+
+**Key Features:**
+- **Authentication**: Supports token or username/password auth
+- **URL Normalization**: Converts web URLs to API URLs
+- **HTTP Client**: Axios instance with proper headers
+- **Pagination**: Built-in paginator for large datasets
+- **Error Handling**: Consistent error messages
+
+**Methods:**
+- `resolveWorkspace()`: Gets workspace from cache or args
+- `api`: Direct Axios access for API calls
+- `paginator`: Pagination helper
+
+### 5. Configuration (`src/config.ts`)
+Centralized environment variable management:
+
+**Environment Variables:**
+- `BITBUCKET_URL`: API base URL (default: https://api.bitbucket.org/2.0)
+- `BITBUCKET_TOKEN`: Authentication token
+- `BITBUCKET_USERNAME`: For basic auth
+- `BITBUCKET_PASSWORD`: For basic auth
+- `BITBUCKET_WORKSPACE`: Default workspace
+- `BITBUCKET_ALLOW_DANGEROUS`: Enable dangerous operations
+- `BITBUCKET_LOG_*`: Logging configuration
+
+### 6. Logger (`src/logger.ts`)
+File-based logging using Winston:
+
+**Features:**
+- Platform-aware log directory selection
+- Structured JSON logging
+- Per-CWD logging option
+- Disableable via environment variable
+
+**Log Locations:**
+- macOS: `~/Library/Logs/bitbucket-mcp/`
+- Windows: `%LOCALAPPDATA%/bitbucket-mcp/`
+- Linux: `~/.local/state/bitbucket-mcp/` or `$XDG_STATE_HOME/bitbucket-mcp/`
+
+### 7. Utilities (`src/utils.ts`)
+Response formatting helpers:
+
+- `jsonResponse()`: Wrap JSON in MCP response format
+- `textResponse()`: Wrap text in MCP response format
+
+### 8. Types (`src/types.ts`)
+Complete TypeScript definitions for:
+- Bitbucket API entities
+- MCP request/response types
+- Handler function signatures
+
+### 9. Schemas (`src/schemas.ts`)
+JSON Schema definitions for tool inputs:
+- Pagination parameters
+- Common field definitions
+- Reusable schema fragments
+
+### 10. Pagination (`src/pagination.ts`)
+BitbucketPaginator class for handling paginated API responses:
+
+**Features:**
+- Automatic pagination following `next` links
+- Configurable page size limits
+- All-items mode with safety caps
+
+## Data Flow
+
+### Typical Request Flow
+
+```
+1. Client calls tool via MCP
+   Example: { name: "listRepositories", arguments: { workspace: "my-ws" } }
+
+2. MCP Server receives request in server.ts
+   └─ handleCallTool() method
+
+3. Server routes to handler module
+   └─ Finds correct handler in pull-requests.ts, repositories.ts, etc.
+
+4. Handler extracts parameters and validates
+   └─ Resolves workspace from config/args
+
+5. Handler calls BitbucketClient
+   └─ client.api.get() or client.paginator.fetchValues()
+
+6. BitbucketClient hits Bitbucket API
+   └─ With proper auth headers and error handling
+
+7. Response is formatted
+   └─ JSON or text response wrapping
+
+8. MCP Server sends back to client
+   └─ { content: [{ type: "text", text: "..." }] }
+```
+
+## Security
+
+### Dangerous Tools Gating
+
+Some operations (delete, remove) are marked dangerous and require explicit enablement:
+
+```typescript
+// In handler module
+dangerousTools: ["deleteBranch", "deleteTag"]
+
+// In server.ts - gates execution
+if (isDangerous && !isDangerousAllowed) {
+  throw error("BITBUCKET_ALLOW_DANGEROUS not set");
+}
+```
+
+### Authentication
+
+Two supported methods (checked in order):
+1. **Token Auth**: `BITBUCKET_TOKEN` (preferred)
+2. **Basic Auth**: `BITBUCKET_USERNAME` + `BITBUCKET_PASSWORD`
+
+Both are passed to Axios as Authorization headers.
+
+## Testing
+
+The project uses Vitest with:
+- Mock BitbucketClient for unit tests
+- Mock Axios instance
+- Handler-by-handler tests
+- Edge case coverage
+
+**Test Structure:**
+```
+__tests__/
+  ├─ test-utils.ts         (Mock helpers)
+  └─ handlers/
+     ├─ repositories.test.ts
+     ├─ pull-requests.test.ts
+     └─ ... (one per handler)
+```
+
+## Build System
+
+- **TypeScript**: Compiles to ES2020 with strict mode
+- **Module System**: ESM (type: "module")
+- **Entry Point**: `dist/index.js` (executable with shebang)
+- **Linting**: ESLint with flat config
+- **Formatting**: Prettier
+- **Testing**: Vitest
+
+## Extension Pattern
+
+To add new functionality:
+
+1. **Create a handler module** `src/handlers/new-feature.ts`:
+   ```typescript
+   export const newFeatureModule: HandlerModule = {
+     tools: [{ name: "...", ... }],
+     createHandlers: (client) => ({
+       toolName: async (args) => { ... }
+     })
+   };
+   ```
+
+2. **Register in** `src/handlers/index.ts`:
+   ```typescript
+   export const allModules = [
+     repositoriesModule,
+     newFeatureModule, // Add here
+     // ...
+   ];
+   ```
+
+3. **The server will automatically pick it up** - no additional wiring needed!
+
+## Performance Considerations
+
+- **Pagination**: Large datasets are paginated by default (100 items/page max)
+- **Lazy Loading**: Handlers only loaded when server starts
+- **Streaming**: Responses returned as-is without buffering
+- **Caching**: Workspace resolution cached per session
+
+## Error Handling
+
+All handlers use consistent error handling:
+
+```typescript
+try {
+  // API call
+  return jsonResponse(data);
+} catch (error) {
+  logger.error("Operation failed", { error, context });
+  throw new McpError(
+    ErrorCode.InternalError,
+    `Descriptive message: ${error.message}`
+  );
+}
+```

package/docs/guides/ENVIRONMENT_VARIABLES.md

@@ -0,0 +1,306 @@
+# Environment Variables Reference
+
+Complete list of environment variables needed to configure and deploy the Bitbucket MCP server.
+
+## Authentication (Required - Select One)
+
+### Token Authentication (Recommended)
+
+```bash
+# App password from Bitbucket
+BITBUCKET_TOKEN=your_app_password_here
+```
+
+**How to get:**
+1. Go to https://bitbucket.org/account/settings/app-passwords/
+2. Click "Create app password"
+3. Select permissions: Pipelines:Read, Repositories:Read+Write, Pull requests:Read+Write
+4. Copy the generated password
+
+### Basic Authentication
+
+```bash
+# Email and app password
+BITBUCKET_USERNAME=your_email@example.com
+BITBUCKET_PASSWORD=your_app_password_here
+```
+
+## Server Configuration (Optional)
+
+```bash
+# API base URL (defaults to Bitbucket Cloud)
+BITBUCKET_URL=https://api.bitbucket.org/2.0
+
+# For self-hosted Bitbucket Server:
+BITBUCKET_URL=https://bitbucket.mycompany.com/rest/api/2.0
+
+# Default workspace (auto-extracted if not set)
+BITBUCKET_WORKSPACE=my-workspace
+
+# Allow dangerous operations (delete branch, delete tag, etc.)
+BITBUCKET_ALLOW_DANGEROUS=true  # default: false
+```
+
+## Logging Configuration (Optional)
+
+```bash
+# Disable file-based logging
+BITBUCKET_LOG_DISABLE=true
+
+# Custom log file path
+BITBUCKET_LOG_FILE=/var/log/bitbucket-mcp/server.log
+
+# Custom log directory
+BITBUCKET_LOG_DIR=/var/log/bitbucket-mcp
+
+# Create per-working-directory subdirectories
+BITBUCKET_LOG_PER_CWD=true
+```
+
+## NPM Publishing (Deployment)
+
+### Local Deployment
+
+```bash
+# npm account credentials
+# These are configured via: npm login
+# Stored in: ~/.npmrc (do NOT commit)
+```
+
+### CI/CD Deployment (GitHub Actions, etc.)
+
+```bash
+# npm access token for automation
+NPM_TOKEN=npm_your_token_here_1234567890
+
+# or use npm credentials
+NPM_USERNAME=your_npm_username
+NPM_PASSWORD=your_npm_password
+NPM_EMAIL=your_email@example.com
+```
+
+**How to get NPM_TOKEN:**
+1. Go to https://www.npmjs.com/settings/~/tokens
+2. Click "Generate New Token"
+3. Select type: "Automation" (for CI/CD)
+4. Copy the token
+5. Add to GitHub Secrets as `NPM_TOKEN`
+
+## Development Environment
+
+```bash
+# Development mode (use tsx watch)
+NODE_ENV=development
+pnpm dev
+
+# Production build
+NODE_ENV=production
+pnpm build
+pnpm start
+```
+
+## Complete Example: Local Setup
+
+```bash
+# Step 1: Create app password on Bitbucket
+# Go to https://bitbucket.org/account/settings/app-passwords/
+
+# Step 2: Set environment variables
+export BITBUCKET_TOKEN="your_app_password"
+export BITBUCKET_WORKSPACE="my-workspace"
+
+# Optional: Enable logging
+export BITBUCKET_LOG_DISABLE=false
+
+# Optional: Allow dangerous operations
+export BITBUCKET_ALLOW_DANGEROUS=true
+
+# Step 3: Run the server
+pnpm start
+# OR
+npx -y bitbucket-mcp@latest
+```
+
+## Complete Example: Docker Deployment
+
+```dockerfile
+FROM node:18-alpine
+WORKDIR /app
+COPY . .
+RUN pnpm install && pnpm build
+
+ENV BITBUCKET_TOKEN=${BITBUCKET_TOKEN}
+ENV BITBUCKET_WORKSPACE=${BITBUCKET_WORKSPACE}
+ENV BITBUCKET_LOG_DISABLE=false
+ENV BITBUCKET_ALLOW_DANGEROUS=${BITBUCKET_ALLOW_DANGEROUS:-false}
+
+CMD ["node", "dist/index.js"]
+```
+
+```bash
+# Run Docker container
+docker run -e BITBUCKET_TOKEN=your_token \
+           -e BITBUCKET_WORKSPACE=my-workspace \
+           bitbucket-mcp:latest
+```
+
+## Complete Example: GitHub Actions Workflow
+
+```yaml
+name: Deploy 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 test
+      - run: pnpm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+**GitHub Secrets to configure:**
+- `NPM_TOKEN`: npm automation token
+
+## Configuration by Environment
+
+### Development
+
+```bash
+BITBUCKET_TOKEN=dev_token
+BITBUCKET_WORKSPACE=dev-workspace
+BITBUCKET_LOG_DISABLE=false
+BITBUCKET_ALLOW_DANGEROUS=true
+NODE_ENV=development
+```
+
+### Staging
+
+```bash
+BITBUCKET_TOKEN=staging_token
+BITBUCKET_WORKSPACE=staging-workspace
+BITBUCKET_LOG_DISABLE=false
+BITBUCKET_ALLOW_DANGEROUS=false
+NODE_ENV=production
+```
+
+### Production
+
+```bash
+BITBUCKET_TOKEN=${BITBUCKET_TOKEN}
+BITBUCKET_WORKSPACE=${BITBUCKET_WORKSPACE}
+BITBUCKET_LOG_DISABLE=false
+BITBUCKET_ALLOW_DANGEROUS=false
+NODE_ENV=production
+```
+
+## Environment Variable Priority
+
+When multiple configuration sources exist, priority is:
+
+1. **Command-line environment variables** (highest)
+   ```bash
+   BITBUCKET_TOKEN=value pnpm start
+   ```
+
+2. **.env file in current directory**
+   ```bash
+   # .env
+   BITBUCKET_TOKEN=value
+   ```
+
+3. **.env.local file** (for local overrides)
+   ```bash
+   # .env.local (in .gitignore)
+   BITBUCKET_TOKEN=local_value
+   ```
+
+4. **System environment variables**
+   ```bash
+   export BITBUCKET_TOKEN=value
+   ```
+
+5. **Default values** (lowest, if any)
+
+## Security Best Practices
+
+1. **Never commit secrets**
+   - Add `.env` and `.env.local` to `.gitignore`
+   - Store tokens in environment or secret management
+
+2. **Use strong tokens**
+   - Use app passwords with minimal required scopes
+   - Rotate tokens regularly
+
+3. **Enable 2FA on npm account**
+   - https://docs.npmjs.com/about-two-factor-authentication
+
+4. **Use specific npm tokens for CI/CD**
+   - Create automation tokens instead of personal tokens
+   - Restrict token scope to "publish"
+
+5. **Disable dangerous operations in production**
+   - Only set `BITBUCKET_ALLOW_DANGEROUS=true` in development
+   - This prevents accidental data loss
+
+## Troubleshooting
+
+### "Invalid credentials" error
+
+```bash
+# Verify token is set
+echo $BITBUCKET_TOKEN
+
+# Test credentials
+curl -X GET https://api.bitbucket.org/2.0/user \
+  -H "Authorization: Bearer $BITBUCKET_TOKEN"
+```
+
+### "Workspace not found"
+
+```bash
+# Verify workspace name
+echo $BITBUCKET_WORKSPACE
+
+# List your workspaces
+curl -X GET https://api.bitbucket.org/2.0/workspaces \
+  -H "Authorization: Bearer $BITBUCKET_TOKEN"
+```
+
+### npm publish fails with "ENEEDAUTH"
+
+```bash
+# Check npm login
+npm whoami
+
+# Login again
+npm login
+
+# Or use token directly
+echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" >> ~/.npmrc
+```
+
+## See Also
+
+- [Getting Started Guide](GETTING_STARTED.md)
+- [NPM Deployment Guide](NPM_DEPLOYMENT.md)
+- [Architecture Documentation](../architecture/ARCHITECTURE.md)