@graphty/remote-logger 1.1.1 → 1.2.0

package/dist/vite/plugin.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Vite plugin for automatic project marker injection.
+ *
+ * This plugin injects global variables that the RemoteLogClient
+ * can use to automatically identify which project/worktree logs
+ * are coming from.
+ * @module vite/plugin
+ */
+/**
+ * Vite plugin configuration object.
+ * Matches Vite's Plugin type but without requiring the full vite dependency.
+ */
+interface VitePlugin {
+    name: string;
+    config: () => {
+        define: Record<string, string>;
+    };
+}
+/**
+ * Creates a Vite plugin that injects project marker globals.
+ *
+ * The plugin detects the current working directory and:
+ * 1. Extracts a project marker (worktree name or directory basename)
+ * 2. Injects `__REMOTE_LOG_PROJECT_MARKER__` with the marker
+ * 3. Injects `__REMOTE_LOG_WORKTREE_PATH__` with the full path
+ *
+ * These globals are automatically read by RemoteLogClient when no
+ * explicit projectMarker/worktreePath options are provided.
+ * @returns A Vite plugin configuration object
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import { remoteLoggerPlugin } from "@graphty/remote-logger/vite";
+ *
+ * export default defineConfig({
+ *     plugins: [remoteLoggerPlugin()]
+ * });
+ * ```
+ */
+export declare function remoteLoggerPlugin(): VitePlugin;
+export {};
+//# sourceMappingURL=plugin.d.ts.map

package/dist/vite/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/vite/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;GAGG;AACH,UAAU,UAAU;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM;QACV,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAClC,CAAC;CACL;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,IAAI,UAAU,CAe/C"}

package/dist/vite/plugin.js

