# Variable Inspection System Design
## Overview
This document defines the MCP tools interface for runtime variable inspection in the debugger MCP server. The system provides comprehensive variable inspection, scope chain analysis, expression evaluation, and watch expression management.
## Architecture
### Core Components
1. **VariableManager** - Central state management for variable inspection
2. **ChromeDebugger Extensions** - CDP Runtime domain integration
3. **MCP Tools** - Five specialized tools for variable operations
4. **Watch Expression System** - Persistent expression monitoring
### Integration with Existing System
- Extends existing ChromeDebugger class with Runtime domain methods
- Follows BreakpointManager pattern for state management
- Uses established MCP tool registration patterns
- Integrates with existing event system for real-time updates
## Data Structures
### VariableDescriptor Interface
```typescript
interface VariableDescriptor {
name: string;
value: any;
type: string; // 'string', 'number', 'object', 'function', etc.
subtype?: string; // 'array', 'null', 'regexp', 'date', etc.
description: string;
objectId?: string; // For complex objects requiring further inspection
writable: boolean;
configurable: boolean;
enumerable: boolean;
isOwn: boolean;
preview?: ObjectPreview; // Abbreviated object representation
}
```
### ScopeDescriptor Interface
```typescript
interface ScopeDescriptor {
type: 'global' | 'local' | 'with' | 'closure' | 'catch' | 'block' | 'script' | 'eval' | 'module';
name?: string;
startLocation?: Location;
endLocation?: Location;
objectId: string;
variableCount: number;
variables?: VariableDescriptor[]; // Populated when requested
}
```
### WatchExpression Interface
```typescript
interface WatchExpression {
id: string;
expression: string;
result?: any;
error?: string;
timestamp: Date;
callFrameId?: string; // Context for evaluation
}
```
### EvaluationResult Interface
```typescript
interface EvaluationResult {
result: any;
type: string;
description: string;
objectId?: string;
exceptionDetails?: ExceptionDetails;
wasThrown: boolean;
}
```
## MCP Tools Interface
### 1. inspect-variables
**Purpose**: Inspect variables in a specific scope of a call frame
**Input Schema**:
```typescript
{
callFrameId: z.string().optional().describe("Call frame ID to inspect (defaults to top frame)"),
scopeNumber: z.number().optional().describe("Scope index to inspect (defaults to 0 - local scope)"),
includeNonEnumerable: z.boolean().optional().describe("Include non-enumerable properties"),
generatePreview: z.boolean().optional().describe("Generate object previews for complex objects")
}
```
**Output**:
```typescript
{
success: boolean;
message: string;
callFrameId: string;
scopeType: string;
variables: VariableDescriptor[];
totalCount: number;
}
```
### 2. get-scope-chain
**Purpose**: Get the complete scope chain for a call frame
**Input Schema**:
```typescript
{
callFrameId: z.string().optional().describe("Call frame ID (defaults to top frame)")
}
```
**Output**:
```typescript
{
success: boolean;
message: string;
callFrameId: string;
scopes: ScopeDescriptor[];
currentScopeIndex: number;
}
```
### 3. evaluate-expression
**Purpose**: Evaluate JavaScript expressions in the context of a call frame
**Input Schema**:
```typescript
{
expression: z.string().describe("JavaScript expression to evaluate"),
callFrameId: z.string().optional().describe("Call frame ID for context (defaults to top frame)"),
includeCommandLineAPI: z.boolean().optional().describe("Include console API (default: false)"),
returnByValue: z.boolean().optional().describe("Return result by value instead of object reference"),
throwOnSideEffect: z.boolean().optional().describe("Throw if expression has side effects"),
timeout: z.number().optional().describe("Evaluation timeout in milliseconds")
}
```
**Output**:
```typescript
{
success: boolean;
message: string;
result: EvaluationResult;
callFrameId: string;
}
```
### 4. modify-variable
**Purpose**: Modify variable values in a specific scope
**Input Schema**:
```typescript
{
callFrameId: z.string().describe("Call frame ID containing the variable"),
scopeNumber: z.number().describe("Scope index containing the variable"),
variableName: z.string().describe("Name of variable to modify"),
newValue: z.any().describe("New value for the variable"),
valueType: z.string().optional().describe("Type hint for the new value")
}
```
**Output**:
```typescript
{
success: boolean;
message: string;
variable: VariableDescriptor;
previousValue: any;
}
```
### 5. manage-watch-expressions
**Purpose**: Manage persistent watch expressions
**Input Schema**:
```typescript
{
action: z.enum(["add", "remove", "list", "clear", "evaluate"]).describe("Watch expression action"),
expression: z.string().optional().describe("Expression to watch (for add action)"),
watchId: z.string().optional().describe("Watch expression ID (for remove action)"),
callFrameId: z.string().optional().describe("Call frame context for evaluation")
}
```
**Output**:
```typescript
{
success: boolean;
message: string;
watchExpressions: WatchExpression[];
affectedWatch?: WatchExpression;
}
```
## Chrome DevTools Protocol Integration
### Required CDP Methods
1. **Runtime.getProperties** - Get object properties
2. **Runtime.evaluate** - Evaluate expressions
3. **Runtime.callFunctionOn** - Call functions on objects
4. **Debugger.evaluateOnCallFrame** - Evaluate in call frame context
5. **Debugger.setVariableValue** - Modify variable values
### Event Handling
- **Debugger.paused** - Update current call frame context
- **Debugger.resumed** - Clear current context
- **Runtime.executionContextCreated/Destroyed** - Track execution contexts
## Error Handling
### Common Error Scenarios
1. **Invalid Call Frame** - Call frame no longer exists
2. **Invalid Scope** - Scope index out of bounds
3. **Read-only Variable** - Attempt to modify non-writable variable
4. **Evaluation Error** - Expression syntax or runtime errors
5. **Context Mismatch** - Variable not found in specified scope
### Error Response Format
```typescript
{
success: false;
message: string;
errorCode: string;
details?: any;
}
```
## Implementation Plan
### Phase 1: Core Infrastructure
1. Create VariableManager class
2. Extend ChromeDebugger with Runtime methods
3. Define TypeScript interfaces
### Phase 2: Basic Variable Inspection
1. Implement inspect-variables tool
2. Implement get-scope-chain tool
3. Add basic error handling
### Phase 3: Expression Evaluation
1. Implement evaluate-expression tool
2. Implement modify-variable tool
3. Add comprehensive error handling
### Phase 4: Watch Expressions
1. Implement manage-watch-expressions tool
2. Add persistence layer
3. Add real-time evaluation updates
### Phase 5: Testing & Integration
1. Unit tests for all components
2. Integration tests with Chrome DevTools
3. End-to-end tests with React/Next.js applications
