hawkeye-mcp-server 1.4.0 → 1.4.1

package/README.md

@@ -6,291 +6,148 @@
 
 > Model Context Protocol (MCP) server that brings Hawkeye's AI-powered incident investigation and root cause analysis directly into your AI coding environment.
 
-## What is it?
+## What is Hawkeye MCP?
 
-The Hawkeye MCP Server enables developers to investigate cloud incidents, analyze alerts, and perform automated root cause analysis directly from AI-powered development tools like Claude Desktop and Cursor.ai. It bridges the gap between your code editor and Hawkeye's powerful cloud telemetry analysis platform.
+Hawkeye MCP Server enables AI assistants (like Claude) to interact with [NeuBird's Hawkeye platform](https://neubird.ai) for autonomous incident investigation and root cause analysis.
 
 **Stop context-switching. Investigate incidents without leaving your IDE.**
 
 ## ✨ Key Features
 
-- 🔍 **Alert Investigation** - Find existing RCAs or create new investigations for specific alert IDs
-- 📊 **Session Management** - List, filter, and inspect investigation sessions with advanced filtering
-- 🎯 **Uninvestigated Incidents** - Quickly find incidents that haven't been analyzed yet
-- 📝 **Comprehensive RCA** - Get formatted analysis with timeline, root cause, and **corrective actions** (including bash scripts)
-- ⏱️ **Time Savings Metrics** - See exactly how much time Hawkeye saved vs manual investigation
-- 📈 **Analytics & Reporting** - Get organization-wide incident statistics, MTTR, and time-saved metrics
-- 🎖️ **Quality Scoring** - Evaluate investigation quality with accuracy and completeness scores
-- 💬 **Follow-up Questions** - Continue investigations with contextual follow-up prompts
-- 🚀 **Real-time Updates** - Stream investigation progress in real-time
-- 🌐 **Cross-platform** - Works on macOS, Linux, and Windows
-- 🔌 **Easy Integration** - Works with Claude Desktop, Cursor.ai, and any MCP-compatible AI agent
+- 🔍 **AI-Powered RCA** - Automated root cause analysis with corrective actions (including bash scripts)
+- 🎯 **39 Tools** - Complete API for projects, connections, investigations, instructions, and analytics
+- 📊 **Time Savings** - Track MTTR and time saved vs manual investigation
+- 🧪 **Test Instructions** - Unique workflow to test investigation instructions before deployment
+- 🔌 **Multi-Cloud** - Connect AWS, Azure, GCP, Datadog, PagerDuty, and more
+- 🤖 **Any MCP Client** - Works with Claude Desktop, Claude Code, Cursor, Continue, and more
 
 ## 🚀 Quick Start
 
 ### Installation
 
 ```bash
-# Install globally with npm
+# Install globally
 npm install -g hawkeye-mcp-server
 
-# Or use directly with npx (no installation required)
+# Or use directly with npx (no installation)
 npx hawkeye-mcp-server
 ```
 
-### Quick Setup for Cursor Users
-
-**Configuration file location:**
-- **macOS/Linux:** `~/.cursor/mcp.json`
-- **Windows:** `%APPDATA%\Cursor\mcp.json`
-
-If the file doesn't exist, create it with this content:
-
-```json
-{
-  "mcpServers": {
-    "hawkeye": {
-      "command": "npx",
-      "args": ["hawkeye-mcp-server"],
-      "env": {
-        "HAWKEYE_EMAIL": "your-email@example.com",
-        "HAWKEYE_PASSWORD": "your-password",
-        "HAWKEYE_BASE_URL": "https://your-instance.app.neubird.ai/api"
-      }
-    }
-  }
-}
-```
-
-Then reload Cursor (`Cmd/Ctrl+Shift+P` → "Developer: Reload Window") and start investigating!
-
 ### Configuration
 
-1. Set up your environment variables:
-
-```bash
-# Create a .env file or set environment variables
-export HAWKEYE_EMAIL="your-email@example.com"
-export HAWKEYE_PASSWORD="your-password"
-export HAWKEYE_BASE_URL="https://your-instance.app.neubird.ai/api"
-```
-
-2. Configure your AI agent:
+Add to your MCP client configuration:
 
-**For Claude Code** (Recommended - add to `~/.config/claude-code/mcp_settings.json`):
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
 
 ```json
 {
   "mcpServers": {
     "hawkeye": {
       "command": "npx",
-      "args": ["hawkeye-mcp-server"],
+      "args": ["-y", "hawkeye-mcp-server"],
       "env": {
-        "HAWKEYE_EMAIL": "your-email@example.com",
+        "HAWKEYE_EMAIL": "your-email@company.com",
         "HAWKEYE_PASSWORD": "your-password",
-        "HAWKEYE_BASE_URL": "https://your-instance.app.neubird.ai/api"
+        "HAWKEYE_BASE_URL": "https://app.neubird.ai/api"
       }
     }
   }
 }
 ```
 
-**For Claude Desktop** (add to `~/Library/Application Support/Claude/claude_desktop_config.json`):
+**Cursor** (`~/.cursor/mcp.json`):
 
 ```json
 {
   "mcpServers": {
     "hawkeye": {
       "command": "npx",
-      "args": ["hawkeye-mcp-server"],
+      "args": ["-y", "hawkeye-mcp-server"],
       "env": {
-        "HAWKEYE_EMAIL": "your-email@example.com",
+        "HAWKEYE_EMAIL": "your-email@company.com",
         "HAWKEYE_PASSWORD": "your-password",
-        "HAWKEYE_BASE_URL": "https://your-instance.app.neubird.ai/api"
+        "HAWKEYE_BASE_URL": "https://app.neubird.ai/api"
       }
     }
   }
 }
 ```
 
-**For Cursor** (add to `~/.cursor/mcp.json`):
-
-```json
-{
-  "mcpServers": {
-    "hawkeye": {
-      "command": "npx",
-      "args": ["hawkeye-mcp-server"],
-      "env": {
-        "HAWKEYE_EMAIL": "your-email@example.com",
-        "HAWKEYE_PASSWORD": "your-password",
-        "HAWKEYE_BASE_URL": "https://your-instance.app.neubird.ai/api"
-      }
-    }
-  }
-}
-```
-
-After adding the configuration, reload Cursor:
-- Press `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)
-- Type "Developer: Reload Window"
-- Press Enter
-
-3. Start using it! Ask your AI agent:
-
-```
-"Show me all uninvestigated incidents from the HTM-Azure project"
-```
+Restart your MCP client and start investigating!
 
 ## 📖 Documentation
 
-- **[Installation Guide](./INSTALLATION.md)** - Detailed installation instructions for all platforms and AI agents
-- **[Usage Guide](./USAGE.md)** - Complete usage examples and workflows
-- **[API Reference](./SPECIFICATION.md)** - Technical specification of all MCP tools
-
-## 🎯 Common Use Cases
+**Complete documentation is available at: [https://neubirdai.github.io/hawkeye-mcp-docs](https://neubirdai.github.io/hawkeye-mcp-docs)**
 
-### 1. List Uninvestigated Incidents
+- **[Installation Guide](https://neubirdai.github.io/hawkeye-mcp-docs/getting-started/installation/)** - Detailed setup for all platforms
+- **[Quick Start](https://neubirdai.github.io/hawkeye-mcp-docs/getting-started/quickstart/)** - 5-minute getting started guide
+- **[Complete Onboarding](https://neubirdai.github.io/hawkeye-mcp-docs/guides/onboarding/)** - End-to-end setup guide
+- **[Tool Reference](https://neubirdai.github.io/hawkeye-mcp-docs/reference/overview/)** - All 39 tools documented
+- **[Examples](https://neubirdai.github.io/hawkeye-mcp-docs/examples/complete-setup/)** - Real-world usage examples
+- **[Troubleshooting](https://neubirdai.github.io/hawkeye-mcp-docs/troubleshooting/)** - Common issues and solutions
 
-Find incidents that haven't been analyzed yet:
+## 🎯 Example Usage
 
 ```
-"List all uninvestigated incidents in my default project"
-```
+You: "Show me uninvestigated alerts from the last 24 hours"
 
-The MCP server will call `hawkeye_list_sessions` with:
-```json
-{
-  "only_uninvestigated": true
-}
-```
+Claude: *Lists uninvestigated incidents*
 
-### 2. Search for Specific Incidents
-
-Search for incidents by keywords in the title:
-
-```
-"List all investigations into load avg issues"
-```
-
-The MCP server will call `hawkeye_list_sessions` with:
-```json
-{
-  "search_term": "load avg",
-  "only_uninvestigated": true
-}
-```
-
-You can search for any keyword like "database", "timeout", "disk space", etc. Works with both investigated and uninvestigated incidents.
-
-### 3. Investigate an Alert
-
-Analyze a specific alert by ID:
-
-```
-"Investigate alert /subscriptions/.../alerts/08f9c803-..."
-```
-
-The server automatically finds existing investigations or creates a new one.
+You: "Investigate the first one"
 
-### 4. Get Investigation RCA
+Claude: *Runs investigation and returns comprehensive RCA including:*
+- Root cause analysis
+- Timeline of events
+- Corrective actions with bash scripts
+- Preventive measures
+- Business impact
+- Time saved (e.g., "45 minutes saved: Manual 50min → Hawkeye 5min")
 
-View the comprehensive Root Cause Analysis (recommended first step):
+You: "Why did this happen? Has it happened before?"
 
-```
-"Show me the RCA for session abc-123-def-456"
+Claude: *Uses follow-up investigation to provide deeper analysis*
 ```
 
-The server returns a formatted analysis including:
-- **Summary** and incident description
-- **Timeline** of events
-- **Root cause** analysis
-- **Corrective actions** with executable bash scripts
-- **Time savings** metrics (e.g., "Saved 17 minutes: Manual 25min → Hawkeye 8min")
+## 🛠️ Tool Categories
 
-### 5. View Analytics
+| Category | Tools | Description |
+|----------|-------|-------------|
+| **Projects** | 5 | Create and manage Hawkeye projects |
+| **Connections** | 10 | Connect AWS, Azure, GCP, Datadog, PagerDuty, etc. |
+| **Investigations** | 10 | Investigate alerts, get RCA, ask follow-ups |
+| **Instructions** | 7 | Create, test, and manage investigation instructions |
+| **Analytics** | 4 | MTTR, time saved, quality scores, incident statistics |
+| **Discovery** | 2 | Explore available resources and data sources |
+| **Help** | 1 | Interactive guidance system |
 
-Get organization-wide incident statistics:
+**Total: 39 tools**
 
-```
-"Show me the incident report with MTTR and time saved metrics"
-```
+See the [Tool Reference](https://neubirdai.github.io/hawkeye-mcp-docs/reference/overview/) for complete documentation.
 
-### 6. Continue an Investigation
+## 🧪 Unique Features
 
-Ask follow-up questions on an existing investigation:
+### Instruction Testing Workflow
 
-```
-"Can you dig deeper into the network policy issues you found?"
-```
+Hawkeye MCP is the only incident investigation tool that lets you **test instructions before deploying them**:
 
-### 7. Switch Hawkeye Instances
+1. Apply instruction to a past investigation
+2. Rerun that investigation with the new instruction
+3. Compare the new RCA with the original
+4. Only add to project if it improves results
 
-Switch between different Hawkeye environments or customer instances with flexible URL formats:
+This prevents bad instructions from affecting all your investigations.
 
-```
-"Switch to the production instance"
-"Switch to customerA deployment"
-"Switch to staging.app.neubird.ai"
-```
+Learn more: [Testing Instructions Guide](https://neubirdai.github.io/hawkeye-mcp-docs/guides/testing-instructions/)
 
-The tool accepts multiple URL formats and automatically normalizes them:
+## 🤝 Supported AI Clients
 
-**Supported Formats:**
-- **Just subdomain**: `"prod"` → `https://prod.app.neubird.ai/api`
-- **Subdomain name**: `"customerA"` → `https://customerA.app.neubird.ai/api`
-- **Partial URL**: `"prod.app.neubird.ai"` → `https://prod.app.neubird.ai/api`
-- **URL without protocol**: `"staging.app.neubird.ai"` → `https://staging.app.neubird.ai/api`
-- **Full URL without path**: `"https://prod.app.neubird.ai"` → `https://prod.app.neubird.ai/api`
-- **Complete URL**: `"https://prod.app.neubird.ai/api"` → `https://prod.app.neubird.ai/api` (no change)
-- **Custom domains**: `"custom.domain.com/api"` → `https://custom.domain.com/api`
-
-**Example:**
-```json
-{
-  "base_url": "prod"
-}
-```
+Works with any MCP-compatible client:
 
-Useful for users managing multiple environments (dev, staging, production) or multiple customer instances. Automatically clears authentication tokens and project cache, requiring re-authentication on the next API call.
-
-## 🛠️ Available Tools
-
-The Hawkeye MCP Server provides the following tools to AI agents:
-
-### Investigation Tools
-| Tool | Description |
-|------|-------------|
-| `hawkeye_investigate_alert` | Investigate a specific alert/incident by ID |
-| `hawkeye_get_investigation_status` | Check the status of an ongoing investigation |
-| `hawkeye_continue_investigation` | Ask follow-up questions on an investigation |
-
-### Session Management & Analysis
-| Tool | Description |
-|------|-------------|
-| `hawkeye_list_sessions` | List sessions with filtering (uninvestigated, date range, search, etc.) |
-| `hawkeye_inspect_session` | Get session metadata and prompt cycle IDs |
-| `hawkeye_get_rca` | **⭐ RECOMMENDED** Get comprehensive RCA with corrective actions, timeline, and time savings |
-| `hawkeye_get_rca_score` | **NEW** Get quality scores (accuracy, completeness, qualitative feedback) |
-| `hawkeye_get_chain_of_thought` | Get investigation reasoning steps |
-| `hawkeye_get_investigation_queries` | Get query execution logs |
-| `hawkeye_get_investigation_sources` | Get data sources consulted |
-| `hawkeye_get_follow_up_suggestions` | Get suggested follow-up questions |
-
-### Analytics & Reporting
-| Tool | Description |
-|------|-------------|
-| `hawkeye_get_session_report` | Get summary reports with time-saved metrics |
-| `hawkeye_get_session_summary` | Get detailed quality scores and analysis metrics |
-| `hawkeye_get_incident_report` | Get organization-wide incident analytics |
-
-### Configuration
-| Tool | Description |
-|------|-------------|
-| `hawkeye_list_projects` | List all available Hawkeye projects |
-| `hawkeye_switch_instance` | Switch to a different Hawkeye instance (dev/staging/prod) |
-
-See the [API Reference](./SPECIFICATION.md) for detailed documentation on each tool.
+- ✅ **Claude Desktop** (macOS, Windows)
+- ✅ **Claude Code** (CLI - macOS, Windows, Linux)
+- ✅ **Cursor** (macOS, Windows, Linux)
+- ✅ **Continue** (VS Code extension)
+- ✅ Any other MCP-compatible client
 
 ## 🔧 Configuration Options
 
@@ -300,161 +157,213 @@ See the [API Reference](./SPECIFICATION.md) for detailed documentation on each t
 |----------|-------------|
 | `HAWKEYE_EMAIL` | Your Hawkeye account email |
 | `HAWKEYE_PASSWORD` | Your Hawkeye account password |
-| `HAWKEYE_BASE_URL` | Hawkeye API base URL |
+| `HAWKEYE_BASE_URL` | Hawkeye API endpoint (e.g., `https://app.neubird.ai/api`) |
 
 ### Optional Environment Variables
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `HAWKEYE_DEFAULT_PROJECT_UUID` | None | Default project for investigations |
-| `HAWKEYE_DEFAULT_ORGANIZATION_UUID` | `ORGANIZATION_NAME_ROOT` | Default organization |
-| `HAWKEYE_MAX_POLL_ATTEMPTS` | `30` | Max attempts when polling for completion |
-| `HAWKEYE_POLL_INTERVAL_MS` | `2000` | Interval between polling attempts (ms) |
-| `HAWKEYE_ENABLE_STREAMING` | `true` | Enable real-time streaming |
-| `HAWKEYE_LOG_ENABLED` | `true` | Enable logging |
+| `HAWKEYE_DEFAULT_PROJECT_UUID` | None | Default project UUID |
 | `HAWKEYE_LOG_LEVEL` | `info` | Log level (debug, info, warn, error) |
+| `HAWKEYE_MAX_POLL_ATTEMPTS` | `30` | Max polling attempts |
+| `HAWKEYE_POLL_INTERVAL_MS` | `2000` | Polling interval (ms) |
+
+## 👥 Contributing
+
+We welcome contributions from NeuBird team members! This section is for internal developers.
+
+### Development Setup
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/neubird/hawkeye-mcp.git
+   cd hawkeye-mcp
+   ```
+
+2. **Install dependencies:**
+   ```bash
+   npm install
+   ```
+
+3. **Set up environment variables:**
+   ```bash
+   cp .env.example .env
+   # Edit .env with your Hawkeye credentials
+   ```
+
+4. **Build the project:**
+   ```bash
+   npm run build
+   ```
+
+5. **Run in development mode:**
+   ```bash
+   npm run dev
+   ```
+
+### Project Structure
+
+```
+hawkeye-mcp/
+├── src/
+│   ├── index.ts           # Main MCP server entry point
+│   ├── hawkeye-client.ts  # Hawkeye API client
+│   ├── tools/             # MCP tool implementations
+│   ├── utils/             # Utility functions
+│   └── types/             # TypeScript type definitions
+├── build/                 # Compiled JavaScript (gitignored)
+├── tests/                 # Test files
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+### Development Workflow
+
+1. **Create a feature branch:**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes:**
+   - Add new tools in `src/tools/`
+   - Update types in `src/types/`
+   - Add tests for new functionality
+   - Update CHANGELOG.md
+
+3. **Test your changes:**
+   ```bash
+   # Build
+   npm run build
+
+   # Test with MCP Inspector
+   npx @modelcontextprotocol/inspector node build/index.js
+
+   # Or test with your MCP client
+   ```
+
+4. **Commit your changes:**
+   ```bash
+   git add .
+   git commit -m "feat: add new feature"
+   ```
+
+   **Commit message format:**
+   - `feat:` New features
+   - `fix:` Bug fixes
+   - `docs:` Documentation changes
+   - `refactor:` Code refactoring
+   - `test:` Test additions/changes
+   - `chore:` Maintenance tasks
+
+5. **Push and create PR:**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+   Create a pull request on GitHub with:
+   - Clear description of changes
+   - Testing steps performed
+   - Any breaking changes noted
+
+### Testing
 
-## 🤝 Supported AI Agents
-
-The Hawkeye MCP Server works with any MCP-compatible AI agent:
-
-- ✅ **Cursor** (macOS, Windows, Linux) - **Recommended for IDE integration**
-- ✅ **Claude Code** (CLI tool - macOS, Windows, Linux) - **Recommended for terminal workflows**
-- ✅ **Claude Desktop** (macOS, Windows)
-- ✅ **Continue.dev** (VS Code extension)
-- ✅ Any other MCP-compatible agent
-
-See the [Installation Guide](./INSTALLATION.md) for setup instructions for each agent.
-
-## 🐛 Troubleshooting
-
-### Authentication Errors
-
-If you see authentication errors:
-
-1. Verify your `HAWKEYE_EMAIL` and `HAWKEYE_PASSWORD` are correct
-2. Check that `HAWKEYE_BASE_URL` points to the correct Hawkeye instance
-3. Ensure your account has API access
-
-### Connection Issues
-
-If the MCP server isn't connecting:
-
-1. Make sure Node.js >= 20.0.0 is installed: `node --version`
-2. Verify the server is accessible: test with `npx hawkeye-mcp-server`
-3. Check your AI agent's MCP configuration
-4. Review logs for detailed error messages
-
-### Investigation Timeouts
-
-If investigations are timing out:
-
-1. Increase `HAWKEYE_MAX_POLL_ATTEMPTS` in your environment
-2. Check your network connection
-3. Verify the investigation is running in Hawkeye
-
-For more troubleshooting tips, see the [Installation Guide](./INSTALLATION.md#troubleshooting).
-
-## 📊 Examples
-
-### Example 1: Using in Cursor IDE
-
-```
-You: "List all my Hawkeye projects"
-
-Cursor: *Shows your available projects with sync status*
-
-You: "Show me all uninvestigated incidents from the Variation1 project"
-
-Cursor: *Lists uninvestigated incidents*
-
-You: "Investigate the most recent one"
-
-Cursor: *Creates investigation and returns detailed RCA*
+```bash
+# Run all tests
+npm test
 
-You: "Can you dig deeper into the network issues mentioned?"
+# Test specific file
+node tests/test-your-feature.js
 
-Cursor: *Continues investigation with follow-up analysis*
+# Test with MCP Inspector (interactive)
+npx @modelcontextprotocol/inspector node build/index.js
 ```
 
-### Example 2: Find and Investigate Uninvestigated Incidents
+### Building and Publishing
 
+**Building:**
+```bash
+npm run build
 ```
-You: "Show me all uninvestigated P1 incidents from last week"
 
-Agent: *Lists uninvestigated P1 incidents*
+**Publishing to npm:**
+```bash
+# Update version in package.json
+npm version patch  # or minor, or major
 
-You: "Investigate the first one"
+# Build
+npm run build
 
-Agent: *Creates investigation and returns RCA*
+# Publish
+npm publish
 ```
 
-### Example 2: Get Project Analytics
+**Note:** Only maintainers can publish to npm.
 
-```
-You: "What's our MTTR and how much time has Hawkeye saved us?"
+### Code Style
 
-Agent: *Returns incident report with metrics*
+- Use TypeScript for all new code
+- Follow existing code patterns
+- Add JSDoc comments for public APIs
+- Use meaningful variable names
+- Keep functions focused and small
 
-Result:
-- Average MTTR: 45 minutes
-- Total time saved: 234 hours
-- Noise reduction: 67%
-- Total investigations: 156
-```
+### Adding New Tools
 
-### Example 3: Get RCA with Corrective Actions
+1. **Create tool file in `src/tools/`:**
+   ```typescript
+   export const toolName = {
+     name: 'hawkeye_tool_name',
+     description: 'Tool description',
+     inputSchema: {
+       type: 'object',
+       properties: {
+         // Define parameters
+       },
+       required: []
+     }
+   };
+   ```
 
-```
-You: "Show me the RCA for session abc-123"
-
-Agent: *Returns comprehensive analysis including:*
-
-**Root Cause:** Application querying non-existent table "ghosts" from IP 172.31.64.56
-
-**Corrective Actions:**
-```sh
-# Example of checking application deployment or configuration
-ssh user@172.31.64.56
-# Locate and examine the application's database query configuration
-grep -r 'ghosts' /path/to/application/
-# Update configuration to reference the correct table
-vi /path/to/application/config/database.cfg
-# Restart application to apply changes
-systemctl restart app_service
-```
+2. **Implement handler in `src/index.ts`:**
+   ```typescript
+   case 'hawkeye_tool_name':
+     // Implementation
+     break;
+   ```
 
-**Time Savings:** 17 minutes (Manual: 25min → Hawkeye: 8min)
+3. **Update documentation:**
+   - Add to TOOLS_REFERENCE.md
+   - Update tool count in README.md
+   - Add examples if needed
 
-You: "What's the quality score for this investigation?"
+4. **Add tests:**
+   - Create test file in `tests/`
+   - Test both success and error cases
 
-Agent: *Uses hawkeye_get_rca_score - Returns:*
-- Accuracy: 66% (Root cause ✓ | Impact ✗ | Timeline ✓)
-- Completeness: 57% (Data sources: 80% | Remediation: 70%)
-- Trust without review: Maybe
-```
+### Documentation Updates
 
-### Example 4: Deep Dive into Investigation Reasoning
+If your changes affect the documentation site:
 
-```
-You: "How did you arrive at that conclusion?"
+1. Documentation lives in separate repo: [neubirdai/hawkeye-mcp-docs](https://github.com/neubirdai/hawkeye-mcp-docs)
+2. Create PR there with documentation updates
+3. Link documentation PR in your code PR
 
-Agent: *Uses hawkeye_get_chain_of_thought - Returns reasoning steps*
+### Getting Help
 
-You: "What data sources did you check?"
+- **Internal Slack:** #hawkeye-mcp channel
+- **Code Questions:** Ask in PR comments
+- **Design Discussions:** Create GitHub issue
 
-Agent: *Uses hawkeye_get_investigation_sources - Returns 24 sources*
-```
+## 🐛 Troubleshooting
 
-For more examples, see the [Usage Guide](./USAGE.md).
+For detailed troubleshooting, see [Troubleshooting Guide](https://neubirdai.github.io/hawkeye-mcp-docs/troubleshooting/).
 
-## 🔐 Security & Privacy
+**Common issues:**
 
-- Credentials are only used for authentication with your Hawkeye instance
-- No data is sent to third parties
-- All communication is over HTTPS
-- Tokens are cached securely in memory only
-- See [SECURITY.md](./SECURITY.md) for our security policy (if applicable)
+- **Authentication errors:** Verify `HAWKEYE_EMAIL`, `HAWKEYE_PASSWORD`, and `HAWKEYE_BASE_URL`
+- **Tools not showing:** Restart MCP client completely
+- **Investigation timeout:** Check connection sync status, increase `HAWKEYE_MAX_POLL_ATTEMPTS`
 
 ## 📝 Changelog
 
@@ -462,17 +371,15 @@ See [CHANGELOG.md](./CHANGELOG.md) for version history and release notes.
 
 ## 🤝 Support
 
-Need help? Have questions?
-
-- **Email**: support@neubird.ai
-- **Documentation**: [Full Documentation](./INSTALLATION.md)
-- **Issues**: For bug reports and feature requests, contact support@neubird.ai
+- **Documentation:** [https://neubirdai.github.io/hawkeye-mcp-docs](https://neubirdai.github.io/hawkeye-mcp-docs)
+- **Email:** support@neubird.ai
+- **Website:** [https://neubird.ai](https://neubird.ai)
 
 ## 📄 License
 
 MIT License - see [LICENSE](./LICENSE) file for details.
 
-Copyright (c) 2024 Neubird AI
+Copyright © 2024 NeuBird AI
 
 ## 🙏 Acknowledgments
 
@@ -484,5 +391,4 @@ Built with:
 
 ---
 
-**Made with ❤️ by [Neubird AI](https://neubird.ai)** | Powered by Hawkeye
-
+**Made with ❤️ by [NeuBird AI](https://neubird.ai)** | [Documentation](https://neubirdai.github.io/hawkeye-mcp-docs) | [npm](https://www.npmjs.com/package/hawkeye-mcp-server)