# Clone the repository
git clone <repository-url>
cd mcp-newrelic

# Install dependencies (using uv - recommended)
uv sync

# Or using pip
pip install -e .

# Configure your credentials (see Configuration section below)

{
  "mcpServers": {
    "newrelic": {
      "command": "uv",
      "args": ["run", "python", "/path/to/mcp-newrelic/server.py"],
      "env": {
        "NEW_RELIC_API_KEY": "your-api-key",
        "NEW_RELIC_ACCOUNT_ID": "your-account-id"
      }
    }
  }
}

uv run python server.py \
  --api-key "NRAK-your-api-key" \
  --account-id "your-account-id" \
  --region "US"

# Copy and edit the example config
cp newrelic-config.json.example config/newrelic-config.json

# Run with config file
uv run python server.py --config config/newrelic-config.json

{
  "api_key": "NRAK-your-api-key",
  "account_id": "your-account-id",
  "region": "US",
  "timeout": 30
}

export NEW_RELIC_API_KEY="NRAK-your-api-key"
export NEW_RELIC_ACCOUNT_ID="your-account-id"
export NEW_RELIC_REGION="US"  # US or EU
export NEW_RELIC_TIMEOUT="30"

## Available Tools

### NRQL & Monitoring
- **`query_nrql`**: Execute custom NRQL queries with full flexibility
- **`get_app_performance`**: Application performance metrics (avg/p95 response time, throughput, Apdex)
- **`get_app_errors`**: Error metrics, counts, and error analysis
- **`get_incidents`**: Recent incidents with time filtering
- **`get_infrastructure_hosts`**: Infrastructure host metrics (CPU, memory, disk)
- **`get_alert_violations`**: Recent alert violations and status
- **`get_deployments`**: Deployment markers and impact analysis

### Dashboard Management
- **`get_dashboards`**: List and search dashboards with filtering
- **`search_all_dashboards`**: Advanced dashboard search with local filtering
- **`get_dashboard_widgets`**: Retrieve all widgets from a dashboard
- **`create_dashboard`**: Create new dashboards for monitoring
- **`delete_dashboard`**: Delete a dashboard by GUID
- **`add_widget_to_dashboard`**: Add custom NRQL-based widgets
- **`update_widget`**: Update existing dashboard widgets
- **`delete_widget`**: Remove widgets from dashboards

### Entity Management
- **`entity_search`**: Search for any entity by name, type (APPLICATION, HOST, MONITOR, KEY_TRANSACTION), or domain (APM, INFRA, SYNTH, BROWSER, EXT). Supports `limit` (default 25, max 200) and `minimal_output` to reduce response size.
- **`get_entity`**: Look up a single entity by GUID with full details (name, type, account, tags, permalink, type-specific metadata)
- **`decode_entity_guid`**: Decode a base64-encoded entity GUID to reveal account ID, domain, entity type, and domain ID without an API call
- **`get_entity_tags`**: Get all tags for an entity by GUID
- **`add_tags_to_entity`**: Add or update key-value tags on an entity
- **`replace_tags_on_entity`**: Replace all tags on an entity (overwrites existing)
- **`delete_tags_from_entity`**: Remove tag keys from an entity
- **`delete_tag_values`**: Delete specific tag key-value pairs from an entity
- **`list_service_levels`**: List all SLIs/SLOs with compliance data and objectives
- **`list_synthetic_monitors`**: List all synthetic monitors with status, success rate, and location health
- **`get_synthetic_results`**: Get recent pass/fail check results per location for a specific monitor

