# xfactor

MCP server that connects AI agents to browser DevTools via CDP (Chrome DevTools Protocol).

Give your AI agent real-time access to browser console logs, network requests, and page state.

## Features

- Real-time console logs capture (errors, warnings, info, debug)
- Network request/response monitoring
- Page state (URL, title, viewport)
- Works with any AI agent that supports MCP (Claude, etc.)

## Quick Start

```bash
# Install dependencies
pnpm install

# Start the server (spawns Chrome + MCP server)
pnpm dev
```

## Connect to your AI Agent

### HTTP Mode (Recommended)

The server runs on `http://localhost:3001` by default.

#### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "xfactor": {
      "url": "http://localhost:3001/mcp"
    }
  }
}
```

#### Other Agents

Point your MCP client to: `http://localhost:3001/mcp`

## Available Tools

### `get_browser_context`

Get browser state including console logs and network requests.

```json
{
  "includePageState": true,
  "includeLogs": true,
  "includeRequests": true
}
```

Returns:
- `status` - Connection status, CDP port, attached pages
- `pageState` - Current URL, title, viewport
- `consoleLogs` - Array of captured console messages
- `networkRequests` - Array of captured network requests

### `refresh_browser`

Refresh the page to capture logs from page load.

```json
{
  "clearLogs": true
}
```

## Configuration

### Environment Variables

- `CDP_PORT` - Chrome DevTools Protocol port (default: 9222)
- `TARGET_URL` - URL to monitor (default: localhost:3000)

### xmcp.config.ts

```typescript
const config: XmcpConfig = {
  http: { port: 3001 },
  // ... other options
};
```

## How It Works

1. `pnpm dev` spawns a Chrome instance with remote debugging enabled
2. MCP server connects to Chrome via CDP
3. CDP listeners capture console logs and network activity
4. AI agents query the captured data via MCP tools

## Requirements

- Node.js >= 20
- Google Chrome installed
- pnpm

## License

MIT