@graphty/remote-logger 0.0.1 → 1.2.0

package/src/mcp/mcp-server.ts

@@ -0,0 +1,364 @@
+/**
+ * MCP Server for remote logging.
+ *
+ * Provides an MCP interface for Claude Code to query logs from browser
+ * applications. Uses STDIO transport for communication.
+ * @module mcp/mcp-server
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+import type { LogStorage } from "../server/log-storage.js";
+import {
+    logsClearHandler,
+    type LogsClearInput,
+    logsClearInputSchema,
+    logsClearTool,
+    logsGetAllHandler,
+    type LogsGetAllInput,
+    logsGetAllInputSchema,
+    logsGetAllTool,
+    logsGetErrorsHandler,
+    type LogsGetErrorsInput,
+    logsGetErrorsInputSchema,
+    logsGetErrorsTool,
+    logsGetFilePathHandler,
+    type LogsGetFilePathInput,
+    logsGetFilePathInputSchema,
+    logsGetFilePathTool,
+    logsGetRecentHandler,
+    type LogsGetRecentInput,
+    logsGetRecentInputSchema,
+    logsGetRecentTool,
+    logsListSessionsHandler,
+    type LogsListSessionsInput,
+    logsListSessionsInputSchema,
+    logsListSessionsTool,
+    logsReceiveHandler,
+    type LogsReceiveInput,
+    logsReceiveInputSchema,
+    logsReceiveTool,
+    logsSearchHandler,
+    type LogsSearchInput,
+    logsSearchInputSchema,
+    logsSearchTool,
+    logsStatusHandler,
+    logsStatusTool,
+} from "./tools/index.js";
+
+// Track registered tool names for testing
+let registeredTools: string[] = [];
+
+/**
+ * Get the names of all registered tools.
+ * Useful for testing.
+ * @returns Array of registered tool names
+ */
+export function getToolNames(): string[] {
+    return [...registeredTools];
+}
+
+/**
+ * Server instructions for LLMs describing the overall purpose and usage.
+ */
+const SERVER_INSTRUCTIONS = `Remote Logger MCP Server - View console.log output from browser applications.
+
+## What is Remote Logging?
+
+Browser applications run in a sandbox - their console.log() output appears in browser DevTools but is NOT visible to CLI tools or this assistant. Remote logging bridges this gap by sending browser logs to a server where they can be queried.
+
+## When to Use Remote Logging
+
+Use this when debugging applications where developer tools aren't easily accessible:
+- Storybook components (stories running in browser)
+- Web applications during development
+- Mobile web apps (phones, tablets) where DevTools requires USB debugging
+- VR/AR applications where you can't see a console while wearing a headset
+- Embedded devices, kiosks, or smart displays without keyboard access
+- Any JavaScript running in a browser context
+
+Remote logging is especially valuable for LLM assistants like this one - it enables reading, interpreting, and acting on application logs without requiring user interaction with browser DevTools.
+
+## Architecture
+
+Browser App → HTTP POST to /logs → Log Server (stores in memory + JSONL files) → MCP Tools (query logs)
+
+## Setting Up a Browser App to Send Logs
+
+First, get the server endpoint URL by calling logs_status - look for server.httpEndpoint in the response.
+
+### Option 1: Using the RemoteLogClient SDK (Recommended)
+
+Install: npm install @graphty/remote-logger
+
+\`\`\`typescript
+import { RemoteLogClient } from "@graphty/remote-logger";
+
+const logger = new RemoteLogClient({
+  serverUrl: "http://localhost:9080/logs",  // Get this from logs_status
+  projectMarker: "my-project",               // Optional: for filtering
+});
+
+// Intercept all console.log/warn/error calls
+logger.interceptConsole();
+
+// Or log manually
+logger.log("INFO", "Hello from browser!");
+\`\`\`
+
+### Option 2: Raw fetch() calls
+
+\`\`\`typescript
+fetch("http://localhost:9080/logs", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({
+    sessionId: "unique-session-id",
+    logs: [
+      { time: new Date().toISOString(), level: "INFO", message: "Hello!" }
+    ]
+  })
+});
+\`\`\`
+
+## Querying Logs (MCP Tools)
+
+Once browser logs are flowing to the server:
+
+1. logs_status - Check server health, get endpoint URL, see retention settings
+2. logs_get_recent - View recent logs (primary tool, sorted chronologically)
+3. logs_get_errors - Quick filter for ERROR level only
+4. logs_search - Find specific text (supports regex)
+5. logs_list_sessions - See all browser sessions
+6. logs_get_all - Get all logs grouped by session
+7. logs_get_file_path - Get JSONL file path for Grep/Read tools
+8. logs_clear - Delete logs (requires confirmation)
+
+## Typical Debugging Workflow
+
+1. Call logs_status to verify server is running and get the endpoint URL
+2. Ensure the browser app is configured to send logs to that endpoint
+3. Trigger the action in the browser you want to debug
+4. Call logs_get_recent to see what happened
+5. Use logs_search if looking for specific errors or messages`;
+
+/**
+ * Create an MCP server with logging tools.
+ *
+ * Registers all logging tools and returns the configured server.
+ * The server is not started; use `startMcpServer` to run it.
+ * @param storage - The LogStorage instance to use for log operations
+ * @returns Configured McpServer instance
+ */
+export function createMcpServer(storage: LogStorage): McpServer {
+    const server = new McpServer(
+        {
+            name: "remote-logger",
+            version: "1.0.0",
+        },
+        {
+            instructions: SERVER_INSTRUCTIONS,
+        },
+    );
+
+    // Reset registered tools
+    registeredTools = [];
+
+    // Register logs_get_recent tool
+    server.registerTool(
+        logsGetRecentTool.name,
+        {
+            description: logsGetRecentTool.description,
+            inputSchema: logsGetRecentInputSchema,
+        },
+        (args: LogsGetRecentInput) => {
+            return logsGetRecentHandler(storage, args).then((r) => ({
+                content: [
+                    {
+                        type: "text" as const,
+                        text: JSON.stringify(r, null, 2),
+                    },
+                ],
+            }));
+        },
+    );
+    registeredTools.push(logsGetRecentTool.name);
+
+    // Register logs_status tool
+    server.registerTool(
+        logsStatusTool.name,
+        {
+            description: logsStatusTool.description,
+        },
+        () => {
+            return logsStatusHandler(storage).then((r) => ({
+                content: [
+                    {
+                        type: "text" as const,
+                        text: JSON.stringify(r, null, 2),
+                    },
+                ],
+            }));
+        },
+    );
+    registeredTools.push(logsStatusTool.name);
+
+    // Register logs_list_sessions tool
+    server.registerTool(
+        logsListSessionsTool.name,
+        {
+            description: logsListSessionsTool.description,
+            inputSchema: logsListSessionsInputSchema,
+        },
+        (args: LogsListSessionsInput) => {
+            return logsListSessionsHandler(storage, args).then((r) => ({
+                content: [
+                    {
+                        type: "text" as const,
+                        text: JSON.stringify(r, null, 2),
+                    },
+                ],
+            }));
+        },
+    );
+    registeredTools.push(logsListSessionsTool.name);
+
+    // Register logs_receive tool
+    server.registerTool(
+        logsReceiveTool.name,
+        {
+            description: logsReceiveTool.description,
+            inputSchema: logsReceiveInputSchema,
+        },
+        (args: LogsReceiveInput) => {
+            return logsReceiveHandler(storage, args).then((r) => ({
+                content: [
+                    {
+                        type: "text" as const,
+                        text: JSON.stringify(r, null, 2),
+                    },
+                ],
+            }));
+        },
+    );
+    registeredTools.push(logsReceiveTool.name);
+
+    // Register logs_get_all tool
+    server.registerTool(
+        logsGetAllTool.name,
+        {
+            description: logsGetAllTool.description,
+            inputSchema: logsGetAllInputSchema,
+        },
+        (args: LogsGetAllInput) => {
+            return logsGetAllHandler(storage, args).then((r) => ({
+                content: [
+                    {
+                        type: "text" as const,
+                        text: JSON.stringify(r, null, 2),
+                    },
+                ],
+            }));
+        },
+    );
+    registeredTools.push(logsGetAllTool.name);
+
+    // Register logs_get_errors tool
+    server.registerTool(
+        logsGetErrorsTool.name,
+        {
+            description: logsGetErrorsTool.description,
+            inputSchema: logsGetErrorsInputSchema,
+        },
+        (args: LogsGetErrorsInput) => {
+            return logsGetErrorsHandler(storage, args).then((r) => ({
+                content: [
+                    {
+                        type: "text" as const,
+                        text: JSON.stringify(r, null, 2),
+                    },
+                ],
+            }));
+        },
+    );
+    registeredTools.push(logsGetErrorsTool.name);
+
+    // Register logs_clear tool
+    server.registerTool(
+        logsClearTool.name,
+        {
+            description: logsClearTool.description,
+            inputSchema: logsClearInputSchema,
+        },
+        (args: LogsClearInput) => {
+            return logsClearHandler(storage, args).then((r) => ({
+                content: [
+                    {
+                        type: "text" as const,
+                        text: JSON.stringify(r, null, 2),
+                    },
+                ],
+            }));
+        },
+    );
+    registeredTools.push(logsClearTool.name);
+
+    // Register logs_search tool
+    server.registerTool(
+        logsSearchTool.name,
+        {
+            description: logsSearchTool.description,
+            inputSchema: logsSearchInputSchema,
+        },
+        (args: LogsSearchInput) => {
+            return logsSearchHandler(storage, args).then((r) => ({
+                content: [
+                    {
+                        type: "text" as const,
+                        text: JSON.stringify(r, null, 2),
+                    },
+                ],
+            }));
+        },
+    );
+    registeredTools.push(logsSearchTool.name);
+
+    // Register logs_get_file_path tool
+    server.registerTool(
+        logsGetFilePathTool.name,
+        {
+            description: logsGetFilePathTool.description,
+            inputSchema: logsGetFilePathInputSchema,
+        },
+        (args: LogsGetFilePathInput) => {
+            return logsGetFilePathHandler(storage, args).then((r) => ({
+                content: [
+                    {
+                        type: "text" as const,
+                        text: JSON.stringify(r, null, 2),
+                    },
+                ],
+            }));
+        },
+    );
+    registeredTools.push(logsGetFilePathTool.name);
+
+    return server;
+}
+
+/**
+ * Start the MCP server with STDIO transport.
+ *
+ * This function runs the MCP server and blocks until the connection is closed.
+ * @param storage - The LogStorage instance to use for log operations
+ */
+export async function startMcpServer(storage: LogStorage): Promise<void> {
+    const server = createMcpServer(storage);
+    const transport = new StdioServerTransport();
+
+    await server.connect(transport);
+
+    // Keep the process alive
+    // The connection will handle cleanup when stdin closes
+}

