Jira Insights MCP

# Jira Insights MCP Improvement Summary This document provides a concise summary of the planned improvements for the Jira Insights MCP based on the feedback and limitations identified. ## Key Issues Identified 1. **Object Attribute Discovery Issues** - The `manage_jira_insight_object_type` function with the "attributes" expand parameter doesn't return attribute information - This appears to be a limitation in how the API is being called or how responses are processed 2. **AQL Query Limitations** - AQL queries consistently fail with validation errors - Error messages are generic and unhelpful - The API_MIGRATION_TODO.md file confirms there's a known issue with AQL query format 3. **Object Listing Limitations** - The `manage_jira_insight_object` function with the list operation fails - This might be related to parameter formatting issues 4. **Schema Property Inspection Limitations** - Documentation and metadata retrieval is inadequate ## Improvement Strategy ### High Priority Improvements (Completed) 1. **Enhanced Error Handling** - Created a centralized error handling utility (`src/utils/error-handler.ts`) - Provided detailed error messages with specific validation issues - Included suggested fixes in error responses - Added operation-specific examples to help users correct issues 2. **AQL Query Improvements** - Created AQL validation and formatting utilities (`src/utils/aql-utils.ts`) - Implemented validation of queries before submission to catch common errors - Added formatting of queries properly for the API - Provided schema-specific example queries 3. **Attribute Discovery Enhancement** - Implemented dedicated attribute discovery function (`src/utils/attribute-utils.ts`) - Added caching for frequently accessed attributes - Ensured proper error handling for attribute retrieval - Fixed the "expand" parameter handling for attributes ### Medium Priority Improvements (Completed) 1. **Object Template Generation** - Created template generation utility based on object types - Added type-specific placeholder generation - Included validation rules in templates - Added documentation for template usage 2. **Example Query Library** - Created schema-specific example queries - Implemented context-aware query suggestions - Added query templates for common operations - Included documentation for query patterns 3. **Improved Documentation** - Updated AQL syntax documentation with more examples - Created operation-specific documentation - Added parameter validation documentation - Documented common error scenarios and solutions ### Lower Priority Improvements 1. **Schema Explorer** - Implement schema visualization data generator - Add relationship mapping between object types - Create hierarchical view of object types - Include attribute relationship visualization 2. **Batch Operations** - Implement batch object creation - Add batch update functionality - Create transaction support for batch operations - Add detailed reporting for batch results ## Implementation Files The implementation details are spread across several files: 1. **TODO.md** - Comprehensive todo list with all tasks organized by priority 2. **IMPLEMENTATION_PLAN.md** - Detailed implementation plans for the high-priority improvements 3. **HANDLER_IMPROVEMENTS.md** - Specific changes needed for each handler file ## Implementation Completed The following steps have been completed: 1. Created the utility files: - `src/utils/error-handler.ts` - Centralized error handling with detailed messages and suggested fixes - `src/utils/aql-utils.ts` - AQL validation and formatting utilities - `src/utils/attribute-utils.ts` - Attribute discovery with caching 2. Updated the handler files to use the new utilities: - `src/handlers/schema-handlers.ts` - Enhanced error handling - `src/handlers/object-type-handlers.ts` - Added attribute discovery - `src/handlers/object-handlers.ts` - Added AQL validation and formatting - `src/handlers/resource-handlers.ts` - Added new resource templates and enhanced documentation 3. Updated the API migration TODO list to reflect progress: - `docs/API_MIGRATION_TODO.md` 4. Created a test script to verify the improvements: - `scripts/test-api.js` ## Next Steps 1. Test the improvements with various scenarios to ensure they address the identified issues. 2. Implement the lower priority features: - Schema explorer with visualization - Batch operation support - Advanced testing and validation By implementing these improvements, the Jira Insights MCP will provide better error messages, more robust AQL query handling, and enhanced attribute discovery capabilities, addressing the key limitations identified in the feedback.