Local Lens Server

HTTP/MCP server component for Local Lens - captures console logs and network requests with response bodies for LLM analysis.

⚠️ Important: This server is designed for local development use only. It runs entirely on your machine with no external connections.

Installation

This package provides both HTTP and MCP server functionality for Local Lens.

As Standalone MCP Server

Install globally via npm to use as MCP server:

npm install -g local-lens

As Development Dependency

For local development of the Local Lens project:

git clone https://github.com/aotakeda/local-lens.git
cd local-lens/server
npm install
npm run dev

Note: The local-lens npm package contains only the MCP server binary. For full Local Lens functionality (browser extension + CLI + server), clone the repository and follow the main README.md setup instructions.

Quick Start

# Install dependencies
npm install

# Start in development mode
npm run dev

# Or build and start production
npm run build
npm start

Server runs on http://localhost:27497

API Endpoints

Console Logs

• POST /logs - Submit log batches
• GET /logs - Query logs with filters
• DELETE /logs - Clear all logs
• GET /logs/stream - Real-time log stream

Network Requests

• POST /network-requests - Submit request batches
• GET /network-requests - Query requests with filters
• GET /network-requests/:id - Get specific network request by ID
• DELETE /network-requests - Clear all requests
• GET /network-requests/stream - Real-time request stream

System

• GET /health - Server health check
• GET /health-local-lens - Special health check for extension port detection
• GET /config - Get server configuration for extension
• POST /mcp-config - Update MCP server configuration

Settings

• GET /settings - Retrieve extension settings
• POST /settings - Update extension settings
• DELETE /settings - Reset settings to defaults
• GET /settings/:key - Get specific setting value
• PUT /settings/:key - Update specific setting value

Network Configuration

• GET /network-config - Get network capture configuration
• POST /network-config - Update network capture configuration
• POST /network-config/reset - Reset network config to defaults

JSON Output Format

All console logs and network requests are output in structured JSON format:

Console Logs

{
  "type": "console_log",
  "level": "info|warn|error",
  "hostname": "example.com",
  "timestamp": "2023-01-01T00:00:00.000Z",
  "page_url": "https://example.com/page",
  "message": "Log message",
  "stack_trace": "Error stack (if error)",
  "user_agent": "Browser info (if available)",
  "browser": "Chrome|Firefox|Safari|Edge",
  "metadata": { "custom": "data" }
}

Network Requests

{
  "type": "network_request",
  "method": "GET|POST|...",
  "url": "https://api.example.com/endpoint",
  "hostname": "api.example.com",
  "timestamp": "2023-01-01T00:00:00.000Z",
  "status": {
    "code": 200,
    "category": "success|client_error|server_error|redirect|pending|unknown"
  },
  "duration_ms": 150,
  "request_headers": { "Content-Type": "application/json" },
  "request_body": {
    "type": "json|text|encoded_data",
    "data": "processed content",
    "truncated": false,
    "original_length": 1024
  },
  "response_headers": { "Content-Type": "application/json" },
  "response_body": {
    "type": "json|text|encoded_data",
    "data": "processed response content",
    "truncated": false,
    "original_length": 2048
  },
  "context": {
    "is_api_endpoint": true,
    "is_authenticated": false,
    "user_agent": "Browser user agent",
    "page_url": "https://example.com"
  }
}

Features

Browser Log Capture

• Console Logs: Captures all console.log/warn/error/info from Chrome extension
• Network Requests: Full HTTP request/response monitoring with response bodies
• Response Body Capture: Full content for JSON, HTML, XML, and JavaScript responses
• Domain Filtering: Configurable domain-based capture via extension settings

Server Log Capture

• Universal Backend Support: Works with Rails, Express, Django, FastAPI, Laravel, etc.
• CLI Integration: Captures server logs via local-lens-cli package
• Process Identification: Tags backend logs with source: "backend-console" and process names
• Real-time Forwarding: Live server log forwarding to Local Lens database

Data Management

• SQLite Storage: Persistent local database with dual tables (logs + network_requests)
• Settings Storage: Separate settings database for configuration persistence
• Circular Buffer: 10k item limit per table with auto-cleanup
• Smart Filtering: Excludes noise (images, tracking, binary content)
• LLM-Optimized: Structured JSON output designed for AI analysis

Integration & Access

• Real-time Streaming: Server-Sent Events for live monitoring
• HTTP API: RESTful endpoints for all data access and configuration
• MCP Integration: Model Context Protocol server for AI assistant access
• Dual Server Mode: Both HTTP (port 27497) and MCP servers share same database

MCP Integration

The server includes a built-in MCP (Model Context Protocol) server that provides AI assistants with access to captured logs and network requests.

Available MCP Tools