package/src/mcp/tools/index.ts

@@ -0,0 +1,69 @@
+/**
+ * MCP tool exports and registration.
+ * @module mcp/tools
+ */
+
+export {
+    logsClearHandler,
+    type LogsClearInput,
+    logsClearInputSchema,
+    type LogsClearOutput,
+    logsClearTool,
+} from "./logs-clear.js";
+export {
+    logsGetAllHandler,
+    type LogsGetAllInput,
+    logsGetAllInputSchema,
+    type LogsGetAllOutput,
+    logsGetAllTool,
+} from "./logs-get-all.js";
+export {
+    logsGetErrorsHandler,
+    type LogsGetErrorsInput,
+    logsGetErrorsInputSchema,
+    type LogsGetErrorsOutput,
+    logsGetErrorsTool,
+} from "./logs-get-errors.js";
+export {
+    getLogFilePath,
+    logsGetFilePathHandler,
+    type LogsGetFilePathInput,
+    logsGetFilePathInputSchema,
+    type LogsGetFilePathOutput,
+    logsGetFilePathTool,
+} from "./logs-get-file-path.js";
+export {
+    logsGetRecentHandler,
+    type LogsGetRecentInput,
+    logsGetRecentInputSchema,
+    type LogsGetRecentOutput,
+    logsGetRecentTool,
+} from "./logs-get-recent.js";
+export {
+    logsListSessionsHandler,
+    type LogsListSessionsInput,
+    logsListSessionsInputSchema,
+    type LogsListSessionsOutput,
+    logsListSessionsTool,
+} from "./logs-list-sessions.js";
+export {
+    logsReceiveHandler,
+    type LogsReceiveInput,
+    logsReceiveInputSchema,
+    type LogsReceiveOutput,
+    logsReceiveTool,
+} from "./logs-receive.js";
+export {
+    logsSearchHandler,
+    type LogsSearchInput,
+    logsSearchInputSchema,
+    type LogsSearchOutput,
+    logsSearchTool,
+} from "./logs-search.js";
+export {
+    logsStatusHandler,
+    type LogsStatusInput,
+    logsStatusInputSchema,
+    type LogsStatusOutput,
+    logsStatusTool,
+} from "./logs-status.js";

