d365fo-client 0.3.0__py3-none-any.whl → 0.3.2__py3-none-any.whl

d365fo_client/mcp/tools/json_service_tools.py

@@ -0,0 +1,326 @@
+"""JSON service tools for MCP server."""
+
+import json
+import logging
+import time
+from typing import Any, Dict, List, Optional
+
+from mcp import Tool
+from mcp.types import TextContent
+
+from ..client_manager import D365FOClientManager
+
+logger = logging.getLogger(__name__)
+
+
+class JsonServiceTools:
+    """JSON service tools for the MCP server."""
+
+    def __init__(self, client_manager: D365FOClientManager):
+        """Initialize JSON service tools.
+
+        Args:
+            client_manager: D365FO client manager instance
+        """
+        self.client_manager = client_manager
+
+    def get_tools(self) -> List[Tool]:
+        """Get list of JSON service tools.
+
+        Returns:
+            List of Tool definitions
+        """
+        return [
+            self._get_call_json_service_tool(),
+            self._get_call_sql_diagnostic_service_tool(),
+        ]
+
+    def _get_call_json_service_tool(self) -> Tool:
+        """Get generic JSON service call tool definition."""
+        return Tool(
+            name="d365fo_call_json_service",
+            description="Call a D365 F&O JSON service endpoint using the /api/services pattern. This provides a generic way to invoke any JSON service operation in D365 F&O.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "serviceGroup": {
+                        "type": "string",
+                        "description": "Service group name (e.g., 'SysSqlDiagnosticService')",
+                    },
+                    "serviceName": {
+                        "type": "string", 
+                        "description": "Service name (e.g., 'SysSqlDiagnosticServiceOperations')",
+                    },
+                    "operationName": {
+                        "type": "string",
+                        "description": "Operation name (e.g., 'GetAxSqlExecuting')",
+                    },
+                    "parameters": {
+                        "type": "object",
+                        "description": "Optional parameters to send in the POST body",
+                        "additionalProperties": True,
+                    },
+                    "profile": {
+                        "type": "string",
+                        "description": "Configuration profile to use (optional - uses default profile if not specified)",
+                    },
+                },
+                "required": ["serviceGroup", "serviceName", "operationName"],
+            },
+        )
+
+    def _get_call_sql_diagnostic_service_tool(self) -> Tool:
+        """Get SQL diagnostic service tool definition with predefined operations."""
+        return Tool(
+            name="d365fo_call_sql_diagnostic_service",
+            description="Call SQL diagnostic service operations for D365 F&O performance monitoring. Provides convenient access to common SQL diagnostic operations.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "operation": {
+                        "type": "string",
+                        "enum": [
+                            "GetAxSqlExecuting",
+                            "GetAxSqlResourceStats", 
+                            "GetAxSqlBlocking",
+                            "GetAxSqlLockInfo",
+                            "GetAxSqlDisabledIndexes",
+                        ],
+                        "description": "SQL diagnostic operation to execute",
+                    },
+                    "parameters": {
+                        "type": "object",
+                        "description": "Operation-specific parameters",
+                        "properties": {
+                            "start": {
+                                "type": "string",
+                                "description": "Start date/time (ISO format) for GetAxSqlResourceStats",
+                            },
+                            "end": {
+                                "type": "string", 
+                                "description": "End date/time (ISO format) for GetAxSqlResourceStats",
+                            },
+                            "sinceLastMinutes": {
+                                "type": "integer",
+                                "description": "Alternative to start/end - get stats for last N minutes",
+                                "minimum": 1,
+                                "maximum": 1440,
+                            },
+                        },
+                    },
+                    "profile": {
+                        "type": "string",
+                        "description": "Configuration profile to use (optional - uses default profile if not specified)",
+                    },
+                },
+                "required": ["operation"],
+            },
+        )
+
+    async def execute_call_json_service(self, arguments: dict) -> List[TextContent]:
+        """Execute generic JSON service call tool.
+
+        Args:
+            arguments: Tool arguments
+
+        Returns:
+            List of TextContent responses
+        """
+        try:
+            start_time = time.time()
+            profile = arguments.get("profile", "default")
+            
+            service_group = arguments["serviceGroup"]
+            service_name = arguments["serviceName"]
+            operation_name = arguments["operationName"]
+            parameters = arguments.get("parameters")
+
+            # Get client and call service
+            client = await self.client_manager.get_client(profile)
+            response = await client.post_json_service(
+                service_group=service_group,
+                service_name=service_name,
+                operation_name=operation_name,
+                parameters=parameters,
+            )
+
+            execution_time = time.time() - start_time
+
+            # Format response
+            result = {
+                "success": response.success,
+                "statusCode": response.status_code,
+                "data": response.data,
+                "executionTimeMs": round(execution_time * 1000, 2),
+                "serviceGroup": service_group,
+                "serviceName": service_name,
+                "operationName": operation_name,
+            }
+
+            if response.error_message:
+                result["errorMessage"] = response.error_message
+
+            return [
+                TextContent(
+                    type="text",
+                    text=json.dumps(result, indent=2, default=str),
+                )
+            ]
+
+        except Exception as e:
+            logger.error(f"Error calling JSON service: {e}")
+            error_result = {
+                "success": False,
+                "error": str(e),
+                "serviceGroup": arguments.get("serviceGroup"),
+                "serviceName": arguments.get("serviceName"),
+                "operationName": arguments.get("operationName"),
+            }
+            return [
+                TextContent(
+                    type="text",
+                    text=json.dumps(error_result, indent=2),
+                )
+            ]
+
+    async def execute_call_sql_diagnostic_service(self, arguments: dict) -> List[TextContent]:
+        """Execute SQL diagnostic service call tool.
+
+        Args:
+            arguments: Tool arguments
+
+        Returns:
+            List of TextContent responses
+        """
+        try:
+            start_time = time.time()
+            profile = arguments.get("profile", "default")
+            operation = arguments["operation"]
+            parameters = arguments.get("parameters", {})
+
+            # Prepare service call parameters
+            service_group = "SysSqlDiagnosticService"
+            service_name = "SysSqlDiagnosticServiceOperations"
+
+            # Handle special parameter processing for GetAxSqlResourceStats
+            service_parameters = None
+            if operation == "GetAxSqlResourceStats":
+                service_parameters = self._prepare_resource_stats_parameters(parameters)
+            elif parameters:
+                service_parameters = parameters
+
+            # Get client and call service
+            client = await self.client_manager.get_client(profile)
+            response = await client.post_json_service(
+                service_group=service_group,
+                service_name=service_name,
+                operation_name=operation,
+                parameters=service_parameters,
+            )
+
+            execution_time = time.time() - start_time
+
+            # Format response
+            result = {
+                "success": response.success,
+                "statusCode": response.status_code,
+                "data": response.data,
+                "executionTimeMs": round(execution_time * 1000, 2),
+                "operation": operation,
+                "parameters": service_parameters,
+            }
+
+            if response.error_message:
+                result["errorMessage"] = response.error_message
+
+            # Add operation-specific formatting
+            if response.success and response.data:
+                result["summary"] = self._format_operation_summary(operation, response.data)
+
+            return [
+                TextContent(
+                    type="text",
+                    text=json.dumps(result, indent=2, default=str),
+                )
+            ]
+
+        except Exception as e:
+            logger.error(f"Error calling SQL diagnostic service: {e}")
+            error_result = {
+                "success": False,
+                "error": str(e),
+                "operation": arguments.get("operation"),
+            }
+            return [
+                TextContent(
+                    type="text",
+                    text=json.dumps(error_result, indent=2),
+                )
+            ]
+
+    def _prepare_resource_stats_parameters(self, parameters: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        """Prepare parameters for GetAxSqlResourceStats operation.
+
+        Args:
+            parameters: Input parameters
+
+        Returns:
+            Formatted parameters for the service call
+        """
+        from datetime import datetime, timezone, timedelta
+
+        if "sinceLastMinutes" in parameters:
+            # Convert sinceLastMinutes to start/end dates
+            minutes = parameters["sinceLastMinutes"]
+            end_time = datetime.now(timezone.utc)
+            start_time = end_time - timedelta(minutes=minutes)
+            
+            return {
+                "start": start_time.isoformat(),
+                "end": end_time.isoformat(),
+            }
+        elif "start" in parameters and "end" in parameters:
+            # Use provided start/end dates
+            return {
+                "start": parameters["start"],
+                "end": parameters["end"],
+            }
+        else:
+            # Default to last 10 minutes
+            end_time = datetime.now(timezone.utc)
+            start_time = end_time - timedelta(minutes=10)
+            
+            return {
+                "start": start_time.isoformat(),
+                "end": end_time.isoformat(),
+            }
+
+    def _format_operation_summary(self, operation: str, data: Any) -> Dict[str, Any]:
+        """Format operation-specific summary information.
+
+        Args:
+            operation: Operation name
+            data: Response data
+
+        Returns:
+            Summary information
+        """
+        summary = {"operation": operation}
+
+        if isinstance(data, list):
+            summary["recordCount"] = str(len(data))
+            
+            if operation == "GetAxSqlExecuting":
+                summary["description"] = f"Found {len(data)} currently executing SQL statements"
+            elif operation == "GetAxSqlResourceStats":
+                summary["description"] = f"Retrieved {len(data)} SQL resource statistics records"
+            elif operation == "GetAxSqlBlocking":
+                summary["description"] = f"Found {len(data)} SQL blocking situations"
+            elif operation == "GetAxSqlLockInfo":
+                summary["description"] = f"Retrieved {len(data)} SQL lock information records"
+            elif operation == "GetAxSqlDisabledIndexes":
+                summary["description"] = f"Found {len(data)} disabled indexes"
+        else:
+            summary["description"] = f"Operation {operation} completed successfully"
+
+        return summary

d365fo_client/models.py

@@ -693,6 +693,51 @@ class SearchResults:
         }
 
 
