jam

What this skill does

## Troubleshooting

If requests fail, run `zero doctor check-connector --env-name JAM_TOKEN` or `zero doctor check-connector --url https://mcp.jam.dev/mcp --method POST`

## How to Use

Jam exposes its API through an MCP (Model Context Protocol) server at `https://mcp.jam.dev/mcp`. All interactions use JSON-RPC 2.0 over HTTP with Bearer token authentication. You need to initialize the MCP session first, then call tools.

### Base URL

- **MCP endpoint**: `https://mcp.jam.dev/mcp`

### 1. Initialize MCP Session

Start an MCP session to get a session URL for subsequent requests.

```bash
curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"vm0","version":"1.0.0"}}}' -D /tmp/jam_headers.txt | jq .
```

After initialization, check the response headers for the `Mcp-Session-Id` or use the session URL from the response. Save the session URL for subsequent calls:

```bash
SESSION_URL=$(grep -i "location:" /tmp/jam_headers.txt | tr -d '\r' | awk '{print $2}')
```

If no redirect location is returned, use the same endpoint with the session ID from the response headers.

### 2. List Available Tools

Discover all available MCP tools.

Write to `/tmp/jam_request.json`:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}
```

Then run:

```bash
curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq '.result.tools[] | {name, description}'
```

### 3. List Jams

Search and filter Jams in your workspace.

Write to `/tmp/jam_request.json`:

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "listJams",
    "arguments": {}
  }
}
```

Then run:

```bash
curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .
```

Filter by text, type, folder, author, URL, or date:

Write to `/tmp/jam_request.json`:

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "listJams",
    "arguments": {
      "text": "login bug",
      "type": "recording"
    }
  }
}
```

Then run:

```bash
curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .
```

### 4. Get Jam Details

Get a quick snapshot of a Jam including who made it, what happened, and which tools to try next. Replace `JAM_ID` with the actual Jam identifier (the URL slug or ID from listJams).

Write to `/tmp/jam_request.json`:

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "getDetails",
    "arguments": {
      "jamUrl": "https://jam.dev/c/JAM_ID"
    }
  }
}
```

Then run:

```bash
curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .
```

### 5. Get Console Logs

Retrieve console logs from a Jam session, filtered by log level and count.

Write to `/tmp/jam_request.json`:

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "getConsoleLogs",
    "arguments": {
      "jamUrl": "https://jam.dev/c/JAM_ID",
      "logLevel": "error",
      "limit": 50
    }
  }
}
```

Then run:

```bash
curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .
```

Available `logLevel` values: `error`, `warn`, `info`, `log`, `debug`.

### 6. Get Network Requests

List all HTTP requests captured during the Jam recording, with optional filters.

Write to `/tmp/jam_request.json`:

```json
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "getNetworkRequests",
    "arguments": {
      "jamUrl": "https://jam.dev/c/JAM_ID",
      "statusCode": 500,
      "limit": 20
    }
  }
}
```

Then run:

```bash
curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .
```

Filter parameters: `statusCode` (HTTP status code), `contentType` (e.g., `application/json`), `host` (e.g., `api.example.com`), `limit` (max results).

### 7. Get User Events

Read user interactions including clicks, inputs, and page navigations in plain language.

Write to `/tmp/jam_request.json`:

```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "getUserEvents",
    "arguments": {
      "jamUrl": "https://jam.dev/c/JAM_ID"
    }
  }
}
```

Then run:

```bash
curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .
```

### 8. Get Screenshots

Extract screenshots from screenshot-type Jams for visual inspection.

Write to `/tmp/jam_request.json`:

```json
{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "getScreenshot",
    "arguments": {
      "jamUrl": "https://jam.dev/c/JAM_ID"
    }
  }
}
```

Then run:

```bash
curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .
```

### 9. Get Video Transcript

Retrieve spoken captions from video Jams in WebVTT format with timestamps.

Write to `/tmp/jam_request.json`:

```json
{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "getVideoTranscript",
    "arguments": {
      "jamUrl": "https://jam.dev/c/JAM_ID"
    }
  }
}
```

Then run:

```bash
curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .
```

### 10. Analyze Video

Use AI-powered analysis on Jam video recordings to extract insights, detect issues, and get structured feedback.

Write to `/tmp/jam_request.json`:

```json
{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "analyzeVideo",
    "arguments": {
      "jamUrl": "https://jam.dev/c/JAM_ID"
    }
  }
}
```

Then run:

```bash
curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .
```

### 11. Get Custom Metadata

Access custom key-value metadata set via the `jam.metadata()` SDK in your application.

Write to `/tmp/jam_request.json`:

```json
{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "getMetadata",
    "arguments": {
      "jamUrl": "https://jam.dev/c/JAM_ID"
    }
  }
}
```

Then run:

```bash
curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .
```

### 12. List Folders

Browse available folders in your Jam workspace.

Write to `/tmp/jam_request.json`:

```json
{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "listFolders",
    "arguments": {}
  }
}
```

Then run:

```bash
curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request.json | jq .
```

### 13. List Team Members

Browse team members in your Jam workspace.

Write to `/tmp/jam_request.json`:

```json
{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "tools/call",
  "params": {
    "name": "listMembers",
    "arguments": {}
  }
}
```

Then run:

```bash
curl -s -X POST "https://mcp.jam.dev/mcp" --header "Content-Type: application/json" --header "Authorization: Bearer $JAM_TOKEN" -d @/tmp/jam_request