package/src/mcp/tools/logs-clear.ts

@@ -0,0 +1,86 @@
+/**
+ * logs_clear MCP tool implementation.
+ *
+ * Clears logs with confirmation requirement for safety.
+ * @module mcp/tools/logs-clear
+ */
+
+import * as z from "zod/v3";
+
+import type { LogStorage } from "../../server/log-storage.js";
+
+/**
+ * Input schema for the logs_clear tool.
+ */
+export const logsClearInputSchema = z.object({
+    /** Safety flag: must be set to true for the operation to proceed. Prevents accidental deletion. */
+    confirm: z.boolean().optional(),
+    /** Clear only logs for this project. Clears all projects if omitted. */
+    projectMarker: z.string().optional(),
+    /** Clear only logs for this specific session. Clears all sessions if omitted. */
+    sessionId: z.string().optional(),
+});
+
+/**
+ * Input type for the logs_clear handler.
+ */
+export type LogsClearInput = z.infer<typeof logsClearInputSchema>;
+
+/**
+ * Output type for the logs_clear handler.
+ */
+export interface LogsClearOutput {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Number of sessions cleared */
+    cleared: number;
+    /** Error message if operation failed */
+    error?: string;
+}
+
+/**
+ * Handler for the logs_clear tool.
+ *
+ * Clears logs with optional filtering. Requires explicit confirmation
+ * to prevent accidental data loss.
+ * @param storage - The log storage instance
+ * @param input - Input parameters
+ * @returns Success status and count of cleared sessions
+ */
+export function logsClearHandler(
+    storage: LogStorage,
+    input: Partial<LogsClearInput>,
+): Promise<LogsClearOutput> {
+    // Require explicit confirmation
+    if (input.confirm !== true) {
+        return Promise.resolve({
+            success: false,
+            cleared: 0,
+            error: "Operation requires confirm: true to proceed. This prevents accidental data loss.",
+        });
+    }
+
+    const result = storage.clearLogs({
+        projectMarker: input.projectMarker,
+        sessionId: input.sessionId,
+    });
+
+    return Promise.resolve({
+        success: true,
+        cleared: result.cleared,
+    });
+}
+
+/**
+ * Tool definition for MCP registration.
+ */
+export const logsClearTool = {
+    name: "logs_clear",
+    description:
+        "Clear logs from the server. " +
+        "Requires confirm: true to proceed - this prevents accidental data loss. " +
+        "Can optionally filter by projectMarker to clear only one project, " +
+        "or by sessionId to clear a specific session. " +
+        "Without filters, clears ALL logs.",
+    inputSchema: logsClearInputSchema,
+};

