fix: resolve variable shadowing bug causing all crates to return 'unwind' as name

The get_crate_summary function had a critical variable shadowing issue where
the crate name was being overwritten by module names in a loop. The last
module processed (often 'unwind') would replace the actual crate name.

Changes:
- Rename loop variable from 'name' to 'module_name' to prevent shadowing
- Remove unnecessary WHERE crate_id = 1 clauses (each DB has single crate)
- Update mcp_server.py tool names to snake_case for consistency
- Document bug and solution in UsefulInformation.json

The bug only affected MCP mode and was causing incorrect crate names in API
responses despite correct data in the database.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: Peter

UsefulInformation.json

@@ -1,6 +1,6 @@
 {
   "projectName": "docsrs-mcp",
-  "lastUpdated": "2025-08-16",
+  "lastUpdated": "2025-08-18",
   "purpose": "Track errors, solutions, and lessons learned during development",
   "categories": {
     "errorSolutions": {
@@ -542,6 +542,30 @@
           "relatedFiles": ["src/docsrs_mcp/mcp_tools.py"],
           "codeExample": "# Standard pattern for all tools:\nasync def tool_function(crate_name: str, ...):\n    # Always attempt ingestion first\n    db_path = await ingest_crate(crate_name, session)\n    if not db_path:\n        raise ValueError(f'Failed to ingest crate: {crate_name}')\n    \n    # Proceed with tool logic\n    return process_data(db_path, ...)",
           "debuggingTechnique": "Review all tool implementations to verify consistent auto-ingestion pattern usage"
+        },
+        {
+          "error": "Variable Shadowing Bug - All Crates Returning 'unwind' as Name",
+          "rootCause": "Variable shadowing in get_crate_summary function at line 1103 of app.py. The crate name variable was being overwritten by module names in a loop processing crate modules. The last module processed ('unwind') would replace the actual crate name.",
+          "solution": "Rename loop variable from 'name' to 'module_name' to prevent shadowing the crate name variable when unpacking tuples in the module processing loop.",
+          "context": "All crates returning 'unwind' as their name in MCP mode, breaking crate identification and search functionality",
+          "implementation": [
+            "Changed loop variable from 'name' to 'module_name' in tuple unpacking",
+            "Preserved original crate name variable throughout function execution",
+            "Fixed variable scope isolation to prevent unintended overwrites"
+          ],
+          "lesson": "Always check for variable shadowing in loops, especially when unpacking tuples. Loop variables can accidentally overwrite outer scope variables if named identically.",
+          "pattern": "Use descriptive, scope-specific variable names in loops to avoid shadowing: use 'module_name' instead of 'name' when processing modules",
+          "dateEncountered": "2025-08-18",
+          "relatedFiles": ["src/docsrs_mcp/app.py"],
+          "affectedLines": ["app.py:1103"],
+          "codeExample": "# Before (variable shadowing):\nfor name, path in modules:\n    # 'name' overwrites the crate name variable\n    \n# After (no shadowing):\nfor module_name, path in modules:\n    # 'module_name' doesn't conflict with crate name",
+          "debuggingTechnique": "Test with multiple different crates to verify each returns its correct name rather than the last processed module name",
+          "additionalNotes": [
+            "The hardcoded crate_id = 1 was also fixed but was NOT the cause of this specific bug",
+            "Old cached databases may need to be deleted and re-ingested if they contain corrupted data from previous buggy runs",
+            "This bug only affected MCP mode because the variable shadowing occurred in the get_crate_summary function"
+          ],
+          "warningFlags": "Variable shadowing, loop variable naming, tuple unpacking scope issues"
         }
       ]
     },
@@ -1741,6 +1765,31 @@
           "debuggingTechnique": "Check ingestion counts in database before running comparisons to identify incomplete data",
           "implementationDetails": "Added MIN_ITEMS_THRESHOLD check in version_diff.py using existing validation utilities from validation.py to provide actionable error messages explaining the issue",
           "impact": "Prevents misleading '0 changes' results and provides clear error messages when comparison data is insufficient"
