@graphty/remote-logger 0.0.1 → 1.2.0

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

@@ -0,0 +1,121 @@
+/**
+ * logs_get_file_path MCP tool implementation.
+ *
+ * Returns the path to the JSONL log file for a project.
+ * @module mcp/tools/logs-get-file-path
+ */
+
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import * as z from "zod/v3";
+
+import type { LogStorage } from "../../server/log-storage.js";
+import { resolveProjectMarker } from "../../server/marker-utils.js";
+
+/**
+ * Input schema for the logs_get_file_path tool.
+ */
+export const logsGetFilePathInputSchema = z.object({
+    /** Project identifier to get the log file for. Derived from workingDirectory if not provided. */
+    projectMarker: z.string().optional(),
+    /** Directory path to derive project marker from. Ignored if projectMarker is set. */
+    workingDirectory: z.string().optional(),
+});
+
+/**
+ * Input type for the logs_get_file_path handler.
+ */
+export type LogsGetFilePathInput = z.infer<typeof logsGetFilePathInputSchema>;
+
+/**
+ * Output type for the logs_get_file_path handler.
+ */
+export interface LogsGetFilePathOutput {
+    /** Full path to the JSONL log file */
+    path: string;
+    /** Whether the file exists */
+    exists: boolean;
+    /** File size in bytes (0 if file doesn't exist) */
+    size: number;
+}
+
+/**
+ * Get the default JSONL file path for a project marker.
+ * This is used when no JsonlWriter is configured.
+ * @param projectMarker - The project marker
+ * @returns Full path to the JSONL file
+ */
+export function getLogFilePath(projectMarker: string): string {
+    return path.join(os.tmpdir(), "remote-logger", projectMarker, "logs.jsonl");
+}
+
+/**
+ * Handler for the logs_get_file_path tool.
+ *
+ * Returns the path to the JSONL log file for the specified project.
+ * The file may not exist if no logs have been written yet.
+ * @param storage - The log storage instance
+ * @param input - Input parameters
+ * @returns File path, existence status, and size
+ */
+export function logsGetFilePathHandler(
+    storage: LogStorage,
+    input: Partial<LogsGetFilePathInput>,
+): Promise<LogsGetFilePathOutput> {
+    // Resolve project marker
+    const projectMarker = resolveProjectMarker({
+        projectMarker: input.projectMarker,
+        workingDirectory: input.workingDirectory,
+    });
+
+    // Get file path from JsonlWriter if available, otherwise use default
+    const jsonlWriter = storage.getJsonlWriter();
+    const filePath = jsonlWriter
+        ? jsonlWriter.getFilePath(projectMarker)
+        : getLogFilePath(projectMarker);
+
+    // Check if file exists and get stats
+    // Prefer JsonlWriter stats if available for consistency
+    if (jsonlWriter) {
+        const stats = jsonlWriter.getFileStats(projectMarker);
+        if (stats) {
+            return Promise.resolve({
+                path: filePath,
+                exists: stats.exists,
+                size: stats.size,
+            });
+        }
+    }
+
+    // Fall back to direct file system check
+    let exists = false;
+    let size = 0;
+
+    try {
+        const stats = fs.statSync(filePath);
+        exists = true;
+        ({ size } = stats);
+    } catch {
+        // File doesn't exist, use defaults
+    }
+
+    return Promise.resolve({
+        path: filePath,
+        exists,
+        size,
+    });
+}
+
+/**
+ * Tool definition for MCP registration.
+ */
+export const logsGetFilePathTool = {
+    name: "logs_get_file_path",
+    description:
+        "Get the file path to the JSONL log file for a project. " +
+        "Use this to access logs via file-based tools like Grep or Read. " +
+        "Each project has its own log file. " +
+        "The file may not exist if no logs have been written yet for that project.",
+    inputSchema: logsGetFilePathInputSchema,
+};

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

