Backlog MCP Server

# Progress Status ## Implemented Features ### Space-related - ✅ Retrieving space information (`get_space`) - ✅ Retrieving user lists (`get_users`) - ✅ Retrieving information about oneself (`get_myself`) - ✅ Retrieving priority lists (`get_priorities`) - ✅ Retrieving resolution lists (`get_resolutions`) - ✅ Retrieving issue type lists (`get_issue_types`) ### Project-related - ✅ Retrieving project lists (`get_project_list`) - ✅ Creating projects (`add_project`) - ✅ Retrieving project information (`get_project`) - ✅ Updating projects (`update_project`) - ✅ Deleting projects (`delete_project`) ### Issue-related - ✅ Retrieving issue information (`get_issue`) - ✅ Retrieving issue lists (`get_issues`) - ✅ Retrieving issue counts (`count_issues`) - ✅ Creating issues (`add_issue`) - ✅ Updating issues (`update_issue`) - ✅ Deleting issues (`delete_issue`) ### Comment-related - ✅ Retrieving issue comment lists (`get_issue_comments`) - ✅ Adding issue comments (`add_issue_comment`) ### Wiki-related - ✅ Retrieving Wiki page lists (`get_wiki_pages`) - ✅ Retrieving Wiki page counts (`get_wikis_count`) - ✅ Retrieving Wiki information (`get_wiki`) ### Category-related - ✅ Retrieving category lists (`get_categories`) ### Notification-related - ✅ Retrieving notification lists (`get_notifications`) - ✅ Retrieving notification counts (`count_notifications`) - ✅ Resetting unread notification counts (`reset_unread_notification_count`) - ✅ Marking notifications as read (`mark_notification_as_read`) ### Git Repository-related - ✅ Retrieving Git repository lists (`get_git_repositories`) - ✅ Retrieving Git repository information (`get_git_repository`) ### Pull Request-related - ✅ Retrieving pull request lists (`get_pull_requests`) - ✅ Retrieving pull request counts (`get_pull_requests_count`) - ✅ Retrieving pull request information (`get_pull_request`) - ✅ Creating pull requests (`add_pull_request`) - ✅ Updating pull requests (`update_pull_request`) - ✅ Retrieving pull request comment lists (`get_pull_request_comments`) - ✅ Adding pull request comments (`add_pull_request_comment`) - ✅ Updating pull request comments (`update_pull_request_comment`) ### Version/Milestone-related - ✅ Retrieving version/milestone lists (`get_version_milestone_list`) - ✅ Adding versions/milestones (`add_version_milestone`) - ✅ Updating versions/milestones (`update_version_milestone`) - ✅ Deleting versions (`delete_version`) ### Watch-related - ✅ Retrieving watched item lists (`get_watching_list_items`) - ✅ Retrieving watch counts (`get_watching_list_count`) ### Infrastructure - ✅ MCP server implementation - ✅ Tool registration system - ✅ Translation system - ✅ Docker containerization - ✅ CI/CD pipeline ## Unimplemented Features ### Watch-related - ❌ Retrieving watches (`get_watching`) - ❌ Adding watches (`add_watching`) - ❌ Updating watches (`update_watching`) - ❌ Deleting watches (`delete_watching`) - ❌ Marking watches as read (`mark_watching_as_read`) ### Attachment-related - ❌ Uploading attachments (`post_attachment_file`) - ❌ Retrieving issue attachment lists (`get_list_of_issue_attachments`) - ❌ Retrieving issue attachments (`get_issue_attachment`) - ❌ Deleting issue attachments (`delete_issue_attachment`) - ❌ Retrieving pull request attachment lists (`get_list_of_pull_request_attachment`) - ❌ Downloading pull request attachments (`download_pull_request_attachment`) - ❌ Deleting pull request attachments (`delete_pull_request_attachments`) ### Star-related - ❌ Adding stars (`add_star`) - ❌ Retrieving received star lists (`get_received_star_list`) - ❌ Retrieving user received star counts (`count_user_received_stars`) - ❌ Retrieving Wiki page stars (`get_wiki_page_star`) ### Shared File-related - ❌ Retrieving shared file lists (`get_list_of_shared_files`) - ❌ Retrieving files (`get_file`) - ❌ Retrieving issue shared file lists (`get_list_of_linked_shared_files`) - ❌ Linking shared files to issues (`link_shared_files_to_issue`) - ❌ Removing shared file links from issues (`remove_link_to_shared_file_from_issue`) - ❌ Retrieving Wiki shared file lists (`get_list_of_shared_files_on_wiki`) - ❌ Linking shared files to Wikis (`link_shared_files_to_wiki`) - ❌ Removing shared file links from Wikis (`remove_link_to_shared_file_from_wiki`) ### Other Features - ❌ Retrieving recent updates (`get_recent_updates`) - ❌ Retrieving space logos (`get_space_logo`) - ❌ Retrieving space notifications (`get_space_notification`) - ❌ Updating space notifications (`update_space_notification`) - ❌ Retrieving space disk usage (`get_space_disk_usage`) - ❌ Retrieving user icons (`get_user_icon`) - ❌ Retrieving user recent updates (`get_user_recent_updates`) - ❌ Retrieving recently viewed issue lists (`get_list_of_recently_viewed_issues`) - ❌ Retrieving recently viewed project lists (`get_list_of_recently_viewed_projects`) - ❌ Retrieving recently viewed Wiki lists (`get_list_of_recently_viewed_wikis`) - ❌ Retrieving project icons (`get_project_icon`) - ❌ Retrieving project recent updates (`get_project_recent_updates`) - ❌ Adding project users (`add_project_user`) - ❌ Retrieving project user lists (`get_project_user_list`) - ❌ Deleting project users (`delete_project_user`) - ❌ Adding project administrators (`add_project_administrator`) - ❌ Retrieving project administrator lists (`get_list_of_project_administrators`) - ❌ Deleting project administrators (`delete_project_administrator`) - ❌ Adding statuses (`add_status`) - ❌ Updating statuses (`update_status`) - ❌ Deleting statuses (`delete_status`) - ❌ Updating status orders (`update_order_of_status`) - ❌ Adding issue types (`add_issue_type`) - ❌ Updating issue types (`update_issue_type`) - ❌ Deleting issue types (`delete_issue_type`) - ❌ Adding categories (`add_category`) - ❌ Updating categories (`update_category`) - ❌ Deleting categories (`delete_category`) - ❌ Retrieving custom field lists (`get_custom_field_list`) - ❌ Adding custom fields (`add_custom_field`) - ❌ Updating custom fields (`update_custom_field`) - ❌ Deleting custom fields (`delete_custom_field`) - ❌ Adding list items for list type custom fields (`add_list_item_for_list_type_custom_field`) - ❌ Updating list items for list type custom fields (`update_list_item_for_list_type_custom_field`) - ❌ Deleting list items for list type custom fields (`delete_list_item_for_list_type_custom_field`) - ❌ Retrieving project disk usage (`get_project_disk_usage`) - ❌ Retrieving webhook lists (`get_list_of_webhooks`) - ❌ Adding webhooks (`add_webhook`) - ❌ Retrieving webhooks (`get_webhook`) - ❌ Updating webhooks (`update_webhook`) - ❌ Deleting webhooks (`delete_webhook`) - ❌ Retrieving comment counts (`count_comment`) - ❌ Retrieving comments (`get_comment`) - ❌ Deleting comments (`delete_comment`) - ❌ Updating comments (`update_comment`) - ❌ Retrieving comment notification lists (`get_list_of_comment_notifications`) - ❌ Adding comment notifications (`add_comment_notification`) - ❌ Retrieving issue participant lists (`get_issue_participant_list`) - ❌ Retrieving Wiki page tag lists (`get_wiki_page_tag_list`) - ❌ Adding Wiki pages (`add_wiki_page`) - ❌ Updating Wiki pages (`update_wiki_page`) - ❌ Deleting Wiki pages (`delete_wiki_page`) - ❌ Retrieving Wiki attachment lists (`get_list_of_wiki_attachments`) - ❌ Attaching files to Wikis (`attach_file_to_wiki`) - ❌ Retrieving Wiki page attachments (`get_wiki_page_attachment`) - ❌ Removing Wiki attachments (`remove_wiki_attachment`) - ❌ Retrieving Wiki page history (`get_wiki_page_history`) - ❌ Retrieving licenses (`get_licence`) - ❌ Retrieving team lists (`get_list_of_teams`) - ❌ Adding teams (`add_team`) - ❌ Retrieving teams (`get_team`) - ❌ Updating teams (`update_team`) - ❌ Deleting teams (`delete_team`) - ❌ Retrieving team icons (`get_team_icon`) - ❌ Retrieving project team lists (`get_project_team_list`) - ❌ Adding project teams (`add_project_team`) - ❌ Deleting project teams (`delete_project_team`) - ❌ Retrieving rate limits (`get_rate_limit`) ## Current Status Currently, the Backlog MCP Server has comprehensive functionality implemented, covering API endpoints in the following categories: - Space information - Project management - Issue management - Comment management - Wiki management - Notification management - Git repository management - Pull request management - Watch management (partial) This allows access to Backlog's main features from Claude, with optimizations for response size and token limits. ## Recent Improvements 1. **Response Optimization** - Added GraphQL-style field selection to reduce response size - Implemented token limiting to prevent large responses from exceeding limits - Added streaming for large responses with automatic truncation 2. **Error Handling** - Enhanced error handling with categorized error types - Improved error messages for better debugging - Added Backlog API-specific error parsing 3. **Documentation** - Updated README with new features and usage examples - Added Japanese translation of documentation - Improved installation and configuration instructions ## Future Plans 1. **High Priority Unimplemented Features** - Remaining watch-related features - Attachment-related features - Star-related features 2. **Medium-term Goals** - Custom field-related features - Webhook-related features - Further performance optimizations 3. **Long-term Goals** - Cover all Backlog API endpoints - Advanced pagination handling - More sophisticated error handling and recovery - Enhanced field selection capabilities ## Known Issues 1. **Large Data Processing** - While token limiting helps, pagination handling for retrieving large numbers of issues or comments could be further optimized - Some complex nested objects may not be optimally handled by field selection 2. **Error Handling Edge Cases** - Some rare API error scenarios may not be handled specifically - Error messages for certain edge cases could be improved 3. **Permission Checking** - Some API endpoints may be restricted by user permissions, but pre-checking is insufficient - Better feedback for permission-related errors would be helpful ## Evolution of Project Decisions 1. **Tool Naming Conventions** - Initially used Backlog API endpoint names directly, but changed to more intuitive names - Example: `getIssue` → `get_issue` 2. **Response Format** - Initially returned Backlog API responses directly, but changed to a more structured format - Returning as JSON strings made it easier for Claude to parse - Added field selection to allow clients to request only needed fields 3. **Multi-language Support** - Initially only supported English, but added multi-language support through configuration files - Provided Japanese translation files to improve usability in Japanese environments - Implemented translation key tracking for consistency 4. **Handler Architecture** - Initially had simple handlers, but evolved to a composed handler pattern - Added transformers for error handling, field picking, token limiting, and result formatting - Implemented a pipeline pattern for response processing 5. **Response Size Management** - Initially returned full responses, but added field selection for targeted data retrieval - Implemented token counting and limiting for large responses - Added streaming for efficient processing of large responses