feat: implement research command with enhanced context gathering - Add comprehensive research command with AI-powered queries - Implement ContextGatherer utility for reusable context extraction - Support multiple context types: tasks, files, custom text, project tree - Add fuzzy search integration for automatic task discovery - Implement detailed token breakdown display with syntax highlighting - Add enhanced UI with boxed output and code block formatting - Support different detail levels (low, medium, high) for responses - Include project-specific context for more relevant AI responses - Add token counting with gpt-tokens library integration - Create reusable patterns for future context-aware commands - Task 94.4 completed

.changeset/bright-windows-sing.md

@@ -1,5 +1,5 @@
 ---
-'task-master-ai': minor
+"task-master-ai": minor
 ---
 
 Add comprehensive AI-powered research command with intelligent context gathering and interactive follow-ups.
@@ -7,6 +7,7 @@ Add comprehensive AI-powered research command with intelligent context gathering
 The new `research` command provides AI-powered research capabilities that automatically gather relevant project context to answer your questions. The command intelligently selects context from multiple sources and supports interactive follow-up questions in CLI mode.
 
 **Key Features:**
+
 - **Intelligent Task Discovery**: Automatically finds relevant tasks and subtasks using fuzzy search based on your query keywords, supplementing any explicitly provided task IDs
 - **Multi-Source Context**: Gathers context from tasks, files, project structure, and custom text to provide comprehensive answers
 - **Interactive Follow-ups**: CLI users can ask follow-up questions that build on the conversation history while allowing fresh context discovery for each question
@@ -15,6 +16,7 @@ The new `research` command provides AI-powered research capabilities that automa
 - **Enhanced Display**: Syntax-highlighted code blocks and structured output with clear visual separation
 
 **Usage Examples:**
+
 ```bash
 # Basic research with auto-discovered context
 task-master research "How should I implement user authentication?"
@@ -30,12 +32,14 @@ task-master research "Quick implementation steps?" --context="Using JWT tokens"
 ```
 
 **Context Sources:**
+
 - **Tasks**: Automatically discovers relevant tasks/subtasks via fuzzy search, plus any explicitly specified via `--id`
 - **Files**: Include specific files via `--files` for code-aware responses
 - **Project Tree**: Add `--tree` to include project structure overview
 - **Custom Context**: Provide additional context via `--context` for domain-specific information
 
 **Interactive Features (CLI only):**
+
 - Follow-up questions that maintain conversation history
 - Fresh fuzzy search for each follow-up to discover newly relevant tasks
 - Cumulative context building across the conversation

.taskmaster/tasks/task_045.txt

@@ -1,134 +1,82 @@
 # Task ID: 45
 # Title: Implement GitHub Issue Import Feature
 # Status: pending
-# Dependencies: None
+# Dependencies: 97
 # Priority: medium
-# Description: Implement a comprehensive LLM-powered 'import_task' command that can intelligently import tasks from GitHub Issues and Discussions. The system uses our existing ContextGatherer.js infrastructure to analyze the full context of GitHub content and automatically generate well-structured tasks with appropriate subtasks, priorities, and implementation details. This feature works in conjunction with the GitHub export feature (Task #97) to provide bidirectional linking between Task Master tasks and GitHub issues.
+# Description: Add a '--from-github' flag to the add-task command that accepts a GitHub issue URL and automatically generates a corresponding task with relevant details. This feature works in conjunction with the GitHub export feature (Task #97) to provide bidirectional linking between Task Master tasks and GitHub issues.
 # Details:
