hawkeye-mcp-server 1.0.0

package/SPECIFICATION.md

@@ -0,0 +1,1073 @@
+# Hawkeye MCP Server - Comprehensive Specification
+
+## Overview
+
+The Hawkeye MCP (Model Context Protocol) Server enables AI coding agents (like Cursor.ai) to investigate cloud environment issues by leveraging Hawkeye's automated incident analysis and root cause analysis capabilities. This server acts as a bridge between coding agents and the Hawkeye API, providing intelligent, context-aware tools for cloud incident investigation.
+
+## Use Cases
+
+### Primary Use Case
+A developer using Cursor.ai encounters an alert or incident in their cloud environment. They can:
+1. Ask Cursor to investigate an alert by providing an alert ID
+2. Request a new investigation with a custom prompt and timeframe
+3. Get status updates on ongoing investigations
+4. Retrieve and analyze completed RCAs
+5. Follow up on existing investigations with additional questions
+
+### Developer Experience Goals
+- **Natural Language Interface**: Developers should be able to say "investigate alert XYZ" or "analyze my EKS cluster for the last 2 hours"
+- **Intelligent Defaults**: The server should automatically handle project selection, timeframe formatting, and session management
+- **Streaming Support**: Real-time feedback during long-running investigations
+- **Context Awareness**: Remember previous investigations and allow follow-up questions
+
+## Architecture
+
+### Components
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Cursor.ai / AI Agent                  │
+└──────────────────────┬──────────────────────────────────┘
+                       │ MCP Protocol
+┌──────────────────────▼──────────────────────────────────┐
+│               Hawkeye MCP Server                         │
+│  ┌──────────────────────────────────────────────────┐   │
+│  │  Tool Handlers:                                   │   │
+│  │  • investigate_alert_by_id                        │   │
+│  │  • create_investigation                           │   │
+│  │  • get_investigation_status                       │   │
+│  │  • get_rca_by_alert_id                           │   │
+│  │  • continue_investigation                         │   │
+│  │  • list_projects                                  │   │
+│  │  • list_sessions                                  │   │
+│  │  • inspect_session                                │   │
+│  │  • get_session_report                             │   │
+│  │  • get_session_summary                            │   │
+│  │  • get_incident_report                            │   │
+│  └──────────────────────────────────────────────────┘   │
+│  ┌──────────────────────────────────────────────────┐   │
+│  │  Core Services:                                   │   │
+│  │  • AuthenticationService                          │   │
+│  │  • SessionManager                                 │   │
+│  │  • ProjectManager                                 │   │
+│  │  • TimeframeParser                                │   │
+│  │  • StreamingHandler                               │   │
+│  └──────────────────────────────────────────────────┘   │
+└──────────────────────┬──────────────────────────────────┘
+                       │ HTTPS/REST
+┌──────────────────────▼──────────────────────────────────┐
+│                  Hawkeye API                             │
+│  • /api/v1/project                                       │
+│  • /api/v1/inference/session/list                        │
+│  • /api/v1/inference/new_session                         │
+│  • /api/v1/inference/session                             │
+│  • /api/v1/inference/session/inspect                     │
+│  • /api/v1/inference/session_report                      │
+│  • /api/v1/inference/session/summary/{uuid}              │
+│  • /api/v1/inference/incident_report                     │
+│  • /api/v1/user/login                                    │
+└──────────────────────────────────────────────────────────┘
+```
+
+## MCP Tools Specification
+
+### 1. `hawkeye_investigate_alert`
+
+**Description**: Finds an existing RCA or creates a new investigation for a specific alert/incident ID.
+
+**Input Schema**:
+```typescript
+{
+  alert_id: string;           // Full alert ID (e.g., /subscriptions/.../alerts/...)
+  project_uuid?: string;      // Optional: if not provided, will auto-detect
+  wait_for_completion?: boolean; // Default: false. If true, polls until complete
+  max_wait_seconds?: number;  // Default: 300 (5 minutes)
+}
+```
+
+**Behavior**:
+1. Searches for existing sessions associated with the alert_id
+2. If found, returns the latest RCA
+3. If not found, creates a new investigation session
+4. If `wait_for_completion` is true, polls for completion
+5. Returns investigation status and results
+
+**Output**:
+```typescript
+{
+  status: "found_existing" | "new_investigation" | "in_progress" | "completed";
+  session_uuid: string;
+  investigation_results?: {
+    final_answer: string;
+    chain_of_thoughts: Array<{
+      description: string;
+      investigation: string;
+    }>;
+    sources: Array<any>;
+    follow_up_suggestions: string[];
+  };
+  message: string;
+}
+```
+
+### 2. `hawkeye_create_investigation`
+
+**Description**: Creates a new custom investigation with a user-provided prompt and timeframe.
+
+**Input Schema**:
+```typescript
+{
+  prompt: string;             // Investigation prompt
+  timeframe?: string;         // Natural language timeframe (e.g., "last 2 hours", "past week")
+  start_time?: string;        // ISO 8601 timestamp
+  end_time?: string;          // ISO 8601 timestamp
+  project_uuid?: string;      // Optional: if not provided, will auto-detect or use default
+  wait_for_completion?: boolean; // Default: false
+  max_wait_seconds?: number;  // Default: 300 (5 minutes)
+  stream_updates?: boolean;   // Default: false. If true, provides real-time updates
+}
+```
+
+**Behavior**:
+1. Validates and parses timeframe into proper format
+2. Enhances prompt to include timeframe context
+3. Selects appropriate project (auto-detect or use default)
+4. Creates new session
+5. Sends investigation prompt
+6. Optionally waits for completion or streams results
+
+**Output**:
+```typescript
+{
+  session_uuid: string;
+  status: "created" | "in_progress" | "completed";
+  enhanced_prompt: string;    // Shows how the prompt was enhanced
+  timeframe_parsed: {
+    start: string;
+    end: string;
+    description: string;
+  };
+  investigation_results?: {
+    // Same as hawkeye_investigate_alert
+  };
+}
+```
+
+### 3. `hawkeye_get_investigation_status`
+
+**Description**: Gets the current status and results of an ongoing or completed investigation.
+
+**Input Schema**:
+```typescript
+{
+  session_uuid: string;
+  project_uuid?: string;      // Optional: will be auto-detected if not provided
+  include_full_details?: boolean; // Default: true
+}
+```
+
+**Output**:
+```typescript
+{
+  session_uuid: string;
+  status: "in_progress" | "completed" | "failed" | "unknown";
+  progress_percentage?: number;
+  current_step?: string;
+  investigation_results?: {
+    // Same as hawkeye_investigate_alert
+  };
+  created_at: string;
+  updated_at: string;
+}
+```
+
+### 4. `hawkeye_continue_investigation`
+
+**Description**: Asks a follow-up question or provides additional context to an existing investigation.
+
+**Input Schema**:
+```typescript
+{
+  session_uuid: string;
+  follow_up_prompt: string;
+  project_uuid?: string;
+  wait_for_completion?: boolean;
+  max_wait_seconds?: number;
+}
+```
+
+**Output**: Same as `hawkeye_create_investigation`
+
+### 5. `hawkeye_list_projects`
+
+**Description**: Lists all available Hawkeye projects for the authenticated user.
+
+**Input Schema**:
+```typescript
+{
+  include_inactive?: boolean; // Default: false
+}
+```
+
+**Output**:
+```typescript
+{
+  projects: Array<{
+    uuid: string;
+    name: string;
+    description: string;
+    state: string;
+    sync_state: string;
+    training_state: string;
+    created_at: string;
+    updated_at: string;
+  }>;
+  default_project?: string; // UUID of the default project
+}
+```
+
+### 6. `hawkeye_list_sessions`
+
+**Description**: Lists sessions for a project with pagination, date filtering, and investigation status filtering support.
+
+**Input Schema**:
+```typescript
+{
+  project_uuid?: string;           // Optional: uses default if not provided
+  page?: number;                   // Page number (1-indexed), default: 1
+  limit?: number;                  // Results per page (max 100), default: 50
+  date_from?: string;              // ISO 8601 date or date string (e.g., "2024-01-01")
+  date_to?: string;                // ISO 8601 date or date string
+  organization_uuid?: string;      // Optional: defaults to ORGANIZATION_NAME_ROOT
+  only_uninvestigated?: boolean;   // Convenience: filter for uninvestigated incidents
+  investigation_status?: string;   // Filter by investigation status (e.g., "INVESTIGATION_STATUS_NOT_STARTED")
+  session_type?: string;           // Filter by session type (e.g., "SESSION_TYPE_INCIDENT")
+  hide_grouped_incidents?: boolean; // If true, hides grouped incidents, default: false
+}
+```
+
+**Behavior**:
+1. Retrieves list of sessions for specified project
+2. Supports pagination using page/limit parameters
+3. Can filter by date range using create_time field
+4. Can filter by investigation status (e.g., not started, in progress, completed)
+5. Can filter by session type (e.g., incident vs manual investigations)
+6. Convenience parameter `only_uninvestigated` automatically sets investigation_status to "INVESTIGATION_STATUS_NOT_STARTED" and session_type to "SESSION_TYPE_INCIDENT"
+7. Can optionally hide grouped incidents
+8. Returns sessions sorted by creation time (most recent first)
+
+**Output**:
+```typescript
+{
+  sessions: Array<{
+    session_uuid: string;
+    name: string;
+    create_time: string;
+    last_update: string;
+    prompt_cycle_count: number;
+    incident_info?: {
+      id: string;
+      title?: string;
+      priority?: string;
+      status?: string;
+      type?: string;
+      grouped_incidents?: {
+        id: string[];
+        reason: string;
+      };
+    };
+  }>;
+  page: number;
+  limit: number;
+  count: number;
+  project_uuid: string;
+  filters_applied: {
+    date_from?: string;
+    date_to?: string;
+    investigation_status?: string;
+    session_type?: string;
+    only_uninvestigated?: boolean;
+    hide_grouped_incidents?: boolean;
+  };
+}
+```
+
+### 7. `hawkeye_inspect_session`
+
+**Description**: Gets detailed information about a session including all prompt cycles, chain of thoughts, sources, and follow-up suggestions.
+
+**Input Schema**:
+```typescript
+{
+  session_uuid: string;
+  project_uuid?: string;      // Optional: will auto-detect if not provided
+  organization_uuid?: string; // Optional: defaults to ORGANIZATION_NAME_ROOT
+}
+```
+
+**Behavior**:
+1. Retrieves full session details using /api/v1/inference/session/inspect
+2. Returns all prompt cycles with detailed information
+3. Includes chain of thoughts (analysis steps)
+4. Includes sources used in the investigation
+5. Includes follow-up suggestions
+
+**Output**:
+```typescript
+{
+  session_info: {
+    session_uuid: string;
+    name: string;
+    create_time: string;
+    last_update: string;
+  };
+  prompt_cycles: Array<{
+    id: string;
+    status: string; // PROMPT_STATUS_COMPLETED, PROMPT_STATUS_ERROR, etc.
+    request: {
+      messages: Array<{
+        content: {
+          content_type: string;
+          parts: string[];
+        };
+      }>;
+    };
+    final_answer?: string;
+    chain_of_thoughts: Array<{
+      description: string;
+      investigation?: string;
+    }>;
+    sources: Array<{
+      id?: string;
+      title?: string;
+      // ... other source fields
+    }>;
+    follow_up_suggestions: string[];
+  }>;
+}
+```
+
+### 8. `hawkeye_get_session_report`
+
+**Description**: Gets a summary report for one or more sessions, including time saved metrics.
+
+**Input Schema**:
+```typescript
+{
+  session_uuids: string[];    // Array of session UUIDs (can be single or multiple)
+  project_uuid: string;       // Required: project UUID
+}
+```
+
+**Behavior**:
+1. Retrieves session reports using GET /api/v1/inference/session_report
+2. Can fetch reports for multiple sessions in one call
+3. Includes summary and time-saved metrics
+
+**Output**:
+```typescript
+{
+  reports: Array<{
+    create_time: string;
+    prompt: string;
+    session_link: string;
+    summary: string;
+    time_saved: number; // in seconds
+  }>;
+}
+```
+
+### 9. `hawkeye_get_session_summary`
+
+**Description**: Gets detailed analysis and scoring for a session, including accuracy and completeness metrics.
+
+**Input Schema**:
+```typescript
+{
+  session_uuid: string;
+}
+```
+
+**Behavior**:
+1. Retrieves session summary using GET /api/v1/inference/session/summary/{uuid}
+2. Returns detailed scoring information if available
+3. Includes qualitative feedback and improvement suggestions
+
+**Output**:
+```typescript
+{
+  analysis_score?: {
+    accuracy: {
+      root_cause_correct: 'Yes' | 'No' | 'Partial';
+      impact_analysis_correct: 'Yes' | 'No' | 'Partial';
+      timeline_accurate: 'Yes' | 'No' | 'Partial';
+      overall_score: number;
+    };
+    completeness: {
+      data_sources: number;
+      remediation_steps: number;
+      prevention_measures: number;
+      business_impact: number;
+      overall_score: number;
+    };
+    qualitative: {
+      trust_without_review: 'Yes' | 'No' | 'Maybe';
+      missing_elements: string;
+      additional_notes: string;
+      improvement_suggestions: string;
+    };
+    scored_by: string;
+    scored_during_call: boolean;
+    call_recording_url: string | null;
+  };
+}
+```
+
+### 10. `hawkeye_get_incident_report`
+
+**Description**: Gets comprehensive incident statistics and analytics across all investigations.
+
+**Input Schema**:
+```typescript
+{
+  // No parameters required - returns organization-wide stats
+}
+```
+
+**Behavior**:
+1. Retrieves incident report using GET /api/v1/inference/incident_report
+2. Returns organization-wide incident analytics
+3. Includes time saved metrics, MTTR, and noise reduction stats
+
+**Output**:
+```typescript
+{
+  avg_investigation_time_saved_minutes: number;
+  avg_mttr: number; // Mean Time To Resolution
+  end_time: string;
+  start_time: string;
+  incident_type_reports: Array<{
+    incident_type: string;
+    priority_reports: Array<{
+      avg_investigation_time_minutes: number;
+      avg_mttr: number;
+      avg_time_saved_minutes: number;
+      investigated_incidents: number;
+      percent_grouped: number;
+      priority: string; // e.g., "P1", "P2", "P3"
+      total_incidents: number;
+    }>;
+  }>;
+  noise_reduction: number; // Percentage
+  total_incidents: number;
+  total_investigation_time_saved_hours: number;
+  total_investigations: number;
+}
+```
+
+### 11. `hawkeye_configure_defaults`
+
+**Description**: Sets default project and preferences for the session.
+
+**Input Schema**:
+```typescript
+{
+  default_project_uuid?: string;
+  default_organization_uuid?: string;
+  default_timeframe?: string; // e.g., "last 1 hour"
+  enable_streaming?: boolean;
+}
+```
+
+**Output**:
+```typescript
+{
+  status: "configured";
+  current_defaults: {
+    project_uuid: string;
+    organization_uuid: string;
+    timeframe: string;
+    streaming_enabled: boolean;
+  };
+}
+```
+
+## Filtering and Search Capabilities
+
+### Investigation Status Filtering
+
+The `hawkeye_list_sessions` tool supports filtering sessions by investigation status. This allows you to find incidents based on whether they've been investigated or not.
+
+**Supported Investigation Statuses**:
+- `INVESTIGATION_STATUS_NOT_STARTED` - Incidents that have not been investigated yet
+- `INVESTIGATION_STATUS_IN_PROGRESS` - Investigations currently in progress
+- `INVESTIGATION_STATUS_COMPLETED` - Completed investigations
+
+**Example - Find uninvestigated incidents**:
+```json
+{
+  "investigation_status": "INVESTIGATION_STATUS_NOT_STARTED",
+  "session_type": "SESSION_TYPE_INCIDENT"
+}
+```
+
+**Convenience Parameter**:
+For the common use case of finding uninvestigated incidents, use the `only_uninvestigated` parameter:
+```json
+{
+  "only_uninvestigated": true
+}
+```
+This automatically sets both `investigation_status` and `session_type` to the appropriate values.
+
+### Session Type Filtering
+
+Filter sessions by their type to distinguish between automated incident investigations and manual investigations.
+
+**Supported Session Types**:
+- `SESSION_TYPE_INCIDENT` - Automated incident investigations triggered by alerts
+- `SESSION_TYPE_MANUAL` - Manual investigations created by users
+
+### Date Range Filtering
+
+Filter sessions by creation date using `date_from` and `date_to` parameters:
+
+```json
+{
+  "date_from": "2024-01-01",
+  "date_to": "2024-01-31"
+}
+```
+
+Supports:
+- ISO 8601 date strings (e.g., "2024-01-01")
+- ISO 8601 datetime strings (e.g., "2024-01-01T00:00:00Z")
+
+### Grouped Incidents
+
+Some incidents may be automatically grouped by Hawkeye when they share similar characteristics. Use the `hide_grouped_incidents` parameter to exclude these from results:
+
+```json
+{
+  "hide_grouped_incidents": true
+}
+```
+
+### Combining Filters
+
+All filters can be combined for precise queries:
+
+```json
+{
+  "project_uuid": "74acc801-3428-4292-8a74-ae16ecb71c24",
+  "only_uninvestigated": true,
+  "date_from": "2024-01-01",
+  "hide_grouped_incidents": true,
+  "limit": 20
+}
+```
+
+## Core Services
+
+### AuthenticationService
+
+**Responsibilities**:
+- Authenticate using email/password from environment variables
+- Cache authentication tokens
+- Refresh tokens before expiry
+- Handle authentication failures gracefully
+
+**Configuration**:
+```typescript
+{
+  HAWKEYE_EMAIL: string;      // From .env
+  HAWKEYE_PASSWORD: string;   // From .env
+  HAWKEYE_BASE_URL: string;   // From .env, default: https://sandbox.app.neubird.ai/api
+  TOKEN_REFRESH_BUFFER: number; // Default: 5 minutes before expiry
+}
+```
+
+### SessionManager
+
+**Responsibilities**:
+- Create and manage investigation sessions
+- Send prompts to sessions
+- Poll for session completion
+- Inspect session details
+- Retrieve investigation results
+- Handle streaming responses
+
+**Key Methods**:
+```typescript
+async createSession(projectUuid: string, organizationUuid: string): Promise<Session>;
+async sendPrompt(sessionUuid: string, projectUuid: string, prompt: string, options?: PromptOptions): Promise<PromptResponse>;
+async inspectSession(sessionUuid: string, projectUuid: string, organizationUuid: string): Promise<SessionDetails>;
+async pollForCompletion(sessionUuid: string, maxAttempts: number, intervalMs: number): Promise<SessionDetails>;
+async findSessionsByAlertId(alertId: string, projectUuid: string, organizationUuid: string): Promise<Session[]>;
+```
+
+### ProjectManager
+
+**Responsibilities**:
+- List available projects
+- Get project details
+- Auto-select appropriate project based on context
+- Manage project preferences
+
+**Key Methods**:
+```typescript
+async listProjects(): Promise<Project[]>;
+async getProject(projectUuid: string): Promise<Project>;
+async getDefaultProject(): Promise<Project>;
+async setDefaultProject(projectUuid: string): Promise<void>;
+```
+
+### TimeframeParser
+
+**Responsibilities**:
+- Parse natural language timeframes (e.g., "last 2 hours", "past 24 hours", "yesterday")
+- Convert to ISO 8601 timestamps
+- Validate timeframe inputs
+- Provide intelligent defaults
+
+**Supported Formats**:
+- "last X hours/minutes/days/weeks"
+- "past X hours/minutes/days/weeks"
+- "since YYYY-MM-DD"
+- "between YYYY-MM-DD and YYYY-MM-DD"
+- ISO 8601 timestamps
+- Relative time strings
+
+**Key Methods**:
+```typescript
+parseTimeframe(input: string): { start: Date, end: Date, description: string };
+formatForPrompt(timeframe: { start: Date, end: Date }): string;
+validateTimeframe(start: Date, end: Date): boolean;
+```
+
+### StreamingHandler
+
+**Responsibilities**:
+- Handle Server-Sent Events (SSE) from Hawkeye API
+- Parse streaming response chunks
+- Extract progress updates
+- Detect completion
+- Aggregate final results
+
+**Key Methods**:
+```typescript
+async streamPromptResponse(sessionUuid: string, projectUuid: string, prompt: string, onProgress: (data: ProgressUpdate) => void): Promise<CompletedResponse>;
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Required
+HAWKEYE_EMAIL=user@example.com
+HAWKEYE_PASSWORD=your_password
+HAWKEYE_BASE_URL=https://your-app.app.neubird.ai/api
+
+# Optional
+HAWKEYE_DEFAULT_PROJECT_UUID=uuid-here
+HAWKEYE_DEFAULT_ORGANIZATION_UUID=ORGANIZATION_NAME_ROOT
+HAWKEYE_DEFAULT_TIMEFRAME="last 1 hour"
+HAWKEYE_ENABLE_STREAMING=true
+HAWKEYE_MAX_POLL_ATTEMPTS=30
+HAWKEYE_POLL_INTERVAL_MS=2000
+```
+
+### Server Configuration
+
+```typescript
+{
+  name: "hawkeye-mcp-server",
+  version: "2.0.0",
+  capabilities: {
+    tools: {},
+    logging: {},
+    resources: {} // For caching investigation results
+  }
+}
+```
+
+## Error Handling
+
+### Error Types
+
+1. **Authentication Errors**
+   - Invalid credentials
+   - Token expiration
+   - Network connectivity issues
+
+2. **API Errors**
+   - Rate limiting
+   - Invalid requests
+   - Server errors
+   - Timeouts
+
+3. **Validation Errors**
+   - Invalid alert IDs
+   - Invalid timeframes
+   - Missing required parameters
+
+4. **Investigation Errors**
+   - Session creation failures
+   - Prompt sending failures
+   - Investigation timeouts
+   - No results found
+
+### Error Response Format
+
+```typescript
+{
+  error: {
+    type: "authentication" | "api" | "validation" | "investigation" | "unknown";
+    message: string;
+    details?: any;
+    recovery_suggestions?: string[];
+  }
+}
+```
+
+## Performance Considerations
+
+### Caching Strategy
+
+1. **Authentication Tokens**: Cache for 55 minutes (with 5-minute buffer)
+2. **Project List**: Cache for 5 minutes
+3. **Completed Investigations**: Cache for 1 hour
+4. **Session Status**: No caching (always fetch fresh)
+
+### Rate Limiting
+
+- Implement exponential backoff for API requests
+- Respect API rate limits (if specified by Hawkeye)
+- Queue requests if necessary
+
+### Optimization
+
+- Parallel project and session listing when possible
+- Lazy-load investigation details
+- Stream large responses
+- Compress request/response payloads where supported
+
+## Security Considerations
+
+1. **Credential Management**
+   - Never log passwords or tokens
+   - Store credentials in environment variables only
+   - Clear sensitive data from memory after use
+
+2. **Input Validation**
+   - Validate all user inputs
+   - Sanitize alert IDs and prompts
+   - Prevent injection attacks
+
+3. **Output Sanitization**
+   - Strip potentially sensitive information from responses
+   - Sanitize HTML in investigation results
+
+## Testing Strategy
+
+### Unit Tests
+
+- Test each service independently
+- Mock API responses
+- Validate input/output schemas
+- Test error handling paths
+
+### Integration Tests
+
+- Test against Hawkeye staging/sandbox environment
+- Validate end-to-end workflows
+- Test streaming functionality
+- Test timeout handling
+
+### E2E Tests with Cursor
+
+- Test natural language interactions
+- Validate agent understanding of tool outputs
+- Test multi-turn investigations
+- Test error recovery
+
+## Implementation Phases
+
+### Phase 1: Core Infrastructure ✅ (COMPLETED)
+- Authentication service
+- Session manager
+- Project manager
+- Basic MCP tool scaffolding
+- `hawkeye_list_projects`
+
+### Phase 2: Investigation Tools ✅ (COMPLETED)
+- `hawkeye_investigate_alert`
+- `hawkeye_get_investigation_status`
+- `hawkeye_continue_investigation`
+
+### Phase 3: Session Management & Analytics ✅ (COMPLETED)
+- `hawkeye_list_sessions` - List sessions with pagination, date filtering, and investigation status filtering
+  - Supports filtering by investigation_status (e.g., not started, in progress, completed)
+  - Supports filtering by session_type (e.g., incident vs manual)
+  - Convenience parameter for uninvestigated incidents
+  - Option to hide grouped incidents
+- `hawkeye_inspect_session` - Get detailed session information
+- `hawkeye_get_session_report` - Get session summaries and time-saved metrics
+- `hawkeye_get_session_summary` - Get detailed analysis scores
+- `hawkeye_get_incident_report` - Get organization-wide analytics
+
+### Phase 4: Advanced Investigation Features (PLANNED)
+- `hawkeye_create_investigation` - Custom investigations with timeframes
+- Timeframe parser for natural language date inputs
+- Enhanced prompt engineering for context-aware investigations
+
+### Phase 5: Streaming & Real-time Updates (PLANNED)
+- Streaming support for long-running investigations
+- Real-time progress updates
+- WebSocket or SSE support
+
+### Phase 6: Optimization & Polish
+- Caching strategies
+- Error handling improvements
+- Performance optimization
+- Rate limiting and retry logic
+- Comprehensive documentation and examples
+
+## Documentation Requirements
+
+### For Developers
+
+1. **Setup Guide**: How to install and configure the MCP server
+2. **Tool Reference**: Detailed documentation for each tool
+3. **Examples**: Common use cases with example prompts
+4. **Troubleshooting**: Common issues and solutions
+
+### For AI Agents
+
+1. **Tool Descriptions**: Clear, concise descriptions for each tool
+2. **Example Interactions**: Sample prompts and expected responses
+3. **Error Handling**: How to interpret and recover from errors
+4. **Best Practices**: Optimal usage patterns
+
+## Example Interactions
+
+### Example 1: List Recent Sessions
+
+**User to Cursor**:
+```
+Show me the recent investigations from the HTM-Azure project from the last week
+```
+
+**Cursor calls**:
+```json
+{
+  "tool": "hawkeye_list_sessions",
+  "arguments": {
+    "project_uuid": "74acc801-3428-4292-8a74-ae16ecb71c24",
+    "limit": 20,
+    "date_from": "2024-01-14"
+  }
+}
+```
+
+### Example 1a: List Uninvestigated Incidents
+
+**User to Cursor**:
+```
+Show me all the incidents that haven't been investigated yet in the HTM-Azure project
+```
+
+**Cursor calls**:
+```json
+{
+  "tool": "hawkeye_list_sessions",
+  "arguments": {
+    "project_uuid": "74acc801-3428-4292-8a74-ae16ecb71c24",
+    "only_uninvestigated": true,
+    "limit": 50
+  }
+}
+```
+
+**Alternative using explicit filters**:
+```json
+{
+  "tool": "hawkeye_list_sessions",
+  "arguments": {
+    "project_uuid": "74acc801-3428-4292-8a74-ae16ecb71c24",
+    "investigation_status": "INVESTIGATION_STATUS_NOT_STARTED",
+    "session_type": "SESSION_TYPE_INCIDENT",
+    "limit": 50
+  }
+}
+```
+
+### Example 2: Get Session Details
+
+**User to Cursor**:
+```
+Can you show me the detailed analysis from session abc-123, including all the sources it used?
+```
+
+**Cursor calls**:
+```json
+{
+  "tool": "hawkeye_inspect_session",
+  "arguments": {
+    "session_uuid": "abc-123",
+    "project_uuid": "74acc801-3428-4292-8a74-ae16ecb71c24"
+  }
+}
+```
+
+### Example 3: Get Incident Analytics
+
+**User to Cursor**:
+```
+Show me the overall incident statistics and how much time Hawkeye has saved us
+```
+
+**Cursor calls**:
+```json
+{
+  "tool": "hawkeye_get_incident_report",
+  "arguments": {}
+}
+```
+
+### Example 4: Get Session Report with Time Saved
+
+**User to Cursor**:
+```
+Give me a summary report for these three investigations
+```
+
+**Cursor calls**:
+```json
+{
+  "tool": "hawkeye_get_session_report",
+  "arguments": {
+    "session_uuids": ["session-1", "session-2", "session-3"],
+    "project_uuid": "74acc801-3428-4292-8a74-ae16ecb71c24"
+  }
+}
+```
+
+### Example 5: Investigate an Alert
+
+**User to Cursor**:
+```
+Can you investigate alert /subscriptions/cb3bc010-0fc7-476a-8577-03c3e45e2296/resourcegroups/test123/providers/microsoft.insights/components/test123-insights/providers/Microsoft.AlertsManagement/alerts/08f9c803-6bff-4030-bbe8-300a993af000?
+```
+
+**Cursor calls**:
+```json
+{
+  "tool": "hawkeye_investigate_alert",
+  "arguments": {
+    "alert_id": "/subscriptions/cb3bc010-0fc7-476a-8577-03c3e45e2296/resourcegroups/test123/providers/microsoft.insights/components/test123-insights/providers/Microsoft.AlertsManagement/alerts/08f9c803-6bff-4030-bbe8-300a993af000",
+    "wait_for_completion": true,
+    "max_wait_seconds": 300
+  }
+}
+```
+
+### Example 6: Create Custom Investigation
+
+**User to Cursor**:
+```
+Analyze my EKS cluster security for the last 2 hours
+```
+
+**Cursor calls**:
+```json
+{
+  "tool": "hawkeye_create_investigation",
+  "arguments": {
+    "prompt": "Analyze my EKS cluster for security vulnerabilities and misconfigurations",
+    "timeframe": "last 2 hours",
+    "wait_for_completion": true
+  }
+}
+```
+
+### Example 7: Follow-up Investigation
+
+**User to Cursor**:
+```
+Can you dig deeper into the network policy issues you found?
+```
+
+**Cursor calls**:
+```json
+{
+  "tool": "hawkeye_continue_investigation",
+  "arguments": {
+    "session_uuid": "previous-session-uuid",
+    "follow_up_prompt": "Please provide more details about the network policy issues, including specific configurations that need to be addressed",
+    "wait_for_completion": true
+  }
+}
+```
+
+## Success Metrics
+
+1. **Response Time**: < 500ms for non-investigation tools, < 5 minutes for investigations
+2. **Success Rate**: > 95% successful API calls
+3. **Developer Satisfaction**: Natural, intuitive interactions with minimal friction
+4. **Cache Hit Rate**: > 80% for authentication tokens and project lists
+5. **Error Recovery**: Clear, actionable error messages with recovery suggestions
+
+## Future Enhancements
+
+1. **Proactive Monitoring**: Subscribe to alerts and automatically trigger investigations
+2. **Multi-Cloud Support**: Extend beyond current cloud providers
+3. **Investigation Templates**: Pre-defined investigation templates for common scenarios
+4. **Collaborative Investigations**: Share and collaborate on investigations
+5. **Historical Analysis**: Trend analysis across multiple investigations
+6. **Custom Integrations**: Webhooks, Slack notifications, etc.
+7. **Advanced Filtering Enhancements**: Additional filtering capabilities such as:
+   - Full-text search across session names and incident titles
+   - Filter by priority (P1, P2, P3, P4)
+   - Filter by incident type (FIREHYDRANT, PAGERDUTY, etc.)
+   - Filter by time range with more granular controls
+   - Saved filter presets
+8. **Investigation Chaining**: Automatically trigger related investigations
+
+---
+
+## Questions for Clarification
+
+Before implementation, please clarify:
+
+1. **Organization UUID**: Is there a single organization UUID or should we support multiple? Should this be auto-detected?
+
+2. **Project Selection**: Should the server:
+   - Auto-detect the appropriate project based on alert content?
+   - Always use a default project from config?
+   - Ask the user to specify?
+
+3. **Streaming Preference**: Should streaming be:
+   - Default enabled for all investigations?
+   - Optional based on investigation type?
+   - User-configurable per request?
+
+4. **Investigation Timeout**: What's a reasonable timeout for investigations?
+   - 5 minutes?
+   - 10 minutes?
+   - Configurable based on investigation type?
+
+5. **Pagination**: Should we support pagination for:
+   - Project lists?
+   - Session lists?
+   - Investigation results?
+
+6. **Alert ID Format**: Are there different alert ID formats we need to support beyond the Azure format shown?
+
+7. **Additional Context**: Should investigations include:
+   - Git commit information?
+   - Recent deployments?
+   - Related code changes?
+
+8. **Cost Considerations**: Are there API rate limits or costs we should be aware of?