@graphty/remote-logger 1.2.2 → 1.3.0

package/src/client/RemoteLogClient.ts

@@ -38,6 +38,7 @@ const DEFAULT_BATCH_INTERVAL_MS = 1000;
 const DEFAULT_MAX_RETRIES = 3;
 const DEFAULT_RETRY_DELAY_MS = 1000;
 const DEFAULT_SESSION_PREFIX = "session";
+const DEFAULT_TIMEOUT_MS = 5000;
 
 /**
  * Generates a unique session ID with the given prefix.
@@ -86,6 +87,7 @@ export class RemoteLogClient {
     private readonly throttlePatterns: ThrottlePattern[];
     private readonly projectMarker: string | undefined;
     private readonly worktreePath: string | undefined;
+    private readonly timeoutMs: number;
 
     private pendingLogs: LogEntry[] = [];
     private batchTimer: ReturnType<typeof setTimeout> | null = null;
@@ -106,6 +108,7 @@ export class RemoteLogClient {
         this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
         this.retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
         this.throttlePatterns = options.throttlePatterns ?? [];
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
 
         // Priority: explicit option > global variable
         this.projectMarker = options.projectMarker ?? getGlobalValue("__REMOTE_LOG_PROJECT_MARKER__");
@@ -229,7 +232,7 @@ export class RemoteLogClient {
     /**
      * Makes the actual HTTP request to send logs.
      * @param logs - The log entries to send
-     * @throws Error if the request fails
+     * @throws Error if the request fails or times out
      */
     private async sendRequest(logs: LogEntry[]): Promise<void> {
         const requestBody: {
@@ -250,16 +253,24 @@ export class RemoteLogClient {
             requestBody.worktreePath = this.worktreePath;
         }
 
-        const response = await fetch(`${this.serverUrl}/log`, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify(requestBody),
-        });
-
-        if (!response.ok) {
-            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => { controller.abort(); }, this.timeoutMs);
+
+        try {
+            const response = await fetch(`${this.serverUrl}/log`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(requestBody),
+                signal: controller.signal,
+            });
+
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+        } finally {
+            clearTimeout(timeoutId);
         }
     }
 

package/src/client/types.ts

@@ -59,4 +59,10 @@ export interface RemoteLogClientOptions {
      * __REMOTE_LOG_WORKTREE_PATH__ global variable (injected by Vite plugin).
      */
     worktreePath?: string;
+    /**
+     * Request timeout in milliseconds.
+     * Requests that take longer than this will be aborted and retried.
+     * @default 5000
+     */
+    timeoutMs?: number;
 }

package/src/mcp/index.ts

@@ -6,17 +6,59 @@
  */
 
 export { createMcpServer, getToolNames, startMcpServer } from "./mcp-server.js";
