fix: Add output limiting to prevent MCP token limit errors

- Module 1: Added comprehensive lesson on handling 25k token limit
  - Implemented max_diff_lines parameter (default 500)
  - Added truncation logic with clear messaging
  - Included test for output limiting
  - Framed as important real-world learning opportunity

- Modules 2 & 3: Pre-included fix so learners can focus on new concepts
  - Updated all starter and solution code
  - Added notes that output limiting is already handled
  - Prevents repetitive debugging of same issue

This ensures learners encounter and solve the token limit problem once
in Module 1 as a valuable lesson, then can focus on webhooks (Module 2)
and Slack integration (Module 3) without distraction.

Fixes the issue where large git diffs cause "MCP tool response exceeds
maximum allowed tokens (25000)" errors.

Author: zealoushacker

projects/unit3/build-mcp-server/solution/server.py

@@ -22,13 +22,15 @@
 @mcp.tool()
 async def analyze_file_changes(
     base_branch: str = "main",
-    include_diff: bool = True
+    include_diff: bool = True,
+    max_diff_lines: int = 500
 ) -> str:
     """Get the full diff and list of changed files in the current git repository.
     
     Args:
         base_branch: Base branch to compare against (default: main)
         include_diff: Include the full diff content (default: true)
+        max_diff_lines: Maximum number of diff lines to include (default: 500)
     """
     try:
         # Get list of changed files