+# ============================================================================
+# JSON Service Models
+# ============================================================================
+
+
+@dataclass
+class JsonServiceRequest:
+    """Request for D365 F&O JSON service endpoint"""
+    
+    service_group: str
+    service_name: str
+    operation_name: str
+    parameters: Optional[Dict[str, Any]] = None
+    
+    def get_endpoint_path(self) -> str:
+        """Get the endpoint path for the service"""
+        return f"/api/services/{self.service_group}/{self.service_name}/{self.operation_name}"
+    
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "service_group": self.service_group,
+            "service_name": self.service_name,
+            "operation_name": self.operation_name,
+            "parameters": self.parameters
+        }
+
+
+@dataclass 
+class JsonServiceResponse:
+    """Response from D365 F&O JSON service endpoint"""
+    
+    success: bool
+    data: Any
+    status_code: int
+    error_message: Optional[str] = None
+    
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "success": self.success,
+            "data": self.data,
+            "status_code": self.status_code,
+            "error_message": self.error_message
+        }
+
+
 # ============================================================================
 # Enhanced V2 Models for Advanced Metadata Caching
 # ============================================================================

d365fo_client/odata_serializer.py

@@ -0,0 +1,300 @@
+"""OData serialization utilities for D365 F&O client.
+
+This module provides shared OData value serialization functionality
+that can be used by both QueryBuilder and other components requiring
+type-aware OData serialization.
+"""
+
+import logging
+from typing import Any, Dict, Optional, TYPE_CHECKING
+from urllib.parse import quote
+
+if TYPE_CHECKING:
+    from .models import PublicEntityInfo, PublicEntityPropertyInfo
+
+logger = logging.getLogger(__name__)
+
+
+class ODataSerializer:
+    """Shared OData value serialization utilities.
+    
+    This class provides comprehensive OData serialization support for all
+    D365 Finance & Operations data types, ensuring proper URL encoding
+    and OData protocol compliance.
+    """
+
+    @staticmethod
+    def serialize_value(value: Any, data_type: str, type_name: str) -> str:
+        """Serialize a value according to OData protocol standards based on data type.
+
+        Handles all OData EDM types and D365 F&O specific ODataXppType values.
+
+        Args:
+            value: The value to serialize
+            data_type: The simplified data type (e.g., "String", "Int32", "DateTime")
+            type_name: The full OData type name (e.g., "Edm.String", "Edm.Int32")
+
+        Returns:
+            Properly serialized value for OData URL
+        """
+        if value is None:
+            return "null"
+
+        # Convert to string first
+        str_value = str(value)
+
+        # Handle different data types according to OData standards and D365 F&O ODataXppType
+        if data_type in [
+            "String", 
+            "Guid", 
+            "Binary", 
+            "Memo", 
+            "Container", 
+            "VarString",
+            "Record",  # D365 F&O ODataXppType.RECORD
+        ]:
+            # String-like types need URL encoding
+            # D365 F&O specific types:
+            # - VarString: variable-length string type
+            # - Memo: long text fields
+            # - Container: binary/container data (ODataXppType.CONTAINER)
+            # - Record: complex record type (ODataXppType.RECORD)
+            return quote(str_value, safe="")
+
+        elif data_type in [
+            "Int32",
+            "Int64", 
+            "Decimal",
+            "Double",
+            "Single",
+            "Real",  # D365 F&O ODataXppType.REAL - floating-point numbers
+            "Float",
+            "Money",  # D365 F&O currency type
+            "Byte",
+            "SByte",
+            "Int16",
+            "UInt16",
+            "UInt32",
+            "UInt64",
+            "Number",  # Generic numeric type
+        ]:
+            # Numeric types don't need quotes or special encoding
+            # Real is D365 F&O's primary floating-point type (ODataXppType.REAL)
+            # Money handles currency values with proper decimal precision
+            return str_value
+
+        elif data_type == "Boolean":
+            # Boolean values should be lowercase
+            return (
+                str_value.lower()
+                if str_value.lower() in ["true", "false"]
+                else str_value
+            )
+
+        elif data_type in [
+            "DateTime", 
+            "DateTimeOffset", 
+            "Date",  # D365 F&O ODataXppType.DATE - date only
+            "Time",  # D365 F&O ODataXppType.TIME - time only
+            "UtcDateTime",  # D365 F&O ODataXppType.UTC_DATETIME - UTC timezone
+        ]:
+            # DateTime values need special formatting
+            # OData expects ISO 8601 format: YYYY-MM-DDTHH:MM:SS.fffZ
+            # D365 F&O specific types:
+            # - Date: date only (YYYY-MM-DD)
+            # - Time: time only (HH:MM:SS)  
+            # - UtcDateTime: full datetime with UTC timezone
+            if "T" in str_value and (
+                "Z" in str_value or "+" in str_value or str_value.count("-") > 2
+            ):
+                # Already in ISO format
+                return quote(str_value, safe="")
+            else:
+                # Try to handle common formats - for now, pass through with encoding
+                return quote(str_value, safe="")
+
+        elif data_type == "Enum":
+            # Enum values need the full qualified name from type_name
+            # e.g., Microsoft.Dynamics.DataEntities.NoYes'Yes'
+            # Corresponds to D365 F&O ODataXppType.ENUM
+            if "Microsoft.Dynamics.DataEntities." in type_name:
+                # Value should already be in the correct enum format
+                return quote(str_value, safe="")
+            else:
+                # Default enum handling
+                return quote(str_value, safe="")
+
+        elif data_type == "Void":
+            # D365 F&O ODataXppType.VOID - represents void/empty values
+            return "null"
+
+        else:
+            # Default: treat as string and URL encode
+            # Log warning only for truly unknown types (not common variations)
+            if data_type not in [
+                "Text", "Char", "Character", "Varchar", "NVarchar", "LongText",
+                "ShortText", "Description", "Name", "Code", "Id", "Key"
+            ]:
+                logger.warning(
+                    f"Unknown data type '{data_type}' for OData serialization, treating as string"
+                )
+            return quote(str_value, safe="")
+
+    @staticmethod
+    def serialize_key_dict(
+        key_dict: Dict[str, Any], 
+        entity_schema: Optional["PublicEntityInfo"] = None
+    ) -> Dict[str, str]:
+        """Serialize key dictionary with proper data type handling.
+
+        Args:
+            key_dict: Dictionary of key field names to values
+            entity_schema: Optional entity schema for type-aware serialization
+
+        Returns:
+            Dictionary with properly serialized key values (URL-encoded but not OData-quoted)
+        """
+        serialized_dict = {}
+
+        if entity_schema:
+            # Create property lookup for efficient access
+            property_lookup = {prop.name: prop for prop in entity_schema.properties}
+
+            for field_name, field_value in key_dict.items():
+                prop = property_lookup.get(field_name)
+                if prop:
+                    # Serialize value according to property data type
+                    # For key formatting, we need URL encoding but not OData quoting yet
+                    serialized_value = ODataSerializer._serialize_for_key(
+                        field_value,
+                        prop.data_type or "String",
+                        prop.type_name or "Edm.String",
+                    )
+                    serialized_dict[field_name] = serialized_value
+                else:
+                    # Fallback: treat as string (URL encode but don't quote)
+                    serialized_dict[field_name] = quote(str(field_value), safe="")
+        else:
+            # No schema available - fallback to string serialization
+            for field_name, field_value in key_dict.items():
+                serialized_dict[field_name] = quote(str(field_value), safe="")
+
+        return serialized_dict
+
+    @staticmethod
+    def _serialize_for_key(value: Any, data_type: str, type_name: str) -> str:
+        """Serialize a value for use in OData keys (URL-encoded, no OData quotes).
+
+        Args:
+            value: The value to serialize
+            data_type: The simplified data type
+            type_name: The full OData type name
+
+        Returns:
+            URL-encoded value ready for key formatting
+        """
+        if value is None:
+            return "null"
+
+        # Convert to string first
+        str_value = str(value)
+
+        # Handle different data types - URL encode when needed but don't add OData quotes
+        if data_type in [
+            "String", "Guid", "Binary", "Memo", "Container", "VarString",
+            "Record", "Text", "Char", "Character", "Varchar", "NVarchar",
+            "LongText", "ShortText", "Description", "Name", "Code", "Id", "Key"
+        ]:
+            # String-like types need URL encoding
+            return quote(str_value, safe="")
+
+        elif data_type in [
+            "DateTime", "DateTimeOffset", "Date", "Time", "UtcDateTime"
+        ]:
+            # DateTime values need URL encoding
+            return quote(str_value, safe="")
+
+        elif data_type == "Enum":
+            # Enum values need URL encoding
+            return quote(str_value, safe="")
+
+        elif data_type == "Boolean":
+            # Boolean values should be lowercase, no encoding needed
+            return str_value.lower() if str_value.lower() in ["true", "false"] else str_value
+
+        elif data_type in [
+            "Int32", "Int64", "Decimal", "Double", "Single", "Real", "Float",
+            "Money", "Byte", "SByte", "Int16", "UInt16", "UInt32", "UInt64", "Number"
+        ]:
+            # Numeric types don't need URL encoding
+            return str_value
+
+        elif data_type == "Void":
+            return "null"
+
+        else:
+            # Default: treat as string and URL encode
+            return quote(str_value, safe="")
+
+    @staticmethod
+    def format_composite_key(
+        key_dict: Dict[str, str], 
+        entity_schema: Optional["PublicEntityInfo"] = None
+    ) -> str:
+        """Format a composite key dictionary into OData key string.
+
+        Args:
+            key_dict: Dictionary of serialized key field names to values
+            entity_schema: Optional entity schema for determining quote requirements
+
+        Returns:
+            Formatted composite key string (e.g., "key1='value1',key2=123")
+        """
+        key_parts = []
+
+        if entity_schema:
+            # Use schema information to determine if quotes are needed
+            property_lookup = {prop.name: prop for prop in entity_schema.properties}
+
+            for key_name, key_value in key_dict.items():
+                prop = property_lookup.get(key_name)
+                if prop and ODataSerializer._needs_quotes(prop.data_type):
+                    # String-like types need quotes
+                    key_parts.append(f"{key_name}='{key_value}'")
+                elif prop and not ODataSerializer._needs_quotes(prop.data_type):
+                    # Numeric, boolean types don't need quotes
+                    key_parts.append(f"{key_name}={key_value}")
+                else:
+                    # Unknown property - default to string behavior (needs quotes)
+                    key_parts.append(f"{key_name}='{key_value}'")
+        else:
+            # No schema - default to quoting all values (backward compatibility)
+            for key_name, key_value in key_dict.items():
+                key_parts.append(f"{key_name}='{key_value}'")
+
+        return ",".join(key_parts)
+
+    @staticmethod
+    def _needs_quotes(data_type: str) -> bool:
+        """Determine if a data type needs quotes in OData key formatting.
+
+        Args:
+            data_type: The data type to check
+
+        Returns:
+            True if the data type needs quotes, False otherwise
+        """
+        # String-like types need quotes
+        string_types = {
+            "String", "Guid", "Binary", "Memo", "Container", "VarString", 
+            "Record", "Enum", "Text", "Char", "Character", "Varchar", 
+            "NVarchar", "LongText", "ShortText", "Description", "Name", 
+            "Code", "Id", "Key"
+        }
+        
+        # Date/time types need quotes for URL encoding
+        datetime_types = {
+            "DateTime", "DateTimeOffset", "Date", "Time", "UtcDateTime"
+        }
+        
+        return data_type in string_types or data_type in datetime_types