feat: Add pagination support to console logs to prevent LLM token limits

Saqoosha · claude · Saqoosha · commit 925431d447a6 · 2025-06-01T20:41:43.000+09:00
- Add offset and limit parameters to GetConsoleLogsResource and GetConsoleLogsTool - Implement GetLogsAsJson method with pagination in ConsoleLogsService - Return logs in newest-first order for better debugging workflow - Add automatic memory management with configurable cleanup thresholds - Update resource descriptions with pagination usage recommendations - Enhance Unity-side and Node.js-side implementations consistently 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/Editor/Resources/GetConsoleLogsResource.cs b/Editor/Resources/GetConsoleLogsResource.cs
@@ -13,38 +13,58 @@ public class GetConsoleLogsResource : McpResourceBase
         public GetConsoleLogsResource(IConsoleLogsService consoleLogsService)
         {
             Name = "get_console_logs";
-            Description = "Retrieves logs from the Unity console, optionally filtered by type (error, warning, info)";
+            Description = "Retrieves logs from the Unity console (newest first), optionally filtered by type (error, warning, info). Use pagination parameters (offset, limit) to avoid LLM token limits. Recommended: limit=20-50 for optimal performance.";
             Uri = "unity://logs/{logType}";
             
             _consoleLogsService = consoleLogsService;
         }
 
         /// <summary>
-        /// Fetch logs from the Unity console, optionally filtered by type
+        /// Fetch logs from the Unity console, optionally filtered by type with pagination support
         /// </summary>
-        /// <param name="parameters">Resource parameters as a JObject (may include 'logType')</param>
-        /// <returns>A JObject containing the list of logs</returns>
+        /// <param name="parameters">Resource parameters as a JObject (may include 'logType', 'offset', 'limit')</param>
+        /// <returns>A JObject containing the list of logs with pagination info</returns>
         public override JObject Fetch(JObject parameters)
         {
             string logType = null;
-            if (parameters != null && parameters.ContainsKey("logType") && parameters["logType"] != null)
+            int offset = 0;
+            int limit = 100;
+            
+            if (parameters != null)
             {
-                logType = parameters["logType"].ToString()?.ToLowerInvariant();
-                if (string.IsNullOrWhiteSpace(logType))
+                // Extract logType
+                if (parameters.ContainsKey("logType") && parameters["logType"] != null)
+                {
+                    logType = parameters["logType"].ToString()?.ToLowerInvariant();
+                    if (string.IsNullOrWhiteSpace(logType))
+                    {
+                        logType = null;
+                    }
+                }
+                
+                // Extract pagination parameters
+                if (parameters.ContainsKey("offset") && parameters["offset"] != null)
+                {
+                    int.TryParse(parameters["offset"].ToString(), out offset);
+                }
+                
+                if (parameters.ContainsKey("limit") && parameters["limit"] != null)
                 {
-                    logType = null;
+                    int.TryParse(parameters["limit"].ToString(), out limit);
                 }
             }
 
-            JArray logsArray = _consoleLogsService.GetAllLogsAsJson(logType);
+            // Use the new paginated method
+            JObject result = _consoleLogsService.GetLogsAsJson(logType, offset, limit);
+            
+            // Add success info to the response
+            result["success"] = true;
+            
+            var pagination = result["pagination"] as JObject;
+            string typeFilter = logType != null ? $" of type '{logType}'" : "";
+            result["message"] = $"Retrieved {pagination["returnedCount"]} of {pagination["filteredCount"]} log entries{typeFilter} (offset: {offset}, limit: {limit})";
 
-            // Create the response
-            return new JObject
-            {
-                ["success"] = true,
-                ["message"] = $"Retrieved {logsArray.Count} log entries" + (logType != null ? $" of type '{logType}'" : ""),
-                ["logs"] = logsArray
-            };
+            return result;
         }
 
 
diff --git a/Editor/Services/ConsoleLogsService.cs b/Editor/Services/ConsoleLogsService.cs
@@ -21,6 +21,10 @@ private class LogEntry
             public DateTime Timestamp { get; set; }
         }
         
