@graphty/remote-logger 1.1.1 → 1.2.0

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

@@ -0,0 +1,95 @@
+/**
+ * logs_search MCP tool implementation.
+ *
+ * Searches logs by substring or regex pattern.
+ * @module mcp/tools/logs-search
+ */
+
+import * as z from "zod/v3";
+
+import type { LogEntryWithSession, LogStorage } from "../../server/log-storage.js";
+
+/**
+ * Input schema for the logs_search tool.
+ */
+export const logsSearchInputSchema = z.object({
+    /** The text pattern to search for in log messages. */
+    query: z.string(),
+    /** When true, treat query as a regular expression. Default: false (substring match). */
+    regex: z.boolean().optional(),
+    /** Filter results to a specific project identifier. Searches all projects if omitted. */
+    projectMarker: z.string().optional(),
+    /** Filter by log level (e.g., "INFO", "ERROR"). Case-sensitive. */
+    level: z.string().optional(),
+    /** Maximum number of results to return. Defaults to 100. Range: 1-1000. */
+    limit: z.number().int().min(1).max(1000).optional(),
+});
+
+/**
+ * Input type for the logs_search handler.
+ */
+export type LogsSearchInput = z.infer<typeof logsSearchInputSchema>;
+
+/**
+ * Output type for the logs_search handler.
+ */
+export interface LogsSearchOutput {
+    /** Matching log entries */
+    results: LogEntryWithSession[];
+    /** Number of results returned */
+    count: number;
+    /** Error message if regex is invalid */
+    error?: string;
+}
+
+/**
+ * Handler for the logs_search tool.
+ *
+ * Searches log messages by substring (case-insensitive) or regex pattern.
+ * @param storage - The log storage instance
+ * @param input - Input parameters
+ * @returns Matching logs and count
+ */
+export function logsSearchHandler(
+    storage: LogStorage,
+    input: LogsSearchInput,
+): Promise<LogsSearchOutput> {
+    // Validate regex if provided
+    if (input.regex) {
+        try {
+            new RegExp(input.query);
+        } catch {
+            return Promise.resolve({
+                results: [],
+                count: 0,
+                error: `Invalid regex pattern: "${input.query}"`,
+            });
+        }
+    }
+
+    const results = storage.search({
+        query: input.query,
+        regex: input.regex,
+        projectMarker: input.projectMarker,
+        level: input.level,
+        limit: input.limit ?? 100,
+    });
+
+    return Promise.resolve({
+        results,
+        count: results.length,
+    });
+}
+
+/**
+ * Tool definition for MCP registration.
+ */
+export const logsSearchTool = {
+    name: "logs_search",
+    description:
+        "Search logs by text pattern. " +
+        "By default, searches are case-insensitive substrings (e.g., 'error' matches 'TypeError'). " +
+        "Use regex: true for regex patterns (e.g., 'user:\\d+' to match 'user:123'). " +
+        "More flexible than logs_get_errors when you need to find specific messages.",
+    inputSchema: logsSearchInputSchema,
+};

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

@@ -0,0 +1,69 @@
+/**
+ * logs_status MCP tool implementation.
+ *
+ * Returns server status including health metrics and HTTP endpoint configuration.
+ * @module mcp/tools/logs-status
+ */
+
+import * as z from "zod/v3";
+
+import type { LogStorage, ServerStatus } from "../../server/log-storage.js";
+
+/**
+ * Input schema for the logs_status tool.
+ */
+export const logsStatusInputSchema = z.object({});
+
+/**
+ * Input type for the logs_status handler.
+ */
+export type LogsStatusInput = z.infer<typeof logsStatusInputSchema>;
+
+/**
+ * Output type for the logs_status handler.
+ */
+export interface LogsStatusOutput extends ServerStatus {
+    /** Memory usage information */
+    memoryUsage: {
+        heapUsed: number;
+        heapTotal: number;
+        rss: number;
+    };
+}
+
+/**
+ * Handler for the logs_status tool.
+ *
+ * Returns the full status of the log server, including health metrics,
+ * HTTP endpoint configuration, and memory usage.
+ * @param storage - The log storage instance
+ * @returns Server status object
+ */
+export function logsStatusHandler(storage: LogStorage): Promise<LogsStatusOutput> {
+    const status = storage.getStatus();
+    const memUsage = process.memoryUsage();
+
+    return Promise.resolve({
+        ...status,
+        memoryUsage: {
+            heapUsed: memUsage.heapUsed,
+            heapTotal: memUsage.heapTotal,
+            rss: memUsage.rss,
+        },
+    });
+}
+
+/**
+ * Tool definition for MCP registration.
+ */
+export const logsStatusTool = {
+    name: "logs_status",
+    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), " +
+        "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, " +
+        "or check server configuration.",
+    inputSchema: logsStatusInputSchema,
+};

