feat: Add includeStackTrace option to reduce LLM token usage by 80-90% #44
Conversation
…tion - Add includeStackTrace parameter to get_console_logs tool and resource - Default to true for backward compatibility (except info logs in resource) - Reduces token usage by 80-90% when set to false - Update tool/resource descriptions with clear hints for LLMs to use this option - Add⚠️ emoji to highlight token-saving recommendations - Implement stack trace filtering in Unity-side ConsoleLogsService This helps prevent LLM context window overflow when retrieving Unity console logs. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
📝 WalkthroughWalkthroughA new optional Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant Tool/Resource Handler
participant UnityService
Client->>Tool/Resource Handler: Request logs (includeStackTrace = true/false)
Tool/Resource Handler->>UnityService: GetLogsAsJson(..., includeStackTrace)
UnityService-->>Tool/Resource Handler: Logs JSON (with/without stack traces)
Tool/Resource Handler-->>Client: Response with logs (as requested)
Possibly related PRs
Suggested reviewers
Poem
✨ Finishing Touches
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
Server~/src/resources/getConsoleLogsResource.ts (1)
83-88: Consider adding validation for the includeStackTrace parameter.The boolean parsing logic accepts "true", "1", or "yes" as true values, which provides flexibility. However, consider validating that the parameter value is one of the expected formats to provide better error messages for invalid inputs.
// Extract includeStackTrace parameter let includeStackTrace = true; // Default to true for backward compatibility if (variables["includeStackTrace"] !== undefined) { const value = variables["includeStackTrace"] as string; + if (!['true', '1', 'yes', 'false', '0', 'no'].includes(value.toLowerCase())) { + throw new McpUnityError(ErrorType.VALIDATION, `Invalid includeStackTrace parameter: must be true/false, 1/0, or yes/no`); + } includeStackTrace = value === 'true' || value === '1' || value === 'yes'; }
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
Editor/Resources/GetConsoleLogsResource.cs(3 hunks)Editor/Services/ConsoleLogsService.cs(2 hunks)Editor/Services/IConsoleLogsService.cs(1 hunks)Server~/build/resources/getConsoleLogsResource.js(3 hunks)Server~/build/tools/getConsoleLogsTool.js(3 hunks)Server~/src/resources/getConsoleLogsResource.ts(6 hunks)Server~/src/tools/getConsoleLogsTool.ts(3 hunks)
🧰 Additional context used
🧬 Code Graph Analysis (5)
Server~/build/tools/getConsoleLogsTool.js (1)
Server~/build/resources/getConsoleLogsResource.js (1)
includeStackTrace(70-70)
Editor/Services/IConsoleLogsService.cs (1)
Server~/build/resources/getConsoleLogsResource.js (4)
logType(63-63)offset(67-67)limit(68-68)includeStackTrace(70-70)
Editor/Services/ConsoleLogsService.cs (1)
Server~/build/resources/getConsoleLogsResource.js (4)
logType(63-63)offset(67-67)limit(68-68)includeStackTrace(70-70)
Editor/Resources/GetConsoleLogsResource.cs (1)
Server~/build/resources/getConsoleLogsResource.js (5)
includeStackTrace(70-70)logType(63-63)offset(67-67)limit(68-68)value(72-72)
Server~/src/tools/getConsoleLogsTool.ts (2)
Server~/build/tools/getConsoleLogsTool.js (1)
params(62-62)Server~/build/resources/getConsoleLogsResource.js (1)
includeStackTrace(70-70)
🔇 Additional comments (22)
Server~/build/tools/getConsoleLogsTool.js (2)
24-27: Clear documentation with actionable guidance.The parameter documentation is excellent with a prominent warning about token savings. This will help developers make informed decisions about stack trace inclusion.
62-62:✅ Verification successful
Verify documentation consistency about info logs default behavior.
The parameter extraction and usage look correct. However, the description mentions "Default: true (except info logs in resource)" but I don't see special handling for info logs in this tool implementation.
Also applies to: 71-71
🏁 Script executed:
#!/bin/bash # Search for any special handling of info logs with different includeStackTrace defaults rg -A 10 -B 5 "info.*includeStackTrace|includeStackTrace.*info" --type js --type tsLength of output: 1357
Default behavior for info logs is handled in the resource, not the tool
The tool’s parameter extraction here correctly defaultsincludeStackTracetotrue. Insrc/resources/getConsoleLogsResource.ts, the info‐logs URI already specifiesincludeStackTrace=false, so no additional handling is needed in the tool.Editor/Services/IConsoleLogsService.cs (1)
19-21: Interface updated correctly with proper documentation.The parameter addition to the interface is well-documented and maintains backward compatibility with the default value of
true.Editor/Services/ConsoleLogsService.cs (2)
88-88: Method signature updated correctly.The parameter addition maintains backward compatibility and follows C# conventions with proper default value.
131-144: Conditional stack trace inclusion implemented correctly.The logic properly creates the base log object and conditionally adds the stack trace field only when requested. This approach is clean and efficient.
Server~/src/tools/getConsoleLogsTool.ts (2)
31-34: TypeScript implementation consistent with JavaScript version.The parameter definition and warning message are identical to the JavaScript version, which ensures consistency across the codebase.
83-83: Parameter handling consistent and type-safe.The parameter extraction and usage follow the same pattern as the JavaScript version while maintaining TypeScript type safety.
Also applies to: 93-93
Editor/Resources/GetConsoleLogsResource.cs (5)
17-17: Excellent documentation with clear guidance for LLM token optimization.The description effectively communicates the purpose and benefits of the new parameter while providing practical usage recommendations.
35-35: Parameter extraction follows established pattern.The implementation correctly uses the new helper method with appropriate default value for backward compatibility.
40-40: Service method call properly updated.The parameter is correctly passed to the service method, maintaining the existing call pattern.
48-48: Response message appropriately includes the parameter value.Adding the
includeStackTracevalue to the pagination summary provides useful feedback to clients about the actual parameter used.
73-85: Well-implemented helper method following established patterns.The
GetBoolParametermethod correctly follows the same pattern as the existingGetIntParametermethod with proper null checking and safe type conversion.Server~/src/resources/getConsoleLogsResource.ts (4)
11-11: Resource URI template correctly updated.The template properly includes the new
includeStackTraceparameter alongside existing pagination parameters.
20-41: Excellent predefined resource configurations with LLM-optimized defaults.The predefined URIs provide sensible defaults for different log types:
- Info logs default to
includeStackTrace=false(optimal for info logs)- Other log types default to
truefor backward compatibility- Clear warnings and guidance in descriptions help users make informed choices
104-106: Parameter correctly added to Unity request.The
includeStackTraceparameter is properly included in the request parameters sent to Unity.
118-118: Response URI correctly reflects actual parameters used.Including the
includeStackTraceparameter in the response URI provides useful feedback about the request that was processed.Server~/build/resources/getConsoleLogsResource.js (6)
6-6: Resource URI template consistent with TypeScript version.The template correctly matches the TypeScript implementation.
14-35: Predefined resource configurations match TypeScript implementation.The URIs and descriptions are consistent with the TypeScript source, providing the same LLM-optimized defaults and clear guidance.
69-74: Boolean parsing logic consistent with TypeScript version.The parameter extraction and parsing logic correctly matches the TypeScript implementation.
88-89: Parameter correctly included in Unity request.The
includeStackTraceparameter is properly added to the request parameters.
97-97: Response URI correctly includes all parameters.The response URI properly reflects the actual parameters used in the request.
76-81:✅ Verification successful
Verify pagination validation exists in TypeScript source.
The JavaScript file includes validation for
offsetandlimitparameters, but this validation doesn't appear to be present in the TypeScript source file. Ensure the TypeScript source includes the same validation logic.
🏁 Script executed:
#!/bin/bash # Description: Check if pagination validation exists in the TypeScript source file # Expected: Find validation logic for offset and limit parameters rg -A 10 -B 2 "isNaN.*offset|isNaN.*limit" Server~/src/resources/getConsoleLogsResource.tsLength of output: 611
Pagination validation is already present in the TypeScript source—no changes needed.
🚨 Problem
After implementing pagination (#42), we discovered another critical issue with LLM token consumption when retrieving Unity console logs. Stack traces alone consume 80-90% of the total tokens, making it difficult to retrieve and analyze logs efficiently within LLM context windows.
Real-world Impact
This becomes especially problematic when:
⚡ Solution
New
includeStackTraceParameterAdded an optional boolean parameter to control stack trace inclusion:
Smart Defaults
truefor backward compatibilityfalse(stack traces rarely needed)LLM-Friendly Documentation
Added clear hints with⚠️ emoji to guide LLMs:
📊 Results
Token Usage Comparison
Recommended Workflow
includeStackTrace: falsefor quick overviewincludeStackTrace: trueonly when needed🧪 Testing with Claude Code
This feature was extensively tested with Claude Code (claude.ai/code), which is how we discovered the token consumption issue and validated the solution.
Test Environment
Claude Code Test Results
Why Claude Code Testing Matters
📋 Technical Details
Unity Side Changes
ConsoleLogsService.cs: Added conditional stack trace inclusionIConsoleLogsService.cs: Updated interface signatureGetConsoleLogsResource.cs: AddedincludeStackTraceparameter handlingNode.js Side Changes
getConsoleLogsTool.ts: Added parameter to Zod schema with detailed descriptiongetConsoleLogsResource.ts: Extended URL template and parameter extractionKey Implementation Details
trueto maintain existing behavior🔍 Why This Matters
For LLM-based Development Tools (like Claude Code)
For Developers Using MCP Unity
Use Case Examples (from Claude Code testing)
Quick Health Check
Shader Error Investigation (actual test case)
Pattern Analysis
Breaking Changes
None - Fully backward compatible. Existing code continues to work unchanged.
Future Considerations
This implementation opens possibilities for:
However, the current boolean approach provides immediate value with minimal complexity.
Summary
This PR addresses a critical usability issue discovered through real-world usage with Claude Code. By adding a simple
includeStackTraceparameter, we enable LLM-based tools to work effectively with Unity console logs without constantly hitting token limits. The 80-90% reduction in token usage transforms the debugging experience from frustrating to smooth.🤖 Generated with Claude Code
Co-Authored-By: Claude [email protected]