# picoclaw-mcp-server

A Model Context Protocol (MCP) server with browser automation, GitHub integration, and persistent opencode repository support.

## Features

### Browser Automation
- **Human-like behavior**: Random delays, bezier-curve mouse movements, viewport/user-agent randomization
- **Stealth mode**: Avoids bot detection using playwright-stealth
- **Full browser control**: Navigate, click, type, scroll, hover, screenshot, get page content

### GitHub Integration
- List repository files
- Read file contents
- Search code
- Search repositories
- Get repository information

### OpenCode Integration (Persistent)
- **Auto-clone/pull**: Automatically clone or pull your opencode repository on startup
- **Heartbeat refresh**: Periodic automatic refresh (configurable interval)
- **Manual refresh**: MCP tools to force pull/refresh
- **Local file access**: Read, list, and search your opencode repository

### Utilities
- Web search via DuckDuckGo
- URL fetching

## Installation

```bash
# Clone the repository
git clone https://github.com/Evansxm/picoclaw-mcp-server.git
cd picoclaw-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

# Install Playwright browsers
playwright install chromium
```

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `GITHUB_TOKEN` | - | GitHub Personal Access Token for higher rate limits |
| `HEADLESS` | `true` | Run browser in headless mode |
| `STEALTH_MODE` | `true` | Enable stealth mode to avoid bot detection |
| `OPENCODE_ENABLED` | `true` | Enable opencode repository integration |
| `OPENCODE_REPO_URL` | - | URL of your opencode repository |
| `OPENCODE_LOCAL_PATH` | `~/opencode-clone` | Local path to clone the repository |
| `OPENCODE_REFRESH_INTERVAL` | `1800` | Seconds between automatic refreshes |

### Configuration File

You can also configure via `~/.picoclaw/config.json`:

```json
{
  "opencode": {
    "enabled": true,
    "repo_url": "https://github.com/yourusername/your-opencode-repo",
    "local_path": "~/opencode-clone",
    "refresh_interval": 1800,
    "github_token": "your-github-token"
  }
}
```

### Claude Desktop Configuration

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "picoclaw": {
      "command": "/path/to/picoclaw-mcp-server/venv/bin/python",
      "args": ["/path/to/picoclaw-mcp-server/server.py"],
      "env": {
        "GITHUB_TOKEN": "your-github-token-here",
        "OPENCODE_ENABLED": "true",
        "OPENCODE_REPO_URL": "https://github.com/yourusername/your-repo",
        "HEADLESS": "false",
        "STEALTH_MODE": "true"
      }
    }
  }
}
```

### Cursor Configuration

Add to Cursor settings (Settings → Tools → MCP):

```json
{
  "mcpServers": {
    "picoclaw": {
      "command": "python",
      "args": ["/absolute/path/to/picoclaw-mcp-server/server.py"],
      "env": {
        "GITHUB_TOKEN": "your-github-token-here",
        "OPENCODE_ENABLED": "true"
      }
    }
  }
}
```

## Available Tools

### OpenCode Tools

| Tool | Description |
|------|-------------|
| `opencode | Force pull/refresh the opencode repository |
| `_pull_repo`opencode_clone_repo` | Clone or ensure repository exists locally |
| `opencode_list_files` | List files in the opencode repository |
| `opencode_read_file` | Read a file from the opencode repository |
| `opencode_search_code` | Search for code in the opencode repository |
| `opencode_get_status` | Get status of the opencode repository |

### Browser Tools

| Tool | Description |
|------|-------------|
| `browser_navigate` | Navigate to a URL |
| `browser_click` | Click element by CSS selector |
| `browser_click_text` | Click element by text content |
| `browser_type` | Type text into input |
| `browser_scroll` | Scroll the page |
| `browser_screenshot` | Take a screenshot |
| `browser_get_screenshot_base64` | Get screenshot as base64 |
| `browser_get_page_content` | Get page text content |
| `browser_get_page_html` | Get page HTML source |
| `browser_hover` | Hover over element |
| `browser_wait` | Wait for seconds |
| `browser_close` | Close browser |

### GitHub Tools

| Tool | Description |
|------|-------------|
| `list_repo_files` | List files in a repository |
| `read_file` | Read file contents |
| `search_code` | Search code on GitHub |
| `search_repositories` | Search repositories |
| `get_repository_info` | Get repository information |

### Utility Tools

| Tool | Description |
|------|-------------|
| `web_search` | Search the web via DuckDuckGo |
| `fetch_url` | Fetch URL content |

## Systemd Service (Always-On)

For persistent always-on behavior on Linux:

```bash
# Copy the service file
sudo cp picoclaw-mcp.service /etc/systemd/system/

# Reload systemd
sudo systemctl daemon-reload

# Enable and start the service
sudo systemctl enable picoclaw-mcp
sudo systemctl start picoclaw-mcp

# Check status
sudo systemctl status picoclaw-mcp
```

### Systemd Service Customization

Edit the service file to customize:

```ini
[Service]
Environment="OPENCODE_REPO_URL=https://github.com/yourusername/your-repo"
Environment="OPENCODE_REFRESH_INTERVAL=1800"
Environment="HEADLESS=true"
```

## Development

```bash
# Run with MCP Inspector
uv run mcp dev server.py

# Run directly
python server.py
```

## License

MIT