@logspace/mcp-server

Model Context Protocol (MCP) server for Logspace - AI-powered session recording analysis and debugging with GitHub Copilot.

Installation

For VS Code / Cursor

The MCP server is automatically configured when you install the Logspace extension. You can also configure it manually:

npx @logspace/mcp-server@latest

Add to your ~/Library/Application Support/Code/User/mcp.json:

{
	"servers": {
		"logspace": {
			"command": "npx",
			"args": ["-y", "@logspace/mcp-server@latest"],
			"env": {
				"API_BASE_URL": "https://api.logspace.io",
				"API_TOKEN_FILE": "/path/to/.logspace/token.txt"
			}
		}
	}
}

For Development

npm install @logspace/mcp-server

Features

🎯 Smart Analysis

AI-powered intelligent analysis that detects patterns, hidden issues, and provides actionable recommendations.

• Multi-level depth: quick (1-3s) / standard (3-8s) / comprehensive (8-15s)
• Pattern detection: Suspicious sequences, correlations, anomalies
• User behavior analysis: Frustration indicators, interaction patterns
• Performance insights: Bottleneck detection, slow requests
• Masked error detection: 200 OK responses with error payloads
• Prioritized recommendations: Critical, high, medium, low severity

→ See detailed Smart Analysis documentation

📊 Available Tools

1. smart_analysis - AI-powered intelligent session analysis

   • Detects patterns and correlations
   • Finds masked errors (200 OK with error data)
   • Identifies user frustration indicators
   • Provides actionable recommendations
   • Three depth levels: quick, standard, comprehensive

2. analyze_session - Basic session analysis

   • Error detection and stack traces
   • Failed network requests
   • User actions timeline
   • Session summary

3. fetch_bug_logs - Raw log data retrieval

   • Complete session data
   • All recorded events
   • Unprocessed format

4. get_error_context - Error context analysis

   • Events 5 seconds before error
   • Related console logs
   • Network activity
   • User actions

5. list_network_requests - Network request filtering

   • Filter by method, status, URL pattern
   • Request/response bodies
   • Performance metrics

6. get_console_logs - Console output filtering

   • Filter by log level (error, warn, info, debug)
   • Text search across logs
   • Timestamp filtering

7. get_storage_logs - Storage operations

   • localStorage, sessionStorage, cookies, indexedDB
   • Filter by storage type, operation, key pattern
   • Track what data was stored/retrieved

8. get_interactions - User interactions

   • Clicks, inputs, scrolls, navigation events
   • Element selectors and coordinates
   • Input values and timestamps

9. get_annotations - Session annotations

   • User-added notes and issue flags
   • Highlights and markers
   • Search annotation content

10. get_sse_websocket_logs - Real-time communication

    • Server-Sent Events (SSE) messages
    • WebSocket connections and messages
    • Filter by URL, message content

11. get_rrweb_events - DOM recording events

    • Access rrweb (DOM mutation recording) events
    • Visual replay event data
    • Filter by event type, time range
    • DOM snapshots and incremental changes

🌐 Browser Automation Tools (Optional)

These tools require Playwright to be installed separately. If not installed, they will return installation instructions.

12. replay_session - Replay user interactions in a real browser

    • Automatically performs clicks, inputs, navigation from recorded session
    • Configurable replay speed (slow/normal/fast)
    • Takes screenshot after replay
    • Useful for reproducing bugs

13. verify_page - Verify page state and capture errors

    • Navigate to URL and capture page state
    • Check for console errors and warnings
    • Detect failed network requests
    • Capture screenshot for verification

14. close_browser - Close browser session

    • Clean up browser resources
    • Use when done with browser automation

Installing Playwright (Optional)

To enable browser automation tools, install Playwright globally:

npm install -g playwright
npx playwright install chromium

Then restart the MCP server.

Tool Comparison

Choose the right tool for your debugging needs:

| Feature | smart_analysis | analyze_session | fetch_bug_logs | get_error_context | list_network_requests | get_console_logs | | ---------------------- | -------------------- | --------------- | --------------- | ------------------- | --------------------- | ----------------- | | Speed | 1-15s (configurable) | 1-2s | <1s | <1s | <1s | <1s | | Use Case | Deep investigation | Quick overview | Raw data export | Error debugging | API debugging | Console debugging | | Pattern Detection | ✅ Advanced | ❌ | ❌ | ❌ | ❌ | ❌ | | Hidden Issues | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | Recommendations | ✅ Actionable | ❌ | ❌ | ❌ | ❌ | ❌ | | Severity Levels | ✅ 4 levels | ❌ | ❌ | ❌ | ❌ | ❌ | | User Behavior | ✅ Advanced | ⚠️ Basic | ❌ | ❌ | ❌ | ❌ | | Error Stack Traces | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | | Network Analysis | ✅ | ✅ | ✅ | ✅ | ✅ Advanced | ❌ | | Console Logs | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ Advanced | | Filtering | ❌ | ❌ | ❌ | ❌ | ✅ Advanced | ✅ Advanced | | Best For | Complex bugs | Quick triage | Data export | Single error | API issues | Console errors | | Recommended When | Need insights | First look | Integration | Investigating crash | 401/500 errors | Warning floods |

