hawkeye-mcp-server 2.3.1 → 3.0.0

package/README.md

@@ -1,575 +1,31 @@
-# Hawkeye MCP Server
+# 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/)
+> **This package has been renamed to [`mcp-server-neubird`](https://www.npmjs.com/package/mcp-server-neubird).**
 
-> 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 Hawkeye MCP?
-
-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
-
-- 🌊 **Real-Time Progress** ✨ **NEW in v2.0** - Stream live investigation progress with emojis and timing
-- 🔍 **AI-Powered RCA** - Automated root cause analysis with corrective actions (including bash scripts)
-- 🎯 **42 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
+Install the new package:
 
 ```bash
-# Install globally
-npm install -g hawkeye-mcp-server
-
-# Or use directly with npx (no installation)
-npx hawkeye-mcp-server
-```
-
-### Configuration
-
-Add to your MCP client configuration:
-
-**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
-
-```json
-{
-  "mcpServers": {
-    "hawkeye": {
-      "command": "npx",
-      "args": ["-y", "hawkeye-mcp-server"],
-      "env": {
-        "HAWKEYE_EMAIL": "your-email@company.com",
-        "HAWKEYE_PASSWORD": "your-password",
-        "HAWKEYE_BASE_URL": "https://app.neubird.ai/api"
-      }
-    }
-  }
-}
+npx mcp-server-neubird@latest
 ```
 
-**Cursor** (`~/.cursor/mcp.json`):
+Or update your MCP configuration:
 
 ```json
 {
   "mcpServers": {
-    "hawkeye": {
+    "neubird": {
       "command": "npx",
-      "args": ["-y", "hawkeye-mcp-server"],
+      "args": ["-y", "mcp-server-neubird@latest"],
       "env": {
-        "HAWKEYE_EMAIL": "your-email@company.com",
-        "HAWKEYE_PASSWORD": "your-password",
-        "HAWKEYE_BASE_URL": "https://app.neubird.ai/api"
-      }
-    }
-  }
-}
-```
-
-Restart your MCP client and start investigating!
-
-## 📖 Documentation
-
-**Complete documentation is available at: [https://neubirdai.github.io/hawkeye-mcp-docs](https://neubirdai.github.io/hawkeye-mcp-docs)**
-
-- **[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
-
-## 🎯 Example Usage
-
-```
-You: "Show me uninvestigated alerts from the last 24 hours"
-
-Claude: *Lists uninvestigated incidents*
-
-You: "Investigate the first one"
-
-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")
-
-You: "Why did this happen? Has it happened before?"
-
-Claude: *Uses follow-up investigation to provide deeper analysis*
-```
-
-## 🌊 Real-Time Streaming Progress (NEW in v2.0)
-
-No more waiting 5-10 minutes with no feedback! Hawkeye MCP now streams real-time investigation progress:
-
-```
-You: "Investigate high CPU usage in production"
-
-Claude:
-🔧 Preparing telemetry sources [2s]
-📚 Loading investigation context [3s]
-🔍 Classifying datasources (Step 1) [18s]
-🎯 Fine-tuning datasources [26s]
-🔎 Consulting telemetry (Query 7) [1m 6s]
-🧠 Analyzing telemetry data (Analysis 12) [1m 13s]
-📝 Summarizing results [1m 29s]
-
-Investigation completed! Here's what I found...
-```
-
-**Benefits:**
-- ✅ See exactly what Hawkeye is doing in real-time
-- ✅ Know how long each phase takes
-- ✅ Track query and analysis counts
-- ✅ Estimated progress percentage (0-100%)
-- ✅ Complete progress log for debugging
-- ✅ Enabled by default (can opt-out with `stream_progress: false`)
-
-**Supported Tools:**
-- `hawkeye_create_manual_investigation` - Stream progress for custom investigations
-- `hawkeye_investigate_alert` - Stream progress when investigating alerts
-
-## 🛠️ Tool Categories
-
-| Category | Tools | Description |
-|----------|-------|-------------|
-| **Projects** | 6 | 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 |
-
-**Total: 42 tools**
-
-See the [Tool Reference](https://neubirdai.github.io/hawkeye-mcp-docs/reference/overview/) for complete documentation.
-
-## 🧪 Unique Features
-
-### Instruction Testing Workflow
-
-Hawkeye MCP is the only incident investigation tool that lets you **test instructions before deploying them**:
-
-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
-
-This prevents bad instructions from affecting all your investigations.
-
-Learn more: [Testing Instructions Guide](https://neubirdai.github.io/hawkeye-mcp-docs/guides/testing-instructions/)
-
-## 🤝 Supported AI Clients
-
-Works with any MCP-compatible client:
-
-- ✅ **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
-
-### Transport Modes
-
-Hawkeye MCP Server supports two transport modes:
-
-| Mode | Use Case | Authentication |
-|------|----------|----------------|
-| **Stdio** (default) | npm/npx usage with MCP clients | Environment variables |
-| **HTTP/SSE** | Kubernetes deployment, multi-user | Headers (Bearer token or password) |
-
-### Stdio Transport (Default)
-
-For use with Claude Desktop, Cursor, and other MCP clients:
-
-#### Required Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `HAWKEYE_EMAIL` | Your Hawkeye account email |
-| `HAWKEYE_PASSWORD` | Your Hawkeye account password |
-| `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 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) |
-
-### HTTP/SSE Transport (Kubernetes Deployment)
-
-For multi-user deployments, use the HTTP/SSE transport with per-request authentication.
-
-#### Server Configuration
-
-| Variable | Description |
-|----------|-------------|
-| `TRANSPORT_MODE` | Set to `http` to enable HTTP/SSE transport |
-| `HTTP_PORT` | HTTP server port (default: 3000) |
-| `HAWKEYE_BASE_URL` | Hawkeye API endpoint |
-| `CONFIGDB_URI` | PostgreSQL connection string |
-| `CONFIGDB_USER` | PostgreSQL username |
-| `CONFIGDB_PASSWORD` | PostgreSQL password |
-
-#### Client Authentication
-
-The HTTP/SSE transport supports two authentication methods:
-
-**1. Bearer Token (Auth0/OAuth) - Recommended**
-```
-Authorization: Bearer <auth0_access_token>
-```
-
-**2. Password Credentials (Legacy)**
-```
-X-Hawkeye-Email: user@example.com
-X-Hawkeye-Password: your-password
-```
-
-#### MCP Client Configuration (HTTP/SSE)
-
-**With Bearer Token:**
-```json
-{
-  "mcpServers": {
-    "hawkeye": {
-      "url": "https://hawkeye-mcp.example.com/mcp",
-      "headers": {
-        "Authorization": "Bearer <auth0_access_token>"
+        "NEUBIRD_EMAIL": "your-email@company.com",
+        "NEUBIRD_PASSWORD": "your-password",
+        "NEUBIRD_BASE_URL": "https://<your-deployment>.app.neubird.ai/api"
       }
     }
   }
 }
 ```
 
-**With Password Credentials:**
-```json
-{
-  "mcpServers": {
-    "hawkeye": {
-      "url": "https://hawkeye-mcp.example.com/mcp",
-      "headers": {
-        "X-Hawkeye-Email": "user@example.com",
-        "X-Hawkeye-Password": "your-password"
-      }
-    }
-  }
-}
-```
-
-#### Obtaining an Auth0 Token
-
-Clients can obtain Auth0 tokens by:
-1. **Via Hawkeye UI**: Login to hawkeye-ui, extract token from localStorage (`access_token`)
-2. **Via Auth0 SDK**: Use Auth0 SDK to perform OAuth flow directly
-
-## 👥 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
-
-Hawkeye MCP includes comprehensive testing for unit, integration, and end-to-end validation.
-
-#### Test Organization
-
-```
-tests/
-├── README.md              # Complete testing guide
-├── unit/                  # Unit tests for individual tools
-├── integration/           # Integration tests (planned)
-└── e2e/                   # End-to-end testing workflows
-    ├── test-connections.md   # Test credentials and setup
-    └── test-prompt.md        # Complete onboarding workflow
-```
-
-#### Running Tests
-
-**Unit Tests:**
-```bash
-# Build first
-npm run build
-
-# Run authentication test
-node tests/unit/test-auth.js
-
-# Run connection tools test
-node tests/unit/test-connection-tools.mjs
-
-# Run manual investigation test (requires prompt argument)
-./tests/unit/test-manual-investigation.mjs "Investigate high CPU in api-gateway"
-
-# Test with MCP Inspector (interactive)
-npx @modelcontextprotocol/inspector node build/index.js
-```
-
-**End-to-End Tests:**
-
-E2E tests are designed for AI coding agents (Claude Desktop/Code):
-
-1. Open your AI coding agent
-2. Navigate to `tests/e2e/test-prompt.md`
-3. Copy the test workflow
-4. Paste into your AI agent
-5. Let it execute each phase
-6. Verify outcomes match expectations
-
-**Test Resources:**
-
-- **[tests/README.md](./tests/README.md)** - Complete testing guide with best practices
-- **[tests/e2e/test-connections.md](./tests/e2e/test-connections.md)** - Test environment credentials
-- **[tests/e2e/test-prompt.md](./tests/e2e/test-prompt.md)** - Complete E2E onboarding workflow
-
-#### Test Types
-
-| Type | Location | Purpose | Duration |
-|------|----------|---------|----------|
-| **Unit** | `tests/unit/` | Test individual tools in isolation | Seconds |
-| **Integration** | `tests/integration/` | Test tools working together | Minutes |
-| **E2E** | `tests/e2e/` | Test complete user workflows with AI agent | 45-90 min |
-
-#### Quick Validation
-
-Before submitting a PR, run these quick tests:
-
-```bash
-# 1. Build
-npm run build
-
-# 2. Test authentication
-node tests/unit/test-auth.js
-
-# 3. Test a few core tools
-node tests/unit/test-connection-tools.mjs
-./tests/unit/test-manual-investigation.mjs "Test investigation"
-
-# 4. Verify tools load in MCP Inspector
-npx @modelcontextprotocol/inspector node build/index.js
-```
-
-For comprehensive testing documentation, see **[tests/README.md](./tests/README.md)**.
-
-### Building and Publishing
-
-**Building:**
-```bash
-npm run build
-```
-
-**Publishing to npm:**
-```bash
-# Update version in package.json
-npm version patch  # or minor, or major
-
-# Build
-npm run build
-
-# Publish
-npm publish
-```
-
-**Note:** Only maintainers can publish to npm.
-
-### Code Style
-
-- 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
-
-### Adding New Tools
-
-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: []
-     }
-   };
-   ```
-
-2. **Implement handler in `src/index.ts`:**
-   ```typescript
-   case 'hawkeye_tool_name':
-     // Implementation
-     break;
-   ```
-
-3. **Update documentation:**
-   - Add to TOOLS_REFERENCE.md
-   - Update tool count in README.md
-   - Add examples if needed
-
-4. **Add tests:**
-   - Create test file in `tests/`
-   - Test both success and error cases
-
-### Documentation Updates
-
-If your changes affect the documentation site:
-
-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
-
-### Getting Help
-
-- **Internal Slack:** #hawkeye-mcp channel
-- **Code Questions:** Ask in PR comments
-- **Design Discussions:** Create GitHub issue
-
-## 🐛 Troubleshooting
-
-For detailed troubleshooting, see [Troubleshooting Guide](https://neubirdai.github.io/hawkeye-mcp-docs/troubleshooting/).
-
-**Common issues:**
-
-- **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
-
-See [CHANGELOG.md](./CHANGELOG.md) for version history and release notes.
-
-## 🤝 Support
-
-- **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 © 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
-
----
+Environment variables `HAWKEYE_EMAIL`, `HAWKEYE_PASSWORD`, and `HAWKEYE_BASE_URL` continue to work but `NEUBIRD_*` is preferred.
 
-**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)
+For full documentation, visit [help.neubird.ai/mcp](https://help.neubird.ai/mcp/overview/).

package/package.json

@@ -1,74 +1,25 @@
 {
   "name": "hawkeye-mcp-server",
-  "version": "2.3.1",
-  "description": "MCP Server for Hawkeye automated incident investigation and root cause analysis",
+  "version": "3.0.0",
+  "description": "This package has been renamed to @neubirdai/mcp-server-neubird. Install @neubirdai/mcp-server-neubird instead.",
   "private": false,
-  "type": "module",
-  "main": "build/index.js",
-  "bin": {
-    "hawkeye-mcp-server": "./build/index.js"
+  "dependencies": {
+    "@neubirdai/mcp-server-neubird": "^3.0.0"
   },
-  "files": [
-    "build/**/*",
-    "README.md",
-    "INSTALLATION.md",
-    "USAGE.md",
-    "SPECIFICATION.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
-  "scripts": {
-    "start": "node build/index.js",
-    "start:http": "TRANSPORT_MODE=http node build/server.js",
-    "build": "tsc && chmod 755 build/index.js && chmod 755 build/server.js",
-    "typecheck": "tsc --noEmit",
-    "prestart": "npm run build",
-    "prepublishOnly": "npm run build",
-    "test": "npm run build && node --test tests/basic/**/*.test.mjs",
-    "test:install": "node build/index.js --version"
+  "bin": {
+    "hawkeye-mcp-server": "./node_modules/.bin/mcp-server-neubird"
   },
   "keywords": [
     "mcp",
-    "model-context-protocol",
-    "hawkeye",
     "neubird",
-    "incident-investigation",
-    "rca",
-    "root-cause-analysis",
-    "cloud-monitoring",
-    "observability",
-    "cursor",
-    "claude",
-    "ai-agent"
+    "hawkeye",
+    "deprecated"
   ],
   "author": "Neubird AI <support@neubird.ai>",
   "license": "MIT",
+  "homepage": "https://help.neubird.ai/mcp/overview/",
   "repository": {
     "type": "git",
-    "url": "https://github.com/neubirdai/mcp-server-hawkeye"
-  },
-  "homepage": "https://github.com/neubirdai/mcp-server-hawkeye/tree/main",
-  "bugs": {
-    "email": "support@neubird.ai"
-  },
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.10.0",
-    "axios": "^1.9.0",
-    "cors": "^2.8.5",
-    "dotenv": "^16.4.5",
-    "express": "^5.2.1",
-    "json-schema-to-zod": "^2.6.1",
-    "pg": "^8.16.3",
-    "zod": "^3.24.3"
-  },
-  "devDependencies": {
-    "@types/cors": "^2.8.19",
-    "@types/express": "^5.0.6",
-    "@types/node": "^22.15.2",
-    "@types/pg": "^8.15.6",
-    "typescript": "^5.8.3"
+    "url": "https://github.com/neubirdai/mcp-server-neubird"
   }
 }