-Implement a new 'import_task' command that leverages LLM-powered analysis to create comprehensive tasks from GitHub Issues and Discussions. The system should be designed as an extensible import framework that can support multiple platforms in the future.
+Implement a new flag '--from-github' for the add-task command that allows users to create tasks directly from GitHub issues. The implementation should work seamlessly with the GitHub export feature (Task #97) to provide bidirectional linking capabilities.
 
 Core functionality:
-1. **New Command Structure**: Create 'import_task' command with source-specific subcommands:
+1. Accept a GitHub issue URL as an argument (e.g., 'taskmaster add-task --from-github https://github.com/owner/repo/issues/123')
-   - 'taskmaster import_task github <URL>' for GitHub imports
+2. Parse the URL to extract the repository owner, name, and issue number
-   - Future: 'taskmaster import_task gitlab <URL>', 'taskmaster import_task linear <URL>', etc.
+3. Use the GitHub API to fetch the issue details including:
+   - Issue title (to be used as task title)
+   - Issue description (to be used as task description)
+   - Issue labels (to be potentially used as tags)
+   - Issue assignees (for reference)
+   - Issue status (open/closed)
+4. Generate a well-formatted task with this information
+5. **Automatically add GitHub link metadata** using the same schema as the export feature:
+   - Store the source GitHub issue URL in task metadata
+   - Use consistent metadata structure with export feature for bidirectional compatibility
+   - Enable future synchronization capabilities
+6. Include a reference link back to the original GitHub issue in the task description
+7. Handle authentication for private repositories using GitHub tokens from environment variables or config file
+8. Implement proper error handling for:
+   - Invalid URLs
+   - Non-existent issues
+   - API rate limiting
+   - Authentication failures
+   - Network issues
+9. **Validate GitHub links** during import to ensure they point to valid, accessible issues
+10. Allow users to override or supplement the imported details with additional command-line arguments
+11. Add appropriate documentation in help text and user guide, including information about the complementary export feature
 
-2. **Multi-Source GitHub Support**: Automatically detect and handle:
+Bidirectional Integration:
-   - GitHub Issues: https://github.com/owner/repo/issues/123
+- Use the same metadata schema as Task #97 for GitHub links
-   - GitHub Discussions: https://github.com/owner/repo/discussions/456
+- Ensure imported tasks can be identified as GitHub-linked for future export operations
-   - Auto-detect URL type and use appropriate API endpoints
+- Prepare infrastructure for future synchronization between tasks and their source issues
-
+- Maintain consistency with export feature's link management approach
-3. **LLM-Powered Context Analysis**: Integrate with ContextGatherer.js to:
-   - Fetch complete GitHub content (main post + all comments/replies)
-   - Analyze discussion threads and extract key insights
-   - Identify references to our project components and codebase
-   - Generate comprehensive task descriptions based on full context
-   - Automatically create relevant subtasks from complex discussions
-   - Determine appropriate priority levels based on content analysis
-   - Suggest dependencies based on mentioned components/features
-
-4. **Smart Content Processing**: The LLM should:
-   - Parse markdown content and preserve important formatting
-   - Extract actionable items from discussion threads
-   - Identify implementation requirements and technical details
-   - Convert complex discussions into structured task breakdowns
-   - Generate appropriate test strategies based on the scope
-   - Preserve important context while creating focused task descriptions
-
-5. **Enhanced GitHub API Integration**:
-   - Support GITHUB_API_KEY environment variable for authentication
-   - Handle both public and private repository access
-   - Fetch issue/discussion metadata (labels, assignees, status)
-   - Retrieve complete comment threads with proper threading
-   - Implement rate limiting and error handling
-
-6. **Rich Metadata Storage**:
-   - Source platform and original URL
-   - Import timestamp and LLM model version used
-   - Content hash for change detection and sync capabilities
-   - Participant information and discussion context
-   - GitHub-specific metadata (labels, assignees, status)
-   - **Use consistent metadata schema with export feature (Task #97)**
-
-7. **Future-Proof Architecture**:
-   - Modular design supporting multiple import sources
-   - Plugin-style architecture for new platforms
-   - Extensible content type handling (issues, PRs, discussions, etc.)
-   - Configurable LLM prompts for different content types
-
-8. **Bidirectional Integration**:
-   - Maintain compatibility with GitHub export feature
-   - Enable round-trip workflows (import → modify → export)
-   - Preserve source linking for synchronization capabilities
-   - Support identification of imported vs. native tasks
-
-9. **Error Handling and Validation**:
-   - Validate GitHub URLs and accessibility
-   - Handle API rate limiting gracefully
-   - Provide meaningful error messages for various failure scenarios
-   - Implement retry logic for transient failures
-   - Validate LLM responses and handle generation errors
-
-10. **Configuration and Customization**:
-    - Allow users to customize LLM prompts for task generation
-    - Support different import strategies (full vs. summary)
-    - Enable filtering of comments by date, author, or relevance
-    - Provide options for manual review before task creation
 
 # Test Strategy:
 Testing should cover the comprehensive LLM-powered import system:
 
-1. **Unit Tests**:
+1. Unit tests:
-   - Test URL parsing for GitHub Issues and Discussions
+   - Test URL parsing functionality with valid and invalid GitHub issue URLs
-   - Test GitHub API client with mocked responses
+   - Test GitHub API response parsing with mocked API responses
-   - Test LLM integration with ContextGatherer.js
+   - Test error handling for various failure cases
-   - Test metadata schema consistency with export feature
+   - **Test metadata schema consistency with export feature**
-   - Test content processing and task generation logic
+   - **Test GitHub link validation functionality**
-   - Test error handling for various failure scenarios
 
-2. **Integration Tests**:
+2. Integration tests:
-   - Test with real GitHub Issues and Discussions (public repos)
+   - Test with real GitHub public issues (use well-known repositories)
-   - Test LLM-powered analysis with various content types
+   - Test with both open and closed issues
-   - Test ContextGatherer integration with GitHub content
+   - Test with issues containing various elements (labels, assignees, comments)
-   - Test bidirectional compatibility with export feature
+   - **Test bidirectional compatibility with export feature**
-   - Test metadata structure and storage
+   - **Verify metadata structure matches export feature requirements**
-   - Test with different GitHub content complexities
 
-3. **LLM and Context Analysis Tests**:
+3. Error case tests:
-   - Test task generation quality with various GitHub content types
+   - Invalid URL format
-   - Test subtask creation from complex discussions
+   - Non-existent repository
-   - Test priority and dependency inference
+   - Non-existent issue number
-   - Test handling of code references and technical discussions
+   - API rate limit exceeded
-   - Test content summarization and structure preservation
-   - Validate LLM prompt effectiveness and response quality
-
-4. **Error Case Tests**:
-   - Invalid or malformed GitHub URLs
-   - Non-existent repositories or issues/discussions
-   - API rate limit handling
    - Authentication failures for private repos
-   - LLM service unavailability or errors
+   - **Invalid or inaccessible GitHub links**
-   - Network connectivity issues
-   - Malformed or incomplete GitHub content
 
-5. **End-to-End Tests**:
+4. End-to-end tests:
-   - Complete import workflow from GitHub URL to created task
+   - Verify that a task created from a GitHub issue contains all expected information
-   - Verify task quality and completeness
+   - **Verify that imported tasks contain proper GitHub link metadata**
-   - Test metadata preservation and linking
+   - Verify that the task can be properly managed after creation
-   - Test compatibility with existing task management features
+   - Test the interaction with other flags and commands
-   - Verify bidirectional workflow with export feature
+   - **Test compatibility with export feature workflows**
 
-6. **Performance and Scalability Tests**:
+5. **Bidirectional feature tests**:
-   - Test with large GitHub discussions (many comments)
+   - Import a GitHub issue and verify it can be exported back
-   - Test LLM processing time and resource usage
+   - Test metadata consistency between import and export operations
-   - Test API rate limiting behavior
+   - Verify link validation works correctly
-   - Test concurrent import operations
 
-7. **Future Platform Preparation Tests**:
+Create mock GitHub API responses for testing to avoid hitting rate limits during development and testing. Use environment variables to configure test credentials if needed.
-   - Test modular architecture extensibility
-   - Verify plugin-style platform addition capability
-   - Test configuration system flexibility
-
-Create comprehensive mock data for GitHub API responses including various issue/discussion types, comment structures, and edge cases. Use environment variables for test credentials and LLM service configuration.
 
 # Subtasks:
 ## 1. Design GitHub API integration architecture [pending]
@@ -173,51 +121,3 @@ Design and implement metadata structure that matches the export feature (Task #9
 ### Details:
 Verify that tasks imported from GitHub can be properly exported back to GitHub. Implement checks to prevent duplicate exports of imported issues. Add metadata flags to identify imported tasks and their source repositories. Test round-trip workflows (import → modify → export) to ensure data integrity.
 
-## 8. Design extensible import_task command architecture [pending]
-### Dependencies: None
-### Description: Create the foundational architecture for the new import_task command that supports multiple platforms and content types.
-### Details:
-Design modular command structure with platform-specific subcommands. Create plugin-style architecture for adding new import sources. Define interfaces for different content types (issues, discussions, PRs). Plan configuration system for platform-specific settings and LLM prompts. Document extensibility patterns for future platform additions.
-
-## 9. Extend GitHub URL parsing for Issues and Discussions [pending]
-### Dependencies: 45.2, 45.8
-### Description: Enhance URL parsing to support both GitHub Issues and Discussions with automatic type detection.
-### Details:
-Extend existing URL parser to handle GitHub Discussions URLs. Implement automatic detection of content type (issue vs discussion). Update validation logic for both content types. Ensure consistent data extraction for owner, repo, and content ID regardless of type.
-
-## 10. Implement comprehensive GitHub API client [pending]
-### Dependencies: 45.3, 45.9
-### Description: Create enhanced GitHub API client supporting both Issues and Discussions APIs with complete content fetching.
-### Details:
-Extend existing API client to support GitHub Discussions API. Implement complete content fetching including all comments and replies. Add support for GITHUB_API_KEY environment variable. Handle threaded discussions and comment hierarchies. Implement robust error handling and rate limiting for both API types.
-
-## 11. Integrate ContextGatherer for LLM-powered analysis [pending]
-### Dependencies: 45.10
-### Description: Integrate with existing ContextGatherer.js to enable LLM-powered analysis of GitHub content.
-### Details:
-Adapt ContextGatherer.js to work with GitHub content as input source. Create GitHub-specific context gathering strategies. Implement content preprocessing for optimal LLM analysis. Add project component identification for GitHub discussions. Create prompts for task generation from GitHub content.
-
-## 12. Implement LLM-powered task generation [pending]
-### Dependencies: 45.11
-### Description: Create the core LLM integration that analyzes GitHub content and generates comprehensive tasks with subtasks.
-### Details:
-Design LLM prompts for task generation from GitHub content. Implement automatic subtask creation from complex discussions. Add priority and dependency inference based on content analysis. Create test strategy generation from technical discussions. Implement quality validation for LLM-generated content. Add fallback mechanisms for LLM failures.
-
-## 13. Enhance metadata system for rich import context [pending]
-### Dependencies: 45.6, 45.12
-### Description: Extend the metadata schema to store comprehensive import context and enable advanced features.
-### Details:
-Extend existing metadata schema with import-specific fields. Add source platform, import timestamp, and LLM model tracking. Implement content hash storage for change detection. Store participant information and discussion context. Add support for custom metadata per platform type. Ensure backward compatibility with existing export feature metadata.
-
-## 14. Implement import_task command interface [pending]
-### Dependencies: 45.8, 45.12, 45.13
-### Description: Create the user-facing command interface for the new import_task system with GitHub support.
-### Details:
-Implement the main import_task command with GitHub subcommand. Add command-line argument parsing and validation. Create progress indicators for LLM processing. Implement user review and confirmation workflow. Add verbose output options for debugging. Create help documentation and usage examples.
-
-## 15. Add comprehensive testing and validation [pending]
-### Dependencies: 45.14
-### Description: Implement comprehensive testing suite covering all aspects of the LLM-powered import system.
-### Details:
-Create unit tests for all new components. Implement integration tests with real GitHub content. Add LLM response validation and quality tests. Create performance tests for large discussions. Implement end-to-end workflow testing. Add mock data for consistent testing. Test bidirectional compatibility with export feature.
-

.taskmaster/tasks/task_098.txt

@@ -26,19 +26,63 @@
 - Check help output and usage documentation for accuracy and completeness.
 
 # Subtasks:
-## 1. Command Registration [in-progress]
+## 1. Command Registration [done]
 ### Dependencies: None
 ### Description: Register the 'research' command with the CLI framework, ensuring it appears in the list of available commands and supports standard CLI conventions.
 ### Details:
 Integrate the new command into the CLI's command registry. Ensure it is discoverable via the CLI's help system and follows established naming and grouping conventions.
 
-## 2. Parameter and Flag Handling [pending]
+## 2. Parameter and Flag Handling [done]
 ### Dependencies: 94.1
 ### Description: Define and implement parsing for all arguments, flags, and options accepted by the 'research' command, including validation and default values.
 ### Details:
 Use a command-line parsing framework to handle parameters. Ensure support for optional and required arguments, order-independence, and clear error messages for invalid input.
+<info added on 2025-05-25T06:00:42.350Z>
+✅ **Parameter and Flag Handling Implementation Complete**
 
-## 3. Context Gathering [pending]
+Successfully implemented comprehensive parameter validation and processing for the research command:
+
+**✅ Implemented Features:**
+1. **Comprehensive Parameter Validation:**
+   - Prompt validation (required, non-empty string)
+   - Detail level validation (low, medium, high)
+   - Task ID format validation (supports "15" and "15.2" formats)
+   - File path validation (comma-separated, existence checks)
+   - Save target validation (security checks for path traversal)
+
+2. **Advanced Parameter Processing:**
+   - Comma-separated value parsing for task IDs and file paths
+   - Whitespace trimming and normalization
+   - Project root detection using `findProjectRoot()`
+   - Relative/absolute path handling for files
+   - Default value application
+
+3. **Informative Error Messages:**
+   - Specific error messages for each validation failure
+   - Clear examples of correct usage
+   - Helpful suggestions for fixing errors
+   - Much more informative than basic Commander.js errors
+
+4. **Structured Output:**
+   - Creates validated parameters object with all processed values
+   - Proper type conversion and normalization
+   - Ready for consumption by core research function
+
+**✅ Validation Examples Tested:**
+- Missing prompt: Shows Commander.js error (expected behavior)
+- Invalid detail level: "Error: Detail level must be one of: low, medium, high"
+- Invalid task ID format: "Error parsing task IDs: Invalid task ID format: "invalid_format". Expected format: "15" or "15.2""
+- Valid parameters: Successfully processes and creates structured parameter object
+
+**✅ Security Features:**
+- Path traversal protection for save targets
+- File existence validation
+- Input sanitization and trimming
+
+The parameter validation is now production-ready and follows the same patterns used throughout the Task Master codebase. Ready to proceed to subtask 94.3 (Context Gathering Utility).
+</info added on 2025-05-25T06:00:42.350Z>
+
+## 3. Context Gathering [done]
 ### Dependencies: 94.2
 ### Description: Implement logic to gather necessary context for the research operation, such as reading from files, stdin, or other sources as specified by the user.
 ### Details:
@@ -90,22 +134,159 @@ const context = await contextGatherer.gather({
 
 This utility will eliminate code duplication between task 51 (explore REPL) and task 94 (research command) while providing a robust, extensible foundation for context gathering operations.
 </info added on 2025-05-25T05:24:58.107Z>
+<info added on 2025-05-25T06:13:19.991Z>
+✅ **Context Gathering Implementation Complete**
 
-## 4. AI Service Integration [pending]
+Successfully implemented the comprehensive ContextGatherer utility in `scripts/modules/utils/contextGatherer.js`:
-### Dependencies: 94.3
+
-### Description: Integrate with the AI service to process the gathered context and parameters, handling API calls, authentication, and error management.
+**✅ Core Features Implemented:**
+
+1. **Task/Subtask Context Extraction:**
+   - ✅ Parse task IDs and subtask IDs (formats: "15", "15.2", "16,17.1")
+   - ✅ Extract task titles, descriptions, details, and dependencies from the task system
+   - ✅ Include parent task context automatically for subtasks
+   - ✅ Format task data optimally for AI consumption
+   - ✅ Proper integration with existing `findTaskById` utility function
+
+2. **File Path Context Processing:**
+   - ✅ Handle single or comma-separated file paths
+   - ✅ Implement safe file reading with comprehensive error handling
+   - ✅ Support multiple file types (JavaScript, markdown, text, JSON, etc.)
+   - ✅ Include file metadata (path, size, type, last modified)
+   - ✅ File size limits (50KB max) to prevent context explosion
+
+3. **Project File Tree Generation:**
+   - ✅ Create structured project overview with configurable depth (max 3 levels)
+   - ✅ Filter out irrelevant directories (.git, node_modules, .env files)
+   - ✅ Include file counts and directory statistics
+   - ✅ Support custom filtering patterns
+
+4. **Custom Context Integration:**
+   - ✅ Accept and merge custom context strings
+   - ✅ Maintain clear context hierarchy and organization
+   - ✅ Preserve context source attribution
+
+5. **Unified API Design:**
+   - ✅ Clean class-based API with factory function
+   - ✅ Flexible options object for configuration
+   - ✅ Multiple output formats (research, chat, system-prompt)
+   - ✅ Proper error handling and graceful degradation
+
+**✅ Output Formatting:**
+- ✅ Support for 'research', 'chat', and 'system-prompt' formats
+- ✅ Consistent context structure across different use cases
+- ✅ Optimized for AI model consumption and token efficiency
+
+**✅ Testing:**
+- ✅ Successfully tested with real task data (Task 94 and subtask 94.1)
+- ✅ Verified task context extraction works correctly
+- ✅ Confirmed proper formatting and structure
+
+**✅ Integration Ready:**
+- ✅ Designed to be shared between task 51 (explore REPL) and task 94 (research command)
+- ✅ Follows existing codebase patterns and utilities
+- ✅ Proper ES6 module exports for easy importing
+
+The ContextGatherer utility is now ready for integration into the core research function (subtask 94.4).
+</info added on 2025-05-25T06:13:19.991Z>
+
+## 4. Core Function Implementation [done]
+### Dependencies: 94.2, 94.3
+### Description: Implement the core research function in scripts/modules/task-manager/ following the add-task.js pattern
 ### Details:
-Establish a robust interface to the AI backend, manage API keys or tokens securely, and handle network or service errors gracefully.
+Create a new core function (e.g., research.js) in scripts/modules/task-manager/ that:
+- Accepts parameters: query, context options (task IDs, file paths, custom context), project tree flag, detail level
+- Implements context gathering using the contextGatherer utility from subtask 94.3
+- Integrates with ai-services-unified.js using research role
+- Handles both CLI and MCP output formats
+- Returns structured results with telemetry data
+- Follows the same parameter validation and error handling patterns as add-task.js
+<info added on 2025-05-25T06:29:01.194Z>
+✅ COMPLETED: Added loading spinner to research command
 
-## 5. Output Formatting [pending]
+**Implementation Details:**
+- Imported `startLoadingIndicator` and `stopLoadingIndicator` from ui.js
+- Added loading indicator that shows "Researching with AI..." during AI service calls
+- Properly wrapped AI service call in try/catch/finally blocks to ensure spinner stops on both success and error
+- Loading indicator only shows in CLI mode (outputFormat === 'text'), not in MCP mode
+- Follows the same pattern as add-task.js for consistent user experience
+
+**Testing:**
+- Tested with `node bin/task-master.js research "What is TypeScript?" --detail=low`
+- Confirmed spinner appears during AI processing and disappears when complete
+- Telemetry display works correctly after spinner stops
+
+The research command now provides the same polished user experience as other AI-powered commands in the system.
+</info added on 2025-05-25T06:29:01.194Z>
+
+## 5. Direct Function Implementation [pending]
 ### Dependencies: 94.4
-### Description: Format the AI-generated output according to user-specified modes (e.g., plain text, JSON), and support writing to stdout or files.
+### Description: Create the MCP direct function wrapper in mcp-server/src/core/direct-functions/ following the add-task pattern
 ### Details:
-Implement flexible output formatting, ensuring compatibility with piping and redirection. Provide clear, user-friendly output and support for machine-readable formats.
+Create a new direct function (e.g., research.js) in mcp-server/src/core/direct-functions/ that:
+- Follows the addTaskDirect pattern for parameter handling and error management
+- Uses enableSilentMode/disableSilentMode to prevent console output interference
+- Creates logger wrapper using createLogWrapper utility
+- Validates required parameters (query, projectRoot)
+- Calls the core research function with proper context (session, mcpLog, projectRoot)
+- Returns standardized result object with success/error structure
+- Handles telemetry data propagation
+- Export and register in task-master-core.js
 
-## 6. Documentation and Help [pending]
+## 6. MCP Tool Implementation [pending]
-### Dependencies: 94.1, 94.2, 94.3, 94.4, 94.5
+### Dependencies: 94.5
-### Description: Document the 'research' command, including usage examples, parameter descriptions, and integration with the CLI's --help system.
+### Description: Create the MCP tool in mcp-server/src/tools/ following the add-task tool pattern
 ### Details:
-Update CLI documentation and ensure the --help flag provides comprehensive guidance on using the command, its options, and expected outputs.
+Create a new MCP tool (e.g., research.js) in mcp-server/src/tools/ that:
+- Defines zod schema for all research command parameters (query, id, files, context, project-tree, save, detail)
+- Uses withNormalizedProjectRoot HOF to handle project path normalization
+- Calls findTasksJsonPath to locate tasks.json file
+- Invokes the direct function with proper parameter mapping
+- Uses handleApiResult for standardized response formatting
+- Registers the tool as 'research' (snake_case) in the MCP server
+- Handles errors with createErrorResponse
+- Register in mcp-server/src/tools/index.js
+- Update .cursor/mcp.json with tool definition
+
+## 7. Add research save-to-file functionality [pending]
+### Dependencies: None
+### Description: Implement functionality to save research results to /research/ folder with optional interactive prompts
+### Details:
+Add capability to save research results to files in a /research/ directory at project root. For CLI mode, use inquirer to prompt user if they want to save the research. For MCP mode, accept a saveToFile parameter.
+
+Key implementation details:
+- Create /research/ directory if it doesn't exist (similar to how tasks/ is handled)
+- Generate meaningful filenames based on query and timestamp
+- Support both CLI interactive mode (inquirer prompts) and MCP parameter mode
+- Follow project root detection pattern from add-task.js stack
+- Handle file writing with proper error handling
+- Return saved file path in response for confirmation
+
+File structure:
+- /research/YYYY-MM-DD_query-summary.md (markdown format)
+- Include query, timestamp, context used, and full AI response
+- Add metadata header with query details and context sources
+
+## 8. Add research-to-task linking functionality [pending]
+### Dependencies: 94.7
+### Description: Implement functionality to link saved research to specific tasks with interactive task selection
+### Details:
+Add capability to link research results to specific tasks by updating task details with research references. For CLI mode, use inquirer to prompt user if they want to link research to tasks and provide task selection. For MCP mode, accept linkToTasks parameter.
+
+Key implementation details:
+- Prompt user if they want to link research to existing tasks (CLI mode)
+- Provide task selection interface using inquirer with task list (ID, title, status)
+- Support multiple task selection (checkbox interface)
+- Update selected tasks' details section with research reference
+- Add timestamped research link in format: "Research: [Query Title](file:///path/to/research.md) - YYYY-MM-DD"
+- Follow add-task.js pattern for task file updates and regeneration
+- Handle task.json reading/writing with proper error handling
+- Support both single and multiple task linking
+- Return list of updated task IDs in response
+
+Research link format in task details:
+```
+## Research References
+- [How to implement authentication](file:///research/2024-01-15_authentication-research.md) - 2024-01-15
+```
 

package.json

@@ -54,14 +54,16 @@
     "ai": "^4.3.10",
     "boxen": "^8.0.1",
     "chalk": "^5.4.1",
+    "cli-highlight": "^2.1.11",
     "cli-table3": "^0.6.5",
     "commander": "^11.1.0",
     "cors": "^2.8.5",
     "dotenv": "^16.3.1",
     "express": "^4.21.2",
-    "fastmcp": "^1.20.5",
+    "fastmcp": "^2.2.2",
     "figlet": "^1.8.0",
     "fuse.js": "^7.1.0",
+    "gpt-tokens": "^1.3.14",
     "gradient-string": "^3.0.0",
     "helmet": "^8.1.0",
     "inquirer": "^12.5.0",
@@ -70,6 +72,7 @@
     "ollama-ai-provider": "^1.2.0",
     "openai": "^4.89.0",
     "ora": "^8.2.0",
+    "task-master-ai": "^0.15.0",
     "uuid": "^11.1.0",
     "zod": "^3.23.8"
   },

scripts/modules/commands.js

@@ -1444,7 +1444,7 @@ function registerCommands(programInstance) {
 			'Additional custom context to include in the research prompt'
 		)
 		.option(
-			'-t, --tree',
+			'--project-tree',
 			'Include project file tree structure in the research context'
 		)
 		.option(
@@ -1578,7 +1578,7 @@ function registerCommands(programInstance) {
 				taskIds: taskIds,
 				filePaths: filePaths,
 				customContext: options.context ? options.context.trim() : null,
-				includeProjectTree: !!options.tree,
+				includeProjectTree: !!options.projectTree,
 				saveTarget: options.save ? options.save.trim() : null,
 				detailLevel: options.detail ? options.detail.toLowerCase() : 'medium',
 				tasksPath: tasksPath,

scripts/modules/task-manager.js

@@ -50,7 +50,7 @@ export {
 	taskExists,
 	isTaskDependentOn,
 	moveTask,
-	performResearch,
 	readComplexityReport,
-	migrateProject
+	migrateProject,
+	performResearch
 };

scripts/modules/ui.js

@@ -924,6 +924,11 @@ function displayHelp() {
 					name: 'expand --all',
 					args: '[--force] [--research]',
 					desc: 'Expand all pending tasks with subtasks'
+				},
+				{
+					name: 'research',
+					args: '"<prompt>" [-i=<task_ids>] [-f=<file_paths>] [-c="<context>"] [--project-tree] [-s=<save_file>] [-d=<detail_level>]',
+					desc: 'Perform AI-powered research queries with project context'
 				}
 			]
 		},

scripts/modules/utils/fuzzyTaskSearch.js

@@ -276,11 +276,7 @@ export class FuzzyTaskSearch {
 	 * @returns {Array<string>} Array of task ID strings
 	 */
 	getTaskIds(searchResults) {
-		return searchResults.results.map((task) => {
+		return searchResults.results.map((task) => task.id.toString());
-			// Use searchableId if available (for flattened tasks with subtasks)
-			// Otherwise fall back to regular id
-			return task.searchableId || task.id.toString();
-		});
 	}
 
 	/**