@@ -0,0 +1,46 @@
+/**
+ * Vite plugin for automatic project marker injection.
+ *
+ * This plugin injects global variables that the RemoteLogClient
+ * can use to automatically identify which project/worktree logs
+ * are coming from.
+ * @module vite/plugin
+ */
+import { extractMarkerFromPath } from "../server/marker-utils.js";
+/**
+ * Creates a Vite plugin that injects project marker globals.
+ *
+ * The plugin detects the current working directory and:
+ * 1. Extracts a project marker (worktree name or directory basename)
+ * 2. Injects `__REMOTE_LOG_PROJECT_MARKER__` with the marker
+ * 3. Injects `__REMOTE_LOG_WORKTREE_PATH__` with the full path
+ *
+ * These globals are automatically read by RemoteLogClient when no
+ * explicit projectMarker/worktreePath options are provided.
+ * @returns A Vite plugin configuration object
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import { remoteLoggerPlugin } from "@graphty/remote-logger/vite";
+ *
+ * export default defineConfig({
+ *     plugins: [remoteLoggerPlugin()]
+ * });
+ * ```
+ */
+export function remoteLoggerPlugin() {
+    return {
+        name: "remote-logger",
+        config() {
+            const cwd = process.cwd();
+            const marker = extractMarkerFromPath(cwd);
+            return {
+                define: {
+                    __REMOTE_LOG_PROJECT_MARKER__: JSON.stringify(marker),
+                    __REMOTE_LOG_WORKTREE_PATH__: JSON.stringify(cwd),
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=plugin.js.map

package/dist/vite/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/vite/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAalE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,kBAAkB;IAC9B,OAAO;QACH,IAAI,EAAE,eAAe;QACrB,MAAM;YACF,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;YAC1B,MAAM,MAAM,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;YAE1C,OAAO;gBACH,MAAM,EAAE;oBACJ,6BAA6B,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;oBACrD,4BAA4B,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC;iBACpD;aACJ,CAAC;QACN,CAAC;KACJ,CAAC;AACN,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/remote-logger",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Remote logging client and server for browser debugging",
   "author": "Adam Powers <apowers@ato.ms>",
   "main": "dist/index.js",
@@ -21,6 +21,14 @@
     "./ui": {
       "import": "./dist/ui/index.js",
       "types": "./dist/ui/index.d.ts"
+    },
+    "./mcp": {
+      "import": "./dist/mcp/index.js",
+      "types": "./dist/mcp/index.d.ts"
+    },
+    "./vite": {
+      "import": "./dist/vite/index.js",
+      "types": "./dist/vite/index.d.ts"
     }
   },
   "types": "dist/index.d.ts",
@@ -60,7 +68,9 @@
     "node": ">=18.19.0"
   },
   "dependencies": {
-    "selfsigned": "^2.4.1"
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "selfsigned": "^2.4.1",
+    "zod": "^3.25.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/client/RemoteLogClient.ts

@@ -6,6 +6,33 @@
 
 import type { LogEntry, RemoteLogClientOptions, ThrottlePattern } from "./types.js";
 
+/**
+ * Global variables that may be injected by the Vite plugin.
+ * These provide automatic project marker detection.
+ */
+declare const __REMOTE_LOG_PROJECT_MARKER__: string | undefined;
+declare const __REMOTE_LOG_WORKTREE_PATH__: string | undefined;
+
+/**
+ * Safely read a global variable that may or may not be defined.
+ * @param name - Name of the global variable
+ * @returns The value of the global variable, or undefined if not defined
+ */
+function getGlobalValue(name: "__REMOTE_LOG_PROJECT_MARKER__" | "__REMOTE_LOG_WORKTREE_PATH__"): string | undefined {
+    try {
+        if (name === "__REMOTE_LOG_PROJECT_MARKER__") {
+            return typeof __REMOTE_LOG_PROJECT_MARKER__ !== "undefined" ? __REMOTE_LOG_PROJECT_MARKER__ : undefined;
+        }
+        if (name === "__REMOTE_LOG_WORKTREE_PATH__") {
+            return typeof __REMOTE_LOG_WORKTREE_PATH__ !== "undefined" ? __REMOTE_LOG_WORKTREE_PATH__ : undefined;
+        }
+    } catch {
+        // ReferenceError if the global is not defined at all
+        return undefined;
+    }
+    return undefined;
+}
+
 /** Default configuration values */
 const DEFAULT_BATCH_INTERVAL_MS = 1000;
 const DEFAULT_MAX_RETRIES = 3;
@@ -57,6 +84,8 @@ export class RemoteLogClient {
     private readonly maxRetries: number;
     private readonly retryDelayMs: number;
     private readonly throttlePatterns: ThrottlePattern[];
+    private readonly projectMarker: string | undefined;
+    private readonly worktreePath: string | undefined;
 
     private pendingLogs: LogEntry[] = [];
     private batchTimer: ReturnType<typeof setTimeout> | null = null;
@@ -77,6 +106,10 @@ export class RemoteLogClient {
         this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
         this.retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
         this.throttlePatterns = options.throttlePatterns ?? [];
+
+        // Priority: explicit option > global variable
+        this.projectMarker = options.projectMarker ?? getGlobalValue("__REMOTE_LOG_PROJECT_MARKER__");
+        this.worktreePath = options.worktreePath ?? getGlobalValue("__REMOTE_LOG_WORKTREE_PATH__");
     }
 
     /**
@@ -199,15 +232,30 @@ export class RemoteLogClient {
      * @throws Error if the request fails
      */
     private async sendRequest(logs: LogEntry[]): Promise<void> {
+        const requestBody: {
+            sessionId: string;
+            logs: LogEntry[];
+            projectMarker?: string;
+            worktreePath?: string;
+        } = {
+            sessionId: this.sessionId,
+            logs,
+        };
+
+        // Only include these fields if they have values
+        if (this.projectMarker !== undefined) {
+            requestBody.projectMarker = this.projectMarker;
+        }
+        if (this.worktreePath !== undefined) {
+            requestBody.worktreePath = this.worktreePath;
+        }
+
         const response = await fetch(`${this.serverUrl}/log`, {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
             },
-            body: JSON.stringify({
-                sessionId: this.sessionId,
-                logs,
-            }),
+            body: JSON.stringify(requestBody),
         });
 
         if (!response.ok) {

package/src/client/types.ts

@@ -46,4 +46,17 @@ export interface RemoteLogClientOptions {
      * Messages matching a pattern will only be sent once per the configured interval.
      */
     throttlePatterns?: ThrottlePattern[];
+    /**
+     * Project marker to identify logs from this project.
+     * If not provided, the client will attempt to read from the
+     * __REMOTE_LOG_PROJECT_MARKER__ global variable (injected by Vite plugin).
+     */
+    projectMarker?: string;
+    /**
+     * Full path to the worktree or project directory.
+     * Used for debugging and log organization.
+     * If not provided, the client will attempt to read from the
+     * __REMOTE_LOG_WORKTREE_PATH__ global variable (injected by Vite plugin).
+     */
+    worktreePath?: string;
 }

package/src/mcp/index.ts

@@ -0,0 +1,25 @@
+/**
+ * MCP server module exports.
+ *
+ * Provides Model Context Protocol interface for log queries.
+ * @module mcp
+ */
+
+export { createMcpServer, getToolNames, startMcpServer } from "./mcp-server.js";
+export {
+    logsGetRecentHandler,
+    type LogsGetRecentInput,
+    logsGetRecentInputSchema,
+    type LogsGetRecentOutput,
+    logsGetRecentTool,
+    logsListSessionsHandler,
+    type LogsListSessionsInput,
+    logsListSessionsInputSchema,
+    type LogsListSessionsOutput,
+    logsListSessionsTool,
+    logsStatusHandler,
+    type LogsStatusInput,
+    logsStatusInputSchema,
+    type LogsStatusOutput,
+    logsStatusTool,
+} from "./tools/index.js";

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";