@@ -0,0 +1,104 @@
+/**
+ * logs_get_recent MCP tool implementation.
+ *
+ * Returns recent logs sorted by time with optional filtering.
+ * @module mcp/tools/logs-get-recent
+ */
+
+import * as z from "zod/v3";
+
+import type { LogEntryWithSession, LogFilter,LogStorage } from "../../server/log-storage.js";
+import { resolveProjectMarker } from "../../server/marker-utils.js";
+
+/**
+ * Input schema for the logs_get_recent tool.
+ * Note: We use a simple shape without .default() to be compatible with MCP SDK.
+ */
+export const logsGetRecentInputSchema = z.object({
+    /** Number of logs to return. Defaults to 50. Range: 1-500. */
+    count: z.number().int().min(1).max(500).optional(),
+    /** Filter logs to a specific project. Derived from workingDirectory if not provided. */
+    projectMarker: z.string().optional(),
+    /** Directory path to derive project marker from. Ignored if projectMarker is set. */
+    workingDirectory: z.string().optional(),
+    /** Filter by log level (e.g., "INFO", "ERROR", "DEBUG"). Case-sensitive. */
+    level: z.string().optional(),
+    /** Return only logs after this timestamp. Format: ISO 8601 (e.g., "2025-01-08T12:00:00Z"). */
+    since: z.string().optional(),
+});
+
+/**
+ * Input type for the logs_get_recent handler.
+ */
+export type LogsGetRecentInput = z.infer<typeof logsGetRecentInputSchema>;
+
+/**
+ * Output type for the logs_get_recent handler.
+ */
+export interface LogsGetRecentOutput {
+    logs: LogEntryWithSession[];
+    count: number;
+}
+
+/**
+ * Handler for the logs_get_recent tool.
+ *
+ * Returns recent logs sorted by time (oldest first), with optional filtering
+ * by project marker, level, or timestamp.
+ * @param storage - The log storage instance
+ * @param input - Input parameters
+ * @returns Recent logs and count
+ */
+export function logsGetRecentHandler(
+    storage: LogStorage,
+    input: Partial<LogsGetRecentInput>,
+): Promise<LogsGetRecentOutput> {
+    // Apply defaults
+    const requestedCount = input.count ?? 50;
+
+    // Resolve project marker from input
+    const projectMarker = resolveProjectMarker({
+        projectMarker: input.projectMarker,
+        workingDirectory: input.workingDirectory,
+    });
+
+    // Build filter
+    const filter: LogFilter = {};
+
+    if (projectMarker !== "default") {
+        filter.projectMarker = projectMarker;
+    }
+
+    if (input.level) {
+        filter.level = input.level;
+    }
+
+    if (input.since) {
+        filter.since = input.since;
+    }
+
+    // Ensure count doesn't exceed 500
+    const limitedCount = Math.min(requestedCount, 500);
+
+    // Get recent logs
+    const logs = storage.getRecentLogs(limitedCount, filter);
+
+    return Promise.resolve({
+        logs,
+        count: logs.length,
+    });
+}
+
+/**
+ * Tool definition for MCP registration.
+ */
+export const logsGetRecentTool = {
+    name: "logs_get_recent",
+    description:
+        "Get recent logs from the remote log server, sorted by time (oldest first). " +
+        "Use this to see the latest log output from browser applications. " +
+        "This is the primary tool for viewing logs. " +
+        "For error-only logs, use logs_get_errors instead. " +
+        "For searching specific text, use logs_search.",
+    inputSchema: logsGetRecentInputSchema,
+};

package/src/mcp/tools/logs-list-sessions.ts

