Metadata-Version: 2.4
Name: roam-fm-mcp
Version: 0.1.0
Summary: MCP server for controlling Roam FM radio app via AI assistants like Claude
Project-URL: Homepage, https://fm.houjoe.me
Project-URL: Repository, https://github.com/houjoe0829/roam-fm-mcp
Project-URL: Documentation, https://fm.houjoe.me/mcp/
Author-email: Joe Hou <houjoe0829@gmail.com>
License-Expression: MIT
Keywords: ai,assistant,claude,mcp,radio,roam-fm
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: MacOS X
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# Roam FM MCP Server

MCP (Model Context Protocol) server for controlling [Roam FM](https://fm.houjoe.me) radio app via AI assistants like Claude.

## Prerequisites

- macOS
- Roam FM app installed and running
- MCP remote control enabled in Roam FM: Settings > Labs > AI Remote Control
- Python 3.10+

## Installation

```bash
cd mcp-server
pip install -e .
```

## Configuration

### Claude Code

Add to your Claude Code MCP settings (`~/.claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "roam-fm": {
      "command": "roam-fm-mcp"
    }
  }
}
```

Or if using a virtual environment:

```json
{
  "mcpServers": {
    "roam-fm": {
      "command": "/path/to/venv/bin/roam-fm-mcp"
    }
  }
}
```

## Available Tools

| Tool | Description |
|------|-------------|
| `roam_play` | Start playing radio. Optionally filter by country code. |
| `roam_pause` | Pause the current station. |
| `roam_resume` | Resume playback. |
| `roam_next` | Skip to next random station. |
| `roam_stop` | Stop playback completely. |
| `roam_status` | Get current playback status and station info. |
| `roam_get_stats` | Get listening statistics. |

### Country Codes

Use ISO 3166-1 alpha-2 country codes for filtering:

- `JP` - Japan
- `US` - United States
- `FR` - France
- `DE` - Germany
- `GB` - United Kingdom
- `CN` - China
- etc.

## Example Usage

Ask your AI assistant:

- "Play Japanese radio stations"
- "Pause the radio"
- "What's currently playing?"
- "Skip to the next station"
- "How long have I been listening?"

## How It Works

```
AI Assistant ──MCP──> roam-fm-mcp ──URL Scheme──> Roam FM App
                                  <──status.json──
```

1. AI sends commands via MCP protocol
2. MCP server triggers URL Scheme (`roam-fm://play`, etc.)
3. Roam FM app executes the command
4. App writes status to `~/.roam-fm/status.json`
5. MCP server reads status and returns result

## Troubleshooting

### "Status file not found"

Make sure MCP remote control is enabled in Roam FM:
1. Open Roam FM
2. Go to Settings > Labs
3. Enable "AI Remote Control"

### Commands not working

1. Check if Roam FM is running
2. Verify the app is responding to URL schemes:
   ```bash
   open "roam-fm://play"
   ```
3. Check status file exists:
   ```bash
   cat ~/.roam-fm/status.json
   ```

## License

MIT