package/src/mcp/tools/logs-get-all.ts

@@ -0,0 +1,78 @@
+/**
+ * logs_get_all MCP tool implementation.
+ *
+ * Returns all logs grouped by session.
+ * @module mcp/tools/logs-get-all
+ */
+
+import * as z from "zod/v3";
+
+import type { LogEntry, LogStorage } from "../../server/log-storage.js";
+
+/**
+ * Input schema for the logs_get_all tool.
+ */
+export const logsGetAllInputSchema = z.object({
+    /** Filter results to a specific project identifier. Returns all projects if omitted. */
+    projectMarker: z.string().optional(),
+});
+
+/**
+ * Input type for the logs_get_all handler.
+ */
+export type LogsGetAllInput = z.infer<typeof logsGetAllInputSchema>;
+
+/**
+ * Output type for the logs_get_all handler.
+ */
+export interface LogsGetAllOutput {
+    /** Logs grouped by session ID */
+    sessions: Record<string, LogEntry[]>;
+    /** Number of sessions */
+    sessionCount: number;
+    /** Total number of logs across all sessions */
+    totalLogs: number;
+}
+
+/**
+ * Handler for the logs_get_all tool.
+ *
+ * Returns all logs grouped by session ID, with optional filtering by
+ * project marker.
+ * @param storage - The log storage instance
+ * @param input - Input parameters
+ * @returns Logs grouped by session
+ */
+export function logsGetAllHandler(
+    storage: LogStorage,
+    input: Partial<LogsGetAllInput>,
+): Promise<LogsGetAllOutput> {
+    const sessions = storage.getAllLogsBySession({
+        projectMarker: input.projectMarker,
+    });
+
+    // Calculate totals
+    let totalLogs = 0;
+    for (const logs of Object.values(sessions)) {
+        totalLogs += logs.length;
+    }
+
+    return Promise.resolve({
+        sessions,
+        sessionCount: Object.keys(sessions).length,
+        totalLogs,
+    });
+}
+
+/**
+ * Tool definition for MCP registration.
+ */
+export const logsGetAllTool = {
+    name: "logs_get_all",
+    description:
+        "Get all logs grouped by session. " +
+        "Use this to see a complete view of logging activity across all browser sessions. " +
+        "Returns logs organized by session ID, making it easy to trace activity per browser tab. " +
+        "For a flat list of recent logs, use logs_get_recent instead.",
+    inputSchema: logsGetAllInputSchema,
+};