@@ -48,13 +50,23 @@ async def analyze_file_changes(
 
         # Get the actual diff if requested
         diff_content = ""
+        truncated = False
         if include_diff:
             diff_result = subprocess.run(
                 ["git", "diff", f"{base_branch}...HEAD"],
                 capture_output=True,
                 text=True
             )
-            diff_content = diff_result.stdout
+            diff_lines = diff_result.stdout.split('\n')
+            
+            # Check if we need to truncate
+            if len(diff_lines) > max_diff_lines:
+                diff_content = '\n'.join(diff_lines[:max_diff_lines])
+                diff_content += f"\n\n... Output truncated. Showing {max_diff_lines} of {len(diff_lines)} lines ..."
+                diff_content += "\n... Use max_diff_lines parameter to see more ..."
+                truncated = True
+            else:
+                diff_content = diff_result.stdout
 
         # Get commit messages for context
         commits_result = subprocess.run(
@@ -68,15 +80,17 @@ async def analyze_file_changes(
             "files_changed": files_result.stdout,
             "statistics": stat_result.stdout,
             "commits": commits_result.stdout,
-            "diff": diff_content if include_diff else "Diff not included (set include_diff=true to see full diff)"
+            "diff": diff_content if include_diff else "Diff not included (set include_diff=true to see full diff)",
+            "truncated": truncated,
+            "total_diff_lines": len(diff_lines) if include_diff else 0
         }
 
         return json.dumps(analysis, indent=2)
 
     except subprocess.CalledProcessError as e:
-        return f"Error analyzing changes: {e.stderr}"
+        return json.dumps({"error": f"Git error: {e.stderr}"})
     except Exception as e:
-        return f"Error: {str(e)}"
+        return json.dumps({"error": str(e)})
 
 
 @mcp.tool()

projects/unit3/build-mcp-server/solution/test_server.py

@@ -71,6 +71,40 @@ async def test_includes_required_fields(self):
             else:
                 # Starter code - just verify it returns something structured
                 assert isinstance(data, dict), "Should return a JSON object even if not implemented"
+    
+    @pytest.mark.asyncio
+    async def test_output_limiting(self):
+        """Test that large diffs are properly truncated."""
+        with patch('subprocess.run') as mock_run:
+            # Create a mock diff with many lines
+            large_diff = "\n".join([f"+ line {i}" for i in range(1000)])
+            
+            # Set up mock responses
+            mock_run.side_effect = [
+                MagicMock(stdout="M\tfile1.py\n", stderr=""),  # files changed
+                MagicMock(stdout="1 file changed, 1000 insertions(+)", stderr=""),  # stats
+                MagicMock(stdout=large_diff, stderr=""),  # diff
+                MagicMock(stdout="abc123 Initial commit", stderr="")  # commits
+            ]
+            
+            # Test with default limit (500 lines)
+            result = await analyze_file_changes(include_diff=True)
+            data = json.loads(result)
+            
+            # Check if it's implemented
+            if "error" not in data or "Not implemented" not in str(data.get("error", "")):
+                if "diff" in data and data["diff"] != "Diff not included (set include_diff=true to see full diff)":
+                    diff_lines = data["diff"].split('\n')
+                    # Should be truncated to around 500 lines plus truncation message
+                    assert len(diff_lines) < 600, "Large diffs should be truncated"
+                    
+                    # Check for truncation indicator
+                    if "truncated" in data:
+                        assert data["truncated"] == True, "Should indicate truncation"
+                    
+                    # Should have truncation message
+                    assert "truncated" in data["diff"].lower() or "..." in data["diff"], \
+                        "Should indicate diff was truncated"
 
 
 @pytest.mark.skipif(not IMPORTS_SUCCESSFUL, reason="Imports failed")

projects/unit3/build-mcp-server/starter/server.py

@@ -42,6 +42,11 @@ async def analyze_file_changes(base_branch: str = "main", include_diff: bool = T
         include_diff: Include the full diff content (default: true)
     """
     # TODO: Implement this tool
+    # IMPORTANT: MCP tools have a 25,000 token response limit!
+    # Large diffs can easily exceed this. Consider:
+    # - Adding a max_diff_lines parameter (e.g., 500 lines)
+    # - Truncating large outputs with a message
+    # - Returning summary statistics alongside limited diffs
     return json.dumps({"error": "Not implemented yet", "hint": "Use subprocess to run git commands"})
 
 

projects/unit3/github-actions-integration/solution/server.py

@@ -22,18 +22,20 @@
 EVENTS_FILE = Path(__file__).parent / "github_events.json"
 
 
-# ===== Original Tools from Module 1 =====
+# ===== Original Tools from Module 1 (with output limiting) =====
 
 @mcp.tool()
 async def analyze_file_changes(
     base_branch: str = "main",
-    include_diff: bool = True
+    include_diff: bool = True,
+    max_diff_lines: int = 500
 ) -> str:
     """Get the full diff and list of changed files in the current git repository.
     
     Args:
         base_branch: Base branch to compare against (default: main)
         include_diff: Include the full diff content (default: true)
+        max_diff_lines: Maximum number of diff lines to include (default: 500)
     """
     try:
         # Get list of changed files
@@ -53,13 +55,23 @@ async def analyze_file_changes(
 
         # Get the actual diff if requested
         diff_content = ""
+        truncated = False
         if include_diff:
             diff_result = subprocess.run(
                 ["git", "diff", f"{base_branch}...HEAD"],
                 capture_output=True,
                 text=True
             )
-            diff_content = diff_result.stdout
+            diff_lines = diff_result.stdout.split('\n')
+            
+            # Check if we need to truncate
+            if len(diff_lines) > max_diff_lines:
+                diff_content = '\n'.join(diff_lines[:max_diff_lines])
+                diff_content += f"\n\n... Output truncated. Showing {max_diff_lines} of {len(diff_lines)} lines ..."
+                diff_content += "\n... Use max_diff_lines parameter to see more ..."
+                truncated = True
+            else:
+                diff_content = diff_result.stdout
 
         # Get commit messages for context
         commits_result = subprocess.run(
@@ -73,15 +85,17 @@ async def analyze_file_changes(
             "files_changed": files_result.stdout,
             "statistics": stat_result.stdout,
             "commits": commits_result.stdout,
-            "diff": diff_content if include_diff else "Diff not included (set include_diff=true to see full diff)"
+            "diff": diff_content if include_diff else "Diff not included (set include_diff=true to see full diff)",
+            "truncated": truncated,
+            "total_diff_lines": len(diff_lines) if include_diff else 0
         }
 
         return json.dumps(analysis, indent=2)
 
     except subprocess.CalledProcessError as e:
-        return f"Error analyzing changes: {e.stderr}"
+        return json.dumps({"error": f"Git error: {e.stderr}"})
     except Exception as e:
-        return f"Error: {str(e)}"
+        return json.dumps({"error": str(e)})
 
 
 @mcp.tool()

projects/unit3/github-actions-integration/starter/server.py

@@ -23,18 +23,20 @@
 # Hint: EVENTS_FILE = Path(__file__).parent / "github_events.json"
 
 
-# ===== Module 1 Tools (Keep these as-is) =====
+# ===== Module 1 Tools (Already includes output limiting fix from Module 1) =====
 
 @mcp.tool()
 async def analyze_file_changes(
     base_branch: str = "main",
-    include_diff: bool = True
+    include_diff: bool = True,
+    max_diff_lines: int = 500
 ) -> str:
     """Get the full diff and list of changed files in the current git repository.
     
     Args:
         base_branch: Base branch to compare against (default: main)
         include_diff: Include the full diff content (default: true)
+        max_diff_lines: Maximum number of diff lines to include (default: 500)
     """
     try:
         # Get list of changed files
@@ -54,13 +56,23 @@ async def analyze_file_changes(
 
         # Get the actual diff if requested
         diff_content = ""
+        truncated = False
         if include_diff:
             diff_result = subprocess.run(
                 ["git", "diff", f"{base_branch}...HEAD"],
                 capture_output=True,
                 text=True
             )
-            diff_content = diff_result.stdout
+            diff_lines = diff_result.stdout.split('\n')
+            
+            # Check if we need to truncate (learned from Module 1)
+            if len(diff_lines) > max_diff_lines:
+                diff_content = '\n'.join(diff_lines[:max_diff_lines])
+                diff_content += f"\n\n... Output truncated. Showing {max_diff_lines} of {len(diff_lines)} lines ..."
+                diff_content += "\n... Use max_diff_lines parameter to see more ..."
+                truncated = True
+            else:
+                diff_content = diff_result.stdout
 
         # Get commit messages for context
         commits_result = subprocess.run(
@@ -74,7 +86,9 @@ async def analyze_file_changes(
             "files_changed": files_result.stdout,
             "statistics": stat_result.stdout,
             "commits": commits_result.stdout,
-            "diff": diff_content if include_diff else "Diff not included (set include_diff=true to see full diff)"
+            "diff": diff_content if include_diff else "Diff not included (set include_diff=true to see full diff)",
+            "truncated": truncated,
+            "total_diff_lines": len(diff_lines) if include_diff else 0
         }
 
         return json.dumps(analysis, indent=2)

projects/unit3/slack-notification/solution/server.py

@@ -23,18 +23,20 @@
 EVENTS_FILE = Path(__file__).parent / "github_events.json"
 
 
-# ===== Tools from Modules 1 & 2 (Complete) =====
+# ===== Tools from Modules 1 & 2 (Complete with output limiting) =====
 
 @mcp.tool()
 async def analyze_file_changes(
     base_branch: str = "main",
-    include_diff: bool = True
+    include_diff: bool = True,
+    max_diff_lines: int = 500
 ) -> str:
     """Get the full diff and list of changed files in the current git repository.
     
     Args:
         base_branch: Base branch to compare against (default: main)
         include_diff: Include the full diff content (default: true)
+        max_diff_lines: Maximum number of diff lines to include (default: 500)
     """
     try:
         # Get list of changed files
@@ -54,13 +56,23 @@ async def analyze_file_changes(
 
         # Get the actual diff if requested
         diff_content = ""
+        truncated = False
         if include_diff:
             diff_result = subprocess.run(
                 ["git", "diff", f"{base_branch}...HEAD"],
                 capture_output=True,
                 text=True
             )
-            diff_content = diff_result.stdout
+            diff_lines = diff_result.stdout.split('\n')
+            
+            # Check if we need to truncate
+            if len(diff_lines) > max_diff_lines:
+                diff_content = '\n'.join(diff_lines[:max_diff_lines])
+                diff_content += f"\n\n... Output truncated. Showing {max_diff_lines} of {len(diff_lines)} lines ..."
+                diff_content += "\n... Use max_diff_lines parameter to see more ..."
+                truncated = True
+            else:
+                diff_content = diff_result.stdout
 
         # Get commit messages for context
         commits_result = subprocess.run(
@@ -74,15 +86,17 @@ async def analyze_file_changes(
             "files_changed": files_result.stdout,
             "statistics": stat_result.stdout,
             "commits": commits_result.stdout,
-            "diff": diff_content if include_diff else "Diff not included (set include_diff=true to see full diff)"
+            "diff": diff_content if include_diff else "Diff not included (set include_diff=true to see full diff)",
+            "truncated": truncated,
+            "total_diff_lines": len(diff_lines) if include_diff else 0
         }
 
         return json.dumps(analysis, indent=2)
 
     except subprocess.CalledProcessError as e:
-        return f"Error analyzing changes: {e.stderr}"
+        return json.dumps({"error": f"Git error: {e.stderr}"})
     except Exception as e:
-        return f"Error: {str(e)}"
+        return json.dumps({"error": str(e)})
 
 
 @mcp.tool()

projects/unit3/slack-notification/starter/server.py

@@ -22,18 +22,20 @@
 EVENTS_FILE = Path(__file__).parent / "github_events.json"
 
 
-# ===== Tools from Modules 1 & 2 (Complete) =====
+# ===== Tools from Modules 1 & 2 (Complete with output limiting) =====
 
 @mcp.tool()
 async def analyze_file_changes(
     base_branch: str = "main",
-    include_diff: bool = True
+    include_diff: bool = True,
+    max_diff_lines: int = 500
 ) -> str:
     """Get the full diff and list of changed files in the current git repository.
     
     Args:
         base_branch: Base branch to compare against (default: main)
         include_diff: Include the full diff content (default: true)
+        max_diff_lines: Maximum number of diff lines to include (default: 500)
     """
     try:
         # Get list of changed files
@@ -53,13 +55,23 @@ async def analyze_file_changes(
 
         # Get the actual diff if requested
         diff_content = ""
+        truncated = False
         if include_diff:
             diff_result = subprocess.run(
                 ["git", "diff", f"{base_branch}...HEAD"],
                 capture_output=True,
                 text=True
             )
-            diff_content = diff_result.stdout
+            diff_lines = diff_result.stdout.split('\n')
+            
+            # Check if we need to truncate
+            if len(diff_lines) > max_diff_lines:
+                diff_content = '\n'.join(diff_lines[:max_diff_lines])
+                diff_content += f"\n\n... Output truncated. Showing {max_diff_lines} of {len(diff_lines)} lines ..."
+                diff_content += "\n... Use max_diff_lines parameter to see more ..."
+                truncated = True
+            else:
+                diff_content = diff_result.stdout
 
         # Get commit messages for context
         commits_result = subprocess.run(
@@ -73,15 +85,17 @@ async def analyze_file_changes(
             "files_changed": files_result.stdout,
             "statistics": stat_result.stdout,
             "commits": commits_result.stdout,
-            "diff": diff_content if include_diff else "Diff not included (set include_diff=true to see full diff)"
+            "diff": diff_content if include_diff else "Diff not included (set include_diff=true to see full diff)",
+            "truncated": truncated,
+            "total_diff_lines": len(diff_lines) if include_diff else 0
         }
 
         return json.dumps(analysis, indent=2)
 
     except subprocess.CalledProcessError as e:
-        return f"Error analyzing changes: {e.stderr}"
+        return json.dumps({"error": f"Git error: {e.stderr}"})
     except Exception as e:
-        return f"Error: {str(e)}"
+        return json.dumps({"error": str(e)})
 
 
 @mcp.tool()