749b0e9986
- Enhanced formatCodeSearchOutput for cleaner AI consumption - Improved HTML entity decoding (", <, >, &, /, ') - Simplified response structure with file:line:text format - Removed HTML formatting tags for better readability - Updated package.json to version 1.0.1 - Updated CHANGELOG.md with comprehensive v1.0.1 entry - Updated memory bank files with testing results and patterns - Enhanced .clinerules with v1.0.1 evolution notes - Validated functionality with live MCP testing workflow - Confirmed search patterns working with real Bitbucket data - Removed currentTask.yml as no longer needed
139 lines
3.7 KiB
Text
139 lines
3.7 KiB
Text
# Bitbucket MCP Server - Project Intelligence
|
|
|
|
## Critical Implementation Paths
|
|
|
|
### Adding New Tools
|
|
1. Create handler in src/handlers/ following existing patterns
|
|
2. Add TypeScript interfaces in src/types/bitbucket.ts
|
|
3. Add type guard in src/types/guards.ts
|
|
4. Add formatter in src/utils/formatters.ts if needed
|
|
5. Register tool in src/tools/definitions.ts
|
|
6. Wire handler in src/index.ts
|
|
7. Update version, CHANGELOG.md, and README.md
|
|
|
|
### API Variant Handling
|
|
- Always check `apiClient.getIsServer()` for Cloud vs Server
|
|
- Server uses `/rest/api/1.0/` prefix
|
|
- Cloud uses direct paths under base URL
|
|
- Different parameter names (e.g., pagelen vs limit)
|
|
|
|
### Error Handling Pattern
|
|
```typescript
|
|
try {
|
|
// API call
|
|
} catch (error: any) {
|
|
const errorMessage = error.response?.data?.errors?.[0]?.message || error.message;
|
|
return {
|
|
content: [{
|
|
type: 'text',
|
|
text: JSON.stringify({
|
|
error: `Failed to ${action}: ${errorMessage}`,
|
|
details: error.response?.data
|
|
}, null, 2)
|
|
}],
|
|
isError: true
|
|
};
|
|
}
|
|
```
|
|
|
|
## User Preferences
|
|
|
|
### Documentation Style
|
|
- Comprehensive examples for each tool
|
|
- Clear parameter descriptions
|
|
- Response format examples
|
|
- Note differences between Cloud and Server
|
|
|
|
### Code Style
|
|
- TypeScript with strict typing
|
|
- ES modules with .js extensions in imports
|
|
- Consistent error handling
|
|
- Modular architecture
|
|
|
|
## Project-Specific Patterns
|
|
|
|
### Authentication
|
|
- Cloud: Username (not email) + App Password
|
|
- Server: Email address + HTTP Access Token
|
|
- Environment variables for configuration
|
|
|
|
### Pagination Pattern
|
|
- `limit` and `start` parameters
|
|
- Return `has_more` and `next_start`
|
|
- Include `total_count` when available
|
|
|
|
### Response Formatting
|
|
- Consistent JSON structure
|
|
- Include operation status message
|
|
- Provide detailed error information
|
|
- Format dates as ISO strings
|
|
|
|
## Known Challenges
|
|
|
|
### Bitbucket API Differences
|
|
- Parameter naming varies (e.g., pagelen vs limit)
|
|
- Response structures differ significantly
|
|
- Some features only available on one variant
|
|
- Authentication methods completely different
|
|
|
|
### Search Functionality
|
|
- Only available on Bitbucket Server
|
|
- Query syntax requires specific format
|
|
- No Cloud API equivalent currently
|
|
|
|
## Tool Usage Patterns
|
|
|
|
### List Operations
|
|
- Always include pagination parameters
|
|
- Return consistent metadata
|
|
- Support filtering where applicable
|
|
|
|
### Modification Operations
|
|
- Validate required parameters
|
|
- Preserve existing data when updating
|
|
- Return updated resource in response
|
|
|
|
### File Operations
|
|
- Smart truncation for large files
|
|
- Type-based default limits
|
|
- Support line range selection
|
|
|
|
## Evolution of Decisions
|
|
|
|
### Version 0.3.0
|
|
- Modularized codebase into handlers
|
|
- Separated types and utilities
|
|
- Improved maintainability
|
|
|
|
### Version 0.6.0
|
|
- Enhanced PR details with comments/files
|
|
- Added parallel API calls for performance
|
|
|
|
### Version 0.9.0
|
|
- Added code snippet matching for comments
|
|
- Implemented confidence scoring
|
|
|
|
### Version 1.0.0
|
|
- Added code search functionality
|
|
- Reached feature completeness
|
|
- Ready for production use
|
|
|
|
### Version 1.0.1
|
|
- Improved search response formatting for AI consumption
|
|
- Added simplified formatCodeSearchOutput
|
|
- Enhanced HTML entity decoding and tag stripping
|
|
- Established live MCP testing workflow
|
|
|
|
## Important Architecture Decisions
|
|
|
|
### Handler Pattern
|
|
Each tool category has its own handler class to maintain single responsibility and make the codebase more maintainable.
|
|
|
|
### Type Guards
|
|
All tool inputs are validated with type guards to ensure type safety at runtime.
|
|
|
|
### Response Normalization
|
|
Different API responses are normalized to consistent formats for easier consumption.
|
|
|
|
### Error Handling
|
|
Consistent error handling across all tools with detailed error messages and recovery suggestions.
|