mcp-logger
Overview
mcp-logger is a Model Context Protocol (MCP) server and companion client
toolkit that captures structured log messages from browsers and Node.js
processes. It forwards those logs to MCP-aware tools (Claude, VS Code, Windsurf,
etc.), provides a live web dashboard, and keeps native console output intact for
local debugging.
Goals
- Collect logs from many clients (browser or Node) and differentiate their
sources. - Preserve native
console.*behavior while streaming structured entries to the
MCP server. - Offer real-time viewing (web UI + MCP logging notifications) and historical
retrieval via fetch APIs. - Support buffer clearing and named sessions so test runs are easy to diff.
- Stay transport-agnostic and open for community adoption.
Feature Set
- MCP Logging Server – stdio-compatible server with optional HTTP/WebSocket
bridge, ring-buffer storage, and tool APIs (push_log,fetch_logs,
clear_logs,set_session). - Web Dashboard – Vite-powered SPA served by the server for live log
monitoring, filtering, session control, and quick links to health/meta/events
endpoints plus the in-browser demo. - Client Adapters – Browser and Node helpers that wrap
console.log, send
structured payloads to the server, and retain native console output. - Session & Client Tagging – Each log includes
clientIdandsessionId
metadata for filtering and grouping. - Structured Schema – Shared definitions for levels, payload shape, and
validation logic to keep all packages in sync.
Architecture```
┌────────────────────────┐ ┌───────────────────────────┐
│ Browser Client │ │ Node Client │
│ @mcp-logger/browser │ │ @mcp-logger/node │
│ • console hook │ │ • console hook │
│ • HTTP/WebSocket push │ │ • HTTP/WebSocket/stdio │
└──────────┬─────────────┘ └──────────┬────────────────┘
│ │
▼ ▼
┌────────────────────────────────────────────────────┐
│ mcp-logger Server │
│ • MCP stdio transport │
│ • HTTP + WebSocket endpoints │
│ • Ring buffer + sessions │
│ • Tools: push_log, fetch_logs, clear_logs, │
│ set_session │
│ • MCP logging notifications │
└──────────┬────────────────────────────┬────────────┘
│ │
▼ ▼
┌────────────────────┐ ┌──────────────────────┐
│ Web Dashboard │ │ MCP Clients (IDE, AI)│
│ SSE / WebSocket │ │ logging/fetch tools │
└────────────────────┘ └──────────────────────┘
## Server Components
- **Transport Layer** – stdio MCP interface plus optional HTTP server with
WebSocket/SSE endpoints for browser clients and dashboard.
- **Ring Buffer Store** – Configurable in-memory circular buffer that stores
logs, maintains cursors, and tracks dropped entries when capacity is
exceeded.
- **Session Manager** – Issues `sessionId` tokens, records start/end metadata,
and exposes session list to clients.
- **Tool Handlers**
- `logging/push` – validate payload, stamp timestamp/sequence, place entry in
buffer, and broadcast notifications.
- `logging/fetch` – filter by level, client, session, time window, and return
paginated results with a cursor.
- `logging/clear` – reset buffer (optionally starting a new default session)
and notify subscribers.
- `logging/set-session` – create or rename a session scope and hand back the
active `sessionId`.
- **Notification Dispatcher** – Emits MCP logging notifications and broadcasts
to WebSocket/SSE subscribers.
## Data Model```jsonc
{
"id": "uuid",
"timestamp": "ISO-8601 string",
"sequence": 123456,
"level": "trace|debug|info|warn|error|fatal",
"clientId": "renderer-web",
"sessionId": "run-48",
"message": "Fog renderer ready",
"data": { "module": "fog", "details": { "cells": 2048 } },
"source": "browser-http"
}
Logging Flow
- Client adapter patches
console.*and forwards structured payloads to the
server. - Server validates payload, assigns sequence number, stores in ring buffer, and
emits MCP notification + WebSocket update. - MCP clients (Claude, IDE) use
logging/fetchto retrieve batches or stream
live messages; dashboard updates in real time. - Users or automations call
logging/clear/logging/set-sessionto reset or
tag test runs, ensuring clean diffs between sessions.
Client Adapters
- Browser (
@mcp-logger/browser) attachLogger({ endpoint, clientId, sessionId?, levels?, enabled? })– full
console hook for application integration.- Lightweight helper
mcpLog(message, session?, client?)for quick scripts or
demos. Defaults to'.'for session/client; passing new values updates the
stored identifiers before sending. Uses Fetch batching and falls back to XHR
(ES5-compatible build). - Built output transpiled to ES5 (no optional chaining, arrow functions, etc.)
so it can run in legacy engines. - Respects runtime feature flags so logging can be toggled without reload.
- Node (
@mcp-logger/node) - Similar API; preserves stdout/stderr; optional hooks for unhandled
rejections or custom metadata injectors. - Both adapters ensure
clientIddefaults (hostname + PID or URL) while allowing
explicit overrides for multi-client deployments.
Web Dashboard
- Served at the server root with static assets built by Vite.
- Sticky header surfaces metadata plus quick links to
/health,/meta,
/events, and/demo, alongside a "Clear logs" button. - Connects via SSE/WebSocket for live updates.
- UI features: level toggles, client/session filters, text search, timeline
graph, clear/session buttons, JSON export, theme toggle. - Uses MCP tool endpoints under the hood for destructive actions (clear, start
session).
Browser Demo
Visit /demo to see the mcpLog helper in action. The page imports the
browser bundle, throws immediately if it fails to load, and sends an info
message every three seconds:```html
<script src="/client/index.js"></script>
<script>
mcpLog('Random message', 'demo-session', 'demo-browser')
</script>
Providing `session`/`client` arguments updates the stored identifiers; omit them
to keep previous values (defaults to `'.'`).
## Configuration
- Environment variables / config file
- `LOG_BUFFER_SIZE` – maximum entries kept in memory.
- `LOG_HTTP_PORT` – optional HTTP/WebSocket listener.
- `LOG_AUTH_TOKEN` – bearer token required for remote pushes.
- `LOG_PERSIST_PATH` (future) – directory for NDJSON archival.
- IDE auto-start (VS Code/Windsurf)
- Add an entry under `mcpServers` pointing to `node packages/server/index.js`
with the appropriate `cwd`.
- Optional npm scripts: `dev` (watch mode), `start` (prod server), `dashboard`
(run web UI standalone).
- `LOG_BROWSER_TARGET=es5` (build flag controlling Babel preset for legacy
bundle).
## Local Development Without Workspaces
The repo now relies on plain npm with direct `file:` links instead of
workspaces. Use the project root scripts to keep package builds in sync:```bash
npm install
npm run build:shared
npm run build:server
npm run build:browser
npm run build:node
npm run build:dashboard
The npm run build shortcut chains those commands in order. Each package can
also be built or tested in isolation via npm run --prefix
packages/.
Roadmap
- Scaffold repo (workspaces, linting, testing, GitHub workflows).
- Implement shared schema utilities and unit tests.
- Build server MVP (MCP stdio + HTTP/WebSocket, ring buffer, tool handlers).
- Release browser & Node adapters with console hooking and transport logic.
- Ship basic web dashboard (live table, filters, clear/session controls).
- Add persistence/export, auth hooks, CLI utilities, and documentation.
- Publish packages to npm and prepare GitHub release templates.
Status
- Spec drafted – implementation in progress.
