refactor: streamline log management and server error handling

- Refactored the `LogStore` class by removing baseline timestamp management to simplify log clearing operations.
- Updated the `clearLogs` tool to enforce hard clearing of logs, removing the scope parameter.
- Enhanced the `getLogs` tool by removing auto-baseline and stacked mode options, improving clarity in log retrieval.
- Added informative messages for users when no logs are found, suggesting available projects for better user experience.
- Improved error handling in the MCP server to better manage port conflicts during server startup.

Author: regenrek

packages/mcp/src/schemas/logs.ts

@@ -8,14 +8,11 @@ export const GetLogsArgs = {
   limit: z.number().int().min(1).max(5000).optional().describe('Max number of entries to return'),
   contains: z.string().optional().describe('Substring filter on entry.text'),
   sinceMs: z.number().nonnegative().optional().describe('Only entries with time >= sinceMs'),
-  project: z.string().optional().describe('Project name to filter logs'),
-  autoBaseline: z.boolean().optional().default(true).describe('Automatically baseline after retrieval to show only new logs next time'),
-  stackedMode: z.boolean().optional().default(false).describe('Disable auto-baseline to accumulate logs across calls')
+  project: z.string().optional().describe('Project name to filter logs')
 } satisfies z.ZodRawShape;
 
 export const ClearLogsArgs = {
   session: z.string().optional().describe('8-char session id prefix to clear only one session'),
-  scope: z.enum(['soft','hard']).optional().default('hard').describe('soft: set baseline (non-destructive), hard: delete entries'),
   project: z.string().optional().describe('Project name to clear only that project\'s logs')
 } satisfies z.ZodRawShape;
 

packages/mcp/src/server.ts