@@ -0,0 +1,71 @@
+/**
+ * logs_list_sessions MCP tool implementation.
+ *
+ * Lists all logging sessions with their metadata.
+ * @module mcp/tools/logs-list-sessions
+ */
+
+import * as z from "zod/v3";
+
+import type { LogStorage, SessionMetadata } from "../../server/log-storage.js";
+
+/**
+ * Input schema for the logs_list_sessions tool.
+ */
+export const logsListSessionsInputSchema = z.object({
+    /** Filter sessions to a specific project identifier. */
+    projectMarker: z.string().optional(),
+    /** When true, only return sessions that contain error-level logs. */
+    hasErrors: z.boolean().optional(),
+});
+
+/**
+ * Input type for the logs_list_sessions handler.
+ */
+export type LogsListSessionsInput = z.infer<typeof logsListSessionsInputSchema>;
+
+/**
+ * Output type for the logs_list_sessions handler.
+ */
+export interface LogsListSessionsOutput {
+    sessions: SessionMetadata[];
+    count: number;
+}
+
+/**
+ * Handler for the logs_list_sessions tool.
+ *
+ * Lists all logging sessions with their metadata including project marker,
+ * log counts, error counts, and timestamps.
+ * @param storage - The log storage instance
+ * @param input - Input parameters
+ * @returns List of sessions and count
+ */
+export function logsListSessionsHandler(
+    storage: LogStorage,
+    input: Partial<LogsListSessionsInput>,
+): Promise<LogsListSessionsOutput> {
+    // Get sessions with filter
+    const sessions = storage.getSessions({
+        projectMarker: input.projectMarker,
+        hasErrors: input.hasErrors,
+    });
+
+    return Promise.resolve({
+        sessions,
+        count: sessions.length,
+    });
+}
+
+/**
+ * Tool definition for MCP registration.
+ */
+export const logsListSessionsTool = {
+    name: "logs_list_sessions",
+    description:
+        "List all logging sessions with their metadata. " +
+        "Each session represents a browser tab or application instance. " +
+        "Use this to discover active sessions before fetching their logs, " +
+        "or to find sessions with errors using the hasErrors filter.",
+    inputSchema: logsListSessionsInputSchema,
+};

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

@@ -0,0 +1,96 @@
+/**
+ * logs_receive MCP tool implementation.
+ *
+ * Stores logs with session metadata for later retrieval.
+ * @module mcp/tools/logs-receive
+ */
+
+import * as z from "zod/v3";
+
+import type { LogStorage } from "../../server/log-storage.js";
+
+/**
+ * Schema for a single log entry.
+ */
+const logEntrySchema = z.object({
+    /** When the log was created. Format: ISO 8601 (e.g., "2025-01-08T12:00:00Z"). */
+    time: z.string(),
+    /** Severity level (e.g., "INFO", "DEBUG", "WARN", "ERROR"). */
+    level: z.string(),
+    /** The log message text. */
+    message: z.string(),
+    /** Additional structured data to attach to the log entry. */
+    data: z.record(z.unknown()).optional(),
+});
+
+/**
+ * Input schema for the logs_receive tool.
+ */
+export const logsReceiveInputSchema = z.object({
+    /** Unique identifier for this logging session. Links related logs together. */
+    sessionId: z.string(),
+    /** Array of log entries to store. At least one entry required. */
+    logs: z.array(logEntrySchema),
+    /** Project identifier for filtering. Derived from sessionId prefix if not provided. */
+    projectMarker: z.string().optional(),
+    /** Git worktree path for project identification. */
+    worktreePath: z.string().optional(),
+    /** URL of the page that generated these logs. */
+    pageUrl: z.string().optional(),
+});
+
+/**
+ * Input type for the logs_receive handler.
+ */
+export type LogsReceiveInput = z.infer<typeof logsReceiveInputSchema>;
+
+/**
+ * Output type for the logs_receive handler.
+ */
+export interface LogsReceiveOutput {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Number of logs stored */
+    count: number;
+    /** The session ID used */
+    sessionId: string;
+}
+
+/**
+ * Handler for the logs_receive tool.
+ *
+ * Stores logs with session metadata. The project marker is derived from
+ * the session ID prefix if not explicitly provided.
+ * @param storage - The log storage instance
+ * @param input - Input parameters
+ * @returns Success status, count, and session ID
+ */
+export function logsReceiveHandler(
+    storage: LogStorage,
+    input: LogsReceiveInput,
+): Promise<LogsReceiveOutput> {
+    storage.addLogs(input.sessionId, input.logs, {
+        projectMarker: input.projectMarker,
+        worktreePath: input.worktreePath,
+        pageUrl: input.pageUrl,
+    });
+
+    return Promise.resolve({
+        success: true,
+        count: input.logs.length,
+        sessionId: input.sessionId,
+    });
+}
+
+/**
+ * Tool definition for MCP registration.
+ */
+export const logsReceiveTool = {
+    name: "logs_receive",
+    description:
+        "Store logs from a browser or application session. " +
+        "Logs are associated with a session ID and can be filtered by project marker. " +
+        "This tool is called by browser clients to send logs to the server. " +
+        "You typically don't need to call this directly - use it when manually testing log ingestion.",
+    inputSchema: logsReceiveInputSchema,
+};

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,
+};