hawkeye-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Neubird AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,289 @@
+# Hawkeye MCP Server
+
+[![npm version](https://img.shields.io/npm/v/hawkeye-mcp-server.svg)](https://www.npmjs.com/package/hawkeye-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
+
+> 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?
+
+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.
+
+**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
+- 📈 **Analytics & Reporting** - Get organization-wide incident statistics, MTTR, and time-saved metrics
+- 💬 **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
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Install globally with npm
+npm install -g hawkeye-mcp-server
+
+# Or use directly with npx (no installation required)
+npx hawkeye-mcp-server
+```
+
+### 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 (example for Claude Desktop):
+
+```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"
+      }
+    }
+  }
+}
+```
+
+3. Start using it! Ask your AI agent:
+
+```
+"Show me all uninvestigated incidents from the HTM-Azure project"
+```
+
+## 📖 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
+
+### 1. List Uninvestigated Incidents
+
+Find incidents that haven't been analyzed yet:
+
+```
+"List all uninvestigated incidents in my default project"
+```
+
+The MCP server will call `hawkeye_list_sessions` with:
+```json
+{
+  "only_uninvestigated": true
+}
+```
+
+### 2. 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.
+
+### 3. Get Investigation Details
+
+Deep dive into a specific investigation:
+
+```
+"Show me the full analysis from session abc-123-def-456"
+```
+
+### 4. View Analytics
+
+Get organization-wide incident statistics:
+
+```
+"Show me the incident report with MTTR and time saved metrics"
+```
+
+### 5. Continue an Investigation
+
+Ask follow-up questions on an existing investigation:
+
+```
+"Can you dig deeper into the network policy issues you found?"
+```
+
+## 🛠️ Available Tools
+
+The Hawkeye MCP Server provides the following tools to AI agents:
+
+| Tool | Description |
+|------|-------------|
+| `hawkeye_list_projects` | List all available Hawkeye projects |
+| `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 |
+| `hawkeye_list_sessions` | List sessions with filtering (uninvestigated, date range, etc.) |
+| `hawkeye_inspect_session` | Get detailed information about a specific session |
+| `hawkeye_get_session_report` | Get summary reports with time-saved metrics |
+| `hawkeye_get_session_summary` | Get quality scores and analysis metrics |
+| `hawkeye_get_incident_report` | Get organization-wide incident analytics |
+
+See the [API Reference](./SPECIFICATION.md) for detailed documentation on each tool.
+
+## 🔧 Configuration Options
+
+### Required Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `HAWKEYE_EMAIL` | Your Hawkeye account email |
+| `HAWKEYE_PASSWORD` | Your Hawkeye account password |
+| `HAWKEYE_BASE_URL` | Hawkeye API base URL |
+
+### 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_LOG_LEVEL` | `info` | Log level (debug, info, warn, error) |
+
+## 🤝 Supported AI Agents
+
+The Hawkeye MCP Server works with any MCP-compatible AI agent:
+
+- ✅ **Claude Desktop** (macOS, Windows)
+- ✅ **Cursor.ai** (macOS, Windows, Linux)
+- ✅ **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: Find and Investigate Uninvestigated Incidents
+
+```
+You: "Show me all uninvestigated P1 incidents from last week"
+
+Agent: *Lists uninvestigated P1 incidents*
+
+You: "Investigate the first one"
+
+Agent: *Creates investigation and returns RCA*
+```
+
+### Example 2: Get Project Analytics
+
+```
+You: "What's our MTTR and how much time has Hawkeye saved us?"
+
+Agent: *Returns incident report with metrics*
+
+Result:
+- Average MTTR: 45 minutes
+- Total time saved: 234 hours
+- Noise reduction: 67%
+- Total investigations: 156
+```
+
+### Example 3: Deep Dive into an Investigation
+
+```
+You: "Show me session abc-123 with all sources and chain of thought"
+
+Agent: *Returns detailed analysis including:*
+- All prompt cycles
+- Chain of thoughts (reasoning steps)
+- Data sources consulted
+- Follow-up suggestions
+```
+
+For more examples, see the [Usage Guide](./USAGE.md).
+
+## 🔐 Security & Privacy
+
+- 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)
+
+## 📝 Changelog
+
+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
+
+## 📄 License
+
+MIT License - see [LICENSE](./LICENSE) file for details.
+
+Copyright (c) 2024 Neubird AI
+
+## 🙏 Acknowledgments
+
+Built with:
+- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk) - MCP Protocol implementation
+- [TypeScript](https://www.typescriptlang.org/) - Type-safe JavaScript
+- [Axios](https://axios-http.com/) - HTTP client
+- [Zod](https://zod.dev/) - Runtime validation
+
+---
+
+**Made with ❤️ by [Neubird AI](https://neubird.ai)** | Powered by Hawkeye
+