# MCP Opener

Model Context Protocol server for opening files, folders, and browsers across different operating systems. Designed specifically to handle Linux Flatpak Firefox complexities on distributions like Fedora Bluefin.

## Features

- **Open Folders**: Launch system file manager (Nautilus, Finder, Explorer, etc.)
- **Open Files**: Open files with their default applications
- **Open Browser**: Open URLs with configurable browser preferences
- **Flatpak Firefox Support**: Auto-detects and handles Flatpak Firefox installations
- **Cross-Platform**: Works on Linux, macOS, and Windows
- **Smart File Handling**: Automatically copies files to `/tmp` for Flatpak browser access when needed

## Installation

```bash
# Install dependencies
pnpm install

# Build
pnpm build

# Install globally (optional)
pnpm link --global
```

## Configuration

Configure via environment variables in your `.env` file or Claude Code MCP settings:

```bash
# Preferred browser: 'firefox' | 'chrome' | 'chromium' | 'default'
MCP_OPENER_BROWSER=firefox

# Explicitly set if Firefox is installed via Flatpak (auto-detected if omitted)
MCP_OPENER_FIREFOX_FLATPAK=true

# Whether to copy files to /tmp for Flatpak access (default: true)
MCP_OPENER_TMP_COPY=true
```

### Claude Code Configuration

Add to your Claude Code MCP settings (`.claude/settings.json` or global settings):

```json
{
  "mcpServers": {
    "opener": {
      "command": "node",
      "args": ["/path/to/mcp-opener/dist/index.js"],
      "env": {
        "MCP_OPENER_BROWSER": "firefox",
        "MCP_OPENER_FIREFOX_FLATPAK": "true",
        "MCP_OPENER_TMP_COPY": "true"
      }
    }
  }
}
```

Or using pnpm:

```json
{
  "mcpServers": {
    "opener": {
      "command": "pnpm",
      "args": ["--dir", "/path/to/mcp-opener", "exec", "node", "dist/index.js"],
      "env": {
        "MCP_OPENER_BROWSER": "firefox"
      }
    }
  }
}
```

## Tools

### `open_folder`

Opens a folder in the system file manager.

**Parameters:**
- `path` (string, required): Absolute or relative path to the folder

**Example:**
```typescript
{
  "path": "/home/user/Documents"
}
```

**Behavior by Platform:**
- **Linux**: Uses `xdg-open`, falls back to `nautilus` or `dolphin`
- **macOS**: Uses `open` (Finder)
- **Windows**: Uses `explorer`

---

### `open_file`

Opens a file with its default application.

**Parameters:**
- `path` (string, required): Absolute or relative path to the file

**Example:**
```typescript
{
  "path": "./report.pdf"
}
```

**Behavior by Platform:**
- **Linux**: Uses `xdg-open`
- **macOS**: Uses `open`
- **Windows**: Uses `start`

---

### `open_browser`

Opens a URL in the preferred web browser.

**Parameters:**
- `url` (string, required): URL to open (must start with `http://`, `https://`, or `file://`)

**Example:**
```typescript
{
  "url": "https://github.com"
}
```

**Behavior:**
1. Checks configured browser preference (`MCP_OPENER_BROWSER`)
2. On Linux with Firefox:
   - Auto-detects Flatpak installation
   - For `file://` URLs with Flatpak: Copies file to `/tmp` for accessibility
   - Uses `flatpak run org.mozilla.firefox` for Flatpak
   - Uses native `firefox` command otherwise
3. Falls back to system default browser if preferred browser unavailable

**Special Handling for Fedora Bluefin / Flatpak Firefox:**

When opening local HTML files or other file:// URLs with Flatpak Firefox:
1. File is copied to `/tmp/mcp-opener-<random>/`
2. Browser opens the `/tmp` copy
3. Cleanup happens after 5 seconds

This works around Flatpak's filesystem sandboxing restrictions.

## Platform Support

| Platform | File Manager | Browser Detection | Flatpak Support |
|----------|--------------|-------------------|-----------------|
| Linux    | xdg-open, Nautilus, Dolphin | ✅ | ✅ |
| macOS    | Finder | ✅ | N/A |
| Windows  | Explorer | ✅ | N/A |

## Usage Examples

### From Claude Code

```
User: Open my Downloads folder
Agent: [Uses open_folder tool with path: /home/user/Downloads]

User: Open this README file
Agent: [Uses open_file tool with path: ./README.md]

User: Open GitHub in my browser
Agent: [Uses open_browser tool with url: https://github.com]

User: Preview this HTML file
Agent: [Uses open_browser tool with url: file:///home/user/project/index.html]
      [On Flatpak Firefox: Copies to /tmp, opens copy, cleans up]
```

### Direct Tool Calls

```json
// Open folder
{
  "name": "open_folder",
  "arguments": {
    "path": "/home/viky/Code"
  }
}

// Open file
{
  "name": "open_file",
  "arguments": {
    "path": "./package.json"
  }
}

// Open browser
{
  "name": "open_browser",
  "arguments": {
    "url": "https://anthropic.com"
  }
}
```

## Error Handling

The server provides detailed error messages:

- **File/folder not found**: `"File does not exist: /path/to/file"`
- **Invalid URL**: `"URL must start with http://, https://, or file://"`
- **Platform not supported**: `"Unsupported platform: <platform>"`
- **No file manager found**: `"No file manager found (tried xdg-open, nautilus, dolphin)"`

## Development

```bash
# Watch mode for development
pnpm dev

# Build for production
pnpm build

# Test the server manually
echo '{"method":"tools/list"}' | node dist/index.js
```

## Troubleshooting

### Flatpak Firefox not detected

Check if Firefox is installed via Flatpak:
```bash
flatpak list --app | grep firefox
```

If installed, you should see `org.mozilla.firefox`. Set `MCP_OPENER_FIREFOX_FLATPAK=true` explicitly if auto-detection fails.

### Files not opening in Flatpak Firefox

Ensure `MCP_OPENER_TMP_COPY=true` (default). The server will copy files to `/tmp` for Flatpak accessibility.

### Wrong browser opens

Set `MCP_OPENER_BROWSER` explicitly:
```bash
MCP_OPENER_BROWSER=firefox
# or
MCP_OPENER_BROWSER=chrome
# or
MCP_OPENER_BROWSER=default
```

## License

MIT

## Author

3viky

## Contributing

Issues and PRs welcome at [github.com/3viky/mcp-opener](https://github.com/3viky/mcp-opener)