When to Use Each Tool

🎯 smart_analysis - Start here for unknown issues

• "Why is this session failing?"
• "What patterns do I see across errors?"
• "Is the user frustrated?"
• Recommended depth: standard for most cases

📋 analyze_session - Quick health check

• "Give me a 10-second summary"
• "What are the obvious errors?"
• "How many requests failed?"

📦 fetch_bug_logs - Raw data needed

• Exporting to external tools
• Custom analysis pipelines
• Compliance/audit requirements

🔍 get_error_context - Investigating specific error

• "What happened right before this crash?"
• "Which user actions triggered this?"
• Focus on 5-second window

🌐 list_network_requests - API debugging

• "Show me all 401 errors"
• "Which POST requests failed?"
• "Find requests to /api/auth/*"

📝 get_console_logs - Console noise

• "Show me only errors"
• "Find logs containing 'timeout'"
• "Filter out debug logs"

Usage Examples

With GitHub Copilot Chat

Once configured, use natural language in Copilot Chat:

@workspace #logspace analyze session 25

@workspace #logspace show me all failed API requests in session 42

@workspace #logspace what errors occurred around timestamp 2024-11-18T10:30:00Z in session 15

Direct Tool Invocation

Smart Analysis (Recommended)

{
	"tool": "smart_analysis",
	"arguments": {
		"bugId": 25,
		"depth": "standard"
	}
}

Output includes:

• Pattern detection results
• Masked error findings
• User frustration indicators
• Prioritized recommendations
• Execution time metrics

Quick Session Overview

{
	"tool": "analyze_session",
	"arguments": {
		"bugId": 25
	}
}

Find Authentication Failures

{
	"tool": "list_network_requests",
	"arguments": {
		"bugId": 25,
		"statusCode": 401,
		"urlPattern": "/api/auth",
		"limit": 10
	}
}

Investigate Error Context

{
	"tool": "get_error_context",
	"arguments": {
		"bugId": 25,
		"errorId": "err_abc123"
	}
}

Filter Console Logs

{
	"tool": "get_console_logs",
	"arguments": {
		"bugId": 25,
		"level": "error",
		"searchText": "timeout",
		"limit": 20
	}
}

Configuration

Environment Variables

| Variable | Description | Default | Required | | ----------------- | ------------------------------------- | ----------------------- | -------- | | API_BASE_URL | Logspace API endpoint | http://localhost:5002 | No | | API_TOKEN_FILE | Path to token JSON file | - | Yes* | | API_TOKEN | Direct token (less secure) | - | Yes* | | LOG_LEVEL | Logging level (debug/info/warn/error) | info | No | | REQUEST_TIMEOUT | API request timeout (seconds) | 3600 | No |

*One of API_TOKEN_FILE or API_TOKEN is required

Token File Format

The API_TOKEN_FILE should contain JSON with access and refresh tokens:

{
	"access_token": "your-jwt-token",
	"refresh_token": "your-refresh-token",
	"updated_at": "2024-11-18T10:00:00Z"
}

Development

Local Setup

git clone https://github.com/logspace-io/logspace-mcp.git
cd logspace-mcp/mcp-server
npm install
npm run build

Watch Mode

npm run dev

Testing

# Test smart analysis with different depth levels
node test-smart-analysis.js 25 quick
node test-smart-analysis.js 25 standard
node test-smart-analysis.js 25 comprehensive

Project Structure

mcp-server/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── tools/
│   │   ├── smartAnalysis.ts  # AI-powered analysis (NEW!)
│   │   ├── analyzeSession.ts # Basic analysis
│   │   ├── fetchBugLogs.ts
│   │   ├── getErrorContext.ts
│   │   ├── getConsoleLogs.ts
│   │   └── listNetworkRequests.ts
│   ├── services/
│   │   ├── apiClient.ts      # API integration
│   │   └── logParser.ts      # Log parsing logic
│   ├── types/                # TypeScript types
│   └── utils/                # Helper functions
├── dist/                     # Compiled JavaScript
├── SMART_ANALYSIS.md         # Smart analysis docs
└── test-smart-analysis.js    # Test script

Architecture

Smart Analysis Pipeline

