@quorum-us/opsgenie-mcp/README.md

MCP server for Opsgenie alert management with comprehensive filtering, custom queries, and AI-friendly interface

# Opsgenie MCP Server

A comprehensive MCP server for Opsgenie alert management with AI assistants.

## Quick Start

### 1. Install via NPM

```bash
npx @quorum-us/opsgenie-mcp
```

### 2. Add to Augment

Add this to your Augment MCP configuration:

```json
{
  "mcpServers": {
    "opsgenie": {
      "command": "npx",
      "args": ["-y", "@quorum-us/opsgenie-mcp"],
      "env": {
        "OPSGENIE_API_KEY": "your-opsgenie-api-key"
      }
    }
  }
}
```

### 3. Opsgenie Setup

Get your Opsgenie API key:

1. Go to Opsgenie → Settings → API key management
2. Create a new API key with appropriate permissions
3. Set the environment variable:
   ```bash
   export OPSGENIE_API_KEY=your_api_key_here
   ```

## Available Tools

### `listAlerts_Opsgenie`

List Opsgenie alerts with comprehensive filtering options.

**Parameters:**
- `limit` (optional): Maximum number of alerts to return (1-100, default: 20)
- `offset` (optional): Number of alerts to skip for pagination (default: 0)
- `status` (optional): Filter by alert status - 'open', 'acknowledged', 'closed', 'all'
- `priority` (optional): Filter by priority - 'P1', 'P2', 'P3', 'P4', 'P5'
- `message` (optional): Filter alerts by message content
- `source` (optional): Filter alerts by source
- `owner` (optional): Filter alerts by owner
- `tags` (optional): Filter by tags (all tags must match)
- `teams` (optional): Filter by team names
- `query` (optional): **Custom Opsgenie search query with full control** (takes precedence over all other filters)
- `searchIdentifier` (optional): Identifier of saved search query
- `searchIdentifierType` (optional): Type of search identifier ('id' or 'name')
- `sort` (optional): Field to sort alerts by (default: 'lastOccurredAt')
- `order` (optional): Sort order - 'asc' or 'desc' (default: 'desc')

### `getAlert_Opsgenie`

Get details of a specific Opsgenie alert.

**Parameters:**
- `identifier` (required): Alert identifier (ID or alias)

## Usage Examples

### Simple Status Filtering
```json
{
  "status": "open",
  "priority": "P1",
  "limit": 10
}
```

### Custom Query (AI Full Control)
```json
{
  "query": "status: open AND priority: (P1 OR P2) AND tag: production AND NOT tag: maintenance",
  "sort": "lastOccurredAt",
  "order": "desc",
  "limit": 50
}
```

### Team and Message Filtering
```json
{
  "teams": ["backend", "devops"],
  "message": "database",
  "status": "open"
}
```

## Example Response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{\"data\":[{\"id\":\"alert-id\",\"tinyId\":\"123\",\"alias\":\"alert-alias\",\"message\":\"Database connection failed\",\"status\":\"open\",\"acknowledged\":false,\"priority\":{\"id\":\"P1\",\"name\":\"P1\"},\"source\":\"monitoring\",\"owner\":\"john.doe\",\"tags\":[\"production\",\"database\"],\"createdAt\":\"2024-01-15T10:30:00Z\",\"lastOccurredAt\":\"2024-01-15T10:30:00Z\"}],\"took\":0.5,\"requestId\":\"req-123\"}"
    }
  ]
}
```

## Advanced Query Syntax

The `query` parameter supports full Opsgenie search syntax:

### Operators
- `AND` - Both conditions must be true
- `OR` - Either condition must be true  
- `NOT` - Condition must be false
- `()` - Group conditions

### Examples
- `"status: open AND priority: P1"`
- `"message: database* AND teams: backend"`
- `"tag: production AND source: monitoring AND (priority: P1 OR priority: P2)"`
- `"createdAt > 2024-01-01 AND status: open"`

See [QUERY_EXAMPLES.md](./QUERY_EXAMPLES.md) for more examples.

## Publishing to NPM

### For Developers

1. **Login to NPM** (first time only):
   ```bash
   npm login
   ```

2. **Update version**:
   ```bash
   npm version patch  # for bug fixes
   npm version minor  # for new features
   npm version major  # for breaking changes
   ```

3. **Build and publish**:
   ```bash
   npm run build
   npm publish --access public
   ```

4. **Test the published package**:
   ```bash
   npx @quorum-us/opsgenie-mcp
   ```

### Publishing Checklist

- [ ] Update version in package.json
- [ ] Update README if needed
- [ ] Build passes (`npm run build`)
- [ ] Test locally
- [ ] Publish to NPM
- [ ] Test published package with `npx`

### Development Setup

```bash
git clone <repository>
cd opsgenie-mcp
npm install
npm run build
```

## License

Proprietary - All rights reserved by Quorum US