Targetprocess MCP Server

# Target Process MCP Server Improvements ## Current Batch (Claude Feedback) ### Entity Type Validation - [x] Expand entity type enums in all tool schemas to include Epic, Portfolio Epics, Solutions, etc. - [x] Update ResourceType in base.types.ts to ensure it's comprehensive - [x] Add dynamic entity type validation that queries the Target Process API - [x] Added getValidEntityTypes method to fetch valid entity types from the API - [x] Update validateEntityType to use dynamic validation with caching - [x] Implement better error messages when an invalid entity type is provided - [x] Added validateEntityType method with detailed error messages - [x] Updated all API methods to use validateEntityType ### Query Syntax - [ ] Refactor validateWhereClause method to be more flexible - [ ] Improve error handling for query parsing with more descriptive messages - [ ] Add query validation step before sending to the API - [ ] Support both searchPresets pattern and direct queries more robustly - [ ] Add examples and documentation for complex query patterns ### Search Parameter Handling - [ ] Add a validation layer that checks parameters before sending them to Target Process - [ ] Provide clearer feedback on what's wrong with the parameters - [ ] Implement parameter normalization to handle common input variations - [ ] Add detailed logging for debugging parameter issues ### Preset Query Library - [ ] Expand the searchPresets to cover more common scenarios - [ ] Add documentation for each preset - [ ] Implement a more robust variable substitution system - [ ] Add support for combining multiple presets ### Relationship Exploration - [ ] Add a new tool for exploring entity relationships - [ ] Implement metadata endpoints that return the entity model schema - [ ] Create visualization tools for entity relationships - [ ] Add helper methods for navigating between related entities ### Batch Queries - [ ] Implement a batch query capability for fetching multiple entity types - [ ] Add support for relationship-based queries - [ ] Optimize performance for large result sets - [ ] Add result caching for frequently accessed data ### Pagination Support - [ ] Add explicit pagination controls with total count information - [ ] Implement cursor-based pagination for large result sets - [ ] Add pagination metadata to response objects - [ ] Create helper methods for navigating paginated results ### Documentation - [ ] Generate OpenAPI specification for the MCP server endpoints - [ ] Add comprehensive examples for each tool - [ ] Create a user guide with common usage patterns - [ ] Document the Target Process data model - [ ] Enhance tool descriptions to highlight metadata discovery capabilities - [ ] Update inspect_object description to mention error-based discovery - [ ] Add code comments explaining how errors can be used for exploration ### API Exploration - [ ] Add simple API discovery mechanism - [ ] Add "discover_api_structure" action to inspect_object tool - [ ] Extract entity types from error messages - [ ] Update tool description to mention discovery capabilities - [ ] Improve entity type discovery mechanisms - [ ] Expose getValidEntityTypes method more prominently for API exploration - [ ] Add helper method for exploring entity type hierarchies - [ ] Document entity type relationships and inheritance ### Query Builder - [ ] Develop a query builder component to construct valid queries - [ ] Add syntax validation for queries - [ ] Implement query templates for common patterns - [ ] Add support for complex conditions and grouping ### Result Transformation - [ ] Add options to transform results into simplified formats - [ ] Implement different view modes (hierarchical, flat, graph) - [ ] Add filtering and sorting options for results - [ ] Create helper methods for extracting specific data ### Mermaid Generation - [ ] Add a feature to generate Mermaid diagrams from query results - [ ] Implement relationship visualization - [ ] Add support for different diagram types - [ ] Create customization options for diagrams ## Implementation Phases ### Phase 1: Critical Fixes (Weeks 1-2) - [x] Expand entity type support - [ ] Fix query syntax handling - [x] Improve error messages and parameter validation - [x] Added better error messages for entity type validation - [x] Improved error handling in API methods - [ ] Improve query parameter validation - [x] Implement dynamic entity type validation with caching ### Phase 2: Core Enhancements (Weeks 3-4) - [ ] Enhance preset query library - [ ] Implement relationship exploration - [ ] Add basic pagination support - [ ] Add API discovery capabilities - [ ] Implement "discover_api_structure" action - [ ] Enhance entity type discovery mechanisms ### Phase 3: Advanced Features (Weeks 5-6) - [ ] Implement batch queries - [ ] Add result transformation options - [ ] Create Mermaid diagram generation ### Phase 4: Documentation and Refinement (Weeks 7-8) - [ ] Generate OpenAPI documentation - [ ] Create comprehensive examples - [ ] Refine and optimize based on usage patterns # Future Improvements ## API Integration - [x] Add proper error handling to extract and display API error messages - [x] Implement retry logic with exponential backoff - [ ] Add rate limiting handling - [ ] Investigate and fix 400 errors with complex where clauses - [ ] Document the exact where clause syntax supported by the TargetProcess API ## Query Capabilities - [x] Fix orderBy functionality in search queries - [x] Add support for complex filtering with multiple conditions - [x] Implement proper escaping for special characters in where clauses - [x] Add validation for query syntax before making API calls - [x] Support more advanced search operators (contains, startswith, etc.) - [ ] Add support for date range queries - [ ] Add support for nested entity filtering ## Documentation - [ ] Update USECASES.md with correct query syntax examples - [ ] Add troubleshooting section with common error solutions - [ ] Document limitations and differences from TargetProcess web interface - [ ] Add examples for each supported query operator - [ ] Include real-world use case examples with working queries ## Error Handling - [x] Improve error messages to be more user-friendly - [x] Added better error messages for entity type validation - [x] Improved error handling in API methods to preserve original error details - [ ] Add specific error types for common failure cases - [ ] Include suggestions for fixing common errors - [ ] Add logging for debugging complex queries - [ ] Implement proper stack traces for debugging ## Entity Support - [x] Add support for Team entity type in search - [x] Add support for Project entity type in search - [x] Add support for Release entity type in search - [x] Add support for Iteration entity type in search - [ ] Support custom field filtering in queries ## Testing - [ ] Add tests for complex query scenarios - [ ] Add tests for error handling - [ ] Add integration tests with real API - [ ] Add performance tests for large result sets - [ ] Add test coverage for all entity types ## Features - [ ] Add bulk operation support - [ ] Add batch query support - [ ] Support custom field updates - [ ] Add support for entity relations - [ ] Add support for comments and attachments ## Performance - [ ] Implement result caching - [ ] Add query optimization - [ ] Implement connection pooling - [ ] Add request batching - [ ] Optimize large result set handling ## Security - [ ] Add input sanitization for query parameters - [ ] Implement proper credential handling - [ ] Add support for token-based authentication - [ ] Add request signing - [ ] Add audit logging ## Developer Experience - [ ] Add query builder helper - [ ] Improve TypeScript type definitions - [ ] Add more code examples - [ ] Create interactive documentation - [ ] Add CLI tools for testing queries ## Monitoring - [ ] Add performance metrics - [ ] Add error tracking - [ ] Add usage analytics - [ ] Add health checks - [ ] Add alerting for API issues