Malleon MCP Server

An MCP (Model Context Protocol) server that gives AI coding agents the ability to discover bugs, diagnose them from session replays, create reference builds, and verify fixes — all without leaving the editor.

Features

• Bug Discovery — Query recent or frequent errors across your app and get replay IDs for each
• Healthy Session Discovery — Find recent sessions with no errors and decent activity for regression testing
• Replay Diagnostics — Pull errors, stack traces, console logs, DOM context, and request summaries from any replay
• Automated Verification — Replay the original buggy session with your new code injected and get a pass/fail result

How It Works

┌──────────────┐    list_errors          ┌─────────────────┐
│              │ ───────────────────────►│                 │
│              │    error summaries +    │  Malleon Replay │
│              │    replay IDs           │     Server      │
│              │ ◄─────────────────────  │                 │
│              │                         │                 │
│              │    diagnose_replay      │                 │
│              │ ───────────────────────►│                 │
│   AI Agent   │    errors, logs, DOM    │                 │
│  (Cursor /   │ ◄─────────────────────  │                 │
│   Claude)    │                         └─────────────────┘
│              │
│              │  create_reference_replay
│              │ ──► reads build output, uploads to server
│              │
│              │    verify_fix           ┌─────────────────┐
│              │ ───────────────────────►│  Local Replay   │
│              │    pass/fail + errors   │   Client        │
│              │ ◄─────────────────────  │  (headless)     │
└──────────────┘                         └─────────────────┘

Your AI agent discovers a bug, reads the replay to understand it, fixes the code, builds, uploads the new code, and replays the original session to confirm the fix — in a fully automated loop.

Prerequisites

• Node.js 18+
• Malleon account with a recorded replay of the bug you want to fix
• Malleon Replay Client running locally (default port 9287)
• A JWT token from Malleon dashboard → App Settings
• Your App ID from the Malleon dashboard

Quick Start

Cursor

Add to your project's .cursor/mcp.json:

