Feature/project discovery and enhanced descriptions

[jhonymiler]

🚀 Feature: Project Discovery and Enhanced Tool Descriptions

Overview

This PR introduces significant enhancements to the Bitbucket Server MCP server, adding project discovery capabilities and dramatically improving tool descriptions for better AI agent understanding and usability.

✨ New Features

🔍 Project Discovery Tools

list_projects

• Purpose: Discover and explore all accessible Bitbucket projects
• Use Cases: Find available projects, explore project structure, discover new accessible projects
• Returns: Project keys, names, descriptions, visibility settings
• Pagination: Supports limit/start parameters for large datasets

list_repositories

• Purpose: Browse repositories within projects or across all accessible projects
• Use Cases: Find repository slugs, explore codebase structure, discover accessible repositories
• Returns: Repository names, slugs, clone URLs, project associations, state information
• Flexible Scope: Can target specific projects or browse all accessible repositories

🔧 Enhanced Project Handling

Optional Project Parameters

• Before: Project parameter was required for all operations
• After: Project parameter is now optional across all tools
• Fallback: Uses BITBUCKET_DEFAULT_PROJECT environment variable when project not specified
• Flexibility: Can override default project on any individual tool call

Improved Validation

• Clear error messages when project cannot be determined
• Better parameter validation with detailed feedback
• Graceful handling of missing optional parameters

📖 Enhanced Documentation

AI-Optimized Tool Descriptions

• Comprehensive Context: Each tool now includes detailed descriptions explaining when and why to use it
• Use Case Examples: Specific scenarios where each tool is most effective
• Parameter Guidance: Clear explanations of what each parameter does and when to use it
• AI-Friendly Language: Descriptions optimized for AI agent understanding and decision-making

Improved README

• Feature Overview: New section highlighting key capabilities
• Usage Examples: Practical examples showing how to use new features
• Enhanced Configuration: Better documentation of environment variables and setup
• Use Case Documentation: Detailed explanations of when to use each tool

🔄 Breaking Changes

None! This is a fully backward-compatible enhancement:

• ✅ All existing tool calls continue to work unchanged
• ✅ Existing configuration remains valid
• ✅ No changes to required parameters
• ✅ Existing behavior preserved when project is specified

🛠️ Technical Implementation

Type Safety Improvements

• Enhanced TypeScript interfaces for better type checking
• Improved parameter validation with proper error handling
• Better null/undefined handling for optional parameters

Code Quality

• Comprehensive input validation
• Detailed error messages for better debugging
• Consistent parameter handling across all tools
• Clean separation of concerns

API Integration

• Efficient Bitbucket API usage with proper pagination
• Optimized data retrieval and formatting
• Proper error handling for API failures
• Consistent response formatting

📋 Testing

Functionality Verified

• ✅ All existing tools work with and without project parameters
• ✅ New discovery tools return expected data formats
• ✅ Proper fallback to default project when configured
• ✅ Error handling works correctly for missing parameters
• ✅ Pagination works correctly for large datasets
• ✅ TypeScript compilation successful with no errors

Compatibility Testing

• ✅ Existing configurations continue to work
• ✅ All tool schemas validate correctly
• ✅ No regression in existing functionality
• ✅ Project parameter backward compatibility maintained

🎯 Use Case Examples

Project Discovery Workflow

// 1. Discover available projects
await mcp.callTool('list_projects', { limit: 50 });

// 2. Explore repositories in a specific project
await mcp.callTool('list_repositories', { project: 'MYPROJECT' });

// 3. Work with discovered repositories
await mcp.callTool('create_pull_request', {
  project: 'MYPROJECT',
  repository: 'discovered-repo',
  title: 'New feature',
  sourceBranch: 'feature/enhancement',
  targetBranch: 'main'
});

Simplified Default Project Workflow

// Set BITBUCKET_DEFAULT_PROJECT=MYPROJECT in environment

// All tools now work without specifying project
await mcp.callTool('list_repositories', {}); // Uses default project
await mcp.callTool('get_pull_request', { repository: 'my-repo', prId: 123 });
await mcp.callTool('merge_pull_request', { repository: 'my-repo', prId: 123 });

🔮 Future Enhancements

This foundation enables future improvements:

• Repository search and filtering capabilities
• Branch discovery and management
• Enhanced project metadata retrieval
• Cross-project operation support

📊 Impact Assessment

Developer Experience

• Significantly Improved: Easier project and repository discovery
• Reduced Friction: No need to know exact project keys upfront
• Better Documentation: AI agents can make better decisions about tool usage

Functionality

• Expanded Capabilities: New discovery and exploration features
• Maintained Compatibility: All existing functionality preserved
• Enhanced Flexibility: More ways to interact with Bitbucket Server

Code Quality

• Better Structure: Cleaner separation of concerns
• Improved Types: Enhanced TypeScript support
• Better Error Handling: More informative error messages

🔗 Related Links

• Branch: feature/project-discovery-and-enhanced-descriptions
• Base: main
• Type: Feature Enhancement
• Breaking Changes: None
• Backward Compatible: Yes ✅

---

This enhancement significantly improves the MCP server's usability and AI agent compatibility while maintaining full backward compatibility. The new discovery features and enhanced descriptions make it much easier for both humans and AI agents to understand and effectively use the Bitbucket Server integration.