┌─────────────────────────────────────────────────────────────┐
│ 1. Fetch Session Data                                       │
│    • API call to Logspace backend                          │
│    • Request-level caching (5min TTL)                      │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. Parse & Structure Logs                                   │
│    • Errors, console logs, network requests                │
│    • User actions, performance metrics                     │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. Run Analysis (depth-dependent)                          │
│    Quick: Critical issues only (~1-3s)                     │
│    Standard: + Pattern detection (~3-8s)                   │
│    Comprehensive: + Hidden issues (~8-15s)                 │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 4. Pattern Detection                                        │
│    • Suspicious sequences (error → user reaction)          │
│    • User frustration (rapid clicks, repeated actions)     │
│    • Performance issues (slow requests, bottlenecks)       │
│    • Missing actions (expected API calls not made)         │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 5. Generate Recommendations                                 │
│    • Prioritized by severity (critical/high/medium/low)    │
│    • Actionable steps with file paths                      │
│    • Related code context                                  │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 6. Return Structured Results                                │
│    • JSON response with findings                           │
│    • Execution metrics                                     │
└─────────────────────────────────────────────────────────────┘

Key Components

• API Client (services/apiClient.ts): Authenticated requests with caching
• Log Parser (services/logParser.ts): Structures raw session data
• Smart Analysis (tools/smartAnalysis.ts): AI-powered pattern detection
• Error Handler (utils/errorHandler.ts): Consistent error responses

Error Handling

All tools return structured error responses:

{
	"success": false,
	"error": "Error message",
	"executionTime": 1234
}

Performance & Optimization

Response Times

| Tool | Typical Response | Max Response | | ------------------------------ | ---------------- | ------------ | | smart_analysis (quick) | 1-3s | 5s | | smart_analysis (standard) | 3-8s | 12s | | smart_analysis (comprehensive) | 8-15s | 20s | | analyze_session | 1-2s | 3s | | Other tools | <500ms | 1s |

Caching Strategy

• Request-level caching: 300s TTL (5 minutes)
• Shared cache: Tools in same request cycle reuse data
• Auto-cleanup: Cache cleared after request completes
• Benefits: Reduces API calls, faster repeated queries

Optimization Tips

1. Use quick depth first: Fastest results for initial triage
2. Filter strategically: Use limit and specific filters to reduce data
3. Leverage caching: Multiple tool calls in same session are faster
4. Batch requests: Use smart_analysis instead of multiple individual tools

API Response Format

All tools return consistent JSON responses:

Success Response

{
	"success": true,
	"data": {
		// Tool-specific data
	},
	"executionTime": 1234,
	"metadata": {
		"bugId": 25,
		"timestamp": "2024-11-18T10:30:00Z"
	}
}

Error Response

{
	"success": false,
	"error": "Descriptive error message",
	"errorCode": "ERROR_TYPE",
	"executionTime": 123
}

Common Error Codes

• AUTHENTICATION_FAILED: Invalid or expired token
• SESSION_NOT_FOUND: Bug ID doesn't exist
• RATE_LIMIT_EXCEEDED: Too many requests
• NETWORK_ERROR: API connectivity issues
• VALIDATION_ERROR: Invalid parameters

Troubleshooting

"Authentication failed" error

1. Check API_TOKEN_FILE path exists
2. Verify token file has valid JSON format
3. Ensure token hasn't expired
4. Try refreshing token via Logspace extension

"Session not found" error

1. Verify bug ID exists in your Logspace account
2. Check you have permission to access the session
3. Confirm session recording completed successfully

Slow response times

1. Use quick depth for faster results
2. Add limit parameters to reduce data volume
3. Check network connectivity to API
4. Verify API endpoint is responsive

MCP connection issues

1. Restart VS Code / Cursor
2. Check mcp.json configuration is correct
3. Verify npx is available: which npx
4. Check Node.js version: node --version (requires ≥18)

Development Guidelines

• Follow existing code style (TypeScript + ESM)
• Add tests for new features
• Update documentation
• Keep response times under limits
• Use semantic commit messages

License

MIT License - see LICENSE file for details

Links

• npm Package: https://www.npmjs.com/package/@logspace/mcp-server
• GitHub: https://github.com/logspace-io/logspace-mcp
• Documentation: SMART_ANALYSIS.md
• Website: https://logspace.io
• Support: [email protected]

Related Projects

• VS Code Extension: Logspace integration for Visual Studio Code
• JetBrains Plugin: Logspace integration for IntelliJ IDEA and WebStorm
• Web Dashboard: https://app.logspace.io

Changelog

v1.0.0

• ✨ Smart analysis tool with AI-powered pattern detection
• ✨ Multi-level analysis depth (quick/standard/comprehensive)
• ✨ Masked error detection
• ✨ User frustration indicators
• ✨ Actionable recommendations with severity levels
• 📋 Basic session analysis
• 🌐 Network request filtering
• 📝 Console log filtering
• 🔍 Error context analysis
• 📦 Raw log data export
• 📚 Comprehensive documentation