package/src/server/dual-server.ts

@@ -0,0 +1,308 @@
+/**
+ * Dual server orchestration for running HTTP and MCP interfaces simultaneously.
+ *
+ * This module provides a unified way to start both HTTP and MCP servers
+ * that share the same log storage instance.
+ * @module server/dual-server
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import type * as http from "http";
+import type * as https from "https";
+import * as net from "net";
+import * as os from "os";
+import * as path from "path";
+
+import { createMcpServer } from "../mcp/mcp-server.js";
+import { JsonlWriter } from "./jsonl-writer.js";
+import { createLogServer } from "./log-server.js";
+import { LogStorage, type ServerMode } from "./log-storage.js";
+import { certFilesExist } from "./self-signed-cert.js";
+
+// ANSI color codes for terminal output
+const colors = {
+    reset: "\x1b[0m",
+    yellow: "\x1b[33m",
+    red: "\x1b[31m",
+    green: "\x1b[32m",
+    cyan: "\x1b[36m",
+};
+
+/** Maximum number of ports to try when scanning for available port */
+const MAX_PORT_SCAN_ATTEMPTS = 100;
+
+/** Maximum port number allowed (ports 9000-9099 per project guidelines) */
+const MAX_PORT_NUMBER = 9099;
+
+/**
+ * Check if a port is available for binding.
+ * @param port - Port number to check
+ * @param host - Host to bind to
+ * @returns Promise resolving to true if port is available, false otherwise
+ */
+async function isPortAvailable(port: number, host: string): Promise<boolean> {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+
+        // Enable SO_REUSEADDR to allow faster port reuse after server shutdown
+        server.once("error", (err: NodeJS.ErrnoException) => {
+            if (err.code === "EADDRINUSE") {
+                resolve(false);
+            } else {
+                // Other errors (permission, etc.) - port is not usable
+                resolve(false);
+            }
+        });
+
+        server.once("listening", () => {
+            server.close(() => {
+                resolve(true);
+            });
+        });
+
+        // Set SO_REUSEADDR before binding
+        server.listen({ port, host, exclusive: false });
+    });
+}
+
+/**
+ * Find an available port starting from the given base port.
+ * Increments port number until an available port is found.
+ * @param basePort - Starting port number
+ * @param host - Host to bind to
+ * @param quiet - Suppress output messages
+ * @returns Promise resolving to available port number
+ * @throws Error if no available port found within MAX_PORT_SCAN_ATTEMPTS
+ */
+export async function findAvailablePort(basePort: number, host: string, quiet: boolean = false): Promise<number> {
+    let port = basePort;
+    let attempts = 0;
+
+    while (attempts < MAX_PORT_SCAN_ATTEMPTS) {
+        if (port > MAX_PORT_NUMBER) {
+            // Wrap around if we exceed max port (shouldn't happen normally)
+            break;
+        }
+
+        if (await isPortAvailable(port, host)) {
+            if (port !== basePort && !quiet) {
+                // eslint-disable-next-line no-console
+                console.log(
+                    `${colors.yellow}Port ${basePort} in use, using port ${port} instead${colors.reset}`,
+                );
+            }
+            return port;
+        }
+
+        if (!quiet && attempts === 0) {
+            // eslint-disable-next-line no-console
+            console.log(
+                `${colors.yellow}Port ${port} is already in use, scanning for available port...${colors.reset}`,
+            );
+        }
+
+        port++;
+        attempts++;
+    }
+
+    // No available port found
+    const errorMsg = `Could not find available port after ${MAX_PORT_SCAN_ATTEMPTS} attempts starting from ${basePort}. ` +
+        `Ports ${basePort}-${port - 1} are all in use. ` +
+        `Try killing existing processes: pkill -f "remote-log-server"`;
+
+    if (!quiet) {
+         
+        console.error(`${colors.red}${errorMsg}${colors.reset}`);
+    }
+
+    throw new Error(errorMsg);
+}
+
+/**
+ * Options for creating a dual server.
+ */
+export interface DualServerOptions {
+    /** Port for HTTP server (default: 9080) */
+    httpPort?: number;
+    /** Host for HTTP server (default: localhost) */
+    httpHost?: string;
+    /** Enable MCP server (default: true) */
+    mcpEnabled?: boolean;
+    /** Enable HTTP server (default: true) */
+    httpEnabled?: boolean;
+    /** Suppress terminal output (default: false) */
+    quiet?: boolean;
+    /** Path to SSL certificate file (HTTPS only used if both certPath and keyPath provided) */
+    certPath?: string;
+    /** Path to SSL private key file (HTTPS only used if both certPath and keyPath provided) */
+    keyPath?: string;
+    /** Path to file for writing logs (optional) */
+    logFile?: string;
+    /** External LogStorage instance (optional, will create one if not provided) */
+    storage?: LogStorage;
+    /** External JSONL writer instance (optional, will create one if not provided) */
+    jsonlWriter?: JsonlWriter;
+    /** Only serve /log POST and /health GET endpoints (default: false) */
+    logReceiveOnly?: boolean;
+}
+
+/**
+ * Result of creating a dual server.
+ */
+export interface DualServerResult {
+    /** HTTP or HTTPS server instance (if httpEnabled) */
+    httpServer?: http.Server | https.Server;
+    /** MCP server instance (if mcpEnabled) */
+    mcpServer?: McpServer;
+    /** Shared log storage instance */
+    storage: LogStorage;
+    /** JSONL writer instance */
+    jsonlWriter?: JsonlWriter;
+    /** Actual HTTP port used (may differ from requested if port was in use) */
+    httpPort?: number;
+    /** Graceful shutdown function */
+    shutdown: () => Promise<void>;
+}
+
+/**
+ * Create and start a dual server with HTTP and/or MCP interfaces.
+ *
+ * By default, both HTTP and MCP are enabled. Use httpEnabled/mcpEnabled
+ * to control which interfaces to start.
+ * @param options - Server configuration options
+ * @returns Promise resolving to the dual server result
+ */
+export async function createDualServer(options: DualServerOptions = {}): Promise<DualServerResult> {
+    const {
+        httpPort: requestedPort = 9080,
+        httpHost = "localhost",
+        mcpEnabled = true,
+        httpEnabled = true,
+        quiet = false,
+        storage: externalStorage,
+        jsonlWriter: externalJsonlWriter,
+        logReceiveOnly = false,
+        certPath,
+        keyPath,
+    } = options;
+
+    // Create or use provided JSONL writer
+    const jsonlBaseDir = path.join(os.tmpdir(), "remote-logger");
+    const jsonlWriter = externalJsonlWriter ?? new JsonlWriter(jsonlBaseDir);
+
+    // Create or use provided storage
+    const storage = externalStorage ?? new LogStorage({ jsonlWriter });
+
+    let httpServer: http.Server | https.Server | undefined;
+    let mcpServer: McpServer | undefined;
+    let actualHttpPort: number | undefined;
+
+    // Start HTTP server if enabled
+    if (httpEnabled) {
+        // Find an available port starting from the requested port
+        actualHttpPort = await findAvailablePort(requestedPort, httpHost, quiet);
+
+        const result = createLogServer({
+            port: actualHttpPort,
+            host: httpHost,
+            storage,
+            quiet,
+            logReceiveOnly,
+            certPath,
+            keyPath,
+        });
+        httpServer = result.server;
+
+        // Wait for HTTP server to be listening
+        const serverToStart = httpServer;
+        const portToUse = actualHttpPort;
+        await new Promise<void>((resolve, reject) => {
+            serverToStart.on("error", (err: NodeJS.ErrnoException) => {
+                // Provide helpful error message for port conflicts
+                if (err.code === "EADDRINUSE") {
+                    const errorMsg = `Port ${portToUse} is already in use. ` +
+                        `This shouldn't happen after port scanning - there may be a race condition. ` +
+                        `Try again or kill existing processes: pkill -f "remote-log-server"`;
+                    if (!quiet) {
+                         
+                        console.error(`${colors.red}${errorMsg}${colors.reset}`);
+                    }
+                    reject(new Error(errorMsg));
+                } else {
+                    reject(err);
+                }
+            });
+            serverToStart.listen({ port: portToUse, host: httpHost, exclusive: false }, () => {
+                serverToStart.removeListener("error", reject);
+                if (!quiet) {
+                    // eslint-disable-next-line no-console
+                    console.log(
+                        `${colors.green}HTTP server listening on ${httpHost}:${portToUse}${colors.reset}`,
+                    );
+                }
+                resolve();
+            });
+        });
+
+        // Set server config in storage so MCP tools can report it
+        // Determine protocol based on whether valid cert files were provided
+        const useHttps = certPath && keyPath && certFilesExist(certPath, keyPath);
+        const protocol = useHttps ? "https" : "http";
+        // Determine mode based on configuration
+        let mode: ServerMode;
+        if (logReceiveOnly && mcpEnabled) {
+            mode = "mcp-only";
+        } else if (!mcpEnabled) {
+            mode = "http-only";
+        } else {
+            mode = "dual";
+        }
+        storage.setServerConfig({
+            httpPort: actualHttpPort,
+            httpHost,
+            protocol,
+            httpEndpoint: `${protocol}://${httpHost}:${actualHttpPort}/log`,
+            mode,
+        });
+    }
+
+    // Create and connect MCP server if enabled
+    if (mcpEnabled) {
+        mcpServer = createMcpServer(storage);
+        const transport = new StdioServerTransport();
+        await mcpServer.connect(transport);
+    }
+
+    // Track if we created the JSONL writer internally
+    const ownsJsonlWriter = !externalJsonlWriter;
+
+    // Shutdown function
+    const shutdown = async (): Promise<void> => {
+        // Close HTTP server
+        if (httpServer?.listening) {
+            await new Promise<void>((resolve) => {
+                httpServer.close(() => { resolve(); });
+            });
+        }
+
+        // Close JSONL writer only if we created it internally
+        if (ownsJsonlWriter) {
+            await jsonlWriter.close();
+        }
+
+        // Stop cleanup timer if storage was created internally
+        if (!externalStorage) {
+            storage.stopCleanupTimer();
+        }
+    };
+
+    return {
+        httpServer,
+        mcpServer,
+        storage,
+        jsonlWriter,
+        httpPort: actualHttpPort,
+        shutdown,
+    };
+}