+
+// Re-export all tool handlers, schemas, and definitions for programmatic use
 export {
+    // logs_get_file_path
+    getLogFilePath,
+    // logs_clear
+    logsClearHandler,
+    type LogsClearInput,
+    logsClearInputSchema,
+    type LogsClearOutput,
+    logsClearTool,
+    // logs_get_all
+    logsGetAllHandler,
+    type LogsGetAllInput,
+    logsGetAllInputSchema,
+    type LogsGetAllOutput,
+    logsGetAllTool,
+    // logs_get_errors
+    logsGetErrorsHandler,
+    type LogsGetErrorsInput,
+    logsGetErrorsInputSchema,
+    type LogsGetErrorsOutput,
+    logsGetErrorsTool,
+    logsGetFilePathHandler,
+    type LogsGetFilePathInput,
+    logsGetFilePathInputSchema,
+    type LogsGetFilePathOutput,
+    logsGetFilePathTool,
+    // logs_get_recent
     logsGetRecentHandler,
     type LogsGetRecentInput,
     logsGetRecentInputSchema,
     type LogsGetRecentOutput,
     logsGetRecentTool,
+    // logs_list_sessions
     logsListSessionsHandler,
     type LogsListSessionsInput,
     logsListSessionsInputSchema,
     type LogsListSessionsOutput,
     logsListSessionsTool,
+    // logs_receive
+    logsReceiveHandler,
+    type LogsReceiveInput,
+    logsReceiveInputSchema,
+    type LogsReceiveOutput,
+    logsReceiveTool,
+    // logs_search
+    logsSearchHandler,
+    type LogsSearchInput,
+    logsSearchInputSchema,
+    type LogsSearchOutput,
+    logsSearchTool,
+    // logs_status
     logsStatusHandler,
     type LogsStatusInput,
     logsStatusInputSchema,

package/src/mcp/mcp-server.ts

@@ -61,8 +61,9 @@ export function getToolNames(): string[] {
 
 /**
  * Server instructions for LLMs describing the overall purpose and usage.
+ * Exported for testing purposes.
  */
-const SERVER_INSTRUCTIONS = `Remote Logger MCP Server - View console.log output from browser applications.
+export const SERVER_INSTRUCTIONS = `Remote Logger MCP Server - View console.log output from browser applications.
 
 ## What is Remote Logging?
 
@@ -82,7 +83,7 @@ Remote logging is especially valuable for LLM assistants like this one - it enab
 
 ## Architecture
 
-Browser App → HTTP POST to /logs → Log Server (stores in memory + JSONL files) → MCP Tools (query logs)
+Browser App → HTTP POST to /log → Log Server (stores in memory + JSONL files) → MCP Tools (query logs)
 
 ## Setting Up a Browser App to Send Logs
 
@@ -96,8 +97,8 @@ Install: npm install @graphty/remote-logger
 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
+  serverUrl: "http://localhost:9080",  // Get this from logs_status (client appends /log)
+  projectMarker: "my-project",          // Optional: for filtering
 });
 
 // Intercept all console.log/warn/error calls
@@ -107,10 +108,32 @@ logger.interceptConsole();
 logger.log("INFO", "Hello from browser!");
 \`\`\`
 
-### Option 2: Raw fetch() calls
+### Option 2: Script tag (zero install)
+
+The server serves a browser-ready script that auto-configures itself.
+Get the script URL from logs_status - look for server.scriptUrl in the response.
+
+Add to HTML:
+\`\`\`html
+<script src="http://localhost:9080/remote-logger.js"></script>
+\`\`\`
+
+Or paste in browser console:
+\`\`\`javascript
+var s=document.createElement('script');s.src='http://localhost:9080/remote-logger.js';document.head.appendChild(s);
+\`\`\`
+
+The script automatically:
+- Intercepts all console.log/warn/error/info/debug calls
+- Sends them to the server it was loaded from (zero config)
+- Exposes window.__remoteLogger__ for manual control (e.g., window.__remoteLogger__.destroy())
+
+Add ?ui=true to the script URL to show a floating console capture widget.
+
+### Option 3: Raw fetch() calls
 
 \`\`\`typescript
-fetch("http://localhost:9080/logs", {
+fetch("http://localhost:9080/log", {
   method: "POST",
   headers: { "Content-Type": "application/json" },
   body: JSON.stringify({
@@ -122,6 +145,28 @@ fetch("http://localhost:9080/logs", {
 });
 \`\`\`
 
+## Debugging Third-Party Websites
+
+The server includes a reverse proxy that injects the remote logger into any website.
+Get the proxy base URL from logs_status - look for server.proxyBaseUrl.
+
+To debug a third-party site, prepend the proxy base URL to the target URL:
+  {proxyBaseUrl}https://example.com/page
+
+Example: http://192.168.1.x:9080/proxy/https://example.com
+
+The proxy automatically:
+- Injects the remote-logger script into HTML responses
+- Strips Content-Security-Policy headers that would block the script
+- Forwards cookies, auth headers, and other request data
+- Passes non-HTML resources (CSS, JS, images) through unmodified
+
+Limitations:
+- Resources using absolute paths (e.g., /fonts/..., /media/...) bypass the base tag and return 404
+- JavaScript fetch() calls using absolute paths may bypass the proxy
+- OAuth redirect flows that check the origin domain will not work
+- WebSocket connections are not proxied (future enhancement)
+
 ## Querying Logs (MCP Tools)
 
 Once browser logs are flowing to the server:
@@ -137,8 +182,9 @@ Once browser logs are flowing to the server:
 
 ## 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
+1. Call logs_status to verify server is running and get the endpoint URL, script URL, and proxy URL
+2. Add logging to the browser app using one of the options above (script tag is simplest)
+   - For third-party sites, use the proxy: navigate to {proxyBaseUrl}https://target-site.com
 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`;