### Alert & Notification Management
- **`create_alert_policy`**: Create alert policies with incident preferences
- **`update_alert_policy`**: Update an existing alert policy
- **`delete_alert_policy`**: Delete an alert policy by ID
- **`create_nrql_condition`**: Create NRQL-based alert conditions
- **`update_nrql_condition`**: Update an existing NRQL alert condition
- **`delete_nrql_condition`**: Delete a NRQL alert condition by ID
- **`create_notification_destination`**: Set up notification endpoints (email, Slack, webhook, PagerDuty)
- **`delete_notification_destination`**: Delete a notification destination by ID
- **`create_notification_channel`**: Create notification channels
- **`create_workflow`**: Connect alerts to notifications with filtering
- **`delete_workflow`**: Delete a workflow by ID
- **`list_alert_policies`**: List all alert policies
- **`list_alert_conditions`**: List alert conditions with optional filters by policy, name, or NRQL query
- **`list_notification_destinations`**: List all notification destinations
- **`list_notification_channels`**: List all notification channels
- **`list_workflows`**: List all alert workflows

## MCP Resources

Access structured data through these MCP resources:

- **`newrelic://applications`**: Complete list of monitored applications
- **`newrelic://incidents/recent`**: Recent incidents and alert summary
- **`newrelic://dashboards`**: Dashboard metadata and widgets
- **`newrelic://alerts/policies`**: Alert policies and configurations
- **`newrelic://alerts/conditions`**: Alert conditions across all policies
- **`newrelic://alerts/workflows`**: Workflow configurations and notifications

## Architecture

### Design
- **Strategy Pattern**: Tool handlers using pluggable strategy implementations
- **Composition**: `NewRelicClient` composes specialized sub-clients (`monitoring`, `alerts`, `dashboards`, `entities`) instead of using multiple inheritance
- **Configuration**: Hierarchical config (CLI > file > env vars) with validation
- **Error Handling**: Typed `ApiError` dataclass for consistent error propagation
- **Pagination**: Cursor-based pagination for NerdGraph queries (entity search, alert policies, conditions, service levels, synthetic monitors)

### Key Components
- **`NewRelicClient`**: Unified client composing all specialized sub-clients
- **`AlertsClient`**: Alert policies, conditions, and notification management
- **`DashboardsClient`**: Dashboard and widget operations
- **`EntitiesClient`**: Entity search, tagging, service levels, and synthetic monitors
- **`MonitoringClient`**: NRQL queries and performance monitoring
- **`ToolHandlers`**: Strategy-based dispatcher for MCP tool calls
- **`ResourceHandlers`**: MCP resource operations and data formatting

## Docker Support

### Quick Docker Run
```bash
docker build -t newrelic-mcp-server .

docker run -e NEW_RELIC_API_KEY=your-key \
           -e NEW_RELIC_ACCOUNT_ID=your-id \
           newrelic-mcp-server

# Setup environment
cp .env.example .env
# Edit .env with your New Relic credentials

# Build and run
docker-compose up --build

# Run in background
docker-compose up -d --build

# Install development dependencies
uv sync --dev

# Install pre-commit hooks
uv run pre-commit install

# Run quality checks
uv run ruff check .          # Linting
uv run ruff format .         # Formatting  
uv run mypy newrelic_mcp/    # Type checking
uv run pylint newrelic_mcp/  # Additional analysis

# Run all tests
uv run pytest tests/

# Run with verbose output
uv run pytest tests/ -v

# 1. Create alert policy
create_alert_policy(name="High CPU Usage Policy")

# 2. Create NRQL condition  
create_nrql_condition(
    policy_id="policy-id-from-step-1",
    name="High CPU Alert",
    nrql_query="SELECT average(cpuPercent) FROM SystemSample",
    threshold=80
)

# 3. Create notification destination
create_notification_destination(
    name="Team Email",
    type="EMAIL", 
    properties={"email": "alerts@company.com"}
)

# 4. Create notification channel
create_notification_channel(
    name="CPU Alert Channel",
    destination_id="destination-id-from-step-3",
    type="EMAIL"
)

# 5. Create workflow
create_workflow(
    name="CPU Alert Workflow",
    channel_ids=["channel-id-from-step-4"]
)