Merge pull request #8 from jhonymiler/feature/project-discovery-and-enhanced-descriptions

garc33 · web-flow · commit 2cb68f0f4297 · 2025-06-17T19:21:57.000+02:00
diff --git a/README.md b/README.md
@@ -5,6 +5,13 @@ MCP (Model Context Protocol) server for Bitbucket Server Pull Request management
 [![smithery badge](https://smithery.ai/badge/@garc33/bitbucket-server-mcp-server)](https://smithery.ai/server/@garc33/bitbucket-server-mcp-server)
 <a href="https://glama.ai/mcp/servers/jskr5c1zq3"><img width="380" height="200" src="https://glama.ai/mcp/servers/jskr5c1zq3/badge" alt="Bitbucket Server MCP server" /></a>
 
+## ✨ New Features
+
+- **🔍 Project Discovery**: List all accessible Bitbucket projects with `list_projects`
+- **📁 Repository Browsing**: Explore repositories across projects with `list_repositories`
+- **🔧 Flexible Project Support**: Make the default project optional - specify per command or use `BITBUCKET_DEFAULT_PROJECT`
+- **📖 Enhanced Documentation**: Improved README with usage examples and better configuration guidance
+
 ## Requirements
 
 - Node.js >= 16
@@ -20,6 +27,7 @@ npx -y @smithery/cli install @garc33/bitbucket-server-mcp-server --client claude
 ```
 
 ### Manual Installation
+
 ```bash
 npm install
 ```
@@ -32,90 +40,194 @@ npm run build
 
 ## Features
 
-The server provides the following tools for Bitbucket Server integration:
+The server provides the following tools for comprehensive Bitbucket Server integration:
+
+### `list_projects`
+
+**Discover and explore Bitbucket projects**: Lists all accessible projects with their details. Essential for project discovery and finding the correct project keys to use in other operations.
+
+**Use cases:**
+
+- Find available projects when you don't know the exact project key
+- Explore project structure and permissions
+- Discover new projects you have access to
+
+Parameters:
+
+- `limit`: Number of projects to return (default: 25, max: 1000)
+- `start`: Start index for pagination (default: 0)
+
+### `list_repositories`
+
+**Browse and discover repositories**: Explore repositories within specific projects or across all accessible projects. Returns comprehensive repository information including clone URLs and metadata.
+
+**Use cases:**
+- Find repository slugs for other operations
+- Explore codebase structure across projects
+- Discover repositories you have access to
+- Browse a specific project's repositories
+
+Parameters:
+
+- `project`: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
+- `limit`: Number of repositories to return (default: 25, max: 1000)
+- `start`: Start index for pagination (default: 0)
 
 ### `create_pull_request`
 
-Creates a new pull request.
+**Propose code changes for review**: Creates a new pull request to submit code changes, request reviews, or merge feature branches. Automatically handles branch references and reviewer assignments.
+
+**Use cases:**
+- Submit feature development for review
+- Propose bug fixes
+- Request code integration from feature branches
+- Collaborate on code changes
 
 Parameters:
 
-- `project`: Bitbucket project key (defaults to BITBUCKET_DEFAULT_PROJECT if set)
+- `project`: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
 - `repository` (required): Repository slug
-- `title` (required): PR title
-- `description`: PR description
-- `sourceBranch` (required): Source branch name
-- `targetBranch` (required): Target branch name
+- `title` (required): Clear, descriptive PR title
+- `description`: Detailed description with context (supports Markdown)
+- `sourceBranch` (required): Source branch containing changes
+- `targetBranch` (required): Target branch for merging
 - `reviewers`: Array of reviewer usernames
 
 ### `get_pull_request`
 
-Retrieves detailed information about a specific pull request.
+**Comprehensive PR information**: Retrieves detailed pull request information including status, reviewers, commits, and all metadata. Essential for understanding PR state before taking actions.
+
+**Use cases:**
+- Check PR approval status
+- Review PR details and progress
+- Understand changes before merging
+- Monitor PR status
 
 Parameters:
 
-- `project`: Bitbucket project key (defaults to BITBUCKET_DEFAULT_PROJECT if set)
+- `project`: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
 - `repository` (required): Repository slug
 - `prId` (required): Pull request ID
 
 ### `merge_pull_request`
 
-Merges a pull request.
+**Integrate approved changes**: Merges an approved pull request into the target branch. Supports different merge strategies based on your workflow preferences.
+
+**Use cases:**
+- Complete the code review process
+- Integrate approved features
+- Apply bug fixes to main branches
+- Release code changes
 
 Parameters:
 
-- `project`: Bitbucket project key (defaults to BITBUCKET_DEFAULT_PROJECT if set)
+- `project`: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
 - `repository` (required): Repository slug
 - `prId` (required): Pull request ID
-- `message`: Merge commit message
-- `strategy`: One of:
-  - `merge-commit` (default)
-  - `squash`
-  - `fast-forward`
+- `message`: Custom merge commit message
+- `strategy`: Merge strategy:
+  - `merge-commit` (default): Creates merge commit preserving history
+  - `squash`: Combines all commits into one
+  - `fast-forward`: Moves branch pointer without merge commit
 
 ### `decline_pull_request`
 
-Declines a pull request.
+**Reject unsuitable changes**: Declines a pull request that should not be merged, providing feedback to the author.
+
+**Use cases:**
+- Reject changes that don't meet standards
+- Close PRs that conflict with project direction
+- Request significant rework
+- Prevent unwanted code integration
 
 Parameters:
 
-- `project`: Bitbucket project key (defaults to BITBUCKET_DEFAULT_PROJECT if set)
+- `project`: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
 - `repository` (required): Repository slug
 - `prId` (required): Pull request ID
-- `message`: Reason for declining
+- `message`: Reason for declining (helpful for author feedback)
 
 ### `add_comment`
 
-Adds a comment to a pull request.
+**Participate in code review**: Adds comments to pull requests for review feedback, discussions, and collaboration. Supports threaded conversations.
+
+**Use cases:**
+- Provide code review feedback
+- Ask questions about specific changes
+- Suggest improvements
+- Participate in technical discussions
+- Document review decisions
 
 Parameters:
 
-- `project`: Bitbucket project key (defaults to BITBUCKET_DEFAULT_PROJECT if set)
+- `project`: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
 - `repository` (required): Repository slug
 - `prId` (required): Pull request ID
-- `text` (required): Comment text
-- `parentId`: Parent comment ID for replies
+- `text` (required): Comment content (supports Markdown)
+- `parentId`: Parent comment ID for threaded replies
 
 ### `get_diff`
 
-Retrieves the diff for a pull request.
+**Analyze code changes**: Retrieves the code differences showing exactly what was added, removed, or modified in the pull request.
+
+**Use cases:**
+- Review specific code changes
+- Understand scope of modifications
+- Analyze impact before merging
+- Inspect implementation details
+- Code quality assessment
 
 Parameters:
 
-- `project`: Bitbucket project key (defaults to BITBUCKET_DEFAULT_PROJECT if set)
+- `project`: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
 - `repository` (required): Repository slug
 - `prId` (required): Pull request ID
-- `contextLines`: Number of context lines (default: 10)
+- `contextLines`: Context lines around changes (default: 10)
 
 ### `get_reviews`
 
-Fetches the review history of a pull request, including approvals and reviews.
+**Track review progress**: Fetches review history, approval status, and reviewer feedback to understand the review state.
 
-Parameters:
+**Use cases:**
+- Check if PR is ready for merging
+- See who has reviewed the changes
+- Understand review feedback
+- Monitor approval requirements
+- Track review progress
 
-- `project`: Bitbucket project key (defaults to BITBUCKET_DEFAULT_PROJECT if set)
-- `repository` (required): Repository slug
-- `prId` (required): Pull request ID
+## Usage Examples
+
+### Listing Projects and Repositories
+
+```bash
+# List all accessible projects
+list_projects
+
+# List repositories in the default project (if BITBUCKET_DEFAULT_PROJECT is set)
+list_repositories
+
+# List repositories in a specific project
+list_repositories --project "MYPROJECT"
+
+# List projects with pagination
+list_projects --limit 10 --start 0
+```
+
+### Working with Pull Requests
+
+```bash
+# Create a pull request (using default project)
+create_pull_request --repository "my-repo" --title "Feature: New functionality" --sourceBranch "feature/new-feature" --targetBranch "main"
+
+# Create a pull request with specific project
+create_pull_request --project "MYPROJECT" --repository "my-repo" --title "Bugfix: Critical issue" --sourceBranch "bugfix/critical" --targetBranch "develop" --description "Fixes critical issue #123"
+
+# Get pull request details
+get_pull_request --repository "my-repo" --prId 123
+
+# Merge a pull request with squash strategy
+merge_pull_request --repository "my-repo" --prId 123 --strategy "squash" --message "Feature: New functionality (#123)"
+```
 
 ## Dependencies
 
@@ -155,7 +267,14 @@ The server requires configuration in the VSCode MCP settings file. Here's a samp
 - Authentication (one of the following is required):
   - `BITBUCKET_TOKEN`: Personal access token
   - `BITBUCKET_USERNAME` and `BITBUCKET_PASSWORD`: Basic authentication credentials
-- `BITBUCKET_DEFAULT_PROJECT`: Default project key to use when not specified in tool calls
+- `BITBUCKET_DEFAULT_PROJECT` (optional): Default project key to use when not specified in tool calls
+
+**Note**: With the new optional project support, you can now:
+
+- Set `BITBUCKET_DEFAULT_PROJECT` to work with a specific project by default
+- Use `list_projects` to discover available projects
+- Use `list_repositories` to browse repositories across projects
+- Override the default project by specifying the `project` parameter in any tool call
 
 ## Logging
 
diff --git a/package.json b/package.json
@@ -10,7 +10,7 @@
   },
   "scripts": {
     "build": "tsc && node -e \"if (process.platform !== 'win32') require('child_process').execSync('chmod +x build/index.js')\"",
-    "postinstall": "node -e \"if (process.platform !== 'win32') require('child_process').execSync('chmod +x build/index.js')\"",
+    "postinstall": "node -e \"const fs=require('fs'); if (process.platform !== 'win32' && fs.existsSync('build/index.js')) require('child_process').execSync('chmod +x build/index.js')\"",
     "start": "node build/index.js",
     "dev": "tsc -w",
     "dev:server": "npm run build && npx @modelcontextprotocol/inspector -e DEBUG=true node build/index.js",
@@ -41,4 +41,4 @@
   "engines": {
     "node": ">=18"
   }
-}
+}
diff --git a/src/index.ts b/src/index.ts