+        // Constants for log management
+        private const int MaxLogEntries = 1000;
+        private const int CleanupThreshold = 200; // Remove oldest entries when exceeding max
+        
         // Collection to store all log messages
         private readonly List<LogEntry> _logEntries = new List<LogEntry>();
         
@@ -71,28 +75,75 @@ public void StopListening()
         /// </summary>
         /// <returns>JArray containing all logs</returns>
         public JArray GetAllLogsAsJson(string logType = "")
+        {
+            var result = GetLogsAsJson(logType, 0, int.MaxValue);
+            return result["logs"] as JArray;
+        }
+        
+        /// <summary>
+        /// Get logs as a JSON array with pagination support
+        /// </summary>
+        /// <param name="logType">Filter by log type (empty for all)</param>
+        /// <param name="offset">Starting index (0-based)</param>
+        /// <param name="limit">Maximum number of logs to return (default: 100)</param>
+        /// <returns>JObject containing logs array and pagination info</returns>
+        public JObject GetLogsAsJson(string logType = "", int offset = 0, int limit = 100)
         {
             // Convert log entries to a JSON array, filtering by logType if provided
             JArray logsArray = new JArray();
             bool filter = !string.IsNullOrEmpty(logType);
+            int totalCount = 0;
+            int filteredCount = 0;
+            int currentIndex = 0;
             
             lock (_logEntries)
             {
+                // First pass: count total and filtered entries
                 foreach (var entry in _logEntries)
                 {
+                    totalCount++;
+                    if (!filter || entry.Type.ToString().Equals(logType, System.StringComparison.OrdinalIgnoreCase))
+                    {
+                        filteredCount++;
+                    }
+                }
+                
+                // Second pass: collect the requested page (newest first)
+                for (int i = _logEntries.Count - 1; i >= 0; i--)
+                {
+                    var entry = _logEntries[i];
                     if (filter && !entry.Type.ToString().Equals(logType, System.StringComparison.OrdinalIgnoreCase))
                         continue;
-                    logsArray.Add(new JObject
+                        
+                    if (currentIndex >= offset && logsArray.Count < limit)
                     {
-                        ["message"] = entry.Message,
-                        ["stackTrace"] = entry.StackTrace,
-                        ["type"] = entry.Type.ToString(),
-                        ["timestamp"] = entry.Timestamp.ToString("yyyy-MM-dd HH:mm:ss.fff")
-                    });
+                        logsArray.Add(new JObject
+                        {
+                            ["message"] = entry.Message,
+                            ["stackTrace"] = entry.StackTrace,
+                            ["type"] = entry.Type.ToString(),
+                            ["timestamp"] = entry.Timestamp.ToString("yyyy-MM-dd HH:mm:ss.fff")
+                        });
+                    }
+                    
+                    currentIndex++;
+                    if (logsArray.Count >= limit) break;
                 }
             }
             
-            return logsArray;
+            return new JObject
+            {
+                ["logs"] = logsArray,
+                ["pagination"] = new JObject
+                {
+                    ["offset"] = offset,
+                    ["limit"] = limit,
+                    ["totalCount"] = totalCount,
+                    ["filteredCount"] = filteredCount,
+                    ["returnedCount"] = logsArray.Count,
+                    ["hasMore"] = offset + logsArray.Count < filteredCount
+                }
+            };
         }
         
         /// <summary>
@@ -106,6 +157,34 @@ private void ClearLogs()
             }
         }
         