@@ -354,20 +354,20 @@ export async function startIngestOnlyServer(
     actualPort = await listenWithResult(nodeServer, opts.host, opts.port);
   } catch (err: any) {
     const isAddrInUse = err && (err.code === 'EADDRINUSE' || String(err.message || '').includes('EADDRINUSE'));
-    if (isAddrInUse) {
-      const base = `http://${opts.host}:${opts.port}`;
-      // If an ingest server already responds to /health, reuse it silently
-      try {
-        const ctrl = new AbortController();
-        const t = setTimeout(() => ctrl.abort(), 400);
-        const res = await fetch(`${base}/health`, { signal: ctrl.signal as any, cache: 'no-store' as any });
-        clearTimeout(t);
-        if (res && res.ok) {
-          // eslint-disable-next-line no-console
-          console.error(`Ingest server already running at ${base}${opts.logsRoute}. Reusing existing instance.`);
-          return; // Treat as success
-        }
-      } catch {}
+          if (isAddrInUse) {
+        const base = `http://${opts.host}:${opts.port}`;
+        // If an ingest server already responds to /health, reuse it silently
+        try {
+          const ctrl = new AbortController();
+          const t = setTimeout(() => ctrl.abort(), 400);
+          const res = await fetch(`${base}/health`, { signal: ctrl.signal as any, cache: 'no-store' as any });
+          clearTimeout(t);
+          if (res && res.ok) {
+            // eslint-disable-next-line no-console
+            console.error(`Ingest server already running at ${base}${opts.logsRoute}. Reusing existing instance.`);
+            return; // Treat as success
+          }
+        } catch {}
       // eslint-disable-next-line no-console
       console.error(`Failed to start ingest-only server: Port in use at ${base}${opts.logsRoute}`);
     }

packages/mcp/src/store.ts

@@ -17,7 +17,6 @@ const DEFAULT_BUFFER = 1000;
 export class LogStore {
   private entries: LogEntry[] = [];
   private max: number;
-  private baselineTimestamps: Map<string, number> = new Map(); // For soft clear
 
   constructor(max = DEFAULT_BUFFER) {
     this.max = Math.max(50, max | 0);
@@ -34,59 +33,27 @@ export class LogStore {
   }
 
   clear(options?: { session?: string; scope?: 'soft' | 'hard'; project?: string }) {
-    const scope = options?.scope || 'hard';
     const session = options?.session;
     const project = options?.project;
 
-    if (scope === 'soft') {
-      if (project && project.trim()) {
-        this.baselineTimestamps.set(`project:${project}`, Date.now());
-      } else if (session && session.trim()) {
-        this.baselineTimestamps.set(`session:${session.slice(0, 8)}`, Date.now());
-      } else {
-        // Global soft baseline (discouraged for multi-project, kept for backward compat)
-        this.baselineTimestamps.set('__global__', Date.now());
-      }
-      return;
-    }
-
-    // Hard clear
     if (project && project.trim()) {
-      // Remove only entries for this project and drop its baseline
+      // Remove only entries for this project
       const p = project;
       this.entries = this.entries.filter(e => (e.project || '') !== p);
-      this.baselineTimestamps.delete(`project:${p}`);
       return;
     }
 
     if (session && session.trim()) {
       const s = session.slice(0, 8);
       this.entries = this.entries.filter(e => (e.sessionId || '').slice(0, 8) !== s);
-      this.baselineTimestamps.delete(`session:${s}`);
       return;
     }
 
-    // Global hard clear
+    // Global clear
     this.entries.length = 0;
-    this.baselineTimestamps.clear();
-  }
-
-  /** Set a baseline timestamp without deleting entries. If session omitted, use global baseline. */
-  baseline(session?: string, when: number = Date.now()) {
-    const key = session ? `session:${session.slice(0, 8)}` : '__global__';
-    this.baselineTimestamps.set(key, when);
-  }
-
-  /** Set a baseline for a specific project (recommended for multi-project use). */
-  baselineProject(project: string, when: number = Date.now()) {
-    if (!project || !project.trim()) return;
-    this.baselineTimestamps.set(`project:${project}`, when);
   }
 
-  /** Set a global baseline (discouraged for multi-project; kept for backward compatibility). */
-  baselineGlobal(when: number = Date.now()) {
-    this.baselineTimestamps.set('__global__', when);
-  }
+  // Baseline methods removed - logs persist until buffer limit
 
   toText(session?: string): string {
     return this.snapshot(session).map((e) => {
@@ -106,24 +73,7 @@ export class LogStore {
   snapshot(session?: string): LogEntry[] {
     let items = this.entries.slice();
     if (session) items = items.filter(e => (e.sessionId || '').slice(0, 8) === session);
-
-    const globalTs = this.baselineTimestamps.get('__global__') || 0;
-    const sessionTs = session ? (this.baselineTimestamps.get(`session:${session}`) || 0) : 0;
-
-    const filtered = items.filter((e) => {
-      const t = e.time || 0;
-      const projectTs = e.project ? (this.baselineTimestamps.get(`project:${e.project}`) || 0) : 0;
-      // Session baseline only applies when caller filtered by that session.
-      const threshold = Math.max(globalTs, sessionTs, projectTs);
-      return t === 0 || t >= threshold;
-    });
-
-    if (filtered.length === 0 && this.entries.length > 0 && (globalTs || sessionTs)) {
-      // eslint-disable-next-line no-console
-      console.warn(`All ${this.entries.length} logs filtered out by baseline. Check timestamp format or baseline scope.`);
-    }
-
-    return filtered;
+    return items;
   }
 }
 

packages/mcp/src/tools/clearLogs.ts

@@ -11,13 +11,12 @@ export function registerClearLogsTool(ctx: McpToolContext) {
     ClearLogsSchema,
     async (args, _extra) => {
       const safeArgs = args || {} as any;
-      const { session, scope = 'hard', project } = safeArgs as typeof ClearLogsSchema['_output'];
+      const { session, project } = safeArgs as typeof ClearLogsSchema['_output'];
       const validSession = validateSessionId(session);
 
-      store.clear({ session: validSession, scope, project });
+      store.clear({ session: validSession, scope: 'hard', project });
 
-      let message = 'Browser log buffer ';
-      message += scope === 'soft' ? 'baseline set' : 'cleared';
+      let message = 'Browser log buffer cleared';
       if (project) message += ` for project ${project}`;
       else if (validSession) message += ` for session ${validSession}`;
       message += '.';

packages/mcp/src/tools/getLogs.ts

@@ -20,14 +20,13 @@ export function registerGetLogsTool(ctx: McpToolContext) {
         contains,
         sinceMs,
         project,
-        autoBaseline = true,
-        stackedMode = false
+        // Removed: autoBaseline and stackedMode
       } = safeArgs as typeof GetLogsSchema['_output'];
 
       const validSession = validateSessionId(session);
       const validSince = typeof sinceMs === 'number' && sinceMs >= 0 ? sinceMs : undefined;
 
-      // Standardize: let store handle session filtering
+      // Get logs with optional session filter
       let items = store.snapshot(validSession);
       if (validSince) items = items.filter(e => !e.time || e.time >= validSince);
       if (level?.length) items = items.filter(e => level.includes(e.level));
@@ -53,6 +52,9 @@ export function registerGetLogsTool(ctx: McpToolContext) {
             .filter(([, t]) => t > 0 && (now - t) <= recentWindowMs)
             .map(([p]) => p);
           if (active.length === 1) autoProject = active[0];
+        } else if (projectsAll.size === 1) {
+          // If only one project exists, auto-select it
+          autoProject = Array.from(projectsAll)[0];
         }
       }
 
@@ -62,6 +64,22 @@ export function registerGetLogsTool(ctx: McpToolContext) {
       // Multi-project awareness: if no explicit project and multiple projects exist, show grouped preview
       const uniqueProjects = new Set(limited.map(e => e.project || '')); uniqueProjects.delete('');
       let text: string;
+      
+      // If no logs found, provide helpful message
+      if (limited.length === 0) {
+        const allProjects = new Set(store.snapshot().map(e => e.project || '').filter(p => p));
+        if (allProjects.size > 0) {
+          text = `No logs found matching your criteria. Available projects: ${Array.from(allProjects).join(', ')}\n\nTry: get_logs with { project: "<project-name>" }`;
+        } else {
+          text = 'No logs available yet.';
+        }
+        return {
+          content: [
+            { type: 'text' as const, text }
+          ]
+        };
+      }
+      
       if (!project && !autoProject && uniqueProjects.size > 1) {
         const groups = Array.from(uniqueProjects.values());
         const byProject: Record<string, typeof limited> = {};
@@ -111,23 +129,30 @@ export function registerGetLogsTool(ctx: McpToolContext) {
         }).join('\n');
       }
 
-      // Auto-baseline unless stackedMode (prefer project/session scopes; avoid global)
-      try {
-        if (autoBaseline && !stackedMode) {
-          if (project) {
-            store.baselineProject(project);
-          } else if (autoProject) {
-            store.baselineProject(autoProject);
-          } else if (validSession) {
-            store.baseline(validSession);
-          }
-          // No global baseline by default to avoid cross-project interference
+      // Add timestamp info to help users understand log freshness
+      const now = Date.now();
+      const oldestTime = limited.find(e => e.time)?.time || 0;
+      const newestTime = limited.findLast(e => e.time)?.time || 0;
+      
+      let timestampInfo = '';
+      if (oldestTime && newestTime) {
+        const ageMs = now - oldestTime;
+        const ageSec = Math.floor(ageMs / 1000);
+        const ageMin = Math.floor(ageSec / 60);
+        
+        const rangeMs = newestTime - oldestTime;
+        const rangeSec = Math.floor(rangeMs / 1000);
+        
+        if (ageMin > 0) {
+          timestampInfo = `\n\n[Log range: ${rangeSec}s, oldest: ${ageMin}m ago]`;
+        } else {
+          timestampInfo = `\n\n[Log range: ${rangeSec}s, oldest: ${ageSec}s ago]`;
         }
-      } catch {}
+      }
 
       return {
         content: [
-          { type: 'text' as const, text }
+          { type: 'text' as const, text: text + timestampInfo }
         ]
       };
     }