# clockwork-mcp-remote

MCP server that plugs AI coding assistants into **Laravel Clockwork** — remotely. Query performance, N+1 detection, slow query analysis, exceptions, and full request debugging for **any Laravel application, anywhere** — localhost, staging, or production.

There are other Clockwork MCP servers, but they require the Laravel project to live on your machine — PHP installed, filesystem access, running alongside the app. **clockwork-mcp-remote** has no such requirement: it speaks the Clockwork HTTP API directly, so you can debug a deployed application from your editor without SSH, shared folders, or a local checkout.

```
You: "Connect to https://staging.my-app.com and find slow queries in the last hour"
```

## How it works

The server consumes the Clockwork HTTP API (`/__clockwork`) exposed by the [itsgoingd/clockwork](https://github.com/itsgoingd/clockwork) Laravel package. Every tool accepts optional connection parameters, so one server instance can inspect any number of applications dynamically:

1. `connect_clockwork` with `{ baseUrl, username?, password? }` verifies the API and caches the authenticated session
2. All other tools accept the same parameters — or reuse an existing connection
3. Credentials are cached per URL, so switching apps is instant

It also works locally: when run inside a Laravel project it can auto-detect the app and read Clockwork storage directly (artisan or file storage), no HTTP required. Remote debugging is simply the default story.

## Installation

### OpenCode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "clockwork": {
      "type": "local",
      "command": ["npx", "-y", "clockwork-mcp-remote"]
    }
  }
}
```

### Claude Code

```json
{
  "mcpServers": {
    "clockwork": {
      "command": "npx",
      "args": ["-y", "clockwork-mcp-remote"]
    }
  }
}
```

### From source

```json
{
  "mcp": {
    "clockwork": {
      "type": "local",
      "command": ["node", "/path/to/clockwork-mcp-remote/dist/index.js"]
    }
  }
}
```

No environment variables are required — connections are made per tool call. For a fixed default connection, set them via environment:

| Variable | Description |
|----------|-------------|
| `CLOCKWORK_BASE_URL` | Default application URL (enables the HTTP driver) |
| `CLOCKWORK_AUTH_USERNAME` | Default authentication username |
| `CLOCKWORK_AUTH_PASSWORD` | Default authentication password |
| `CLOCKWORK_AUTH_TOKEN` | Pre-authenticated `X-Clockwork-Auth` token |
| `CLOCKWORK_STORAGE_DRIVER` | Force driver: `http`, `artisan`, or `file` |
| `CLOCKWORK_PROJECT_PATH` | Laravel project root (local drivers) |
| `CLOCKWORK_STORAGE_PATH` | Direct Clockwork storage path (file driver) |
| `CLOCKWORK_PHP_PATH` | Custom PHP binary path (artisan driver) |
| `CLOCKWORK_HTTP_TIMEOUT` | HTTP request timeout in ms (default 30000) |

**Precedence:** per-call connection parameters → environment variables → local auto-detection.

## Laravel setup

The target application needs Clockwork installed and its API reachable:

```bash
composer require itsgoingd/clockwork
```

For **remote** hosts, the API must be explicitly enabled since Clockwork only serves non-local requests when configured. In `config/clockwork.php`:

```php
'enable' => env('CLOCKWORK_ENABLE', true),
'authentication' => env('CLOCKWORK_AUTHENTICATION', true),
'authentication_password' => env('CLOCKWORK_AUTH_PASSWORD'),
```

Then pass the same password to the MCP tools. Local hosts (same origin or localhost) work with no configuration at all.

## Tools

### Connection

| Tool | Description |
|------|-------------|
| `connect_clockwork` | Connect to any Clockwork URL — verifies API + auth, caches the session |

### Request discovery

| Tool | Description |
|------|-------------|
| `list_requests` | List recent requests with filtering (type, status, URI, method, time range) |
| `get_request` | Full details of a request by ID |
| `get_latest_request` | Most recent request |
| `search_requests` | Search by controller, URI, status, or duration |

### Database

| Tool | Description |
|------|-------------|
| `get_queries` | Queries for a request, with optional slow-query filter |
| `analyze_slow_queries` | Slow queries grouped by normalized SQL pattern across requests |
| `detect_n_plus_one` | N+1 pattern detection across requests |
| `get_query_stats` | Aggregate query statistics (counts, durations, type breakdown) |

### Performance

| Tool | Description |
|------|-------------|
| `get_performance_summary` | Response time, memory, queries, cache ratio |
| `get_timeline` | Execution timeline events |
| `compare_requests` | Side-by-side comparison of two requests |

### Cache & Redis

| Tool | Description |
|------|-------------|
| `get_cache_operations` | Cache hits, misses, writes, deletes |
| `get_cache_stats` | Hit ratio and totals |
| `get_redis_commands` | Redis commands executed |

### Application context

| Tool | Description |
|------|-------------|
| `get_logs` | Log entries with level filtering |
| `get_events` | Dispatched events and listeners |
| `get_views` | Rendered views |
| `get_http_requests` | Outgoing HTTP requests |
| `get_auth_user` | Authenticated user for a request |
| `get_session_data` | Session data |
| `get_middleware_chain` | Middleware chain |
| `get_route_details` | Route details |

### Traces & execution flow

| Tool | Description |
|------|-------------|
| `get_call_graph` | Hierarchical execution tree from timeline events |
| `get_query_stack_trace` | Source location for a query |
| `get_log_stack_trace` | Source location for a log entry |

### Multi-request analysis

| Tool | Description |
|------|-------------|
| `analyze_exceptions` | Group exceptions by message pattern |
| `analyze_route_performance` | Route performance with percentiles (p50/p95/p99) |
| `detect_memory_issues` | High memory usage and growth patterns |

### Commands, queues & tests

| Tool | Description |
|------|-------------|
| `list_commands` / `get_command` | Profiled artisan command executions |
| `list_queue_jobs` / `get_queue_job` | Queue job executions |
| `list_tests` / `get_test` | Test executions |

### Utility

| Tool | Description |
|------|-------------|
| `get_clockwork_status` | Storage status and statistics |
| `explain_request_flow` | High-level summary of what happened in a request |

## Example sessions

**Debug a slow endpoint:**

```
You: "https://staging.my-app.com is slow on /api/orders — connect and analyze it"