package/src/server/index.ts

@@ -4,14 +4,51 @@
  * @module server
  */
 
+export {
+    createDualServer,
+    type DualServerOptions,
+    type DualServerResult,
+} from "./dual-server.js";
+export {
+    type FileStats,
+    type JsonlEntry,
+    JsonlWriter,
+} from "./jsonl-writer.js";
 export {
     clearLogs,
+    createLogServer,
+    type CreateLogServerOptions,
+    type CreateLogServerResult,
+    getJsonlWriter,
+    getLogStorage,
     HELP_TEXT,
     type LogEntry,
     type LogServerOptions,
     main,
     parseArgs,
     type ParseArgsResult,
+    setLogStorage,
     startLogServer,
 } from "./log-server.js";
+export {
+    type AddLogsOptions,
+    type ClearFilter,
+    type HealthStatus,
+    type LogEntryWithSession,
+    type LogFilter,
+    LogStorage,
+    type LogStorageOptions,
+    type SearchOptions,
+    type ServerConfig,
+    type ServerMode,
+    type ServerStatus,
+    type SessionFilter,
+    type SessionMetadata,
+} from "./log-storage.js";
+export {
+    extractMarkerFromPath,
+    extractMarkerFromSessionId,
+    type MarkerResolutionOptions,
+    resolveProjectMarker,
+} from "./marker-utils.js";
 export { certFilesExist, type GeneratedCert, generateSelfSignedCert, readCertFiles } from "./self-signed-cert.js";