# Logpush MCP

MCP server for reading Cloudflare Workers logpush data from R2 buckets.

## Features

- List available log dates by environment (production/staging)
- Browse and read individual log files
- Search logs with filters (worker, status code, outcome, text)
- Get aggregated statistics
- Quick access to errors and exceptions
- Get latest logs with one command

## Installation

```bash
# Using uv (recommended)
uv pip install -e .

# Or with pip
pip install -e .
```

## Configuration

Set these environment variables (or create a `.env` file):

```bash
R2_ACCOUNT_ID=your_account_id
R2_ACCESS_KEY_ID=your_access_key_id
R2_SECRET_ACCESS_KEY=your_secret_access_key
R2_BUCKET_NAME=your-bucket-name
```

Get R2 API credentials from: Cloudflare Dashboard > R2 > Manage R2 API Tokens

## Usage

### Run locally

```bash
uv run logpush-mcp
```

### Claude Desktop Configuration

Add to your Claude Desktop config (`~/.config/claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "logpush": {
      "command": "uv",
      "args": ["run", "logpush-mcp"],
      "cwd": "/path/to/arross-cf-mcp",
      "env": {
        "R2_ACCOUNT_ID": "your_account_id",
        "R2_ACCESS_KEY_ID": "your_access_key_id",
        "R2_SECRET_ACCESS_KEY": "your_secret_access_key",
        "R2_BUCKET_NAME": "your-bucket-name"
      }
    }
  }
}
```

## MCP Tools

### `list_log_dates`
List available date folders in the bucket.
- `environment`: production, staging, or omit for all
- `limit`: max dates to return (default 30)

### `list_log_files`
List log files for a specific date.
- `date`: YYYYMMDD format
- `environment`: production or staging
- `limit`: max files (default 50)
- `cursor`: pagination token

### `read_log_file`
Read contents of a specific log file.
- `path`: full object key
- `limit`: max entries (default 100)

### `search_logs`
Search logs with filters.
- `date`: YYYYMMDD format
- `environment`: production or staging
- `script_name`: filter by worker name
- `status_code`: exact status code
- `status_gte`: status >= value (e.g., 400)
- `status_lt`: status < value
- `outcome`: "ok" or "exception"
- `search_text`: search in URL and log messages
- `limit`: max entries (default 50)

### `get_log_stats`
Get aggregated statistics for a date.
- `date`: YYYYMMDD format
- `environment`: production or staging

### `get_errors`
Get error logs and exceptions.
- `date`: YYYYMMDD format
- `environment`: production or staging
- `script_name`: optional filter
- `limit`: max entries (default 50)

### `get_latest`
Get the most recent log entries.
- `environment`: production or staging
- `script_name`: optional filter
- `limit`: max entries (default 50)

## Log Structure

Expects Cloudflare Workers Trace Events logpush format:

```
bucket/
├── production/YYYYMMDD/*.log.gz
└── staging/YYYYMMDD/*.log.gz
```

Files are NDJSON with Cloudflare's workers_trace_events schema.

## Deployment to FastMCP Cloud

### Step 1: Sign up at FastMCP Cloud
1. Go to [fastmcp.cloud](https://fastmcp.cloud)
2. Sign in with your GitHub account

### Step 2: Create a new project
1. Click "Create Project"
2. Select this repository (`logpush-mcp`)
3. FastMCP will auto-detect the `pyproject.toml` entry point

### Step 3: Configure environment variables
In the FastMCP Cloud dashboard, add these environment variables:

| Variable | Description |
|----------|-------------|
| `R2_ACCOUNT_ID` | Your Cloudflare account ID |
| `R2_ACCESS_KEY_ID` | R2 API token access key ID |
| `R2_SECRET_ACCESS_KEY` | R2 API token secret access key |
| `R2_BUCKET_NAME` | Name of your logpush R2 bucket |

### Step 4: Deploy
Click "Deploy" - FastMCP handles the rest automatically.

### Step 5: Connect to your MCP client
FastMCP Cloud provides a URL like `https://your-project.fastmcp.cloud/mcp`

For Claude Desktop, add to your config:
```json
{
  "mcpServers": {
    "logpush": {
      "command": "npx",
      "args": ["mcp-remote", "https://your-project.fastmcp.cloud/mcp"]
    }
  }
}
```

### Getting R2 API Credentials

1. Go to Cloudflare Dashboard → R2 → Manage R2 API Tokens
2. Create a new API token with:
   - **Permissions**: Object Read & Write
   - **Scope**: Specific bucket (your logpush bucket)
3. Copy the Access Key ID and Secret Access Key

## License

MIT