+        },
+        {
+          "error": "getCrateSummary returning 'unwind' as name for all crates in MCP mode",
+          "context": "All crates return 'unwind' as the name field in getCrateSummary responses when using MCP mode, despite database containing correct crate names",
+          "investigation": {
+            "suspectedCause": "tools_to_fix dictionary in FastMCP schema override using camelCase operation_ids instead of snake_case tool names",
+            "attemptedFix": "Changed tool names from camelCase (getCrateSummary) to snake_case (get_crate_summary) in tools_to_fix dictionary",
+            "result": "Bug persists after schema override fix - root cause appears deeper than initially suspected"
+          },
+          "currentStatus": "Unresolved - database contains correct data, issue appears to be in response generation or serialization layer",
+          "debuggingFindings": [
+            "Database queries return correct crate names when tested directly",
+            "Issue specific to MCP mode - REST mode returns correct names",
+            "Schema override modification did not resolve the issue",
+            "Problem likely in FastMCP response serialization or field mapping"
+          ],
+          "nextSteps": [
+            "Investigate FastMCP response serialization logic",
+            "Check field mapping between database results and MCP responses",
+            "Test with simplified response models to isolate the issue",
+            "Compare MCP vs REST response generation pathways"
+          ],
+          "dateEncountered": "2025-08-16",
+          "relatedFiles": ["src/docsrs_mcp/mcp_server.py", "src/docsrs_mcp/mcp_tools.py", "src/docsrs_mcp/models.py"],
+          "impact": "All MCP clients receive incorrect crate names, affecting user experience and tool reliability"
         }
       ]
     },

src/docsrs_mcp/app.py

@@ -1080,8 +1080,7 @@ async def get_crate_summary(request: Request, params: GetCrateSummaryRequest):
                 """
                 SELECT name, path, parent_id, depth, item_count 
                 FROM modules 
-                WHERE crate_id = 1
-                  AND depth <= 3
+                WHERE depth <= 3
                   AND (item_count >= 2 OR depth = 0)
                   AND path NOT LIKE '%target::%'
                   AND path NOT LIKE '%.cargo::%'
@@ -1101,10 +1100,10 @@ async def get_crate_summary(request: Request, params: GetCrateSummaryRequest):
             # Additional filtering in Python for more complex patterns
             filtered_modules = []
             for row in all_rows:
-                name, path, parent_id, depth, item_count = row
+                module_name, path, parent_id, depth, item_count = row
 
                 # Skip internal/private modules (often start with underscore)
-                if name.startswith("_") and depth > 0:
+                if module_name.startswith("_") and depth > 0:
                     continue
 
                 # Skip generated modules
@@ -1117,7 +1116,7 @@ async def get_crate_summary(request: Request, params: GetCrateSummaryRequest):
                 # Include the module
                 filtered_modules.append(
                     CrateModule(
-                        name=name,
+                        name=module_name,
                         path=path,
                         parent_id=parent_id,
                         depth=depth,
@@ -1132,8 +1131,7 @@ async def get_crate_summary(request: Request, params: GetCrateSummaryRequest):
                     """
                     SELECT name, path, parent_id, depth, item_count 
                     FROM modules 
-                    WHERE crate_id = 1
-                      AND (depth <= 1 OR item_count >= 5)
+                    WHERE (depth <= 1 OR item_count >= 5)
                       AND path NOT LIKE '%target::%'
                       AND path NOT LIKE '%.cargo::%'
                     ORDER BY depth ASC, item_count DESC

src/docsrs_mcp/mcp_server.py

@@ -75,32 +75,33 @@ async def override_fastmcp_schemas():
             # Each tool maps to parameters that need type override and their original types
             # We track original types for logging/debugging purposes
             tools_to_fix = {
-                "searchItems": {
+                "search_items": {
                     "k": "integer",  # Number of results
                     "min_doc_length": "integer",  # Min doc length filter
                     "has_examples": "boolean",  # Filter for examples
                     "deprecated": "boolean",  # Deprecation filter
                 },
-                "startPreIngestion": {
+                "start_pre_ingestion": {
                     "count": "integer",  # Number of crates to ingest
                     "concurrency": "integer",  # Parallel workers
                     "force": "boolean",  # Force restart flag
                 },
-                "ingestCargoFile": {
+                "ingest_cargo_file": {
                     "concurrency": "integer",  # Parallel workers
                     "skip_existing": "boolean",  # Skip already ingested
                     "resolve_versions": "boolean",  # Resolve version specs
                 },
-                "compareVersions": {
+                "compare_versions": {
                     "include_unchanged": "boolean",  # Include unchanged items
                     "max_results": "integer",  # Max changes to return
                 },
-                "searchExamples": {
+                "get_crate_summary": {},  # Only has string parameters
+                "search_examples": {
                     "k": "integer"  # Number of examples
                 },
                 # These tools have no problematic parameters but are listed for completeness
-                "listVersions": {},  # Only has string parameters
-                "controlPreIngestion": {},  # Only has enum parameters
+                "list_versions": {},  # Only has string parameters
+                "control_pre_ingestion": {},  # Only has enum parameters
             }
 
             # Iterate through tools and modify their schemas