# Jon's Pushover MCP Server

An MCP server for sending push notifications via [Pushover](https://pushover.net).

## Requirements

- Python 3.10+
- Pushover account with API token and user key

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `PUSHOVER_API_TOKEN` | Yes | Application API token from https://pushover.net/apps |
| `PUSHOVER_USER_KEY` | Yes | User key from https://pushover.net |

## Installation

```bash
# Clone the repository
git clone <your-repo-url>
cd jons-mcp-pushover

# Install with uv
uv pip install -e .
```

## Running the Server

```bash
uv run jons-mcp-pushover
```

## Claude Desktop Configuration

Add this to your Claude Desktop config file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "pushover": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/jons-mcp-pushover", "jons-mcp-pushover"],
      "env": {
        "PUSHOVER_API_TOKEN": "your-api-token-here",
        "PUSHOVER_USER_KEY": "your-user-key-here"
      }
    }
  }
}
```

## Adding to Claude Code

```bash
# Register the MCP server with Claude Code
claude mcp add jons-mcp-pushover \
  -e PUSHOVER_API_TOKEN=your-api-token-here \
  -e PUSHOVER_USER_KEY=your-user-key-here \
  -- uv run --directory /path/to/jons-mcp-pushover jons-mcp-pushover
```

## Available Tools

### `send_notification`

Send a push notification to your devices.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `message` | string | Yes | - | The notification message body |
| `title` | string | No | App name | Title shown at top of notification |
| `url` | string | No | - | URL to include (tappable in notification) |
| `url_title` | string | No | - | Label for the URL |
| `priority` | integer | No | 0 | Priority: -2 (silent) to 2 (emergency) |
| `sound` | string | No | device default | Notification sound name |

**Example:**
```python
send_notification(
    message="Build completed successfully!",
    title="CI Pipeline",
    url="https://github.com/user/repo/actions",
    url_title="View Build",
    priority=1,
    sound="magic"
)
```

## Development

### Setup

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

### Running Tests

```bash
# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src

# Run a specific test
uv run pytest tests/test_pushover.py::test_send_notification_success
```

### Code Quality

```bash
# Type check
uv run mypy src/jons_mcp_pushover

# Format code
uv run black src tests

# Lint code
uv run ruff check src tests
```

## Project Structure

```
jons-mcp-pushover/
├── src/
│   ├── __init__.py
│   └── jons_mcp_pushover/
│       ├── __init__.py          # Package exports
│       ├── constants.py         # Configuration constants
│       ├── exceptions.py        # Custom exceptions
│       ├── utils.py             # Utility functions
│       ├── server.py            # FastMCP server setup
│       └── tools/
│           ├── __init__.py      # Tool exports
│           └── pushover.py      # Pushover notification tool
├── tests/
│   ├── conftest.py              # Test fixtures
│   └── test_pushover.py         # Pushover tool tests
├── pyproject.toml               # Project configuration
├── CLAUDE.md                    # AI assistant guidance
└── README.md                    # This file
```

## Adding New Tools

1. Create a new file in `src/jons_mcp_pushover/tools/` or add to an existing file
2. Write an async function with type hints and a docstring:
   ```python
   async def my_tool(param: str) -> str:
       """Brief description for the MCP tool listing.

       Args:
           param: What this parameter does.

       Returns:
           What the tool returns.
       """
       return f"Result: {param}"
   ```
3. Export from `src/jons_mcp_pushover/tools/__init__.py`
4. Register in `server.py` with `mcp.tool(my_tool)`

## License

MIT