hawkeye-mcp-server 1.0.0

package/USAGE.md

@@ -0,0 +1,849 @@
+# Usage Guide
+
+Complete guide to using the Hawkeye MCP Server effectively with practical examples and workflows.
+
+## Table of Contents
+
+- [Basic Concepts](#basic-concepts)
+- [Getting Started](#getting-started)
+- [Common Workflows](#common-workflows)
+- [Available Tools Reference](#available-tools-reference)
+- [Advanced Usage](#advanced-usage)
+- [Tips & Best Practices](#tips--best-practices)
+- [Examples Library](#examples-library)
+
+---
+
+## Basic Concepts
+
+### What is MCP?
+
+**Model Context Protocol (MCP)** is a standard protocol that allows AI agents to use external tools and services. Think of it like plugins for your AI assistant.
+
+### How Does Hawkeye MCP Work?
+
+```
+You (via AI Agent) → MCP Server → Hawkeye API → Investigation Results
+     ↑_________________________________________________↓
+                  (Results displayed in your AI agent)
+```
+
+1. **You ask** your AI agent a question about incidents
+2. **AI agent decides** which Hawkeye tool to use
+3. **MCP server** translates the request and calls Hawkeye API
+4. **Hawkeye** performs the investigation
+5. **Results** are returned to you through the AI agent
+
+### Key Terminology
+
+- **Session**: An investigation or conversation with Hawkeye
+- **Investigation**: The process of analyzing an incident/alert
+- **RCA**: Root Cause Analysis - the investigation result
+- **Project**: A Hawkeye project containing your cloud environment data
+- **Alert/Incident**: A cloud issue that needs investigation
+- **Chain of Thoughts**: The step-by-step reasoning Hawkeye used
+- **Prompt Cycle**: One round of question/answer in an investigation
+
+---
+
+## Getting Started
+
+### Your First Investigation
+
+Let's start with the simplest workflow:
+
+**Step 1: List Your Projects**
+
+```
+You: "What Hawkeye projects do I have access to?"
+
+Agent: *Calls hawkeye_list_projects*
+
+Response:
+- HTM-Azure (74acc801-3428-4292-8a74-ae16ecb71c24)
+- HTM-GCP (13541fe6-b849-4d56-b620-54fd584f1300)
+- Datadog_AWS (a6c01691-2fc2-4065-9e32-8c8f1d3d19f5)
+```
+
+**Step 2: List Recent Sessions**
+
+```
+You: "Show me recent investigations from the HTM-Azure project"
+
+Agent: *Calls hawkeye_list_sessions with project_uuid*
+
+Response:
+- Incident: 217 - ImagePullBackOff issue (2025-09-12)
+- Incident: 215 - ImagePullBackOff issue (2025-09-12)
+- Incident: 541 - Testing 8910 (2025-07-19)
+...
+```
+
+**Step 3: Inspect a Session**
+
+```
+You: "Show me the full details of session 68c3663ff7afd98ca1b1ebe2"
+
+Agent: *Calls hawkeye_inspect_session*
+
+Response: Complete investigation with chain of thoughts, sources, and findings
+```
+
+---
+
+## Common Workflows
+
+### Workflow 1: Finding Uninvestigated Incidents
+
+This is one of the most common use cases - finding incidents that haven't been analyzed yet.
+
+**Quick Method:**
+
+```
+You: "Show me all uninvestigated incidents in HTM-Azure project"
+
+Agent: *Calls hawkeye_list_sessions with:*
+{
+  "project_uuid": "74acc801-3428-4292-8a74-ae16ecb71c24",
+  "only_uninvestigated": true
+}
+
+Response:
+Found 15 uninvestigated incidents:
+1. Incident: 217 - ImagePullBackOff (P4, Created: 2025-09-12)
+2. Incident: 215 - ImagePullBackOff (P4, Created: 2025-09-12)
+...
+```
+
+**With Date Filter:**
+
+```
+You: "Show me uninvestigated incidents from the last 7 days"
+
+Agent: *Adds date_from filter*
+{
+  "only_uninvestigated": true,
+  "date_from": "2025-11-12"
+}
+```
+
+**With Priority Focus (Manual):**
+
+Since filtering by priority isn't built-in yet, ask the agent to filter results:
+
+```
+You: "Show me uninvestigated P1 incidents"
+
+Agent: *Gets all uninvestigated, then filters for P1 in results*
+```
+
+---
+
+### Workflow 2: Investigating a Specific Alert
+
+When you have an alert ID and want to investigate it:
+
+**Standard Investigation:**
+
+```
+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"
+
+Agent: *Calls hawkeye_investigate_alert*
+{
+  "alert_id": "/subscriptions/.../alerts/08f9c803...",
+  "wait_for_completion": true
+}
+
+Response:
+- Checks for existing investigation
+- If found: Returns existing RCA
+- If not found: Creates new investigation
+- Returns: Root cause analysis with recommendations
+```
+
+**Quick Investigation (Don't Wait):**
+
+```
+You: "Start investigating alert XYZ but don't wait for completion"
+
+Agent: *Sets wait_for_completion: false*
+
+Response:
+Investigation started, session_uuid: abc-123
+You can check status later with get_investigation_status
+```
+
+**Check Status Later:**
+
+```
+You: "What's the status of investigation abc-123?"
+
+Agent: *Calls hawkeye_get_investigation_status*
+
+Response: Investigation 85% complete, currently analyzing logs...
+```
+
+---
+
+### Workflow 3: Deep Diving into an Investigation
+
+When you want to understand how Hawkeye reached its conclusions:
+
+**Get Full Session Details:**
+
+```
+You: "Show me everything about session 68c3663ff7afd98ca1b1ebe2"
+
+Agent: *Calls hawkeye_inspect_session*
+
+Response includes:
+- Session metadata (creation time, last update)
+- All prompt cycles (questions asked)
+- Chain of thoughts for each cycle (reasoning steps)
+- All data sources consulted
+- Follow-up suggestions
+```
+
+**Example Output Structure:**
+
+```
+Session: 68c3663ff7afd98ca1b1ebe2
+Name: Incident: 217
+Created: 2025-09-12T00:15:59Z
+
+Prompt Cycle 1:
+  Status: COMPLETED
+  Final Answer: "The ImagePullBackOff error is caused by..."
+
+  Chain of Thoughts:
+    1. "Analyzing pod status in namespace neubird-alex"
+    2. "Checking image registry connectivity"
+    3. "Reviewing recent deployment changes"
+
+  Sources:
+    - Kubernetes Events (234 events analyzed)
+    - Pod Logs (15 pods checked)
+    - Deployment History (last 5 deployments)
+
+  Follow-up Suggestions:
+    - "Would you like me to check if this affects other namespaces?"
+    - "Should I analyze the image registry configuration?"
+```
+
+---
+
+### Workflow 4: Following Up on Investigations
+
+Continue a conversation with Hawkeye about an investigation:
+
+**Basic Follow-up:**
+
+```
+You: "In session abc-123, can you dig deeper into the network issues?"
+
+Agent: *Calls hawkeye_continue_investigation*
+{
+  "session_uuid": "abc-123",
+  "follow_up_prompt": "Analyze the network policy issues in more detail",
+  "wait_for_completion": true
+}
+
+Response: Detailed analysis of network policies, routes, and connectivity
+```
+
+**Contextual Follow-up:**
+
+The AI agent can reference previous conversation:
+
+```
+You: "What about the database you mentioned?"
+
+Agent: *Uses context from previous responses*
+"Analyzing the database connection issues mentioned in the previous investigation..."
+```
+
+---
+
+### Workflow 5: Getting Analytics and Reports
+
+Understand your incident patterns and time saved:
+
+**Organization-Wide Statistics:**
+
+```
+You: "Show me our incident statistics and how much time Hawkeye has saved us"
+
+Agent: *Calls hawkeye_get_incident_report*
+
+Response:
+Incident Report:
+- Time Period: 2025-07-01 to 2025-11-19
+- Total Incidents: 342
+- Total Investigations: 156
+- Average MTTR: 45 minutes
+- Time Saved: 234 hours (14,040 minutes)
+- Noise Reduction: 67%
+
+By Priority:
+- P1: 12 incidents (avg MTTR: 25min, 95% investigated)
+- P2: 34 incidents (avg MTTR: 35min, 78% investigated)
+- P3: 89 incidents (avg MTTR: 50min, 62% investigated)
+- P4: 207 incidents (avg MTTR: 60min, 34% investigated)
+```
+
+**Session-Specific Reports:**
+
+```
+You: "Get me a summary report for sessions abc-123, def-456, and ghi-789"
+
+Agent: *Calls hawkeye_get_session_report*
+{
+  "session_uuids": ["abc-123", "def-456", "ghi-789"],
+  "project_uuid": "74acc801-3428-4292-8a74-ae16ecb71c24"
+}
+
+Response: Individual reports for each session with time-saved metrics
+```
+
+**Quality Scores:**
+
+```
+You: "How good was the analysis for session abc-123?"
+
+Agent: *Calls hawkeye_get_session_summary*
+
+Response:
+Analysis Score:
+Accuracy:
+  - Root Cause Correct: Yes
+  - Impact Analysis: Yes
+  - Timeline Accurate: Partial
+  - Overall Score: 92/100
+
+Completeness:
+  - Data Sources: 8/10
+  - Remediation Steps: 9/10
+  - Prevention Measures: 7/10
+  - Overall Score: 85/100
+```
+
+---
+
+## Available Tools Reference
+
+### 1. hawkeye_list_projects
+
+**Purpose:** List all available Hawkeye projects
+
+**When to use:**
+- First time setup
+- When you don't know the project UUID
+- To see all available projects
+
+**Example:**
+```
+"List all my Hawkeye projects"
+"What projects do I have access to?"
+"Show me available Hawkeye projects"
+```
+
+---
+
+### 2. hawkeye_investigate_alert
+
+**Purpose:** Investigate a specific alert by ID
+
+**When to use:**
+- You have an alert ID from your monitoring system
+- You want to find or create an RCA for a specific alert
+- Starting a new investigation
+
+**Parameters:**
+- `alert_id` (required): Full alert identifier
+- `wait_for_completion` (optional): Whether to wait for results
+- `max_wait_seconds` (optional): Max time to wait
+- `project_uuid` (optional): Which project to use
+
+**Example:**
+```
+"Investigate alert /subscriptions/.../alerts/08f9c803..."
+"Analyze this alert: [paste alert ID]"
+"Create an RCA for alert XYZ"
+```
+
+---
+
+### 3. hawkeye_list_sessions
+
+**Purpose:** List investigation sessions with filtering
+
+**When to use:**
+- Finding uninvestigated incidents
+- Reviewing recent investigations
+- Searching for specific sessions
+- Filtering by date or status
+
+**Key Parameters:**
+- `only_uninvestigated`: Quick filter for new incidents
+- `investigation_status`: Filter by status
+- `session_type`: Filter by incident vs manual
+- `date_from`/`date_to`: Date range filtering
+- `page`/`limit`: Pagination
+
+**Example:**
+```
+"Show uninvestigated incidents"
+"List sessions from last week"
+"Show me recent investigations in HTM-Azure"
+"Find all incidents from October"
+```
+
+---
+
+### 4. hawkeye_inspect_session
+
+**Purpose:** Get detailed information about a session
+
+**When to use:**
+- Deep diving into an investigation
+- Understanding Hawkeye's reasoning
+- Reviewing data sources used
+- Getting follow-up suggestions
+
+**Example:**
+```
+"Show me session abc-123 in detail"
+"What sources did Hawkeye use for session XYZ?"
+"Explain how Hawkeye solved incident ABC"
+```
+
+---
+
+### 5. hawkeye_continue_investigation
+
+**Purpose:** Ask follow-up questions on an existing investigation
+
+**When to use:**
+- Need more details on a specific aspect
+- Want to explore a different angle
+- Following up on suggestions
+
+**Example:**
+```
+"In session abc-123, analyze the database connections"
+"Can you dig deeper into the network issues from that investigation?"
+"Tell me more about the root cause you found"
+```
+
+---
+
+### 6. hawkeye_get_investigation_status
+
+**Purpose:** Check progress of an ongoing investigation
+
+**When to use:**
+- Investigation started without waiting
+- Checking if investigation is complete
+- Getting current progress
+
+**Example:**
+```
+"What's the status of investigation abc-123?"
+"Is the investigation complete yet?"
+"Check progress on session XYZ"
+```
+
+---
+
+### 7. hawkeye_get_session_report
+
+**Purpose:** Get summary reports with time-saved metrics
+
+**When to use:**
+- Quick overview of investigations
+- Getting time-saved numbers
+- Comparing multiple sessions
+
+**Example:**
+```
+"Get a report for sessions A, B, and C"
+"How much time did we save on investigation XYZ?"
+"Summarize these three incidents"
+```
+
+---
+
+### 8. hawkeye_get_session_summary
+
+**Purpose:** Get quality scores and detailed analysis metrics
+
+**When to use:**
+- Evaluating investigation quality
+- Understanding accuracy scores
+- Getting detailed metrics
+
+**Example:**
+```
+"How accurate was the analysis for session abc-123?"
+"Give me quality scores for investigation XYZ"
+"Was this a good investigation?"
+```
+
+---
+
+### 9. hawkeye_get_incident_report
+
+**Purpose:** Get organization-wide incident analytics
+
+**When to use:**
+- Understanding overall incident patterns
+- Getting MTTR metrics
+- Calculating time saved
+- Reporting to management
+
+**Example:**
+```
+"Show me our incident statistics"
+"How much time has Hawkeye saved us?"
+"What's our average MTTR?"
+"Give me an overview of all incidents"
+```
+
+---
+
+## Advanced Usage
+
+### Working with Multiple Projects
+
+If you manage multiple Hawkeye projects:
+
+**Set Default Project:**
+
+Set `HAWKEYE_DEFAULT_PROJECT_UUID` in your configuration, or always specify:
+
+```
+"List uninvestigated incidents in project 74acc801-3428-4292-8a74-ae16ecb71c24"
+```
+
+**Switch Between Projects:**
+
+```
+"Show incidents from HTM-Azure"
+"Now show me incidents from HTM-GCP"
+```
+
+The AI agent will remember project names and UUIDs from earlier in the conversation.
+
+---
+
+### Filtering and Searching
+
+**Date Range Queries:**
+
+```
+"Show incidents from last week"
+"List investigations between Oct 1 and Oct 15"
+"Find sessions from the past 30 days"
+```
+
+**Status Filtering:**
+
+```
+"Show only uninvestigated incidents"
+"List completed investigations"
+"Find investigations in progress"
+```
+
+**Combining Filters:**
+
+```
+"Show uninvestigated P1 incidents from last week in HTM-Azure project, excluding grouped incidents"
+```
+
+---
+
+### Batch Operations
+
+**Analyzing Multiple Sessions:**
+
+```
+"Get reports for all sessions from last week"
+"Analyze these 5 incidents: [list of UUIDs]"
+"Compare these three investigations"
+```
+
+**Bulk Status Checks:**
+
+```
+"Check status of these investigations: abc, def, ghi"
+```
+
+---
+
+## Tips & Best Practices
+
+### 1. Be Specific with Project Names
+
+**Good:**
+```
+"Show uninvestigated incidents in HTM-Azure project"
+```
+
+**Less Good:**
+```
+"Show uninvestigated incidents"  # May not know which project
+```
+
+### 2. Use Natural Language
+
+The AI agent understands context:
+
+**Good:**
+```
+You: "List my projects"
+Agent: *Shows projects*
+You: "Show uninvestigated incidents in the Azure one"
+Agent: *Knows you mean HTM-Azure*
+```
+
+### 3. Ask for Summaries
+
+Don't get overwhelmed with data:
+
+```
+"Give me a summary of the top 5 most critical uninvestigated incidents"
+```
+
+### 4. Follow the Investigation Flow
+
+Natural workflow:
+
+1. List uninvestigated incidents
+2. Pick one to investigate
+3. Review the analysis
+4. Ask follow-up questions if needed
+5. Move to next incident
+
+### 5. Use Filters Effectively
+
+Start broad, then narrow down:
+
+```
+"Show all incidents from last week"
+"Now filter for P1 priority"
+"Exclude the ones that are already investigated"
+```
+
+### 6. Save Session UUIDs
+
+When you find an interesting session:
+
+```
+"Save session abc-123 for me to review later"
+```
+
+Or keep them in your notes for future reference.
+
+### 7. Leverage Chain of Thoughts
+
+Understanding the reasoning:
+
+```
+"Explain step-by-step how you reached this conclusion"
+"Show me the chain of thoughts for this investigation"
+```
+
+---
+
+## Examples Library
+
+### Example 1: Morning Incident Review
+
+**Scenario:** Start of day, review overnight incidents
+
+```
+You: "Show me all uninvestigated incidents from the last 24 hours"
+
+Agent: *Lists 8 new incidents*
+
+You: "Which ones are P1 or P2?"
+
+Agent: *Filters and shows 2 P1 incidents*
+
+You: "Investigate the first P1"
+
+Agent: *Creates investigation and returns RCA*
+
+You: "That makes sense. Investigate the second one too"
+
+Agent: *Investigates second incident*
+
+You: "Create a summary I can send to my team"
+
+Agent: *Summarizes both investigations with action items*
+```
+
+### Example 2: Investigating a Production Issue
+
+**Scenario:** Production alert just fired
+
+```
+You: "We just got alert /subscriptions/.../alerts/NEW-ALERT-123, investigate it ASAP"
+
+Agent: *Starts investigation immediately*
+{
+  "wait_for_completion": true,
+  "alert_id": "/subscriptions/.../alerts/NEW-ALERT-123"
+}
+
+Response: [RCA with root cause and remediation steps]
+
+You: "The root cause mentions database connections. Can you analyze the database more deeply?"
+
+Agent: *Continues investigation focusing on database*
+
+Response: [Detailed database analysis]
+
+You: "What are the recommended fixes?"
+
+Agent: *Provides actionable remediation steps*
+```
+
+### Example 3: Weekly Report Generation
+
+**Scenario:** Create weekly incident report
+
+```
+You: "Show me all incidents from the past week"
+
+Agent: *Lists incidents from last 7 days*
+
+You: "How many were investigated?"
+
+Agent: "45 total incidents, 32 investigated (71%)"
+
+You: "Give me the incident report with all statistics"
+
+Agent: *Calls hawkeye_get_incident_report*
+
+Response: [Full statistics with MTTR, time saved, etc.]
+
+You: "Create a summary suitable for management review"
+
+Agent: *Formats report with key metrics and highlights*
+```
+
+### Example 4: Post-Mortem Analysis
+
+**Scenario:** Analyze a past incident
+
+```
+You: "Find the incident about ImagePullBackOff from September 12"
+
+Agent: *Searches and finds session 68c3663ff7afd98ca1b1ebe2*
+
+You: "Show me the complete investigation"
+
+Agent: *Displays full session details*
+
+You: "What data sources were used?"
+
+Agent: "Kubernetes Events (234), Pod Logs (15 pods), Deployment History"
+
+You: "Give me the quality score for this investigation"
+
+Agent: *Shows 92/100 accuracy, 85/100 completeness*
+
+You: "Perfect, export this for the post-mortem document"
+
+Agent: *Formats investigation for documentation*
+```
+
+### Example 5: Trend Analysis
+
+**Scenario:** Understanding incident patterns
+
+```
+You: "Show me all incidents from October"
+
+Agent: *Lists October incidents*
+
+You: "Group them by type"
+
+Agent: *Groups: 15 database issues, 23 network issues, 8 pod issues*
+
+You: "Focus on the database issues - show me if they're related"
+
+Agent: *Analyzes and finds 12 of 15 share same root cause*
+
+You: "What's the common root cause?"
+
+Agent: "Connection pool exhaustion during peak hours"
+
+You: "Get me the incident report to see the impact"
+
+Agent: *Shows MTTR, time to detect, business impact*
+```
+
+---
+
+## Frequently Asked Questions
+
+### Q: Can I investigate multiple alerts at once?
+
+A: Currently, you need to investigate alerts one at a time. However, you can start multiple investigations without waiting for completion:
+
+```
+"Start investigating alert A, don't wait"
+"Start investigating alert B, don't wait"
+"Check status of both investigations"
+```
+
+### Q: How long do investigations take?
+
+A: Typically 30 seconds to 5 minutes, depending on:
+- Complexity of the incident
+- Amount of data to analyze
+- Current system load
+
+### Q: Can I cancel an investigation?
+
+A: Not currently. If you don't wait for completion, you can simply ignore it and start a new one.
+
+### Q: What happens if my session times out?
+
+A: The investigation continues in Hawkeye. You can check its status later using the session UUID.
+
+### Q: Can I re-investigate an alert?
+
+A: Yes, but Hawkeye will find the existing investigation by default. To force a new investigation, ask specifically:
+
+```
+"Create a new investigation for alert XYZ (ignore existing ones)"
+```
+
+### Q: How do I share an investigation with my team?
+
+A: Get the session details and share the formatted output, or share the Hawkeye web UI link:
+
+```
+"Give me a shareable link for session abc-123"
+```
+
+---
+
+## Next Steps
+
+- **Explore:** Try different queries and see what works
+- **Experiment:** Use the filters and parameters
+- **Integrate:** Build this into your incident response workflow
+- **Automate:** Consider automating daily uninvestigated incident reviews
+- **Feedback:** Let us know what works and what doesn't (support@neubird.ai)
+
+---
+
+**Happy investigating! 🔍**
+
+For technical details, see [SPECIFICATION.md](./SPECIFICATION.md)
+
+For installation help, see [INSTALLATION.md](./INSTALLATION.md)