→ connect_clockwork { baseUrl: "https://staging.my-app.com", password: "..." }
→ search_requests { uri: "/api/orders", baseUrl: ... }
→ get_queries { requestId: "...", baseUrl: ... }
→ detect_n_plus_one { count: 5, baseUrl: ... }
"The /api/orders endpoint runs 34 queries per request — the Product::find()
loop at OrderController.php:87 triggers an N+1. Use Product::whereIn() or
eager loading with ->with('products')."
```

**Investigate a 500 error:**

```
You: "Got a 500 on checkout on staging, what happened?"

→ get_latest_request { baseUrl: ..., }
→ get_logs { requestId: "...", level: "error" }
→ analyze_exceptions { since: "1h" }
```

**Compare environments or apps:**

```
You: "Compare response times of /api/products on staging and production"

→ search_requests { uri: "/api/products", baseUrl: "https://staging..." }
→ search_requests { uri: "/api/products", baseUrl: "https://prod..." }
→ compare_requests { ... }
```

## Development

```bash
git clone https://github.com/ahmedbally/clockwork-mcp
cd clockwork-mcp
npm install
npm run build     # build to dist/
npm test          # run test suite
npm run typecheck # verify types
npm run lint      # eslint
```

## Requirements

- Node.js 18+
- A Laravel application with [itsgoingd/clockwork](https://github.com/itsgoingd/clockwork) installed
- Any MCP client (OpenCode, Claude Code, Cursor, etc.)

## License

MIT