Kaleidoscope

Responsive preview tooling for local and public web apps. Load a URL once, inspect it across multiple device profiles, capture screenshots, tunnel local sites, and use the MCP server to automate the flow.

Visual Tour

What It Does

Kaleidoscope currently ships these product surfaces:

• Multi-device preview for local and public HTTP/HTTPS URLs
• Local development support for loopback targets such as http://localhost:3000
• Auth preview through a server-side proxy with cookie and header injection
• Live reload for trusted local sessions
• Screenshot capture across device profiles
• Inspect tooling for local targets, including selector discovery and source mapping
• MCP tools for preview, screenshots, proxy auth, and inspect flows

Current Scope

The active UI is the preview workspace. Older flow-diagram and crawl-authoring code has been removed from the shipped client and server packages.

Supported Device Profiles

The shared device catalog currently includes 14 profiles across mobile, tablet, and desktop classes, including iPhone 14-17, Samsung Galaxy S21/S24/S24 Ultra/S25 Ultra, Google Pixel 6, iPad, iPad Pro, MacBook Air, Desktop HD, and Desktop 4K.

Quick Start

Prerequisites

• Node.js 20+
• npm 9+
• Optional: Docker
• Optional but recommended for screenshots and E2E tests: Playwright Chromium
• Optional for localhost sharing: cloudflared or ngrok

Local Development

git clone <your-repo-url>
cd Kaleidoscope
npm run install:all
npm run dev:all

The frontend runs on the Vite URL printed in the terminal, usually http://localhost:5173, with fallback ports such as 5174 when needed. The backend runs on http://localhost:5000.

Optional Browser Install

Kaleidoscope does not download Playwright browsers during npm install. Install Chromium explicitly when you need screenshots or Playwright tests.

npm run install:browsers

Docker Development

docker compose up

Docker Production

For a local production-style run:

CORS_ORIGIN=http://localhost:5000 docker compose -f docker-compose.prod.yml up --build

For a real deployment, replace http://localhost:5000 with the public origin serving the app.

Usage

Basic Preview

1. Open the frontend URL printed by Vite.
2. Enter a target URL such as https://example.com or http://localhost:3000.
3. Switch devices, pin devices for comparison mode, or capture screenshots.

For a follow-along workflow while an agent is making changes, load your local app URL in Kaleidoscope and turn on the Live Reload toggle. Trusted local sessions can automatically refresh as files change.

Auth Preview

For authenticated pages, use the auth panel in the sidebar. Kaleidoscope can create a server-side proxy session with cookies or safe custom headers, then load the proxied page inside the preview.

Inspect Mode

Inspect mode is limited to trusted local loopback targets such as localhost and 127.0.0.1. It can:

• Discover likely selectors from natural-language queries
• Resolve a selected element back to source context when available
• Export JSON or LLM-friendly source summaries

Sharing Localhost

The tunnel panel uses external tunnel binaries rather than bundling a JS tunnel dependency. Install either:

• cloudflared for Cloudflare quick tunnels
• ngrok for ngrok-managed tunnels

MCP Server

The MCP server lives in mcp-server and exposes tools for preview, screenshots, auth proxy sessions, selector discovery, and source inspection.

Example MCP config:

{
  "mcpServers": {
    "kaleidoscope": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "cwd": "/path/to/Kaleidoscope/mcp-server",
      "env": {
        "KALEIDOSCOPE_SERVER_URL": "https://your-kaleidoscope-api.example.com"
      }
    }
  }
}

Leave KALEIDOSCOPE_SERVER_URL unset for local development. The MCP server defaults to http://localhost:5000 when the API is running on the same machine.

Claude Code

Claude Code can run Kaleidoscope as a local stdio MCP server.

Windows:

claude mcp add --transport stdio kaleidoscope --scope project -- cmd /c npx tsx src/index.ts

Then set the working directory and optional API URL in .mcp.json at the repo root:

{
  "mcpServers": {
    "kaleidoscope": {
      "command": "cmd",
      "args": ["/c", "npx", "tsx", "src/index.ts"],
      "cwd": "c:/Code/kaleidoscope/mcp-server",
      "env": {
        "KALEIDOSCOPE_SERVER_URL": "http://localhost:5000"
      }
    }
  }
}

macOS or Linux:

claude mcp add --transport stdio kaleidoscope --scope project -- npx tsx src/index.ts

