fix: resolve list_versions Pydantic validation error

Add missing fields to response models to match service layer output:
- Add is_latest field to VersionInfo model
- Add latest field to ListVersionsResponse model

The service layer was returning these fields but strict validation
(extra='forbid') was rejecting them, causing 100% failure for
version listing functionality.

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

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

Author: Peter

Architecture.md

@@ -519,6 +519,7 @@ The models package implements a **modular, function-based split** that maintains
 - Response formatting with consistent field naming
 - Integration with FastAPI automatic documentation
 - **Phase 2 Enhancement**: `SearchResult` and `GetItemDocResponse` now include `is_stdlib: bool` and `is_dependency: bool` fields for enhanced filtering and context
+- **Version Response Models**: `VersionInfo` includes `is_latest: bool` field, `ListVersionsResponse` includes `latest: str | None` field for version metadata
 
 **models/version_diff.py (~245 LOC)**
 - Version comparison and change tracking models
@@ -3974,6 +3975,38 @@ PATH_ALIASES = {
 - **Performance**: O(1) alias lookup before O(n) fuzzy matching
 - **Extensible**: Alias dictionary can be expanded based on usage patterns
 
+### Pydantic Validation Error Fix in list_versions
+
+**Location**: `models/responses.py` - VersionInfo and ListVersionsResponse models
+
+**Issue Description**:
+The list_versions service endpoint was failing with Pydantic validation errors due to field mismatch between service layer responses and response model definitions.
+
+**Root Cause Analysis**:
+- Service layer was returning "is_latest" and "latest" fields in version data
+- Response models (VersionInfo and ListVersionsResponse) didn't declare these fields
+- Pydantic's strict validation rejected the extra fields, causing endpoint failures
+
+**Fix Implementation**:
+```python
+# Fixed VersionInfo model
+class VersionInfo(BaseModel):
+    version: str
+    yanked: bool | None = None
+    is_latest: bool = Field(False, description="Whether this is the latest version of the crate")
+
+# Fixed ListVersionsResponse model  
+class ListVersionsResponse(BaseModel):
+    versions: list[VersionInfo]
+    latest: str | None = Field(None, description="Latest version string")
+```
+
+**Impact Assessment**:
+- **Pre-Fix**: Complete failure of list_versions endpoint due to validation errors
+- **Post-Fix**: Successful version listing with proper latest version metadata
+- **Architectural Benefit**: Ensures service layer and response model field alignment
+- **Data Integrity**: Maintains type safety while supporting version metadata requirements
+
 ### Known Architectural Issues Requiring Defensive Programming
 
 The following section documents architectural issues identified in four key features that require defensive programming improvements to prevent runtime failures.
@@ -9188,6 +9221,11 @@ class MCPTool(BaseModel):
     )
 ```
 
+**Service Layer Model Alignment**:
+- **Critical Requirement**: Service layer response data must exactly match response model field definitions
+- **Validation Enforcement**: Pydantic models validate that service layer returns only declared fields to prevent validation errors
+- **Field Consistency**: Any new fields returned by services (like `is_latest`, `latest`) must be added to corresponding response models before implementation
+
 ### Tutorial Content Embedding
 
 Tutorial content is embedded directly in the `get_mcp_manifest()` function rather than loaded from external files, following the same pattern established by the `start_pre_ingestion` tool:

UsefulInformation.json

@@ -2619,6 +2619,20 @@
             "defaultImplementation": "Default CLI flag changed from 'fastmcp' to 'sdk' for new users"
           },
           "architecturalBenefits": "Official SDK's @server.tool() decorator pattern is cleaner and more maintainable than FastMCP conversion patterns"
+        },
+        {
+          "error": "Extra inputs are not permitted - list_versions Pydantic validation failure",
+          "rootCause": "Service layer returned 'is_latest' field in VersionInfo and 'latest' field in root response, but Pydantic models used strict validation with extra='forbid' and these fields were missing from model definitions",
+          "solution": "Added missing fields to Pydantic response models: 'is_latest: bool = Field(False, description=\"Whether this is the latest version of the crate\")' to VersionInfo model and 'latest: str | None = Field(None, description=\"Latest version string\")' to ListVersionsResponse model",
+          "context": "list_versions API endpoint failing due to mismatch between service layer output and response model definition when using strict Pydantic validation",
+          "problem": "Service layer included additional fields not defined in Pydantic models, causing validation errors when models used ConfigDict(extra='forbid') for security",
+          "prevention": "Always ensure service layer output matches response model fields exactly when using strict validation. Keep service layer and response models in sync during development",
+          "pattern": "When using extra='forbid' in Pydantic models, all service layer output fields must be explicitly defined in the model schema",
+          "dateEncountered": "2025-08-25",
+          "relatedFiles": ["src/docsrs_mcp/models/responses.py", "src/docsrs_mcp/service/version_service.py"],
+          "codeExample": "# Added to VersionInfo model:\nis_latest: bool = Field(False, description=\"Whether this is the latest version of the crate\")\n\n# Added to ListVersionsResponse model:\nlatest: str | None = Field(None, description=\"Latest version string\")\n\n# Root cause - service returned extra fields:\nresponse_data = {\n    'versions': [...],\n    'latest': '1.2.3',  # This field was missing from model\n    # ... other fields\n}\n\n# Each VersionInfo contained:\n{\n    'version': '1.0.0',\n    'is_latest': False,  # This field was missing from model\n    # ... other fields\n}",
+          "debuggingTechnique": "Check service layer output fields against Pydantic model definitions when using strict validation to identify missing fields",
+          "impact": "Fixed list_versions endpoint validation errors and ensured proper response structure for version listing functionality"
         }
       ]
     },

src/docsrs_mcp/models/responses.py

@@ -118,13 +118,16 @@ class VersionInfo(BaseModel):
     """
     Crate version information.
 
-    Represents a single version of a crate with its yanked status.
+    Represents a single version of a crate with its yanked status and latest indicator.
     """
 
     version: str = Field(..., description="Version string (e.g., '1.0.0')")
     yanked: bool = Field(
         False, description="Whether this version has been yanked from crates.io"
     )
+    is_latest: bool = Field(
+        False, description="Whether this is the latest version of the crate"
+    )
 
     model_config = strict_config
 
@@ -303,6 +306,7 @@ class ListVersionsResponse(BaseModel):
 
     crate_name: str = Field(..., description="Name of the crate")
     versions: list[VersionInfo] = Field(..., description="List of cached versions")
+    latest: str | None = Field(None, description="Latest version string")
 
     model_config = strict_config