Metadata-Version: 2.4
Name: rapid7-mcp-server
Version: 0.1.0
Summary: MCP server wrapping the Rapid7 InsightOps REST API (EU region) for log search and analysis
Author-email: QikServe <dev@qikserve.com>
License-Expression: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.34.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Rapid7 InsightOps MCP Server

An MCP (Model Context Protocol) server that wraps the [Rapid7 InsightOps REST API](https://docs.rapid7.com/insightops/rest-api/) for log search and analysis. Designed for use with **Devin Web** (app.devin.ai) as an STDIO MCP server, enabling AI agents to search, query, and analyze production logs directly.

> **Region:** EU only (`eu.rest.logs.insight.rapid7.com`). Other regions are not supported.

## Installation

```bash
# From PyPI (once published)
pip install rapid7-mcp-server

# Or directly via uvx
uvx rapid7-mcp-server

# Or from source
pip install git+https://github.com/YOUR_ORG/rapid7-mcp-server.git
```

## Devin Web Setup

1. Open [app.devin.ai](https://app.devin.ai) and go to **Settings** > **MCP Marketplace**
2. Click **"Add Your Own"**
3. Paste this configuration:

```json
{
  "transport": "STDIO",
  "command": "uvx",
  "args": ["rapid7-mcp-server"],
  "env_variables": {
    "RAPID7_API_KEY": "<your Rapid7 API key>"
  }
}
```

4. Save. The server will start automatically when Devin uses any Rapid7 tool.

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `RAPID7_API_KEY` | Yes | Your Rapid7 InsightOps API key (read-only permission is sufficient) |

If `RAPID7_API_KEY` is not set, the server starts but every tool returns a clear error message.

## Available Tools

| Tool | Description |
|------|-------------|
| `rapid7_list_logs` | List all available logs to discover log key UUIDs. Optional name filter. |
| `rapid7_list_log_sets` | List all log sets. Optional name filter. |
| `rapid7_query_log` | Search a single log using a LEQL query with time range, pagination. |
| `rapid7_query_multiple_logs` | Search across multiple logs simultaneously (POST-based). |
| `rapid7_query_log_set` | Search all logs within a log set by name or ID. |
| `rapid7_get_context` | Get surrounding log lines before/after a specific log entry. |
| `rapid7_download_logs` | Download raw log data as plain text (max 10 logs). |
| `rapid7_search_trace` | High-level convenience: search for a traceId across multiple logs. |

## LEQL Quick Reference

LEQL (Log Entry Query Language) is used in the `query` parameter:

```
# Text search (case-insensitive substring)
where(error)
where(NullPointerException)

# Key-value search
where(traceId=abc-123-def)
where(statusCode>=400 AND statusCode<500)

# Regex search
where(/timeout.*connection/i)

# Boolean operators
where(error AND NOT healthcheck)
where(level=ERROR OR level=FATAL)

# Statistical queries (returns counts/aggregates, not log lines)
calculate(COUNT)
where(level=ERROR) calculate(COUNT)
where(statusCode>=500) calculate(COUNT) groupby(service)
calculate(AVERAGE:responseTime) groupby(endpoint)
```

### Time Range Examples

Relative: `last 5 minutes`, `last 1 hour`, `last 24 hours`, `last 7 days`, `yesterday`, `today`

Absolute: Use `from_timestamp` and `to_timestamp` (UNIX milliseconds).

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run the server locally (for testing)
RAPID7_API_KEY=your-key rapid7-mcp-server
```

## License

MIT