+        /// <summary>
+        /// Manually clean up old log entries, keeping only the most recent ones
+        /// </summary>
+        /// <param name="keepCount">Number of recent entries to keep (default: 500)</param>
+        public void CleanupOldLogs(int keepCount = 500)
+        {
+            lock (_logEntries)
+            {
+                if (_logEntries.Count > keepCount)
+                {
+                    int removeCount = _logEntries.Count - keepCount;
+                    _logEntries.RemoveRange(0, removeCount);
+                }
+            }
+        }
+        
+        /// <summary>
+        /// Get current log count
+        /// </summary>
+        /// <returns>Number of stored log entries</returns>
+        public int GetLogCount()
+        {
+            lock (_logEntries)
+            {
+                return _logEntries.Count;
+            }
+        }
+        
         /// <summary>
         /// Check if console was cleared using reflection (for Unity 2022.3)
         /// </summary>
@@ -154,6 +233,12 @@ private void OnLogMessageReceived(string logString, string stackTrace, LogType t
                     Type = type,
                     Timestamp = DateTime.Now
                 });
+                
+                // Clean up old entries if we exceed the maximum
+                if (_logEntries.Count > MaxLogEntries)
+                {
+                    _logEntries.RemoveRange(0, CleanupThreshold);
+                }
             }
         }
         
diff --git a/Editor/Services/IConsoleLogsService.cs b/Editor/Services/IConsoleLogsService.cs
@@ -17,6 +17,15 @@ public interface IConsoleLogsService
         /// <returns>JArray containing filtered logs</returns>
         JArray GetAllLogsAsJson(string logType = "");
         
+        /// <summary>
+        /// Get logs as a JSON object with pagination support
+        /// </summary>
+        /// <param name="logType">Filter by log type (empty for all)</param>
+        /// <param name="offset">Starting index (0-based)</param>
+        /// <param name="limit">Maximum number of logs to return (default: 100)</param>
+        /// <returns>JObject containing logs array and pagination info</returns>
+        JObject GetLogsAsJson(string logType = "", int offset = 0, int limit = 100);
+        
         /// <summary>
         /// Start listening for logs
         /// </summary>
@@ -26,5 +35,17 @@ public interface IConsoleLogsService
         /// Stop listening for logs
         /// </summary>
         void StopListening();
+        
+        /// <summary>
+        /// Manually clean up old log entries, keeping only the most recent ones
+        /// </summary>
+        /// <param name="keepCount">Number of recent entries to keep (default: 500)</param>
+        void CleanupOldLogs(int keepCount = 500);
+        
+        /// <summary>
+        /// Get current log count
+        /// </summary>
+        /// <returns>Number of stored log entries</returns>
+        int GetLogCount();
     }
 }
diff --git a/Server~/build/resources/getConsoleLogsResource.js b/Server~/build/resources/getConsoleLogsResource.js
@@ -3,7 +3,7 @@ import { McpUnityError, ErrorType } from '../utils/errors.js';
 // Constants for the resource
 const resourceName = 'get_console_logs';
 const resourceMimeType = 'application/json';
-const resourceUri = 'unity://logs/{logType}';
+const resourceUri = 'unity://logs/{logType}?offset={offset}&limit={limit}';
 const resourceTemplate = new ResourceTemplate(resourceUri, {
     list: () => listLogTypes(resourceMimeType)
 });
@@ -13,25 +13,25 @@ function listLogTypes(resourceMimeType) {
             {
                 uri: `unity://logs/`,
                 name: "All logs",
-                description: "Retrieve all Unity console logs",
+                description: "Retrieve Unity console logs (newest first). Use pagination to avoid token limits: ?offset=0&limit=50 for recent logs. Default limit=100 may be too large for LLM context.",
                 mimeType: resourceMimeType
             },
             {
                 uri: `unity://logs/error`,
                 name: "Error logs",
-                description: "Retrieve only error logs from the Unity console",
+                description: "Retrieve only error logs from Unity console (newest first). Use ?offset=0&limit=20 to avoid token limits. Large log sets may exceed LLM context window.",
                 mimeType: resourceMimeType
             },
             {
                 uri: `unity://logs/warning`,
                 name: "Warning logs",
-                description: "Retrieve only warning logs from the Unity console",
+                description: "Retrieve only warning logs from Unity console (newest first). Use pagination ?offset=0&limit=30 to manage token usage effectively.",
                 mimeType: resourceMimeType
             },
             {
                 uri: `unity://logs/info`,
                 name: "Info logs",
-                description: "Retrieve only info logs from the Unity console",
+                description: "Retrieve only info logs from Unity console (newest first). Use smaller limits like ?limit=25 to prevent token overflow in LLM responses.",
                 mimeType: resourceMimeType
             }
         ]
