@graphty/remote-logger 1.1.1 → 1.2.0

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

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