• get_console_logs - Retrieve console logs with filtering options
• get_network_requests - Retrieve network requests with filtering options
• search_logs - Search console logs by text content
• search_network_requests - Search network requests by URL/content
• clear_console_logs - Clear all stored console logs
• clear_network_requests - Clear all stored network requests
• trace_request - Trace requests across browser and backend systems using correlation ID

Usage with Claude Code

# Install globally first
npm install -g local-lens

# Add to Claude Code
claude mcp add local-lens -- local-lens

Usage with Cursor

First install globally, then add to ~/.cursor/mcp.json:

# Install globally first
npm install -g local-lens

{
  "mcpServers": {
    "local-lens": {
      "command": "local-lens"
    }
  }
}

Development

npm test              # Run all tests
npm run dev           # Development with auto-reload (builds and starts with tsx watch)
npm run build         # Compile TypeScript (HTTP server)
npm run build:mcp     # Compile TypeScript (MCP server) 
npm run build:all     # Build both HTTP and MCP servers
npm start             # Start production server (builds and runs from dist/)
npm run lint          # Run ESLint
npm run lint:fix      # Auto-fix linting issues

Project Structure

server/
├── src/
│   ├── index.ts              # HTTP server entry point
│   ├── mcp-standalone.ts     # MCP server entry point
│   ├── mcp.ts               # MCP server setup
│   ├── types.ts             # TypeScript definitions
│   ├── __tests__/           # Test files
│   ├── mcp/                 # MCP server implementation
│   ├── routes/              # HTTP API routes
│   ├── storage/             # Database and storage logic
│   ├── services/            # Business logic services
│   └── utils/               # Utility functions
├── dist/                    # Compiled HTTP server
├── dist-mcp/               # Compiled MCP server
├── data/                   # SQLite databases
│   ├── browserrelay.db     # Main data storage
│   └── browserrelay-settings.db # Settings storage
├── package.json            # Dependencies and scripts
├── tsconfig.json          # TypeScript config (HTTP server)
└── tsconfig.mcp.json      # TypeScript config (MCP server)

Database Initialization

The server automatically creates the database files and directory structure on first startup:

• Directory: server/data/ (created automatically)
• Main Database: server/data/browserrelay.db (console logs and network requests)
• Settings Database: server/data/browserrelay-settings.db (extension configuration)

Automatic Setup: No manual database setup required. The server handles:

• Directory creation with proper permissions
• Database file creation with correct SQLite format
• Table schema initialization
• Concurrent access handling for multiple server instances

Troubleshooting Database Issues:

# If database errors occur, reset databases:
rm -rf server/data/
npm run dev  # Databases will be recreated automatically

Database Schema

Console Logs Table (logs)

• id - Auto-incrementing primary key
• timestamp - ISO 8601 timestamp string
• level - Log level (info, warn, error, log)
• message - Log message content
• stackTrace - Error stack trace (if applicable)
• pageUrl - Page URL (or process://name for backend)
• userAgent - Browser user agent
• metadata - JSON metadata object (includes source, backendProcess, etc.)
• created_at - Database insertion timestamp

Network Requests Table (network_requests)

• id - Auto-incrementing primary key
• requestId - Unique request identifier
• timestamp - ISO 8601 timestamp string
• method - HTTP method (GET, POST, etc.)
• url - Request URL
• requestHeaders - JSON request headers
• responseHeaders - JSON response headers
• requestBody - Request body as text (truncated if > 1MB)
• responseBody - Response body as text (truncated if > 1MB)
• statusCode - HTTP status code
• duration - Request duration in milliseconds
• responseSize - Response size in bytes
• pageUrl - Source page URL (or process://name for backend)
• userAgent - Browser user agent
• metadata - JSON metadata object (includes source, backendProcess, correlationId, etc.)
• created_at - Database insertion timestamp

Environment Variables

The server supports these optional environment variables:

• NODE_ENV - Set to production for production mode (affects logging)
• LOG_CONSOLE_MESSAGES - Set to false to disable console log JSON output (default: true)
• LOG_NETWORK_REQUESTS - Set to false to disable network request JSON output (default: true)
• SETTINGS_DB_PATH - Custom path for settings database (default: data/browserrelay-settings.db)

Database Locations

• Main Database: server/data/browserrelay.db (logs and network requests)
• Settings Database: server/data/browserrelay-settings.db (extension configuration)
• Test Database: :memory: (in-memory for tests)

Databases are automatically created in the data/ directory when the server starts.

Performance Notes

• Circular Buffer: Each table maintains a maximum of 10,000 entries with automatic cleanup
• Body Truncation: Request/response bodies are truncated at 1MB during storage
• MCP Optimization: Network request responses are heavily truncated (200 chars) for AI consumption
• Indexing: Automatic indexes on timestamp, URL, method, and other frequently queried fields

License

MIT License - see LICENSE file for details.