# Parameter Validation Guide for Session-MGMT-MCP
This comprehensive guide covers the implementation and usage of Pydantic parameter validation models for improved type safety and error handling across all MCP tools.
## Table of Contents
1. [Implementation Summary](#implementation-summary)
1. [Quick Start Guide](#quick-start-guide)
1. [Available Parameter Models](#available-parameter-models)
1. [Migration Examples](#migration-examples)
1. [Validation Features](#validation-features)
1. [Best Practices](#best-practices)
1. [Error Handling](#error-handling)
1. [Testing Parameter Models](#testing-parameter-models)
1. [Integration Patterns](#integration-patterns)
## Implementation Summary
### 🎯 Mission Accomplished
Successfully added comprehensive Pydantic parameter validation models for MCP tools, improving type safety and providing consistent validation patterns across all tools.
### 📁 Files Created/Modified
#### ✅ New Files Created
1. **`session_buddy/parameter_models.py`** (266 lines)
- Complete Pydantic parameter validation models library
- Reusable models for common MCP tool parameter patterns
- Helper functions for validation and integration
1. **`session_buddy/tools/validated_memory_tools.py`** (190 lines)
- Practical integration examples showing parameter validation in action
- Demonstrates migration from manual validation to Pydantic models
- Complete working examples with error handling
1. **`tests/unit/test_parameter_models.py`** (38 test cases, 100% passing)
- Comprehensive test coverage for all validation scenarios
- Edge case testing and property validation
- Integration tests for realistic workflows
1. **`docs/developer/PARAMETER_VALIDATION.md`** (This file)
- Complete migration guide with before/after examples
- Best practices and integration patterns
- Troubleshooting and usage examples
## Quick Start Guide
### 1. Basic Parameter Validation
The `session_buddy.parameter_models` module provides:
- **Reusable Pydantic models** for common parameter patterns
- **Type-safe validation** with descriptive error messages
- **Consistent constraints** across all MCP tools
- **Integration helpers** for easy adoption
```text
from session_buddy.parameter_models import SearchQueryParams, validate_mcp_params
@mcp.tool()
async def search_reflections(
query: str, limit: int = 10, project: str | None = None, min_score: float = 0.7
) -> str:
try:
# Validate all parameters at once
validated = validate_mcp_params(
SearchQueryParams,
query=query,
limit=limit,
project=project,
min_score=min_score,
)
# Use validated parameters (guaranteed to be valid)
query = validated["query"] # Non-empty, 1-1000 chars
limit = validated["limit"] # 1-1000 range
project = validated.get("project") # None or valid project name
min_score = validated["min_score"] # 0.0-1.0 range
# Implementation with confidence in parameter validity...
return f"Searching for '{query}' with limit {limit}"
except ValueError as e:
return f"❌ Parameter validation error: {e}"
```
## Available Parameter Models
### 🏗️ Core Building Blocks
- **`WorkingDirectoryParams`** - Directory path validation with existence checks
- **`ProjectContextParams`** - Project identifier validation (1-200 chars)
- **`SearchLimitParams`** - Pagination and result limits (1-1,000)
- **`TimeRangeParams`** - Time-based filtering (1-3,650 days)
- **`ScoreThresholdParams`** - Relevance scoring (0.0-1.0)
- **`TagParams`** - Tag format validation (alphanumeric + hyphens/underscores)
- **`IDParams`** - Entity identifier validation
- **`FilePathParams`** - File path format validation
### 🔧 Composite Models for MCP Tools
- **`SearchQueryParams`** - Complete search parameters
- **`ReflectionStoreParams`** - Reflection storage with content validation (1-50,000 chars)
- **`FileSearchParams`** - File-based search parameters
- **`ConceptSearchParams`** - Development concept search
- **`TeamUserParams`** - Team user management with email validation
- **`TeamCreationParams`** - Team creation parameters
- **`CrackerjackExecutionParams`** - Command execution with working directory
- **`SessionInitParams`** & **`SessionStatusParams`** - Session management
## Migration Examples
### Before: Manual Validation
```text
@mcp.tool()
async def store_reflection(content: str, tags: list[str] | None = None) -> str:
# Manual validation - error-prone and inconsistent
if not content or not content.strip():
return "❌ Content cannot be empty"
if len(content) > 50000:
return "❌ Content too long (max 50,000 characters)"
if tags:
for tag in tags:
if not isinstance(tag, str):
return "❌ Tags must be strings"
if len(tag) > 50:
return "❌ Tag too long"
if not tag.replace("-", "").replace("_", "").isalnum():
return "❌ Invalid tag format"
# Implementation...
```
### After: Pydantic Validation
```text
from session_buddy.parameter_models import ReflectionStoreParams, validate_mcp_params
@mcp.tool()
async def store_reflection(content: str, tags: list[str] | None = None) -> str:
try:
# All validation in one line
validated = validate_mcp_params(
ReflectionStoreParams, content=content, tags=tags
)
# Parameters are guaranteed valid
content = validated["content"] # Non-empty, 1-50,000 chars
tags = validated.get("tags") # None or valid tag list
# Implementation...
return f"✅ Stored reflection with {len(tags) if tags else 0} tags"
except ValueError as e:
return f"❌ {e}"
```
## Validation Features
### 1. **Type-Safe Validation**
```text
# Before: Manual validation, error-prone
if not query or not query.strip():
return "❌ Query cannot be empty"
# After: Automatic validation with Pydantic
validated = validate_mcp_params(SearchQueryParams, **params)
query = validated["query"] # Guaranteed non-empty, 1-1000 chars
```
### 2. **Consistent Error Messages**
```text
# Standardized validation errors across all tools
"❌ Parameter validation failed: query: ensure this value has at least 1 characters"
"❌ Parameter validation failed: min_score: ensure this value is less than or equal to 1.0"
```
### 3. **Smart Data Normalization**
```python
# Automatic path expansion
working_directory="~/project" → "/Users/user/project"
# Tag normalization
tags=[" Python ", "ASYNC"] → ["python", "async"]
# Email validation with proper format checking
```
### 4. String Validation
```python
# Non-empty strings with length limits
content: str = Field(min_length=1, max_length=50000)
# Trimmed and normalized
query: str # Automatically stripped of whitespace
# Pattern validation for special fields
email: str # Basic email format validation
```
### 5. Path Validation
```python
# Automatic path expansion
working_directory: str # ~/project -> /Users/user/project
# Existence validation
working_directory: str # Must exist and be a directory
# Format validation
file_path: str # No null characters, basic format checks
```
### 6. Numeric Constraints
```python
# Range validation
limit: int = Field(ge=1, le=1000) # 1-1000 inclusive
min_score: float = Field(ge=0.0, le=1.0) # 0.0-1.0 inclusive
timeout: int = Field(ge=1, le=3600) # 1 second to 1 hour
```
### 7. Tag Validation
```python
# Automatic normalization
tags: ["Python", " ASYNC "] -> ["python", "async"]
# Format validation
valid_tags = ["python", "async-await", "database_orm"]
invalid_tags = ["python!", "tag with spaces", "tag@symbol"]
# Length limits
max_tag_length = 50 # characters
```
### 8. Enum Validation
```text
# Strict enum validation
role: Literal["owner", "admin", "moderator", "contributor", "viewer"]
access_level: Literal["private", "team", "public"]
dependency_type: Literal["uses", "extends", "references", "shares_code"]
```
## Best Practices
### 1. Use Appropriate Models
```text
# For simple working directory operations
validate_mcp_params(WorkingDirectoryParams, working_directory=wd)
# For search operations
validate_mcp_params(SearchQueryParams, query=q, limit=l, min_score=s)
# For team operations
validate_mcp_params(TeamUserParams, user_id=uid, username=name, role=role)
```
### 2. Handle Validation Errors Gracefully
```text
@mcp.tool()
async def my_tool(**params) -> str:
try:
validated = validate_mcp_params(MyParamsModel, **params)
# ... implementation
except ValueError as e:
# Log the error for debugging
logger.warning(f"Parameter validation failed: {e}")
# Return user-friendly error
return f"❌ Invalid parameters: {e}"
except Exception as e:
# Handle unexpected errors
logger.exception(f"Tool execution failed: {e}")
return f"❌ Tool execution failed: {e}"
```
### 3. Leverage Validation Features
```python
# Use path expansion
params = WorkingDirectoryParams(working_directory="~/project")
expanded_path = params.working_directory # /Users/user/project
# Use tag normalization
params = TagParams(tags=[" Python ", "ASYNC"])
normalized_tags = params.tags # ["python", "async"]
# Use None exclusion
validated = validate_mcp_params(SearchParams, query="test", project=None)
# 'project' key won't be in validated dict
```
## Error Handling
The validation system provides clear, actionable error messages:
```python
# Empty content
"❌ Parameter validation failed: content: ensure this value has at least 1 characters"
# Invalid score range
"❌ Parameter validation failed: min_score: ensure this value is less than or equal to 1.0"
# Invalid tag format
"❌ Parameter validation failed: tags: Tags must contain only letters, numbers, hyphens, and underscores: invalid@tag"
# Multiple validation errors
"❌ Parameter validation failed: query: ensure this value has at least 1 characters; limit: ensure this value is greater than or equal to 1"
```
## Testing Parameter Models
```text
import pytest
from pydantic import ValidationError
from session_buddy.parameter_models import SearchQueryParams
def test_valid_search_params():
"""Test valid parameter validation."""
params = SearchQueryParams(query="python async", limit=20, min_score=0.8)
assert params.query == "python async"
assert params.limit == 20
assert params.min_score == 0.8
def test_invalid_search_params():
"""Test invalid parameter validation."""
with pytest.raises(ValidationError):
SearchQueryParams(query="", limit=0) # Empty query, invalid limit
def test_parameter_defaults():
"""Test default parameter values."""
params = SearchQueryParams(query="test")
assert params.limit == 10 # Default
assert params.min_score == 0.7 # Default
```
### 📊 Test Coverage & Quality
- **38 test cases** covering all validation scenarios
- **77.12% coverage** on parameter_models.py (tested lines)
- **Edge case testing** for boundary conditions
- **Integration testing** for realistic workflows
- **Property-based validation** for complex constraints
## Integration Patterns
### Pattern 1: Helper Function Integration
```text
@mcp.tool()
async def search_reflections(**params) -> str:
try:
validated = validate_mcp_params(SearchQueryParams, **params)
# Use validated parameters...
except ValueError as e:
return f"❌ Parameter validation error: {e}"
```
### Pattern 2: Direct Model Usage
```text
def validate_and_process(params: SearchQueryParams):
# Parameters are already validated
return process_search(params.query, params.limit)
```
### Pattern 3: Inheritance and Composition
```text
class SearchQueryParams(ProjectContextParams, SearchLimitParams, ScoreThresholdParams):
# Inherits validation from all parent classes
query: str = Field(min_length=1, max_length=1000)
```
### Integration with FastMCP
The parameter models work seamlessly with FastMCP's `@mcp.tool()` decorator:
```text
@mcp.tool()
async def enhanced_search(
query: str, limit: int = 10, project: str | None = None, min_score: float = 0.7
) -> str:
"""Enhanced search with parameter validation.
Args:
query: Search query text (1-1,000 chars)
limit: Maximum results to return (1-1,000)
project: Optional project identifier (1-200 chars)
min_score: Minimum relevance score (0.0-1.0)
"""
# Validation and implementation...
```
## Custom Parameter Models
Create custom models for specific use cases:
```python
from pydantic import BaseModel, Field
from session_buddy.parameter_models import NonEmptyStringMixin, PathValidationMixin
class CustomToolParams(BaseModel, NonEmptyStringMixin, PathValidationMixin):
"""Custom parameters for specialized tool."""
tool_specific_field: str = Field(
min_length=1, max_length=100, description="Tool-specific parameter"
)
optional_path: str | None = Field(
default=None, description="Optional path that will be expanded"
)
complexity_level: Literal["simple", "moderate", "complex"] = Field(
default="moderate", description="Complexity level for processing"
)
```
## Benefits Achieved
### ✅ **Developer Experience**
- **Reduced boilerplate**: No more manual validation code
- **Type safety**: Guaranteed parameter validity
- **IDE support**: Full autocomplete and type hints
- **Error clarity**: Descriptive validation messages
### ✅ **Code Quality**
- **DRY principle**: Reusable validation across tools
- **Consistency**: Same validation patterns everywhere
- **Maintainability**: Centralized validation logic
- **Testability**: Easy to test parameter edge cases
### ✅ **User Experience**
- **Better error messages**: Clear, actionable feedback
- **Input normalization**: Automatic cleanup (trim, lowercase tags)
- **Path expansion**: User-friendly path handling (~/ expansion)
- **Format validation**: Prevent invalid inputs early
## 🎯 Following Crackerjack Patterns
### **EVERY LINE IS A LIABILITY**
- Focused, single-responsibility models
- No over-engineering or unnecessary complexity
- Minimal code for maximum functionality
### **DRY (Don't Repeat Yourself)**
- Reusable validation patterns across all tools
- Inheritance for common parameter combinations
- Helper functions for validation logic
### **KISS (Keep It Simple, Stupid)**
- Simple, clear validation without over-engineering
- Straightforward integration patterns
- Easy-to-understand error messages
## 🔄 Migration Impact
**Before**: 15+ lines of manual validation per tool
**After**: 1-3 lines with automatic validation
**Example reduction**:
```text
# Before: 15 lines of manual validation
if not content or not content.strip():
return "❌ Content cannot be empty"
if len(content) > 50000:
return "❌ Content too long"
# ... more validation code
# After: 1 line with Pydantic
validated = validate_mcp_params(ReflectionStoreParams, **params)
```
## Migration Checklist
- [ ] **Identify parameter patterns** in existing tools
- [ ] **Choose appropriate parameter models** from the library
- [ ] **Add validation calls** to tool implementations
- [ ] **Update error handling** to use validation errors
- [ ] **Add parameter documentation** with constraints
- [ ] **Write tests** for parameter validation
- [ ] **Update tool docstrings** with parameter details
## 📈 Next Steps for Full Integration
1. **Migrate existing tools** to use parameter validation models
1. **Update documentation** with parameter constraints
1. **Add more specialized models** as needed for specific tools
1. **Integrate with FastMCP** native parameter validation when available
## ✨ Summary
This comprehensive parameter validation implementation provides a production-ready foundation for type-safe MCP tool parameters that:
- **Improves reliability** through consistent validation
- **Reduces development time** with reusable patterns
- **Enhances user experience** with clear error messages
- **Maintains code quality** following crackerjack principles
The parameter validation system is now ready for integration across all MCP tools in the session-buddy project, with complete documentation, testing, and examples available for immediate use.
## Examples in Action
See the complete examples in:
- `session_buddy/tools/validated_memory_tools.py` - Full integration examples
- `tests/unit/test_parameter_models.py` - Comprehensive test suite
- `session_buddy/parameter_models.py` - All available models and utilities