Then use the same .mcp.json shape, but with command: "npx" and args: ["tsx", "src/index.ts"].

Codex

Codex can also run Kaleidoscope as a local stdio MCP server.

Add this to .codex/config.toml in the repo or your user config:

[mcp_servers.kaleidoscope]
command = "npx"
args = ["tsx", "src/index.ts"]
cwd = "c:/Code/kaleidoscope/mcp-server"
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 60

[mcp_servers.kaleidoscope.env]
KALEIDOSCOPE_SERVER_URL = "http://localhost:5000"
KALEIDOSCOPE_WALKTHROUGH_DIR = "c:/Code/my-app/walkthroughs"

If you prefer the CLI, add it like this and then adjust cwd in config.toml afterward:

codex mcp add kaleidoscope -- npx tsx src/index.ts

Or use the published package form once it is installed from npm:

codex mcp add kaleidoscope -- npx -y kaleidoscope-mcp-server

Core tools:

• kaleidoscope_list_devices
• preview_responsive
• capture_screenshots
• record_walkthrough
• preview_with_auth
• inject_mock_data
• discover_page_elements
• inspect_element_source
• kaleidoscope_status
• kaleidoscope_start
• kaleidoscope_stop

Current MCP status:

• Tools return structured MCP responses instead of plain text only.
• kaleidoscope_list_devices returns the supported device presets and default screenshot set so agents can ask users which ones they want.
• capture_screenshots returns screenshot metadata, preferred local display paths, chat-ready absolute Markdown display paths, per-image markdownImageTag values, a top-level readyToPasteMarkdown array, file URIs, download URLs, resource_link blocks, and inline image blocks when the PNGs are small enough.
• capture_screenshots accepts device IDs and common device names, so agents can request devices: ["iphone-14"] or devices: ["iPhone 14"] for the same iPhone 14 capture.
• The chat-ready paths are OS-agnostic absolute local paths: C:/... on Windows, /Users/... or /home/... on macOS/Linux, and //server/share/... for UNC network shares.
• For the most reliable chat rendering in Codex, paste an entry from readyToPasteMarkdown directly into the response instead of reconstructing an image tag from downloadUrl.
• record_walkthrough records a local .webm walkthrough with scripted clicks, typing, hover, scroll, and navigation steps, plus an optional cursor overlay for clearer demos.
• record_walkthrough accepts either structured steps or a simpler one-command-per-line script format such as click #save and type "hello@example.com" into #email.
• record_walkthrough supports deliverable and inspection artifact modes. Deliverables save to output_dir, then KALEIDOSCOPE_WALKTHROUGH_DIR, then ./walkthroughs; inspection recordings default to the OS temp directory unless output_dir is provided.
• discover_page_elements and inspect_element_source return structured inspect payloads suitable for agent workflows.
• mcp-server includes stdio integration tests for the registered MCP tools.

For record_walkthrough, make sure Playwright Chromium is installed on the machine running the MCP server:

npx playwright install chromium

Scripts

# Development
npm run dev:client
npm run dev:server
npm run dev:all

# Quality checks
npm run lint
npm run check
npm run test:ci
npm --prefix mcp-server test

# Full local suites
npm run test:unit
npm run test:e2e
npm run test:e2e:ui

# Browser install for screenshots and Playwright
npm run install:browsers

# GitHub CLI wrapper for shells where gh is not on PATH
npm run gh -- --version

Windows-only video helper:

.\scripts\Invoke-FfmpegVideoTool.ps1 -InputFile .\input.webm -OutputFile .\output.webm -SpeedMultiplier 1.08 -Overwrite

Security Notes

• Production mode requires CORS_ORIGIN.
• Local management APIs are restricted to trusted Kaleidoscope clients.
• Inspect mode is limited to loopback targets.
• Auth proxy sessions are temporary and cleaned up automatically.

Repository Layout

Kaleidoscope/
|- mosaic-client/   React client
|- server/          Express API and local tooling services
|- mcp-server/      MCP server and process manager
|- shared/          Shared device definitions
|- examples/        Sample apps for manual testing
|- tests/           End-to-end coverage

Contributing

See CONTRIBUTING.md for local setup and contribution expectations.

Security Reporting

See SECURITY.md for how to report vulnerabilities responsibly.

License

This project is released under the MIT License. See LICENSE.