{
  "mcpServers": {
    "malleon": {
      "command": "npx",
      "args": ["-y", "@malleon/mcp"],
      "env": {
        "MALLEON_JWT": "your-jwt-here",
        "MALLEON_APP_ID": "your-app-id-here"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "malleon": {
      "command": "npx",
      "args": ["-y", "@malleon/mcp"],
      "env": {
        "MALLEON_JWT": "your-jwt-here",
        "MALLEON_APP_ID": "your-app-id-here"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add malleon -- npx -y @malleon/mcp

Set MALLEON_JWT and MALLEON_APP_ID as environment variables in your shell before launching.

Global Install (alternative)

npm install -g @malleon/mcp

Configuration

| Variable | Required | Default | Description | | ------------------------- | -------- | ----------------------- | ---------------------------------------- | | MALLEON_JWT | Yes | — | JWT token from Malleon dashboard → App Settings | | MALLEON_APP_ID | Yes | — | App ID from the Malleon dashboard | | MALLEON_SERVER_URL | No | https://malleon.io | Replay server base URL | | MALLEON_TEST_RUNNER_URL | No | http://localhost:9287 | Local replay client URL |

Tools

find_healthy_sessions

Find recent sessions with no errors and decent activity. Use these as regression-test candidates after making code changes.

| Parameter | Type | Required | Description | |-----------------------|--------|----------|-----------------------------------------------------------------------------| | limit | number | No | Max sessions to return (default: 10) | | since | string | No | ISO timestamp — only sessions created after this time (default: 2 days ago at 00:00:00 UTC) | | minEventCount | number | No | Minimum event count for activity (default: 20) | | pageOrStatePattern | string | No | Optional substring — session must have visited a page/URL or transition matching this (ILIKE on dom_context_page_url, dom_context_page_title, user_transitions) | | appId | string | No | App ID (falls back to MALLEON_APP_ID) |

Returns: sessions (each with replayId, createdAt, eventCount) and totalCount.

list_errors

Discover recent or frequent errors across all replays for your app.

| Parameter | Type | Required | Description | |-----------|--------|----------|-----------------------------------------------------------------| | limit | number | No | Max errors to return (default: 10) | | sortBy | string | No | "recent" or "frequent" (default: "recent") | | since | string | No | ISO timestamp — only return errors after this time | | appId | string | No | App ID (falls back to MALLEON_APP_ID) |

Returns: error summaries with errorType, errorMessage, count, firstSeen, lastSeen, lastReplayId, and compiledFrame.

diagnose_replay

Fetch all diagnostic info from a replay to understand a bug.

| Parameter | Type | Required | Description | |-----------|--------|----------|------------------------------------------| | replayId | string | Yes | The replay ID (UUID) with the bug | | appId | string | No | App ID (falls back to MALLEON_APP_ID) |

Returns: errors with stack traces, console logs, DOM context from user events, resource filenames, request summaries, and replay metadata.

create_reference_replay

Upload your compiled build output as a new reference replay for verification.

| Parameter | Type | Required | Description | |-----------------|--------------------|----------|----------------------------------------------------------------| | buildOutputDir | string or string[] | Yes | Path(s) to build output (e.g., "./dist") | | sourceReplayId | string | No* | Replay ID of the bug you're fixing — used to infer baseUrl. Required if baseUrl is not provided. | | baseUrl | string | No* | Base URL for resource URLs (e.g., https://myapp.com). Required if sourceReplayId is not provided. | | appId | string | No | App ID (falls back to MALLEON_APP_ID) | | indexHtmlPath | string | No | Explicit path to index.html (auto-detected if omitted) | | include | string | No | Comma-separated globs (default: **/*.js,**/*.css) | | label | string | No | Human-readable label for the reference replay |

* At least one of sourceReplayId or baseUrl must be provided.

Returns: referenceReplayId, resourceCount, resourceUrls, and indexHtmlPath.

verify_fix

Replay the original buggy session with new code and check if the bug is fixed.

| Parameter | Type | Required | Description | |--------------------|---------|----------|--------------------------------------------------| | originalReplayId | string | Yes | Replay ID with the bug (the events to replay) | | referenceReplayId | string | Yes | Reference replay ID with the new compiled code | | appId | string | No | App ID (falls back to MALLEON_APP_ID) | | maxDelayMs | number | No | Cap inter-event delays to this many ms (0 = no cap). Recommended: 2000 |

Returns: passed (boolean), errors, throws, warnings, domFailures, logs, and failureReasons.

Example Workflows

"What bugs should I fix?"

1. list_errors({ sortBy: "recent", limit: 5 })
2. diagnose_replay({ replayId: "<replayId from step 1>" })
3. Fix the code
4. npm run build
5. create_reference_replay({ buildOutputDir: "./dist", sourceReplayId: "<replayId>" })
6. verify_fix({ originalReplayId: "<replayId>", referenceReplayId: "<from step 5>", maxDelayMs: 2000 })
7. If failed → read errors, iterate from step 3

"Fix the error in replay abc-123"

1. diagnose_replay({ replayId: "abc-123" })
2. Fix the code
3. npm run build
4. create_reference_replay({ buildOutputDir: "./dist", sourceReplayId: "abc-123" })
5. verify_fix({ originalReplayId: "abc-123", referenceReplayId: "<from step 4>", maxDelayMs: 2000 })
6. If failed → read errors, iterate from step 2

"Ensure working sessions still work" (regression)

1. find_healthy_sessions({ limit: 5 })  // sessions with no errors, good activity
2. create_reference_replay({ buildOutputDir: "./dist", sourceReplayId: "<first healthy session>" })
3. For each session: verify_fix({ originalReplayId: "<session>", referenceReplayId: "<from step 2>", maxDelayMs: 2000 })
4. If any fail → your change may have broken a working flow

License

Proprietary. Copyright Malleon, Inc. All rights reserved.