package/src/mcp/tools/index.ts

@@ -7,24 +7,29 @@ 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 {
@@ -45,12 +50,14 @@ 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 {

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

@@ -29,7 +29,7 @@ export type LogsClearInput = z.infer<typeof logsClearInputSchema>;
 /**
  * Output type for the logs_clear handler.
  */
-interface LogsClearOutput {
+export interface LogsClearOutput {
     /** Whether the operation succeeded */
     success: boolean;
     /** Number of sessions cleared */

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

@@ -25,7 +25,7 @@ export type LogsGetAllInput = z.infer<typeof logsGetAllInputSchema>;
 /**
  * Output type for the logs_get_all handler.
  */
-interface LogsGetAllOutput {
+export interface LogsGetAllOutput {
     /** Logs grouped by session ID */
     sessions: Record<string, LogEntry[]>;
     /** Number of sessions */

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

@@ -27,7 +27,7 @@ export type LogsGetErrorsInput = z.infer<typeof logsGetErrorsInputSchema>;
 /**
  * Output type for the logs_get_errors handler.
  */
-interface LogsGetErrorsOutput {
+export interface LogsGetErrorsOutput {
     /** Array of ERROR level log entries */
     errors: LogEntryWithSession[];
     /** Number of errors returned */

package/src/mcp/tools/logs-get-file-path.ts

@@ -31,7 +31,7 @@ export type LogsGetFilePathInput = z.infer<typeof logsGetFilePathInputSchema>;
 /**
  * Output type for the logs_get_file_path handler.
  */
-interface LogsGetFilePathOutput {
+export interface LogsGetFilePathOutput {
     /** Full path to the JSONL log file */
     path: string;
     /** Whether the file exists */
@@ -46,7 +46,7 @@ interface LogsGetFilePathOutput {
  * @param projectMarker - The project marker
  * @returns Full path to the JSONL file
  */
-function getLogFilePath(projectMarker: string): string {
+export function getLogFilePath(projectMarker: string): string {
     return path.join(os.tmpdir(), "remote-logger", projectMarker, "logs.jsonl");
 }
 

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

@@ -47,7 +47,7 @@ export type LogsReceiveInput = z.infer<typeof logsReceiveInputSchema>;
 /**
  * Output type for the logs_receive handler.
  */
-interface LogsReceiveOutput {
+export interface LogsReceiveOutput {
     /** Whether the operation succeeded */
     success: boolean;
     /** Number of logs stored */

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

@@ -33,7 +33,7 @@ export type LogsSearchInput = z.infer<typeof logsSearchInputSchema>;
 /**
  * Output type for the logs_search handler.
  */
-interface LogsSearchOutput {
+export interface LogsSearchOutput {
     /** Matching log entries */
     results: LogEntryWithSession[];
     /** Number of results returned */

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

@@ -61,9 +61,12 @@ export const logsStatusTool = {
     description:
         "Get the status of the remote log server. " +
         "Returns health metrics (uptime, session count, log count, memory usage), " +
-        "HTTP endpoint configuration (port, host, URL for browser clients), " +
+        "HTTP endpoint configuration (port, host, URL for browser clients, script URL for zero-config injection, " +
+        "proxy base URL for debugging third-party sites), " +
         "and retention settings (how long logs are kept before automatic cleanup). " +
         "Use this to verify the server is running, find the endpoint URL for configuring browser clients, " +
+        "get the script URL (server.scriptUrl) for injecting via a script tag, " +
+        "get the proxy URL (server.proxyBaseUrl) for debugging third-party sites, " +
         "or check server configuration.",
     inputSchema: logsStatusInputSchema,
 };