# Kagami

**Claude Code Web exclusive** Playwright MCP server. Enables browser automation via JWT authentication proxy.

## Overview

This project is **designed exclusively for Claude Code Web environment** and provides an MCP (Model Context Protocol) server for using Playwright.

**Important:** This project is designed to work only in Claude Code Web environment. It will not work in local environments or other environments.

**Key Features:**

- Auto-setup functionality (automatically installs required components on first startup)
- External access via JWT authentication proxy
- Automation using Firefox browser
- Automatic CA certificate import
- MCP protocol compliant

## Architecture

```
Claude Code → mcp.py → playwright-mcp (Firefox) → proxy.py → JWT Auth Proxy → Internet
```

1. **mcp.py**: MCP server entry point. Responsible for initial setup and launching proxy.py
2. **@playwright/mcp**: Playwright MCP server implementation (Node.js)
3. **Firefox**: Browser engine
4. **proxy.py**: Local proxy server
5. **JWT Auth Proxy**: Authentication proxy for external access

## Setup

### Automatic Setup (Recommended)

The following will be automatically set up on first startup:

1. certutil installation
2. @playwright/mcp installation
3. Firefox installation
4. Firefox profile creation
5. CA certificate import
6. Configuration file generation

**Note:**
- First startup may take 30 seconds or more

## Usage

### Launch as MCP Server

Configure in `.mcp.json` and Claude Code will automatically launch it:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "python3",
      "args": [
        "playwright_mcp_claude_code_web/mcp.py"
      ]
    }
  }
}
```

## File Structure

```
.
├── playwright_mcp_claude_code_web/
│   ├── mcp.py                          # MCP server (uses only standard library)
│   ├── setup_minimal.py                # Minimal synchronous setup
│   ├── setup_mcp.py                    # Full asynchronous setup
│   └── README.md                       # Detailed documentation
├── .mcp.json                           # MCP server configuration
└── README.md                           # This file
```

## Technical Details

### Startup Flow

**mcp.py** uses a two-phase setup approach to avoid timeout issues:

#### Phase 1: Synchronous Setup (runs before responding)

1. **Minimal Setup** (`setup_minimal.py`)
   - Install `@playwright/mcp` via npm
   - Create minimal Firefox configuration file

2. **Fetch Tool List**
   - Start temporary `@playwright/mcp` process
   - Fetch available tool definitions
   - Store tool list for immediate response to `tools/list` requests
   - Terminate temporary process

3. **Start MCP Server**
   - Begin responding as MCP server
   - Return stored tool list for `tools/list` requests
   - Return "setup in progress" error for `tools/call` requests

#### Phase 2: Asynchronous Setup (runs in background)

4. **Full Setup** (`setup_mcp.py` - runs in background thread)
   - Install `certutil` (for certificate management)
   - Install `proxy.py` via uv
   - Install Firefox browser
   - Create Firefox profile (`/home/user/firefox-profile`)
   - Import CA certificates for TLS inspection
   - Generate final configuration file

5. **Start Services**
   - Start `proxy.py` (localhost:18915)
   - Start `@playwright/mcp` with full configuration
   - Begin proxying all requests to `@playwright/mcp`

### Communication Flow (After Setup)

1. Claude Code sends request to `mcp.py` via MCP protocol (stdin/stdout)
2. `mcp.py` proxies request to `@playwright/mcp`
3. `@playwright/mcp` launches Firefox (proxy setting: localhost:18915)
4. `proxy.py` forwards requests to JWT authentication proxy
5. Access external sites through authenticated proxy

### Security

- Import CA certificate for TLS inspection into Firefox profile
- All HTTPS traffic goes through JWT authentication proxy
- Firefox runs with dedicated profile (/home/user/firefox-profile)

**Note:** Claude Code Web environment performs TLS Inspection on all HTTPS communications for security auditing purposes. This project imports the necessary CA certificates to enable secure browsing within this monitored environment.

## References

- [Playwright Documentation](https://playwright.dev/)
- [@playwright/mcp GitHub](https://github.com/microsoft/playwright)
- [MCP Protocol](https://modelcontextprotocol.io/)
- [proxy.py Documentation](https://github.com/abhinavsingh/proxy.py)

## License

MIT