package/src/mcp/tools/logs-get-errors.ts

@@ -0,0 +1,71 @@
+/**
+ * logs_get_errors MCP tool implementation.
+ *
+ * Returns only ERROR level logs.
+ * @module mcp/tools/logs-get-errors
+ */
+
+import * as z from "zod/v3";
+
+import type { LogEntryWithSession, LogStorage } from "../../server/log-storage.js";
+
+/**
+ * Input schema for the logs_get_errors tool.
+ */
+export const logsGetErrorsInputSchema = z.object({
+    /** Filter errors to a specific project identifier. Returns all projects if omitted. */
+    projectMarker: z.string().optional(),
+    /** Return only errors after this timestamp. Format: ISO 8601 (e.g., "2025-01-08T12:00:00Z"). */
+    since: z.string().optional(),
+});
+
+/**
+ * Input type for the logs_get_errors handler.
+ */
+export type LogsGetErrorsInput = z.infer<typeof logsGetErrorsInputSchema>;
+
+/**
+ * Output type for the logs_get_errors handler.
+ */
+export interface LogsGetErrorsOutput {
+    /** Array of ERROR level log entries */
+    errors: LogEntryWithSession[];
+    /** Number of errors returned */
+    count: number;
+}
+
+/**
+ * Handler for the logs_get_errors tool.
+ *
+ * Returns only ERROR level logs, sorted chronologically.
+ * @param storage - The log storage instance
+ * @param input - Input parameters
+ * @returns Error logs and count
+ */
+export function logsGetErrorsHandler(
+    storage: LogStorage,
+    input: Partial<LogsGetErrorsInput>,
+): Promise<LogsGetErrorsOutput> {
+    const errors = storage.getErrors({
+        projectMarker: input.projectMarker,
+        since: input.since,
+    });
+
+    return Promise.resolve({
+        errors,
+        count: errors.length,
+    });
+}
+
+/**
+ * Tool definition for MCP registration.
+ */
+export const logsGetErrorsTool = {
+    name: "logs_get_errors",
+    description:
+        "Get only ERROR level logs. " +
+        "Use this to quickly find error messages across all sessions. " +
+        "This is faster and more focused than logs_get_recent when you only need errors. " +
+        "Results are sorted chronologically.",
+    inputSchema: logsGetErrorsInputSchema,
+};