Limelight

Limelight MCP

MCP Server

​

Overview

The Limelight MCP Server connects your running React or React Native app to AI coding assistants like Cursor, Claude Code, and any MCP-compatible editor. Instead of copying logs into ChatGPT or hoping your AI can guess what’s wrong from source code alone, Limelight streams live runtime data — renders, state changes, network requests, and console logs — directly into your editor’s AI. Ask your AI “why is my app slow?” and it answers with real data, not guesses.

The MCP server runs locally on your machine. No data leaves your system.

​

Quickstart

1

Add the MCP server to your editor

• Claude Code
• Cursor
• Other MCP Clients

claude mcp add limelight-mcp npx limelight-mcp

2

Install the SDK in your app

npm install @getlimelight/sdk

Initialize with the MCP target:

import { Limelight } from "@getlimelight/sdk";

Limelight.connect({
  target: "mcp",
});

Add Zustand or Redux stores to capture state changes:

Limelight.connect({
  target: "mcp",
  stores: { authStore: useAuthStore, cartStore: useCartStore },
});

3

Start your app and ask your AI

With your app running and your AI editor open, try:

• “My app feels slow. Do you see any issues?”
• “Why is my search showing wrong results?”
• “Which components are re-rendering the most?” Your AI will call Limelight’s tools automatically to inspect your app’s runtime state and give you answers backed by real data.

​

What your AI can see

Once connected, your AI assistant has access to everything happening in your running app:

Renders

Which components are rendering, how often, how expensive, and why. Detects render loops, unnecessary re-renders, and unstable props.

State

Zustand and Redux store contents, recent changes, and diffs. See exactly how state evolved over time.

Network

Every request and response with timing, status, headers, and bodies. Detects race conditions, waterfalls, and failed requests.

Console

All console output with levels, timestamps, and stack traces. Filtered and searchable.

​

Tools reference

The MCP server exposes 11 tools that your AI calls automatically based on your questions. For detailed usage workflows and examples, see the Tools & Workflows guide.

​

Diagnostics

limelight_get_session_overview

High-level snapshot of your running app. Event counts, errors, suspicious components, and detected patterns. **This is usually the first tool your AI calls.**Returns: total events by type, error/warning counts, top rendered components, suspicious items, and session metadata.

limelight_find_issues

Proactive scan across all captured events. Runs Limelight’s correlation engine and Debug IR pipeline on anything that looks problematic.Detects: unnecessary re-renders, unstable props, render cascades, race conditions, N+1 queries, state thrashing, and more.

Parameter	Type	Default	Description
verbose	boolean	false	Include causal summaries and event IDs
limit	number	5	Max issues to return
deduplicate	boolean	true	Group similar issues together

limelight_investigate_error

Full root cause analysis on an error. Runs the Debug IR pipeline to produce a causal chain, state deltas, violations, and suggested fixes.

Parameter	Type	Default	Description
error_id	string	—	Specific event ID
error_pattern	string	—	Match against error messages
scope	"most_recent" | "all"	"most_recent"	Which errors to analyze

​

Querying

limelight_query_network

Filter and search captured network requests.

Parameter	Type	Default	Description
url_pattern	string	—	URL substring or pattern
method	string	—	HTTP method filter
status_range	{ min, max }	—	Status code range
min_duration_ms	number	—	Slow request threshold
include_bodies	boolean	false	Include request/response bodies
limit	number	10	Max results

limelight_query_logs

Filter and search console events.

Parameter	Type	Default	Description
level	"error" | "warn"	"log"	"info"	"debug"	—	Log level filter
message_pattern	string	—	Search within messages
include_stack_traces	boolean	auto	Include stack traces
limit	number	10	Max results

limelight_get_timeline

Chronological view of all events within a time range.

Parameter	Type	Default	Description
last_n_seconds	number	10	Time window
event_types	array	all	Filter by type
min_severity	"info" | "warning"	"error"	—	Minimum importance

​

Deep dives

limelight_investigate_component

Full analysis of a React component — render history, props driving re-renders, and correlated state/network activity.

Parameter	Type	Description
component_name	string	Component to investigate

limelight_get_render_profile

Component render performance profiling. Shows render counts, costs, velocity, cause breakdown, and suspicious flags.

Parameter	Type	Default	Description
component_name	string	—	Filter to one component
suspicious_only	boolean	false	Only flagged components
sort_by	"render_count" | "render_cost"	"velocity"	"render_cost"	Sort order
limit	number	10	Max results

limelight_get_state_snapshot

Current state store contents and recent change history.

Parameter	Type	Default	Description
store_id	string	—	Specific store
path	string	—	Dot-notation path into state
include_history	boolean	false	Include recent changes
history_limit	number	10	Number of recent changes

limelight_correlate_event

Find everything related to a specific event using Limelight’s correlation engine. Returns a timeline (before/concurrent/after) and a correlation graph with edge types and confidence scores.

Parameter	Type	Default	Description
event_id	string	—	Event to correlate (required)
verbose	boolean	false	Full graph with all nodes and edges

limelight_get_event

Retrieve the full details of a single event by its ID. Returns complete event data including bodies, headers, stack traces, state diffs, or render details depending on event type. Use this for cheap inspection after finding event IDs from other tools.

Parameter	Type	Description
event_id	string	The ID of the event to retrieve (required)

​

Configuration

The MCP server accepts CLI arguments for customization:

npx limelight-mcp --port 9229 --max-events 10000 --verbose

Flag	Default	Description
--port	9229	WebSocket port for SDK connection
--max-events	10000	Maximum events stored in memory
--verbose	false	Enable verbose logging

​

How it works

Your App (with SDK) → WebSocket → Limelight MCP Server → stdio → AI Editor

1. The Limelight SDK captures runtime events in your app
2. Events stream to the MCP server over a local WebSocket connection
3. The MCP server runs correlation and analysis on the events
4. Your AI assistant calls Limelight’s tools via the MCP protocol
5. Responses include structured, pre-analyzed debugging context — not raw logs All data stays on your machine. The MCP server runs locally and communicates with your editor over stdio.

The MCP server stores events in memory. Data resets when the server restarts. Maximum capacity is configurable with --max-events.

​

Supported frameworks

Framework	Status
React Native	Supported
React (web)	Supported
Next.js	Supported
Node	Supported

​

Supported state libraries

Library	Status
Zustand	Supported
Redux	Supported
Jotai	Coming soon
MobX	Planned

SecurityTools & Workflows