MCP Nautobot Server

# MCP Nautobot Server Optimization Recommendations ## Executive Summary Based on analysis of the current implementation and Nautobot API best practices, this document outlines critical optimizations needed to make the MCP server suitable for AI agent applications, particularly for Vista's enterprise network management use cases. ## Current Issues Identified 1. **Response Format Issues** - Server returns Python dict representation instead of proper JSON - Causes parsing errors in AI agents expecting standard JSON - HttpUrl objects are not serializable 2. **Performance Inefficiencies** - No depth control for nested objects - Full object details returned even when not needed - No support for field selection - Large response sizes for simple queries 3. **Limited Filtering Capabilities** - Missing site-based filtering for devices - No support for multiple filter values - No advanced query capabilities 4. **Missing Enterprise Features** - No device-specific tools for warranty/EOL data - No bulk operations support - No GraphQL support for complex queries - No caching mechanism ## Recommended Optimizations ### 1. Response Format Standardization ```python # Fix JSON serialization import json from pydantic.json import pydantic_encoder # In handle_call_tool: result = { "count": len(items), "filters_applied": filters, "results": [item.model_dump(mode='json') for item in items] } return [ types.TextContent( type="text", text=json.dumps(result, indent=2, default=pydantic_encoder) ) ] ``` ### 2. Add Depth Control for Performance ```python # Add depth parameter to all tools async def get_devices( site: Optional[str] = None, depth: int = 0, # 0=minimal, 1=standard, 2=detailed fields: Optional[List[str]] = None, # Specific fields to include exclude_fields: Optional[List[str]] = None, # Fields to exclude limit: int = 50, offset: int = 0 ): """Get devices with optimized response size.""" params = { "depth": depth, "limit": limit, "offset": offset } if fields: params["include"] = ",".join(fields) if exclude_fields: params["exclude"] = ",".join(exclude_fields) ``` ### 3. New Tool: get_devices Essential for Vista's device management use cases: ```python types.Tool( name="get_devices", description="Retrieve network devices with warranty and lifecycle info", inputSchema={ "type": "object", "properties": { "site": { "type": "string", "description": "Site name (e.g., 'reno', 'berlin')" }, "device_type": { "type": "string", "description": "Device type (e.g., 'router', 'switch', 'firewall')" }, "manufacturer": { "type": "string", "description": "Manufacturer name (e.g., 'Cisco', 'Juniper')" }, "model": { "type": "string", "description": "Device model" }, "status": { "type": "string", "description": "Device status" }, "include_warranty": { "type": "boolean", "description": "Include warranty/EOL data", "default": false }, "depth": { "type": "integer", "description": "Response detail level (0-2)", "default": 0, "minimum": 0, "maximum": 2 }, "fields": { "type": "array", "items": {"type": "string"}, "description": "Specific fields to include" }, "limit": { "type": "integer", "default": 50, "maximum": 200 } } } ) ``` ### 4. Implement Smart Filtering ```python # Support multiple values and advanced operators def build_filter_params(filters: Dict[str, Any]) -> Dict[str, Any]: """Build API filter parameters with support for operators.""" params = {} for key, value in filters.items(): if isinstance(value, list): # Multiple values (OR condition) params[key] = ",".join(str(v) for v in value) elif isinstance(value, dict) and "operator" in value: # Advanced operators op = value["operator"] val = value["value"] if op == "contains": params[f"{key}__ic"] = val # Case-insensitive contains elif op == "startswith": params[f"{key}__isw"] = val elif op == "gt": params[f"{key}__gt"] = val # Add more operators as needed else: params[key] = value return params ``` ### 5. Add Caching Layer ```python from functools import lru_cache from datetime import datetime, timedelta class CachedNautobotClient: def __init__(self, client: NautobotClient, cache_ttl: int = 300): self.client = client self.cache_ttl = cache_ttl self._cache = {} async def get_with_cache(self, cache_key: str, fetch_func, *args, **kwargs): """Get data with caching.""" now = datetime.now() if cache_key in self._cache: cached_data, timestamp = self._cache[cache_key] if now - timestamp < timedelta(seconds=self.cache_ttl): return cached_data # Fetch fresh data data = await fetch_func(*args, **kwargs) self._cache[cache_key] = (data, now) return data ``` ### 6. GraphQL Support for Complex Queries ```python types.Tool( name="graphql_query", description="Execute GraphQL queries for complex data retrieval", inputSchema={ "type": "object", "properties": { "query": { "type": "string", "description": "GraphQL query string" }, "variables": { "type": "object", "description": "Query variables" } }, "required": ["query"] } ) # Implementation async def execute_graphql(query: str, variables: Optional[Dict] = None): """Execute GraphQL query against Nautobot.""" response = await client.post( "/api/graphql/", json={"query": query, "variables": variables or {}} ) return response.json() ``` ### 7. Bulk Operations Support ```python types.Tool( name="bulk_update_devices", description="Update multiple devices efficiently", inputSchema={ "type": "object", "properties": { "device_ids": { "type": "array", "items": {"type": "string"}, "description": "List of device IDs to update" }, "updates": { "type": "object", "description": "Fields to update" } }, "required": ["device_ids", "updates"] } ) ``` ## AI Agent Integration Best Practices ### 1. Structured Response Templates Provide consistent response formats that AI agents can reliably parse: ```python class StandardResponse(BaseModel): success: bool count: int data: List[Dict] metadata: Dict[str, Any] error: Optional[str] = None def to_ai_format(self) -> str: """Format for AI consumption.""" if self.error: return f"Error: {self.error}" return f""" Found {self.count} results. Data: {json.dumps(self.data, indent=2)} Metadata: - Filters: {self.metadata.get('filters', 'None')} - Page: {self.metadata.get('page', 1)} - Total Pages: {self.metadata.get('total_pages', 1)} """ ``` ### 2. Intent-Based Tools Create high-level tools that match user intents: ```python types.Tool( name="find_devices_needing_refresh", description="Find devices approaching EOL or needing updates", inputSchema={ "type": "object", "properties": { "months_until_eol": { "type": "integer", "description": "Months until EOL threshold", "default": 12 }, "include_warranty_expired": { "type": "boolean", "default": true } } } ) ``` ### 3. Progressive Data Loading Implement tools that start with minimal data and allow drilling down: ```python # First call: Get device summary devices = await get_devices(site="reno", depth=0, fields=["name", "model", "status"]) # Second call: Get details for specific device device_detail = await get_device_by_id( device_id="abc123", depth=2, include_warranty=True, include_interfaces=True ) ``` ## Implementation Priority 1. **High Priority (Week 1)** - Fix JSON serialization issues - Add depth control to existing tools - Implement get_devices tool - Add basic caching 2. **Medium Priority (Week 2)** - Advanced filtering capabilities - GraphQL support - Bulk operations - Response templates 3. **Low Priority (Week 3+)** - Intent-based tools - Advanced caching strategies - Performance monitoring - Rate limiting optimizations ## Expected Benefits 1. **Performance Improvements** - 70-90% reduction in response size with depth=0 - 50% faster response times for common queries - Reduced API load on Nautobot server 2. **Better AI Agent Experience** - Consistent, parseable responses - Contextual data retrieval - Support for complex queries 3. **Enterprise Features** - Device lifecycle management - Bulk operations for efficiency - Site-specific queries for distributed teams ## Monitoring and Metrics Track these metrics to measure optimization success: - Average response time per tool - Response size distribution - Cache hit rate - Error rate by tool type - Most common query patterns ## Conclusion These optimizations will transform the MCP Nautobot server from a basic API wrapper into an enterprise-ready AI agent integration platform, specifically optimized for Vista's network management needs. The improvements focus on performance, usability, and reliability while maintaining backward compatibility.