@@ -43,7 +43,7 @@ function listLogTypes(resourceMimeType) {
 export function registerGetConsoleLogsResource(server, mcpUnity, logger) {
     logger.info(`Registering resource: ${resourceName}`);
     server.resource(resourceName, resourceTemplate, {
-        description: 'Retrieve Unity console logs by type',
+        description: 'Retrieve Unity console logs by type (newest first). IMPORTANT: Use pagination parameters ?offset=0&limit=50 to avoid LLM token limits. Default limit=100 may exceed context window.',
         mimeType: resourceMimeType
     }, async (uri, variables) => {
         try {
@@ -63,19 +63,24 @@ async function resourceHandler(mcpUnity, uri, variables, logger) {
     let logType = variables["logType"] ? decodeURIComponent(variables["logType"]) : undefined;
     if (logType === '')
         logType = undefined;
+    // Extract pagination parameters
+    const offset = variables["offset"] ? parseInt(variables["offset"], 10) : 0;
+    const limit = variables["limit"] ? parseInt(variables["limit"], 10) : 100;
     // Send request to Unity
     const response = await mcpUnity.sendRequest({
         method: resourceName,
         params: {
-            logType: logType
+            logType: logType,
+            offset: offset,
+            limit: limit
         }
     });
     if (!response.success) {
         throw new McpUnityError(ErrorType.RESOURCE_FETCH, response.message || 'Failed to fetch logs from Unity');
     }
     return {
         contents: [{
-                uri: `unity://logs/${logType ?? ''}`,
+                uri: `unity://logs/${logType ?? ''}?offset=${offset}&limit=${limit}`,
                 mimeType: resourceMimeType,
                 text: JSON.stringify(response, null, 2)
             }]
diff --git a/Server~/build/tools/getConsoleLogsTool.js b/Server~/build/tools/getConsoleLogsTool.js
@@ -2,12 +2,25 @@ import * as z from "zod";
 import { McpUnityError, ErrorType } from "../utils/errors.js";
 // Constants for the tool
 const toolName = "get_console_logs";
-const toolDescription = "Retrieves logs from the Unity console";
+const toolDescription = "Retrieves logs from the Unity console with pagination support to avoid token limits";
 const paramsSchema = z.object({
     logType: z
         .enum(["info", "warning", "error"])
         .optional()
         .describe("The type of logs to retrieve (info, warning, error) - defaults to all logs if not specified"),
+    offset: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("Starting index for pagination (0-based, defaults to 0)"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(500)
+        .optional()
+        .describe("Maximum number of logs to return (defaults to 50, max 500 to avoid token limits)")
 });
 /**
  * Creates and registers the Get Console Logs tool with the MCP server
@@ -42,13 +55,15 @@ export function registerGetConsoleLogsTool(server, mcpUnity, logger) {
  * @throws McpUnityError if the request to Unity fails
  */
 async function toolHandler(mcpUnity, params) {
-    const { logType } = params;
+    const { logType, offset = 0, limit = 50 } = params;
     // Send request to Unity using the same method name as the resource
     // This allows reusing the existing Unity-side implementation
     const response = await mcpUnity.sendRequest({
         method: "get_console_logs",
         params: {
             logType: logType,
+            offset: offset,
+            limit: limit,
         },
     });
     if (!response.success) {
diff --git a/Server~/src/resources/getConsoleLogsResource.ts b/Server~/src/resources/getConsoleLogsResource.ts
diff --git a/Server~/src/tools/getConsoleLogsTool.ts b/Server~/src/tools/getConsoleLogsTool.ts
