hawkeye-mcp-server 1.0.0

package/INSTALLATION.md

@@ -0,0 +1,734 @@
+# Installation Guide
+
+Complete installation instructions for the Hawkeye MCP Server across all platforms and AI agents.
+
+## Table of Contents
+
+- [System Requirements](#system-requirements)
+- [Installation Methods](#installation-methods)
+  - [Method 1: npm Global Install (Recommended)](#method-1-npm-global-install-recommended)
+  - [Method 2: npx (No Install)](#method-2-npx-no-install)
+  - [Method 3: Local Development Setup](#method-3-local-development-setup)
+- [Configuration](#configuration)
+- [Integration with AI Agents](#integration-with-ai-agents)
+  - [Claude Desktop](#claude-desktop)
+  - [Cursor.ai](#cursorai)
+  - [Continue.dev](#continuedev)
+- [Verification](#verification)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## System Requirements
+
+### Minimum Requirements
+
+- **Node.js**: >= 20.0.0
+- **npm**: >= 9.0.0 (comes with Node.js)
+- **Operating System**: macOS, Windows 10/11, or Linux
+- **Network**: Internet connection to reach your Hawkeye instance
+- **Hawkeye Access**: Valid Hawkeye account with API access
+
+### Checking Your System
+
+```bash
+# Check Node.js version
+node --version
+# Should output v20.0.0 or higher
+
+# Check npm version
+npm --version
+# Should output 9.0.0 or higher
+```
+
+### Installing Node.js
+
+If you don't have Node.js >= 20.0.0:
+
+**macOS:**
+```bash
+# Using Homebrew
+brew install node@20
+
+# Or download from nodejs.org
+# https://nodejs.org/
+```
+
+**Windows:**
+```bash
+# Download installer from nodejs.org
+# https://nodejs.org/
+
+# Or using Chocolatey
+choco install nodejs-lts
+```
+
+**Linux (Ubuntu/Debian):**
+```bash
+# Using NodeSource repository
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt-get install -y nodejs
+```
+
+**Linux (Fedora):**
+```bash
+sudo dnf install nodejs
+```
+
+---
+
+## Installation Methods
+
+### Method 1: npm Global Install (Recommended)
+
+This method installs the Hawkeye MCP Server globally on your system, making it available from anywhere.
+
+**Installation:**
+
+```bash
+npm install -g hawkeye-mcp-server
+```
+
+**Verification:**
+
+```bash
+# Check that it's installed
+npm list -g hawkeye-mcp-server
+
+# Try running it (it will show configuration error if env vars not set)
+hawkeye-mcp
+```
+
+**Pros:**
+- Easy to use
+- Available system-wide
+- Simple updates: `npm update -g hawkeye-mcp-server`
+
+**Cons:**
+- Requires installation step
+- May need sudo on some Linux systems
+
+---
+
+### Method 2: npx (No Install)
+
+Use the server directly without installing it. npx downloads and runs the latest version automatically.
+
+**Usage:**
+
+```bash
+npx hawkeye-mcp-server
+```
+
+**Pros:**
+- No installation required
+- Always uses latest version
+- Great for trying it out
+- No global package pollution
+
+**Cons:**
+- Slightly slower first run (downloads package)
+- Requires internet connection each time cache expires
+
+**When to use:**
+- Quick testing
+- CI/CD environments
+- When you don't want global installs
+- One-time usage
+
+---
+
+### Method 3: Local Development Setup
+
+For contributors or those who want to run from source.
+
+**Clone and Setup:**
+
+```bash
+# Clone the repository (adjust path as needed)
+git clone https://github.com/neubird/solutions
+cd solutions/hawkeye-mcp
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run the server
+npm start
+```
+
+**Development Commands:**
+
+```bash
+# TypeScript type checking
+npm run typecheck
+
+# Build
+npm run build
+
+# Run
+npm start
+```
+
+---
+
+## Configuration
+
+The Hawkeye MCP Server is configured using environment variables.
+
+### Required Environment Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `HAWKEYE_EMAIL` | Your Hawkeye account email | `user@example.com` |
+| `HAWKEYE_PASSWORD` | Your Hawkeye account password | `your-secure-password` |
+| `HAWKEYE_BASE_URL` | Hawkeye API base URL | `https://app.neubird.ai/api` |
+
+### Optional Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `HAWKEYE_DEFAULT_PROJECT_UUID` | None | Default project UUID |
+| `HAWKEYE_DEFAULT_ORGANIZATION_UUID` | `ORGANIZATION_NAME_ROOT` | Default organization |
+| `HAWKEYE_MAX_POLL_ATTEMPTS` | `30` | Max polling attempts |
+| `HAWKEYE_POLL_INTERVAL_MS` | `2000` | Polling interval (ms) |
+| `HAWKEYE_ENABLE_STREAMING` | `true` | Enable streaming |
+| `HAWKEYE_LOG_ENABLED` | `true` | Enable logging |
+| `HAWKEYE_LOG_LEVEL` | `info` | Log level |
+
+### Configuration Methods
+
+#### Option 1: Environment Variables (Recommended for AI Agents)
+
+Set environment variables directly in your AI agent's MCP configuration. See the integration sections below.
+
+#### Option 2: .env File (For Development)
+
+Create a `.env` file in the project directory:
+
+```bash
+# Copy the example file
+cp .env.example .env
+
+# Edit .env with your credentials
+nano .env  # or use your favorite editor
+```
+
+Example `.env` file:
+
+```env
+HAWKEYE_EMAIL=user@example.com
+HAWKEYE_PASSWORD=your-password
+HAWKEYE_BASE_URL=https://app.neubird.ai/api
+```
+
+#### Option 3: System Environment Variables
+
+**macOS/Linux:**
+
+Add to your `~/.bashrc`, `~/.zshrc`, or `~/.profile`:
+
+```bash
+export HAWKEYE_EMAIL="user@example.com"
+export HAWKEYE_PASSWORD="your-password"
+export HAWKEYE_BASE_URL="https://app.neubird.ai/api"
+```
+
+Then reload:
+```bash
+source ~/.bashrc  # or ~/.zshrc
+```
+
+**Windows (PowerShell):**
+
+```powershell
+$env:HAWKEYE_EMAIL="user@example.com"
+$env:HAWKEYE_PASSWORD="your-password"
+$env:HAWKEYE_BASE_URL="https://app.neubird.ai/api"
+```
+
+**Windows (Command Prompt):**
+
+```cmd
+set HAWKEYE_EMAIL=user@example.com
+set HAWKEYE_PASSWORD=your-password
+set HAWKEYE_BASE_URL=https://app.neubird.ai/api
+```
+
+---
+
+## Integration with AI Agents
+
+### Claude Desktop
+
+Claude Desktop is Anthropic's desktop application that supports MCP servers.
+
+#### macOS Installation
+
+1. **Install Claude Desktop**
+
+Download from: https://claude.ai/download
+
+2. **Locate Configuration File**
+
+```bash
+# Claude Desktop config location
+~/Library/Application Support/Claude/claude_desktop_config.json
+```
+
+3. **Edit Configuration**
+
+Open the file and add the Hawkeye MCP server:
+
+```json
+{
+  "mcpServers": {
+    "hawkeye": {
+      "command": "npx",
+      "args": ["hawkeye-mcp-server"],
+      "env": {
+        "HAWKEYE_EMAIL": "your-email@example.com",
+        "HAWKEYE_PASSWORD": "your-password",
+        "HAWKEYE_BASE_URL": "https://app.neubird.ai/api"
+      }
+    }
+  }
+}
+```
+
+**Alternative (if installed globally):**
+
+```json
+{
+  "mcpServers": {
+    "hawkeye": {
+      "command": "hawkeye-mcp",
+      "args": [],
+      "env": {
+        "HAWKEYE_EMAIL": "your-email@example.com",
+        "HAWKEYE_PASSWORD": "your-password",
+        "HAWKEYE_BASE_URL": "https://app.neubird.ai/api"
+      }
+    }
+  }
+}
+```
+
+4. **Restart Claude Desktop**
+
+Close and reopen Claude Desktop for changes to take effect.
+
+5. **Verify**
+
+In Claude Desktop, you should see Hawkeye tools available. Try asking:
+```
+"List my Hawkeye projects"
+```
+
+#### Windows Installation
+
+1. **Install Claude Desktop**
+
+Download from: https://claude.ai/download
+
+2. **Locate Configuration File**
+
+```
+%APPDATA%\Claude\claude_desktop_config.json
+```
+
+Or navigate to:
+```
+C:\Users\YourUsername\AppData\Roaming\Claude\claude_desktop_config.json
+```
+
+3. **Edit Configuration**
+
+Same JSON configuration as macOS above.
+
+**Note for Windows:** Use `npx` command as shown above, not direct paths.
+
+4. **Restart Claude Desktop**
+
+5. **Verify**
+
+Ask Claude to list your projects to verify the integration works.
+
+---
+
+### Cursor.ai
+
+Cursor is an AI-powered code editor with MCP support.
+
+#### Installation (All Platforms)
+
+1. **Install Cursor**
+
+Download from: https://cursor.sh
+
+2. **Open MCP Settings**
+
+- **macOS**: `Cmd+Shift+P` → "MCP: Edit Configuration"
+- **Windows/Linux**: `Ctrl+Shift+P` → "MCP: Edit Configuration"
+
+Or manually edit the file:
+- **macOS**: `~/.cursor/mcp.json`
+- **Windows**: `%APPDATA%\Cursor\mcp.json`
+- **Linux**: `~/.config/cursor/mcp.json`
+
+3. **Add Hawkeye Configuration**
+
+```json
+{
+  "mcpServers": {
+    "hawkeye": {
+      "command": "npx",
+      "args": ["hawkeye-mcp-server"],
+      "env": {
+        "HAWKEYE_EMAIL": "your-email@example.com",
+        "HAWKEYE_PASSWORD": "your-password",
+        "HAWKEYE_BASE_URL": "https://app.neubird.ai/api"
+      }
+    }
+  }
+}
+```
+
+4. **Reload Cursor**
+
+- **macOS**: `Cmd+Shift+P` → "Developer: Reload Window"
+- **Windows/Linux**: `Ctrl+Shift+P` → "Developer: Reload Window"
+
+5. **Verify**
+
+Open Cursor's AI chat and ask:
+```
+"Show me all Hawkeye projects"
+```
+
+#### Cursor-Specific Tips
+
+- **Workspace Configuration**: You can also add MCP configuration per-workspace in `.cursor/mcp.json`
+- **Multiple Projects**: If you have multiple Hawkeye projects, set `HAWKEYE_DEFAULT_PROJECT_UUID`
+- **Performance**: Use global install (`hawkeye-mcp` command) for faster startup
+
+---
+
+### Continue.dev
+
+Continue is a VS Code extension that supports MCP.
+
+#### Installation
+
+1. **Install Continue Extension**
+
+In VS Code:
+- Open Extensions (`Cmd+Shift+X` or `Ctrl+Shift+X`)
+- Search for "Continue"
+- Install the extension
+
+2. **Open Continue Configuration**
+
+- Click Continue icon in sidebar
+- Click gear icon ⚙️ for settings
+- Or open `~/.continue/config.json`
+
+3. **Add MCP Server**
+
+Add to the `mcpServers` section:
+
+```json
+{
+  "mcpServers": {
+    "hawkeye": {
+      "command": "npx",
+      "args": ["hawkeye-mcp-server"],
+      "env": {
+        "HAWKEYE_EMAIL": "your-email@example.com",
+        "HAWKEYE_PASSWORD": "your-password",
+        "HAWKEYE_BASE_URL": "https://app.neubird.ai/api"
+      }
+    }
+  }
+}
+```
+
+4. **Reload VS Code**
+
+Reload VS Code window for changes to take effect.
+
+5. **Verify**
+
+Use Continue's chat to ask about your Hawkeye projects.
+
+---
+
+### Generic MCP Client
+
+For any other MCP-compatible client:
+
+**Standard Configuration:**
+
+```json
+{
+  "command": "npx",
+  "args": ["hawkeye-mcp-server"],
+  "env": {
+    "HAWKEYE_EMAIL": "your-email@example.com",
+    "HAWKEYE_PASSWORD": "your-password",
+    "HAWKEYE_BASE_URL": "https://app.neubird.ai/api"
+  }
+}
+```
+
+**If Globally Installed:**
+
+```json
+{
+  "command": "hawkeye-mcp",
+  "args": [],
+  "env": {
+    "HAWKEYE_EMAIL": "your-email@example.com",
+    "HAWKEYE_PASSWORD": "your-password",
+    "HAWKEYE_BASE_URL": "https://app.neubird.ai/api"
+  }
+}
+```
+
+---
+
+## Verification
+
+### Test the Server Directly
+
+```bash
+# If installed globally
+hawkeye-mcp
+
+# Or using npx
+npx hawkeye-mcp-server
+
+# You should see MCP server output (not errors about missing config)
+```
+
+### Test in AI Agent
+
+After integration, test with these prompts:
+
+1. **List Projects:**
+```
+"List all my Hawkeye projects"
+```
+
+2. **List Sessions:**
+```
+"Show me recent sessions from project XYZ"
+```
+
+3. **List Uninvestigated:**
+```
+"Show me all uninvestigated incidents"
+```
+
+### Check Logs
+
+If something isn't working, enable debug logging:
+
+```json
+{
+  "env": {
+    "HAWKEYE_LOG_LEVEL": "debug",
+    "HAWKEYE_LOG_ENABLED": "true"
+  }
+}
+```
+
+Then check your AI agent's logs for detailed output.
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. "Node.js version too old"
+
+**Problem:** Node.js < 20.0.0
+
+**Solution:**
+```bash
+# Check version
+node --version
+
+# Upgrade Node.js (see System Requirements section)
+```
+
+#### 2. "Cannot find module 'hawkeye-mcp-server'"
+
+**Problem:** Package not installed or not in PATH
+
+**Solutions:**
+- Use npx: `npx hawkeye-mcp-server`
+- Or install globally: `npm install -g hawkeye-mcp-server`
+- Check PATH: `echo $PATH` (macOS/Linux) or `echo %PATH%` (Windows)
+
+#### 3. "Authentication failed"
+
+**Problem:** Invalid credentials or wrong API URL
+
+**Solutions:**
+- Verify `HAWKEYE_EMAIL` and `HAWKEYE_PASSWORD` are correct
+- Check `HAWKEYE_BASE_URL` points to correct instance
+- Test login in Hawkeye web UI
+- Ensure account has API access
+
+#### 4. "Connection timeout"
+
+**Problem:** Network issues or firewall
+
+**Solutions:**
+- Check internet connection
+- Verify Hawkeye instance is accessible
+- Check firewall settings
+- Try: `curl https://your-instance.app.neubird.ai/api/v1/user/login`
+
+#### 5. "MCP server not showing in AI agent"
+
+**Problem:** Configuration not loaded
+
+**Solutions:**
+- Verify JSON syntax in config file
+- Restart AI agent completely (not just reload)
+- Check config file location is correct
+- Look at AI agent logs for errors
+
+#### 6. "Permission denied" (macOS/Linux)
+
+**Problem:** npm global install permissions
+
+**Solutions:**
+```bash
+# Option 1: Use npx instead (recommended)
+npx hawkeye-mcp-server
+
+# Option 2: Fix npm permissions
+sudo chown -R $USER /usr/local/lib/node_modules
+
+# Option 3: Use sudo (not recommended)
+sudo npm install -g hawkeye-mcp-server
+```
+
+#### 7. "Module parse failed" or build errors
+
+**Problem:** Corrupted installation
+
+**Solution:**
+```bash
+# Clear npm cache
+npm cache clean --force
+
+# Reinstall
+npm uninstall -g hawkeye-mcp-server
+npm install -g hawkeye-mcp-server
+```
+
+### Getting Debug Information
+
+Enable debug logging in your configuration:
+
+```json
+{
+  "env": {
+    "HAWKEYE_LOG_LEVEL": "debug",
+    "HAWKEYE_LOG_ENABLED": "true"
+  }
+}
+```
+
+### Platform-Specific Issues
+
+#### macOS
+
+**Issue:** "command not found: hawkeye-mcp"
+
+**Solution:**
+```bash
+# Check npm global bin path
+npm config get prefix
+
+# Add to PATH in ~/.zshrc or ~/.bashrc
+export PATH="$PATH:$(npm config get prefix)/bin"
+
+# Reload shell
+source ~/.zshrc
+```
+
+#### Windows
+
+**Issue:** PowerShell execution policy
+
+**Solution:**
+```powershell
+# Allow scripts
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+**Issue:** Path with spaces
+
+**Solution:** Use quotes in configuration:
+```json
+{
+  "command": "C:\\Program Files\\nodejs\\npx.cmd"
+}
+```
+
+#### Linux
+
+**Issue:** EACCES permissions error
+
+**Solution:**
+```bash
+# Create npm global directory in home
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+
+# Add to PATH in ~/.bashrc
+export PATH=~/.npm-global/bin:$PATH
+
+# Reload
+source ~/.bashrc
+
+# Reinstall
+npm install -g hawkeye-mcp-server
+```
+
+### Still Having Issues?
+
+Contact support with:
+
+1. **Error message** (full text)
+2. **Platform** (macOS/Windows/Linux + version)
+3. **Node.js version**: `node --version`
+4. **npm version**: `npm --version`
+5. **Installation method** used
+6. **AI agent** (Claude Desktop/Cursor/etc.)
+7. **Configuration** (remove sensitive data)
+
+**Email:** support@neubird.ai
+
+---
+
+## Next Steps
+
+After installation:
+
+1. **Read the [Usage Guide](./USAGE.md)** for examples and workflows
+2. **Review the [API Reference](./SPECIFICATION.md)** for detailed tool documentation
+3. **Try the examples** in the Usage Guide
+4. **Set up default project** if you mainly use one project
+
+---
+
+**Installation complete! Start investigating incidents with AI.** 🚀