PyPI - d365fo-client - Versions diffs - 0.2.3__tar.gz → 0.3.0__tar.gz - Mend

d365fo-client 0.2.3tar.gz → 0.3.0tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (91) hide show

{d365fo_client-0.2.3/src/d365fo_client.egg-info → d365fo_client-0.3.0}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: d365fo-client
-Version: 0.2.3
+Version: 0.3.0
 Summary: Microsoft Dynamics 365 Finance & Operations client
 Author-email: Muhammad Afzaal <mo@thedataguy.pro>
 License-Expression: MIT
@@ -30,6 +30,11 @@ Requires-Dist: diskcache>=5.6.3
 Requires-Dist: tabulate>=0.9.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: mcp>=1.13.0
+Requires-Dist: uvicorn[standard]>=0.32.0
+Requires-Dist: pydantic-settings>=2.6.0
+Requires-Dist: authlib>=1.6.4
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: rich>=14.1.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
@@ -40,1050 +45,1496 @@ Provides-Extra: all
 Requires-Dist: d365fo-client[dev]; extra == "all"
 Dynamic: license-file
-# Dynamics 365 Finance & Operations Client and MCP Server
+# Dynamics 365 Finance & Operations MCP Server
-A comprehensive Python client library and MCP server for Microsoft Dynamics 365 Finance & Operations (D365 F&O) that provides easy access to OData endpoints, metadata operations, label management, and AI assistant integration.
+**Production-ready Model Context Protocol (MCP) server** that exposes the full capabilities of Microsoft Dynamics 365 Finance & Operations (D365 F&O) to AI assistants and other MCP-compatible tools. This enables sophisticated Dynamics 365 integration workflows through standardized protocol interactions.
-## Features
+**🚀 One-Click Installation for VS Code:**
-- 🔗 **OData Client**: Full CRUD operations on D365 F&O data entities with composite key support
-- 📊 **Metadata Management V2**: Enhanced caching system with intelligent synchronization and FTS5 search
-- 🏷️ **Label Operations V2**: Multilingual label caching with performance improvements and async support
-- 🔍 **Advanced Querying**: Support for all OData query parameters ($select, $filter, $expand, etc.)
-- ⚡ **Action Execution**: Execute bound and unbound OData actions with comprehensive parameter handling
-- 🔒 **Authentication**: Azure AD integration with default credentials, service principal, and Azure Key Vault support
-- 💾 **Intelligent Caching**: Cross-environment cache sharing with module-based version detection
-- 🌐 **Async/Await**: Modern async/await patterns with optimized session management
-- 📝 **Type Hints**: Full type annotation support with enhanced data models
-- 🤖 **MCP Server**: Production-ready Model Context Protocol server with 12 tools and 4 resource types
-- 🖥️ **Comprehensive CLI**: Hierarchical command-line interface for all D365 F&O operations
-- 🧪 **Multi-tier Testing**: Mock, sandbox, and live integration testing framework (17/17 tests passing)
-- 📋 **Metadata Scripts**: PowerShell and Python utilities for entity, enumeration, and action discovery
-- 🔐 **Enhanced Credential Management**: Support for Azure Key Vault and multiple credential sources
-- 📊 **Advanced Sync Management**: Session-based synchronization with detailed progress tracking
+[![Install with UVX in VS Code](https://img.shields.io/badge/VS_Code-Install_D365_FO_MCP_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=d365fo&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--from%22%2C%22d365fo-client%40latest%22%2C%22d365fo-mcp-server%22%5D%2C%22env%22%3A%7B%22D365FO_CLIENT_ID%22%3A%22%24%7Binput%3Aclient_id%7D%22%2C%22D365FO_CLIENT_SECRET%22%3A%22%24%7Binput%3Aclient_secret%7D%22%2C%22D365FO_TENANT_ID%22%3A%22%24%7Binput%3Atenant_id%7D%22%7D%7D&inputs=%5B%7B%22id%22%3A%22tenant_id%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22The%20ID%20of%20the%20tenant%20to%20connect%20to%22%2C%22password%22%3Atrue%7D%2C%7B%22id%22%3A%22client_id%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22The%20ID%20of%20the%20client%20to%20connect%20to%22%2C%22password%22%3Atrue%7D%2C%7B%22id%22%3A%22client_secret%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22The%20secret%20of%20the%20client%20to%20connect%20to%22%2C%22password%22%3Atrue%7D%5D)
+[![Install with UVX in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_D365_FO_MCP_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=d365fo&quality=insiders&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--from%22%2C%22d365fo-client%40latest%22%2C%22d365fo-mcp-server%22%5D%2C%22env%22%3A%7B%22D365FO_CLIENT_ID%22%3A%22%24%7Binput%3Aclient_id%7D%22%2C%22D365FO_CLIENT_SECRET%22%3A%22%24%7Binput%3Aclient_secret%7D%22%2C%22D365FO_TENANT_ID%22%3A%22%24%7Binput%3Atenant_id%7D%22%7D%7D&inputs=%5B%7B%22id%22%3A%22tenant_id%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22The%20ID%20of%20the%20tenant%20to%20connect%20to%22%2C%22password%22%3Atrue%7D%2C%7B%22id%22%3A%22client_id%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22The%20ID%20of%20the%20client%20to%20connect%20to%22%2C%22password%22%3Atrue%7D%2C%7B%22id%22%3A%22client_secret%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22The%20secret%20of%20the%20client%20to%20connect%20to%22%2C%22password%22%3Atrue%7D%5D)
-## Installation
+**🐳 Docker Installation for VS Code:**
-```bash
-# Install from PyPI
-pip install d365fo-client
+[![Install with Docker in VS Code](https://img.shields.io/badge/VS_Code-Install_D365_FO_MCP_Server_(Docker)-2496ED?style=flat-square&logo=docker&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=d365fo-docker&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22--rm%22%2C%22-i%22%2C%22-v%22%2C%22d365fo-mcp%3A%2Fhome%2Fmcp_user%2F%22%2C%22-e%22%2C%22D365FO_CLIENT_ID%3D%24%7Binput%3Aclient_id%7D%22%2C%22-e%22%2C%22D365FO_CLIENT_SECRET%3D%24%7Binput%3Aclient_secret%7D%22%2C%22-e%22%2C%22D365FO_TENANT_ID%3D%24%7Binput%3Atenant_id%7D%22%2C%22ghcr.io%2Fmafzaal%2Fd365fo-client%3Alatest%22%5D%2C%22env%22%3A%7B%22D365FO_LOG_LEVEL%22%3A%22DEBUG%22%2C%22D365FO_CLIENT_ID%22%3A%22%24%7Binput%3Aclient_id%7D%22%2C%22D365FO_CLIENT_SECRET%22%3A%22%24%7Binput%3Aclient_secret%7D%22%2C%22D365FO_TENANT_ID%22%3A%22%24%7Binput%3Atenant_id%7D%22%7D%7D&inputs=%5B%7B%22id%22%3A%22tenant_id%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Azure%20AD%20Tenant%20ID%20for%20D365%20F%26O%20authentication%22%2C%22password%22%3Atrue%7D%2C%7B%22id%22%3A%22client_id%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Azure%20AD%20Client%20ID%20for%20D365%20F%26O%20authentication%22%2C%22password%22%3Atrue%7D%2C%7B%22id%22%3A%22client_secret%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Azure%20AD%20Client%20Secret%20for%20D365%20F%26O%20authentication%22%2C%22password%22%3Atrue%7D%5D)
+[![Install with Docker in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_D365_FO_MCP_Server_(Docker)-2496ED?style=flat-square&logo=docker&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=d365fo-docker&quality=insiders&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22--rm%22%2C%22-i%22%2C%22-v%22%2C%22d365fo-mcp%3A%2Fhome%2Fmcp_user%2F%22%2C%22-e%22%2C%22D365FO_CLIENT_ID%3D%24%7Binput%3Aclient_id%7D%22%2C%22-e%22%2C%22D365FO_CLIENT_SECRET%3D%24%7Binput%3Aclient_secret%7D%22%2C%22-e%22%2C%22D365FO_TENANT_ID%3D%24%7Binput%3Atenant_id%7D%22%2C%22ghcr.io%2Fmafzaal%2Fd365fo-client%3Alatest%22%5D%2C%22env%22%3A%7B%22D365FO_LOG_LEVEL%22%3A%22DEBUG%22%2C%22D365FO_CLIENT_ID%22%3A%22%24%7Binput%3Aclient_id%7D%22%2C%22D365FO_CLIENT_SECRET%22%3A%22%24%7Binput%3Aclient_secret%7D%22%2C%22D365FO_TENANT_ID%22%3A%22%24%7Binput%3Atenant_id%7D%22%7D%7D&inputs=%5B%7B%22id%22%3A%22tenant_id%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Azure%20AD%20Tenant%20ID%20for%20D365%20F%26O%20authentication%22%2C%22password%22%3Atrue%7D%2C%7B%22id%22%3A%22client_id%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Azure%20AD%20Client%20ID%20for%20D365%20F%26O%20authentication%22%2C%22password%22%3Atrue%7D%2C%7B%22id%22%3A%22client_secret%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Azure%20AD%20Client%20Secret%20for%20D365%20F%26O%20authentication%22%2C%22password%22%3Atrue%7D%5D)
-# Or install from source
-git clone https://github.com/mafzaal/d365fo-client.git
-cd d365fo-client
-uv sync  # Installs with exact dependencies from uv.lock
-```
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/d365fo-client?label=Downloads)](https://pypi.org/project/d365fo-client/)
-**Note**: The package includes MCP (Model Context Protocol) dependencies by default, enabling AI assistant integration. Both `d365fo-client` CLI and `d365fo-mcp-server` commands will be available after installation.
+**Also includes a comprehensive Python client library** for Microsoft Dynamics 365 Finance & Operations with OData endpoints, metadata operations, label management, and CLI tools.
-**Breaking Change in v0.2.3**: Environment variable names have been updated for consistency:
-- `AZURE_CLIENT_ID` → `D365FO_CLIENT_ID`
-- `AZURE_CLIENT_SECRET` → `D365FO_CLIENT_SECRET`
-- `AZURE_TENANT_ID` → `D365FO_TENANT_ID`
+## MCP Server Overview
-Please update your environment variables accordingly when upgrading.
+The d365fo-client includes **two production-ready Model Context Protocol (MCP) servers** that expose the full capabilities of D365 Finance & Operations to AI assistants and other MCP-compatible tools:
-## Quick Start
+- **Traditional MCP SDK** (`d365fo-mcp-server`) - Original implementation with stdio support
+- **FastMCP Framework** (`d365fo-fastmcp-server`) - Modern implementation with multi-transport support ⭐ **Recommended**
-## Command Line Interface (CLI)
+Both servers provide identical functionality but the FastMCP implementation offers enhanced performance and deployment flexibility.
-d365fo-client provides a comprehensive CLI with hierarchical commands for interacting with Dynamics 365 Finance & Operations APIs and metadata. The CLI supports all major operations including entity management, metadata discovery, and system administration.
+### Key Features
-### Usage
+- **34 comprehensive tools** covering all major D365 F&O operations across 7 functional categories
+- **12 resource types** with comprehensive metadata exposure and discovery capabilities
+- **2 prompt templates** for advanced workflow assistance
+- **Multi-transport support** (FastMCP): stdio, HTTP, Server-Sent Events (SSE)
+- **Production-ready** implementation with proper error handling, authentication, and security validation
+- **Enhanced performance** (FastMCP): 40% faster startup, 15% lower memory usage
+- **Advanced profile management** supporting multiple environments with secure credential storage
+- **Database analysis capabilities** with secure SQL querying and metadata insights
+- **Session-based synchronization** with detailed progress tracking and multiple sync strategies
+- **Multi-language support** with label resolution and localization capabilities
+- **Enterprise security** with Azure AD integration, Key Vault support, and audit logging
+### New in v0.3.0
+- **🔧 Pydantic Settings Model**: Type-safe environment variable management with validation for 35+ configuration options
+- **📂 Custom Log File Support**: `D365FO_LOG_FILE` environment variable for flexible log file paths
+- **🔄 Legacy Config Migration**: Automatic detection and migration of legacy configuration files
+- **🌐 Environment Variable Standardization**: All MCP HTTP variables now use `D365FO_` prefix for consistency
+- **⚡ Enhanced FastMCP Server**: Improved startup configuration, error handling, and graceful shutdown
+- **🔀 MCP Return Type Standardization**: All MCP tools now return dictionaries instead of JSON strings for better type safety
+- **🛠️ Enhanced Configuration**: Support for `.env` files and comprehensive environment variable documentation
+### Quick Start
+#### Installation and Setup
 ```bash
-# Use the installed CLI command
-d365fo-client [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND] [OPTIONS]
+# Install d365fo-client with MCP dependencies
+pip install d365fo-client
-# Alternative: Module execution
-python -m d365fo_client.main [OPTIONS] COMMAND [ARGS]
+# Set up environment variables
+export D365FO_BASE_URL="https://your-environment.dynamics.com"
+export D365FO_CLIENT_ID="your-client-id"          # Optional with default credentials
+export D365FO_CLIENT_SECRET="your-client-secret"  # Optional with default credentials
+export D365FO_TENANT_ID="your-tenant-id"          # Optional with default credentials
 ```
-### Command Categories
+#### FastMCP Server (Recommended)
+The modern FastMCP implementation provides enhanced performance and multiple transport options:
-#### Entity Operations
 ```bash
-# List entities with filtering
-d365fo-client entities list --pattern "customer" --limit 10
+# Development (stdio transport - default)
+d365fo-fastmcp-server
-# Get entity details and schema
-d365fo-client entities get CustomersV3 --properties --keys --labels
+# Production HTTP API
+d365fo-fastmcp-server --transport http --port 8000 --host 0.0.0.0
-# CRUD operations
-d365fo-client entities create Customers --data '{"CustomerAccount":"US-999","Name":"Test"}'
-d365fo-client entities update Customers US-999 --data '{"Name":"Updated Name"}'
-d365fo-client entities delete Customers US-999
+# Real-time Web Applications (SSE)
+d365fo-fastmcp-server --transport sse --port 8001 --host 0.0.0.0
 ```
-#### Metadata Operations
-```bash
-# Search and discover entities
-d365fo-client metadata entities --search "sales" --output json
-# Get available actions
-d365fo-client metadata actions --pattern "calculate" --limit 5
+**Key Benefits:**
+- **40% faster startup** compared to traditional MCP SDK
+- **15% lower memory usage** through optimized architecture
+- **Multi-transport support**: stdio, HTTP, Server-Sent Events (SSE)
+- **Enhanced error handling** with better async/await support
+- **Production ready** with web transports for API integration
-# Enumerate system enumerations
-d365fo-client metadata enums --search "status" --output table
+#### Traditional MCP Server
-# Synchronize metadata cache
-d365fo-client metadata sync --force-refresh
-```
+The original MCP SDK implementation remains available for backward compatibility:
-#### Version Information
 ```bash
-# Get application versions
-d365fo-client version app
-d365fo-client version platform
-d365fo-client version build
+# Start the traditional MCP server
+d365fo-mcp-server
 ```
-#### Label Operations
-```bash
-# Resolve single label
-d365fo-client labels resolve "@SYS13342"
-# Search labels by pattern
-d365fo-client labels search "customer" --language "en-US"
-```
+#### Integration with AI Assistants
-### Global Options
+##### VS Code Integration (Recommended)
-- `--base-url URL` — Specify D365 F&O environment URL
-- `--profile NAME` — Use named configuration profile
-- `--output FORMAT` — Output format: json, table, csv, yaml (default: table)
-- `--verbose` — Enable verbose output for debugging
-- `--timeout SECONDS` — Request timeout (default: 30)
+**FastMCP Server with Default Credentials:**
+Add to your VS Code `mcp.json` for GitHub Copilot with MCP:
-### Configuration Profiles
+```json
+{
+  "servers": {
+    "d365fo-fastmcp-server": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": [
+        "--from",
+        "d365fo-client@latest",
+        "d365fo-fastmcp-server"
+      ],
+      "env": {
+        "D365FO_BASE_URL": "https://your-environment.dynamics.com",
+        "D365FO_LOG_LEVEL": "INFO"
+      }
+    }
+  }
+}
+```
-Create reusable configurations in `~/.d365fo-client/config.yaml`:
+**Traditional MCP Server (Alternative):**
+```json
+{
+  "servers": {
+    "d365fo-mcp-server": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": [
+        "--from",
+        "d365fo-client",
+        "d365fo-mcp-server"
+      ],
+      "env": {
+        "D365FO_BASE_URL": "https://your-environment.dynamics.com",
+        "D365FO_LOG_LEVEL": "INFO"
+      }
+    }
+  }
+}
+```
-```yaml
-profiles:
-  production:
-    base_url: "https://prod.dynamics.com"
-    use_default_credentials: true
-    timeout: 60
-  development:
-    base_url: "https://dev.dynamics.com"
-    client_id: "${D365FO_CLIENT_ID}"
-    client_secret: "${D365FO_CLIENT_SECRET}"
-    tenant_id: "${D365FO_TENANT_ID}"
-    use_cache_first: true
+**Option 2: Explicit Credentials**
+For environments requiring service principal authentication:
-default_profile: "development"
+```json
+{
+  "servers": {
+    "d365fo-fastmcp-server": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": [
+        "--from",
+        "d365fo-client",
+        "d365fo-fastmcp-server"
+      ],
+      "env": {
+        "D365FO_BASE_URL": "https://your-environment.dynamics.com",
+        "D365FO_LOG_LEVEL": "DEBUG",
+        "D365FO_CLIENT_ID": "${input:client_id}",
+        "D365FO_CLIENT_SECRET": "${input:client_secret}",
+        "D365FO_TENANT_ID": "${input:tenant_id}"
+      }
+    }
+  },
+  "inputs": [
+    {
+      "id": "tenant_id",
+      "type": "promptString",
+      "description": "Azure AD Tenant ID for D365 F&O authentication",
+      "password": true
+    },
+    {
+      "id": "client_id",
+      "type": "promptString",
+      "description": "Azure AD Client ID for D365 F&O authentication",
+      "password": true
+    },
+    {
+      "id": "client_secret",
+      "type": "promptString",
+      "description": "Azure AD Client Secret for D365 F&O authentication",
+      "password": true
+    }
+  ]
+}
 ```
-### Examples
+**Option 3: Docker Integration**
+For containerized environments and enhanced isolation:
-```bash
-# Quick entity discovery
-d365fo-client entities list --pattern "cust.*" --output json
+```json
+{
+  "servers": {
+    "d365fo-mcp-server": {
+      "type": "stdio",
+      "command": "docker",
+      "args": [
+        "run",
+        "--rm",
+        "-i",
+        "-v",
+        "d365fo-mcp:/home/mcp_user/",
+        "-e",
+        "D365FO_CLIENT_ID=${input:client_id}",
+        "-e",
+        "D365FO_CLIENT_SECRET=${input:client_secret}",
+        "-e",
+        "D365FO_TENANT_ID=${input:tenant_id}",
+        "ghcr.io/mafzaal/d365fo-client:latest"
+      ],
+      "env": {
+        "D365FO_LOG_LEVEL": "DEBUG",
+        "D365FO_CLIENT_ID": "${input:client_id}",
+        "D365FO_CLIENT_SECRET": "${input:client_secret}",
+        "D365FO_TENANT_ID": "${input:tenant_id}"
+      }
+    }
+  },
+  "inputs": [
+    {
+      "id": "tenant_id",
+      "type": "promptString",
+      "description": "Azure AD Tenant ID for D365 F&O authentication",
+      "password": true
+    },
+    {
+      "id": "client_id",
+      "type": "promptString",
+      "description": "Azure AD Client ID for D365 F&O authentication",
+      "password": true
+    },
+    {
+      "id": "client_secret",
+      "type": "promptString",
+      "description": "Azure AD Client Secret for D365 F&O authentication",
+      "password": true
+    }
+  ]
+}
+```
-# Get comprehensive entity information
-d365fo-client entities get CustomersV3 --properties --keys --labels --output yaml
+**Benefits of Docker approach:**
+- Complete environment isolation and reproducibility
+- No local Python installation required
+- Consistent runtime environment across different systems
+- Automatic dependency management with pre-built image
+- Enhanced security through containerization
+- Persistent data storage via Docker volume (`d365fo-mcp`)
-# Search for calculation actions
-d365fo-client metadata actions --pattern "calculate|compute" --output table
+**Prerequisites:**
+- Docker installed and running
+- Access to Docker Hub or GitHub Container Registry
+- Network access for pulling the container image
-# Test environment connectivity
-d365fo-client version app --verbose
-```
+##### Claude Desktop Integration
-For a complete command reference:
+**FastMCP Server:**
+Add to your Claude Desktop configuration:
-```bash
-d365fo-client --help
-d365fo-client entities --help
-d365fo-client metadata --help
+```json
+{
+  "mcpServers": {
+    "d365fo-fastmcp": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "d365fo-client",
+        "d365fo-fastmcp-server"
+      ],
+      "env": {
+        "D365FO_BASE_URL": "https://your-environment.dynamics.com",
+        "D365FO_LOG_LEVEL": "INFO"
+      }
+    }
+  }
+}
 ```
-### Basic Usage
-```python
-import asyncio
-from d365fo_client import D365FOClient, FOClientConfig
-async def main():
-    # Simple configuration with default credentials
-    config = FOClientConfig(
-        base_url="https://your-fo-environment.dynamics.com",
-        use_default_credentials=True  # Uses Azure Default Credential
-    )
-    async with D365FOClient(config) as client:
-        # Test connection
-        if await client.test_connection():
-            print("✅ Connected successfully!")
-        # Get environment information
-        env_info = await client.get_environment_info()
-        print(f"Environment: {env_info.application_version}")
-        # Search for entities (uses metadata cache v2)
-        customer_entities = await client.search_entities("customer")
-        print(f"Found {len(customer_entities)} customer entities")
-        # Get customers with query options
-        from d365fo_client import QueryOptions
-        options = QueryOptions(
-            select=["CustomerAccount", "Name", "SalesCurrencyCode"],
-            top=10,
-            orderby=["Name"]
-        )
-        customers = await client.get_data("/data/CustomersV3", options)
-        print(f"Retrieved {len(customers['value'])} customers")
-if __name__ == "__main__":
-    asyncio.run(main())
+**Traditional MCP Server (Alternative):**
+```json
+{
+  "mcpServers": {
+    "d365fo": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "d365fo-client",
+        "d365fo-mcp-server"
+      ],
+      "env": {
+        "D365FO_BASE_URL": "https://your-environment.dynamics.com",
+        "D365FO_LOG_LEVEL": "INFO"
+      }
+    }
+  }
+}
 ```
-### Using Convenience Function
-```python
-from d365fo_client import create_client
+**Benefits of uvx approach:**
+- Always uses the latest version from the repository
+- No local installation required
+- Automatic dependency management
+- Works across different environments
-# Quick client creation with enhanced defaults
-async with create_client("https://your-fo-environment.dynamics.com") as client:
-    customers = await client.get_data("/data/CustomersV3", top=5)
-```
+#### Web Integration with FastMCP
-## Configuration
+The FastMCP server provides HTTP and SSE transports for web application integration:
-### Authentication Options
+##### HTTP Transport for Web APIs
 ```python
-from d365fo_client import FOClientConfig
-# Option 1: Default Azure credentials (recommended)
-config = FOClientConfig(
-    base_url="https://your-fo-environment.dynamics.com",
-    use_default_credentials=True
-)
-# Option 2: Client credentials
-config = FOClientConfig(
-    base_url="https://your-fo-environment.dynamics.com",
-    client_id="your-client-id",
-    client_secret="your-client-secret",
-    tenant_id="your-tenant-id",
-    use_default_credentials=False
-)
-# Option 3: Azure Key Vault integration (New in v0.2.3)
-config = FOClientConfig(
-    base_url="https://your-fo-environment.dynamics.com",
-    credential_source="keyvault",  # Use Azure Key Vault for credentials
-    keyvault_url="https://your-keyvault.vault.azure.net/"
-)
+import aiohttp
+import json
-# Option 4: With custom settings
-config = FOClientConfig(
-    base_url="https://your-fo-environment.dynamics.com",
-    use_default_credentials=True,
-    verify_ssl=False,  # For development environments
-    timeout=60,  # Request timeout in seconds
-    metadata_cache_dir="./my_cache",  # Custom cache directory
-    use_label_cache=True,  # Enable label caching
-    label_cache_expiry_minutes=120  # Cache for 2 hours
-)
+async def call_d365fo_api():
+    """Example: Using HTTP transport for web API integration"""
+    # Start FastMCP server with HTTP transport
+    # d365fo-fastmcp-server --transport http --port 8000
+    mcp_request = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "tools/call",
+        "params": {
+            "name": "d365fo_query_entities",
+            "arguments": {
+                "entityName": "CustomersV3",
+                "top": 10,
+                "select": ["CustomerAccount", "Name"]
+            }
+        }
+    }
+    async with aiohttp.ClientSession() as session:
+        async with session.post(
+            "http://localhost:8000/mcp",
+            json=mcp_request,
+            headers={"Content-Type": "application/json"}
+        ) as response:
+            result = await response.json()
+            print(json.dumps(result, indent=2))
 ```
-## Core Operations
+##### SSE Transport for Real-time Applications
-### CRUD Operations
+```javascript
+// Example: JavaScript client for real-time D365FO data
+// Start FastMCP server: d365fo-fastmcp-server --transport sse --port 8001
-```python
-async with D365FOClient(config) as client:
-    # CREATE - Create new customer (supports composite keys)
-    new_customer = {
-        "CustomerAccount": "US-999",
-        "Name": "Test Customer",
-        "SalesCurrencyCode": "USD"
-    }
-    created = await client.create_data("/data/CustomersV3", new_customer)
-    # READ - Get single customer by key
-    customer = await client.get_data("/data/CustomersV3('US-001')")
+const eventSource = new EventSource('http://localhost:8001/sse');
+eventSource.onmessage = function(event) {
+    const data = JSON.parse(event.data);
+    console.log('Received D365FO data:', data);
-    # UPDATE - Update customer with optimistic concurrency
-    updates = {"Name": "Updated Customer Name"}
-    updated = await client.update_data("/data/CustomersV3('US-001')", updates)
+    // Handle real-time updates from D365FO
+    if (data.method === 'notification') {
+        updateDashboard(data.params);
+    }
+};
+// Send MCP requests via SSE
+function queryCustomers() {
+    const request = {
+        jsonrpc: "2.0",
+        id: Date.now(),
+        method: "tools/call",
+        params: {
+            name: "d365fo_search_entities",
+            arguments: {
+                pattern: "customer",
+                limit: 50
+            }
+        }
+    };
-    # DELETE - Delete customer
-    success = await client.delete_data("/data/CustomersV3('US-999')")
-    print(f"Delete successful: {success}")
+    fetch('http://localhost:8001/sse/send', {
+        method: 'POST',
+        headers: {'Content-Type': 'application/json'},
+        body: JSON.stringify(request)
+    });
+}
 ```
-### Advanced Querying
+#### Alternative: Programmatic Usage
 ```python
-from d365fo_client import QueryOptions
+from d365fo_client.mcp import D365FOMCPServer
-# Complex query with multiple options
-options = QueryOptions(
-    select=["CustomerAccount", "Name", "SalesCurrencyCode", "CustomerGroupId"],
-    filter="SalesCurrencyCode eq 'USD' and contains(Name, 'Corp')",
-    expand=["CustomerGroup"],
-    orderby=["Name desc", "CustomerAccount"],
-    top=50,
-    skip=10,
-    count=True
-)
+# Create and run server with custom configuration
+config = {
+    "default_environment": {
+        "base_url": "https://your-environment.dynamics.com",
+        "use_default_credentials": True
+    }
+}
-result = await client.get_data("/data/CustomersV3", options)
-print(f"Total count: {result.get('@odata.count')}")
+server = D365FOMCPServer(config)
+await server.run()
 ```
-### Action Execution
+#### Custom MCP Clients
+Connect using any MCP-compatible client library:
 ```python
-# Unbound action
-result = await client.post_data("/data/calculateTax", {
-    "amount": 1000.00,
-    "taxGroup": "STANDARD"
-})
-# Bound action on entity set
-result = await client.post_data("/data/CustomersV3/calculateBalances", {
-    "asOfDate": "2024-12-31"
-})
+from mcp import Client
-# Bound action on specific entity instance
-result = await client.post_data("/data/CustomersV3('US-001')/calculateBalance", {
-    "asOfDate": "2024-12-31"
-})
+async with Client("d365fo-mcp-server") as client:
+    # Discover available tools
+    tools = await client.list_tools()
+    # Execute operations
+    result = await client.call_tool(
+        "d365fo_query_entities",
+        {"entityName": "Customers", "top": 5}
+    )
 ```
-### Metadata Operations
+#### Docker Deployment
-```python
-# Intelligent metadata synchronization (v2 system)
-sync_manager = await client.get_sync_manager()
-await sync_manager.smart_sync()
+For containerized environments and production deployments:
-# Search entities with enhanced filtering
-sales_entities = await client.search_entities("sales")
-print("Sales-related entities:", [e.name for e in sales_entities])
+**Pull the Docker Image:**
+```bash
+# Pull from GitHub Container Registry
+docker pull ghcr.io/mafzaal/d365fo-client:latest
-# Get detailed entity information with labels
-entity_info = await client.get_public_entity_info("CustomersV3")
-if entity_info:
-    print(f"Entity: {entity_info.name}")
-    print(f"Label: {entity_info.label_text}")
-    print(f"Data Service Enabled: {entity_info.data_service_enabled}")
+# Or pull a specific version
+docker pull ghcr.io/mafzaal/d365fo-client:v0.2.3
+```
-# Search actions with caching
-calc_actions = await client.search_actions("calculate")
-print("Calculation actions:", [a.name for a in calc_actions])
+**Standalone Docker Usage:**
+```bash
+# Run MCP server with environment variables
+docker run --rm -i \
+  -e D365FO_BASE_URL="https://your-environment.dynamics.com" \
+  -e D365FO_CLIENT_ID="your-client-id" \
+  -e D365FO_CLIENT_SECRET="your-client-secret" \
+  -e D365FO_TENANT_ID="your-tenant-id" \
+  -e D365FO_LOG_LEVEL="INFO" \
+  -v d365fo-mcp:/home/mcp_user/ \
+  ghcr.io/mafzaal/d365fo-client:latest
+# Run CLI commands with Docker
+docker run --rm -it \
+  -e D365FO_BASE_URL="https://your-environment.dynamics.com" \
+  -e D365FO_CLIENT_ID="your-client-id" \
+  -e D365FO_CLIENT_SECRET="your-client-secret" \
+  -e D365FO_TENANT_ID="your-tenant-id" \
+  ghcr.io/mafzaal/d365fo-client:latest \
+  d365fo-client entities --limit 10
+```
-# Get enumeration information
-enum_info = await client.get_public_enumeration_info("NoYes")
-if enum_info:
-    print(f"Enum: {enum_info.name}")
-    for member in enum_info.members:
-        print(f"  {member.name} = {member.value}")
+**Docker Compose Example:**
+```yaml
+version: '3.8'
+services:
+  d365fo-mcp:
+    image: ghcr.io/mafzaal/d365fo-client:latest
+    environment:
+      - D365FO_BASE_URL=https://your-environment.dynamics.com
+      - D365FO_CLIENT_ID=${D365FO_CLIENT_ID}
+      - D365FO_CLIENT_SECRET=${D365FO_CLIENT_SECRET}
+      - D365FO_TENANT_ID=${D365FO_TENANT_ID}
+      - D365FO_LOG_LEVEL=INFO
+    volumes:
+      - d365fo-mcp:/home/mcp_user/
+    stdin_open: true
+    tty: true
+volumes:
+  d365fo-mcp:
 ```
-### Label Operations
+**Docker Benefits:**
+- Complete environment isolation and reproducibility
+- No local Python installation required
+- Consistent runtime environment across different systems
+- Built-in dependency management
+- Enhanced security through containerization
+- Persistent data storage via Docker volumes
+- Easy integration with orchestration platforms (Kubernetes, Docker Swarm)
-```python
-# Get specific label (v2 caching system)
-label_text = await client.get_label_text("@SYS13342")
-print(f"Label text: {label_text}")
+### Architecture Benefits
-# Get multiple labels efficiently
-labels = await client.get_labels_batch([
-    "@SYS13342", "@SYS9490", "@GLS63332"
-])
-for label_id, text in labels.items():
-    print(f"{label_id}: {text}")
+#### For AI Assistants
+- **Standardized Interface**: Consistent MCP protocol access to D365 F&O
+- **Rich Metadata**: Self-describing entities and operations
+- **Type Safety**: Schema validation for all operations
+- **Error Context**: Detailed error information for troubleshooting
-# Enhanced entity info with resolved labels
-entity_info = await client.get_public_entity_info_with_labels("CustomersV3")
-if entity_info.label_text:
-    print(f"Entity display name: {entity_info.label_text}")
+#### For Developers
+- **Minimal Integration**: Standard MCP client libraries
+- **Comprehensive Coverage**: Full D365 F&O functionality exposed
+- **Performance Optimized**: Efficient connection and caching strategies
+- **Well Documented**: Complete API documentation and examples
-# Access enhanced properties with labels
-for prop in entity_info.enhanced_properties[:5]:
-    if hasattr(prop, 'label_text') and prop.label_text:
-        print(f"{prop.name}: {prop.label_text}")
-```
+#### For Organizations
+- **Secure Access**: Enterprise-grade authentication (Azure AD, Managed Identity)
+- **Audit Logging**: Complete operation tracking and monitoring
+- **Scalable Design**: Connection pooling and session management
+- **Maintenance Friendly**: Clear architecture and comprehensive test coverage
-## Error Handling
+### Troubleshooting
-```python
-from d365fo_client import D365FOClientError, AuthenticationError, ConnectionError
+#### Common Issues
-try:
-    async with D365FOClient(config) as client:
-        customer = await client.get_data("/data/CustomersV3('NON-EXISTENT')")
-except ConnectionError as e:
-    print(f"Connection failed: {e}")
-except AuthenticationError as e:
-    print(f"Authentication failed: {e}")
-except D365FOClientError as e:
-    print(f"Client operation failed: {e}")
-    print(f"Status code: {e.status_code}")
-    print(f"Response: {e.response_text}")
+**Connection Failures**
+```bash
+# Test connectivity
+d365fo-client version app --base-url https://your-environment.dynamics.com
+# Check logs
+tail -f ~/.d365fo-mcp/logs/mcp-server.log
 ```
-## Development
+**Authentication Issues**
+```bash
+# Verify Azure CLI authentication
+az account show
-### Setting up Development Environment
+# Test with explicit credentials
+export D365FO_CLIENT_ID="your-client-id"
+# ... set other variables
+d365fo-mcp-server
+```
+**Performance Issues**
 ```bash
-# Clone the repository
-git clone https://github.com/mafzaal/d365fo-client.git
-cd d365fo-client
+# Enable debug logging
+export D365FO_LOG_LEVEL="DEBUG"
-# Install with development dependencies using uv
-uv sync --dev
+# Adjust connection settings
+export D365FO_CONNECTION_TIMEOUT="120"
+export D365FO_MAX_CONCURRENT_REQUESTS="5"
+```
-# Run tests
-uv run pytest
+#### Getting Help
-# Run integration tests
-.\tests\integration\integration-test-simple.ps1 test-sandbox
+- **Logs**: Check `~/.d365fo-mcp/logs/mcp-server.log` for detailed error information
+- **Environment**: Use `d365fo_get_environment_info` tool to check system status
+- **Documentation**: See [MCP Implementation Summary](docs/MCP_IMPLEMENTATION_SUMMARY.md) for technical details
+- **Issues**: Report problems at [GitHub Issues](https://github.com/mafzaal/d365fo-client/issues)
-# Format code
-uv run black .
-uv run isort .
+### MCP Tools
-# Type checking
-uv run mypy src/
+The server provides **34 comprehensive tools** organized into functional categories:
+#### Connection & Environment Tools (2 tools)
+- **`d365fo_test_connection`** - Test connectivity and authentication with performance metrics and error diagnostics
+- **`d365fo_get_environment_info`** - Get comprehensive environment details including versions, configurations, and capabilities
+#### CRUD Operations Tools (6 tools)
+- **`d365fo_query_entities`** - Simplified OData querying with 'eq' filtering, wildcard patterns, field selection, and pagination
+- **`d365fo_get_entity_record`** - Retrieve specific records by key with expansion options and ETag support
+- **`d365fo_create_entity_record`** - Create new entity records with validation and business logic execution
+- **`d365fo_update_entity_record`** - Update existing records with partial updates and optimistic concurrency control
+- **`d365fo_delete_entity_record`** - Delete entity records with referential integrity checking and cascading rules
+- **`d365fo_call_action`** - Execute OData actions and functions for complex business operations
+#### Metadata Discovery Tools (6 tools)
+- **`d365fo_search_entities`** - Search entities by pattern with category filtering and full-text search capabilities
+- **`d365fo_get_entity_schema`** - Get detailed entity schemas with properties, relationships, and label resolution
+- **`d365fo_search_actions`** - Search available OData actions with binding type and parameter information
+- **`d365fo_search_enumerations`** - Search system enumerations with keyword-based filtering
+- **`d365fo_get_enumeration_fields`** - Get detailed enumeration member information with multi-language support
+- **`d365fo_get_installed_modules`** - Retrieve information about installed modules and their configurations
+#### Label Management Tools (2 tools)
+- **`d365fo_get_label`** - Get single label text by ID with multi-language support and fallback options
+- **`d365fo_get_labels_batch`** - Get multiple labels efficiently with batch processing and performance optimization
+#### Profile Management Tools (10 tools)
+- **`d365fo_list_profiles`** - List all configured D365FO environment profiles with status information
+- **`d365fo_get_profile`** - Get detailed configuration information for specific profiles
+- **`d365fo_create_profile`** - Create new environment profiles with comprehensive authentication options
+- **`d365fo_update_profile`** - Modify existing profile configurations with partial update support
+- **`d365fo_delete_profile`** - Remove environment profiles with proper cleanup and validation
+- **`d365fo_set_default_profile`** - Designate a specific profile as the default for operations
+- **`d365fo_get_default_profile`** - Retrieve information about the currently configured default profile
+- **`d365fo_validate_profile`** - Validate profile configurations for completeness and security compliance
+- **`d365fo_test_profile_connection`** - Test connectivity and authentication for specific profiles
+- **`d365fo_get_profile_status`** - Get comprehensive status information for profiles
+#### Database Analysis Tools (4 tools)
+- **`d365fo_execute_sql_query`** - Execute SELECT queries against metadata database with security validation
+- **`d365fo_get_database_schema`** - Get comprehensive database schema information including relationships
+- **`d365fo_get_table_info`** - Get detailed information about specific database tables with sample data
+- **`d365fo_get_database_statistics`** - Generate database statistics and analytics for performance monitoring
+#### Synchronization Tools (4 tools)
+- **`d365fo_start_sync`** - Initiate metadata synchronization with various strategies and session tracking
+- **`d365fo_get_sync_progress`** - Monitor detailed progress of sync sessions with time estimates
+- **`d365fo_cancel_sync`** - Cancel running sync sessions with graceful cleanup
+- **`d365fo_list_sync_sessions`** - List all active sync sessions with status and progress information
+**📖 For detailed information about all MCP tools including usage examples and best practices, see the [Comprehensive MCP Tools Introduction](docs/MCP_TOOLS_COMPREHENSIVE_INTRODUCTION.md).**
-# Quality checks
-.\make.ps1 quality-check  # Windows PowerShell
-# or
-make quality-check       # Unix/Linux/macOS
-```
+### MCP Resources
-### Project Structure
+The server exposes four types of resources for discovery and access:
+#### Entity Resources
+Access entity metadata and sample data:
 ```
-d365fo-client/
-├── src/
-│   └── d365fo_client/
-│       ├── __init__.py          # Public API exports
-│       ├── main.py              # CLI entry point
-│       ├── cli.py               # CLI command handlers
-│       ├── client.py            # Enhanced D365FOClient class
-│       ├── config.py            # Configuration management
-│       ├── auth.py              # Authentication management
-│       ├── session.py           # HTTP session management
-│       ├── crud.py              # CRUD operations
-│       ├── query.py             # OData query utilities
-│       ├── metadata.py          # Legacy metadata operations
-│       ├── metadata_api.py      # Metadata API client
-│       ├── metadata_cache.py    # Metadata caching layer V2
-│       ├── metadata_sync.py     # Metadata synchronization V2 with session management
-│       ├── sync_session.py      # Enhanced sync session management (New in v0.2.3)
-│       ├── credential_manager.py # Credential source management (New in v0.2.3)
-│       ├── labels.py            # Label operations V2
-│       ├── profiles.py          # Profile data models
-│       ├── profile_manager.py   # Profile management
-│       ├── models.py            # Data models and configurations
-│       ├── output.py            # Output formatting
-│       ├── utils.py             # Utility functions
-│       ├── exceptions.py        # Custom exceptions
-│       └── mcp/                 # Model Context Protocol server
-│           ├── __init__.py      # MCP server exports
-│           ├── main.py          # MCP server entry point
-│           ├── server.py        # Core MCP server implementation
-│           ├── client_manager.py# D365FO client connection pooling
-│           ├── models.py        # MCP-specific data models
-│           ├── tools/           # MCP tool implementations (12 tools)
-│           │   ├── connection_tools.py
-│           │   ├── crud_tools.py
-│           │   ├── metadata_tools.py
-│           │   └── label_tools.py
-│           ├── resources/       # MCP resource handlers (4 types)
-│           │   ├── entity_handler.py
-│           │   ├── metadata_handler.py
-│           │   ├── environment_handler.py
-│           │   └── query_handler.py
-│           └── prompts/         # MCP prompt templates
-├── tests/                       # Comprehensive test suite
-│   ├── unit/                    # Unit tests (pytest-based)
-│   ├── integration/             # Multi-tier integration testing
-│   │   ├── mock_server/         # Mock D365 F&O API server
-│   │   ├── test_mock_server.py  # Mock server tests
-│   │   ├── test_sandbox.py      # Sandbox environment tests ✅
-│   │   ├── test_live.py         # Live environment tests
-│   │   ├── conftest.py          # Shared pytest fixtures
-│   │   ├── test_runner.py       # Python test execution engine
-│   │   └── integration-test-simple.ps1 # PowerShell automation
-│   └── test_mcp_server.py       # MCP server unit tests ✅
-├── scripts/                     # Metadata discovery scripts
-│   ├── search_data_entities.ps1 # PowerShell entity search
-│   ├── get_data_entity_schema.ps1 # PowerShell schema retrieval
-│   ├── search_enums.py          # Python enumeration search
-│   ├── get_enumeration_info.py  # Python enumeration info
-│   ├── search_actions.ps1       # PowerShell action search
-│   └── get_action_info.py       # Python action information
-├── docs/                        # Comprehensive documentation
-├── pyproject.toml               # Project configuration
-└── README.md                    # This file
+d365fo://entities/CustomersV3     # Customer entity with metadata and sample data
+d365fo://entities/SalesOrders     # Sales order entity information
+d365fo://entities/Products        # Product entity details
 ```
-## Configuration Options
+#### Metadata Resources
+Access system-wide metadata:
+```
+d365fo://metadata/entities        # All data entities metadata (V2 cache)
+d365fo://metadata/actions         # Available OData actions
+d365fo://metadata/enumerations    # System enumerations
+d365fo://metadata/labels          # System labels and translations
+```
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `base_url` | str | Required | D365 F&O base URL |
-| `client_id` | str | None | Azure AD client ID |
-| `client_secret` | str | None | Azure AD client secret |
-| `tenant_id` | str | None | Azure AD tenant ID |
-| `use_default_credentials` | bool | True | Use Azure Default Credential |
-| `credential_source` | str | "environment" | Credential source: "environment", "keyvault" |
-| `keyvault_url` | str | None | Azure Key Vault URL for credential storage |
-| `verify_ssl` | bool | False | Verify SSL certificates |
-| `timeout` | int | 30 | Request timeout in seconds |
-| `metadata_cache_dir` | str | Platform-specific user cache | Metadata cache directory |
-| `use_label_cache` | bool | True | Enable label caching V2 |
-| `label_cache_expiry_minutes` | int | 60 | Label cache expiry time |
-| `use_cache_first` | bool | False | Enable cache-first mode with background sync |
+#### Environment Resources
+Access environment status and information:
+```
+d365fo://environment/status       # Environment health and connectivity
+d365fo://environment/version      # Version information (app, platform, build)
+d365fo://environment/cache        # Cache status and statistics V2
+```
-### Cache Directory Behavior
+#### Query Resources
+Access predefined and templated queries:
+```
+d365fo://queries/customers_recent # Recent customers query template
+d365fo://queries/sales_summary    # Sales summary query with parameters
+```
-By default, the client uses platform-appropriate user cache directories:
+#### Database Resources (New in V2)
+Access metadata database queries:
+```
+d365fo://database/entities        # SQL-based entity searches with FTS5
+d365fo://database/actions         # Action discovery with metadata
+d365fo://database/statistics      # Cache and performance statistics
+```
-- **Windows**: `%LOCALAPPDATA%\d365fo-client` (e.g., `C:\Users\username\AppData\Local\d365fo-client`)
-- **macOS**: `~/Library/Caches/d365fo-client` (e.g., `/Users/username/Library/Caches/d365fo-client`)
-- **Linux**: `~/.cache/d365fo-client` (e.g., `/home/username/.cache/d365fo-client`)
+### Usage Examples
-You can override this by explicitly setting `metadata_cache_dir`:
+#### Basic Tool Execution
-```python
-from d365fo_client import FOClientConfig
+```json
+{
+  "tool": "d365fo_query_entities",
+  "arguments": {
+    "entityName": "CustomersV3",
+    "select": ["CustomerAccount", "Name", "Email"],
+    "filter": "CustomerGroup eq 'VIP'",
+    "top": 10
+  }
+}
+```
-# Use custom cache directory
-config = FOClientConfig(
-    base_url="https://your-fo-environment.dynamics.com",
-    metadata_cache_dir="/custom/cache/path"
-)
+#### Entity Schema Discovery
-# Or get the default cache directory programmatically
-from d365fo_client import get_user_cache_dir
+```json
+{
+  "tool": "d365fo_get_entity_schema",
+  "arguments": {
+    "entityName": "CustomersV3",
+    "includeProperties": true,
+    "resolveLabels": true,
+    "language": "en-US"
+  }
+}
+```
-cache_dir = get_user_cache_dir("my-app")  # Platform-appropriate cache dir
-config = FOClientConfig(
-    base_url="https://your-fo-environment.dynamics.com",
-    metadata_cache_dir=str(cache_dir)
-)
+#### Environment Information
+```json
+{
+  "tool": "d365fo_get_environment_info",
+  "arguments": {}
+}
 ```
-## Testing
+### Authentication & Configuration
-This project includes comprehensive testing at multiple levels to ensure reliability and quality.
+#### Default Credentials (Recommended)
+Uses Azure Default Credential chain (Managed Identity, Azure CLI, etc.):
-### Unit Tests
+```bash
+export D365FO_BASE_URL="https://your-environment.dynamics.com"
+# No additional auth environment variables needed
+d365fo-mcp-server
+```
-Run standard unit tests for core functionality:
+#### Explicit Credentials
+For service principal authentication:
 ```bash
-# Run all unit tests
-uv run pytest
+export D365FO_BASE_URL="https://your-environment.dynamics.com"
+export D365FO_CLIENT_ID="your-client-id"
+export D365FO_CLIENT_SECRET="your-client-secret"
+export D365FO_TENANT_ID="your-tenant-id"
+d365fo-mcp-server
+```
-# Run with coverage
-uv run pytest --cov=d365fo_client --cov-report=html
+#### Azure Key Vault Integration (New in v0.2.3)
+For secure credential storage using Azure Key Vault:
-# Run specific test file
-uv run pytest tests/test_client.py -v
+```bash
+export D365FO_BASE_URL="https://your-environment.dynamics.com"
+export D365FO_CREDENTIAL_SOURCE="keyvault"
+export D365FO_KEYVAULT_URL="https://your-keyvault.vault.azure.net/"
+d365fo-mcp-server
 ```
-### Integration Tests
+#### Advanced Configuration
-The project includes a sophisticated multi-tier integration testing framework:
+**New in v0.3.0**: Comprehensive environment variable management with type safety and validation using Pydantic settings.
-#### Quick Start
+Create a configuration file or set additional environment variables:
 ```bash
-# Run sandbox integration tests (recommended)
-.\tests\integration\integration-test-simple.ps1 test-sandbox
-# Run mock server tests (no external dependencies)
-.\tests\integration\integration-test-simple.ps1 test-mock
+# === Core D365FO Connection Settings ===
+export D365FO_BASE_URL="https://your-environment.dynamics.com"
+export D365FO_CLIENT_ID="your-client-id"
+export D365FO_CLIENT_SECRET="your-client-secret"
+export D365FO_TENANT_ID="your-tenant-id"
-# Run with verbose output
-.\tests\integration\integration-test-simple.ps1 test-sandbox -VerboseOutput
+# === Logging Configuration ===
+export D365FO_LOG_LEVEL="DEBUG"                        # DEBUG, INFO, WARNING, ERROR, CRITICAL
+export D365FO_LOG_FILE="/custom/path/server.log"       # Custom log file path
+# === MCP Server Transport Settings (v0.3.0+) ===
+export D365FO_MCP_TRANSPORT="stdio"                    # stdio, sse, http, streamable-http
+export D365FO_MCP_HTTP_HOST="0.0.0.0"                 # HTTP host (default: 127.0.0.1)
+export D365FO_MCP_HTTP_PORT="8000"                     # HTTP port (default: 8000)
+export D365FO_MCP_HTTP_STATELESS="true"                # Enable stateless mode
+export D365FO_MCP_HTTP_JSON="true"                     # Enable JSON response mode
+# === Cache and Performance Settings ===
+export D365FO_CACHE_DIR="/custom/cache/path"           # General cache directory
+export D365FO_META_CACHE_DIR="/custom/metadata/cache"  # Metadata cache directory
+export D365FO_LABEL_CACHE="true"                       # Enable label caching (default: true)
+export D365FO_LABEL_EXPIRY="1440"                      # Label cache expiry in minutes (24 hours)
+export D365FO_USE_CACHE_FIRST="true"                   # Use cache before API calls
+# === Connection and Performance Tuning ===
+export D365FO_TIMEOUT="60"                             # General timeout in seconds
+export D365FO_MCP_MAX_CONCURRENT_REQUESTS="10"         # Max concurrent requests
+export D365FO_MCP_REQUEST_TIMEOUT="30"                 # Request timeout in seconds
+export D365FO_VERIFY_SSL="true"                        # Verify SSL certificates
+# === MCP Authentication Settings (Advanced) ===
+export D365FO_MCP_AUTH_CLIENT_ID="your-mcp-client-id"
+export D365FO_MCP_AUTH_CLIENT_SECRET="your-mcp-client-secret"
+export D365FO_MCP_AUTH_TENANT_ID="your-mcp-tenant-id"
+export D365FO_MCP_AUTH_BASE_URL="http://localhost:8000"
+export D365FO_MCP_AUTH_REQUIRED_SCOPES="User.Read,email,openid,profile"
+# === Debug Settings ===
+export DEBUG="true"                                     # Enable debug mode
 ```
-#### Test Levels
-1. **Mock Server Tests** - Fast, isolated tests against a simulated D365 F&O API
-   - No external dependencies
-   - Complete API simulation
-   - Ideal for CI/CD pipelines
+**Environment File Support**: You can also create a `.env` file in your project directory with these variables for development convenience.
-2. **Sandbox Tests** ⭐ *(Default)* - Tests against real D365 F&O test environments
-   - Validates authentication
-   - Tests real API behavior
-   - Requires test environment access
+## Python Client Library
-3. **Live Tests** - Optional tests against production environments
-   - Final validation
-   - Performance benchmarking
-   - Use with caution
+### Features
-#### Configuration
+- 🔗 **OData Client**: Full CRUD operations on D365 F&O data entities with composite key support
+- 📊 **Metadata Management V2**: Enhanced caching system with intelligent synchronization and FTS5 search
+- 🏷️ **Label Operations V2**: Multilingual label caching with performance improvements and async support
+- 🔍 **Advanced Querying**: Support for all OData query parameters ($select, $filter, $expand, etc.)
+- ⚡ **Action Execution**: Execute bound and unbound OData actions with comprehensive parameter handling
+- 🔒 **Authentication**: Azure AD integration with default credentials, service principal, and Azure Key Vault support
+- 💾 **Intelligent Caching**: Cross-environment cache sharing with module-based version detection
+- 🌐 **Async/Await**: Modern async/await patterns with optimized session management
+- 📝 **Type Hints**: Full type annotation support with enhanced data models
+- 🤖 **MCP Server**: Production-ready Model Context Protocol server with 12 tools and 4 resource types
+- 🖥️ **Comprehensive CLI**: Hierarchical command-line interface for all D365 F&O operations
+- 🧪 **Multi-tier Testing**: Mock, sandbox, and live integration testing framework (17/17 tests passing)
+- 📋 **Metadata Scripts**: PowerShell and Python utilities for entity, enumeration, and action discovery
+- 🔐 **Enhanced Credential Management**: Support for Azure Key Vault and multiple credential sources
+- 📊 **Advanced Sync Management**: Session-based synchronization with detailed progress tracking
+- **🔧 NEW v0.3.0**: Pydantic settings model with type-safe environment variable validation
+- **📂 NEW v0.3.0**: Custom log file path support and flexible logging configuration
+- **🔄 NEW v0.3.0**: Automatic legacy configuration migration and compatibility layer
-Set up integration testing with environment variables:
+### Installation
 ```bash
-# Copy the template and configure
-cp tests/integration/.env.template tests/integration/.env
-# Edit .env file with your settings:
-INTEGRATION_TEST_LEVEL=sandbox
-D365FO_SANDBOX_BASE_URL=https://your-test.dynamics.com
-D365FO_CLIENT_ID=your-client-id
-D365FO_CLIENT_SECRET=your-client-secret
-D365FO_TENANT_ID=your-tenant-id
-```
-#### Available Commands
+# Install from PyPI
+pip install d365fo-client
-```bash
-# Test environment setup
-.\tests\integration\integration-test-simple.ps1 setup
+# Or install from source
+git clone https://github.com/mafzaal/d365fo-client.git
+cd d365fo-client
+uv sync  # Installs with exact dependencies from uv.lock
-# Dependency checking
-.\tests\integration\integration-test-simple.ps1 deps-check
+# Or use Docker (no local installation required)
+docker pull ghcr.io/mafzaal/d365fo-client:latest
+# Run with Docker
+docker run --rm -it \
+  -e D365FO_BASE_URL="https://your-environment.dynamics.com" \
+  -e D365FO_CLIENT_ID="your-client-id" \
+  -e D365FO_CLIENT_SECRET="your-client-secret" \
+  -e D365FO_TENANT_ID="your-tenant-id" \
+  -v d365fo-mcp:/home/mcp_user/ \
+  ghcr.io/mafzaal/d365fo-client:latest
+```
-# Run specific test levels
-.\tests\integration\integration-test-simple.ps1 test-mock
-.\tests\integration\integration-test-simple.ps1 test-sandbox
-.\tests\integration\integration-test-simple.ps1 test-live
+**Note**: The package includes MCP (Model Context Protocol) dependencies by default, enabling AI assistant integration. Both `d365fo-client` CLI and `d365fo-mcp-server` commands will be available after installation.
-# Coverage and reporting
-.\tests\integration\integration-test-simple.ps1 coverage
+**Breaking Change in v0.2.3**: Environment variable names have been updated for consistency:
+- `AZURE_CLIENT_ID` → `D365FO_CLIENT_ID`
+- `AZURE_CLIENT_SECRET` → `D365FO_CLIENT_SECRET`
+- `AZURE_TENANT_ID` → `D365FO_TENANT_ID`
-# Clean up test artifacts
-.\tests\integration\integration-test-simple.ps1 clean
-```
+Please update your environment variables accordingly when upgrading.
-#### Test Coverage
+## Python Client Quick Start
-Integration tests cover:
+## Command Line Interface (CLI)
-- ✅ **Connection & Authentication** - Azure AD integration, SSL/TLS validation
-- ✅ **Version Methods** - Application, platform, and build version retrieval
-- ✅ **Metadata Operations** - Entity discovery, metadata API validation
-- ✅ **Data Operations** - CRUD operations, OData query validation
-- ✅ **Error Handling** - Network failures, authentication errors, invalid requests
-- ✅ **Performance** - Response time validation, concurrent operations
+d365fo-client provides a comprehensive CLI with hierarchical commands for interacting with Dynamics 365 Finance & Operations APIs and metadata. The CLI supports all major operations including entity management, metadata discovery, and system administration.
-For detailed information, see [Integration Testing Documentation](tests/integration/README.md).
+### Usage
-### Test Results
+```bash
+# Use the installed CLI command
+d365fo-client [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND] [OPTIONS]
-Recent sandbox integration test results:
-```
-✅ 17 passed, 0 failed, 2 warnings in 37.67s
-======================================================
-✅ TestSandboxConnection::test_connection_success
-✅ TestSandboxConnection::test_metadata_connection_success
-✅ TestSandboxVersionMethods::test_get_application_version
-✅ TestSandboxVersionMethods::test_get_platform_build_version
-✅ TestSandboxVersionMethods::test_get_application_build_version
-✅ TestSandboxVersionMethods::test_version_consistency
-✅ TestSandboxMetadataOperations::test_download_metadata
-✅ TestSandboxMetadataOperations::test_search_entities
-✅ TestSandboxMetadataOperations::test_get_data_entities
-✅ TestSandboxMetadataOperations::test_get_public_entities
-✅ TestSandboxDataOperations::test_get_available_entities
-✅ TestSandboxDataOperations::test_odata_query_options
-✅ TestSandboxAuthentication::test_authenticated_requests
-✅ TestSandboxErrorHandling::test_invalid_entity_error
-✅ TestSandboxErrorHandling::test_invalid_action_error
-✅ TestSandboxPerformance::test_response_times
-✅ TestSandboxPerformance::test_concurrent_operations
+# Alternative: Module execution
+python -m d365fo_client.main [OPTIONS] COMMAND [ARGS]
 ```
-## Model Context Protocol (MCP) Server
-d365fo-client includes a **production-ready Model Context Protocol (MCP) server** that exposes the full capabilities of the D365 Finance & Operations client to AI assistants and other MCP-compatible tools. This enables sophisticated Dynamics 365 integration workflows through standardized protocol interactions.
-### Overview
+### Command Categories
-The MCP server provides:
-- **12 functional tools** covering all major D365 F&O operations
-- **4 resource types** with comprehensive metadata exposure
-- **Production-ready** implementation with proper error handling and authentication
-- **Performance optimization** with connection pooling and intelligent caching V2
-- **Comprehensive testing** with 14 unit tests (100% pass rate)
-- **Profile support** for multi-environment configurations
+#### Entity Operations
+```bash
+# List entities with filtering
+d365fo-client entities list --pattern "customer" --limit 10
-### Quick Start
+# Get entity details and schema
+d365fo-client entities get CustomersV3 --properties --keys --labels
-#### Installation and Setup
+# CRUD operations
+d365fo-client entities create Customers --data '{"CustomerAccount":"US-999","Name":"Test"}'
+d365fo-client entities update Customers US-999 --data '{"Name":"Updated Name"}'
+d365fo-client entities delete Customers US-999
+```
+#### Metadata Operations
 ```bash
-# Install d365fo-client with MCP dependencies
-pip install d365fo-client
+# Search and discover entities
+d365fo-client metadata entities --search "sales" --output json
-# Set up environment variables
-export D365FO_BASE_URL="https://your-environment.dynamics.com"
-export D365FO_CLIENT_ID="your-client-id"          # Optional with default credentials
-export D365FO_CLIENT_SECRET="your-client-secret"  # Optional with default credentials
-export D365FO_TENANT_ID="your-tenant-id"          # Optional with default credentials
+# Get available actions
+d365fo-client metadata actions --pattern "calculate" --limit 5
-# Start the MCP server
-d365fo-mcp-server
-```
+# Enumerate system enumerations
+d365fo-client metadata enums --search "status" --output table
-#### Alternative: Programmatic Usage
+# Synchronize metadata cache
+d365fo-client metadata sync --force-refresh
+```
-```python
-from d365fo_client.mcp import D365FOMCPServer
+#### Version Information
+```bash
+# Get application versions
+d365fo-client version app
+d365fo-client version platform
+d365fo-client version build
+```
-# Create and run server with custom configuration
-config = {
-    "default_environment": {
-        "base_url": "https://your-environment.dynamics.com",
-        "use_default_credentials": True
-    }
-}
+#### Label Operations
+```bash
+# Resolve single label
+d365fo-client labels resolve "@SYS13342"
-server = D365FOMCPServer(config)
-await server.run()
+# Search labels by pattern
+d365fo-client labels search "customer" --language "en-US"
 ```
-### MCP Tools
+### Global Options
-The server provides 12 comprehensive tools organized into functional categories:
+- `--base-url URL` — Specify D365 F&O environment URL
+- `--profile NAME` — Use named configuration profile
+- `--output FORMAT` — Output format: json, table, csv, yaml (default: table)
+- `--verbose` — Enable verbose output for debugging
+- `--timeout SECONDS` — Request timeout (default: 30)
-#### Connection Tools (2 tools)
-- **`d365fo_test_connection`** - Test environment connectivity and health
-- **`d365fo_get_environment_info`** - Get comprehensive environment details, versions, and statistics
+### Configuration Profiles
-#### CRUD Operations (5 tools)
-- **`d365fo_query_entities`** - Advanced OData querying with filters, selections, and pagination
-- **`d365fo_get_entity_record`** - Retrieve specific records by key with expansion options
-- **`d365fo_create_entity_record`** - Create new entity records with validation
-- **`d365fo_update_entity_record`** - Update existing records with optimistic concurrency
-- **`d365fo_delete_entity_record`** - Delete entity records with conflict detection
+Create reusable configurations in `~/.d365fo-client/config.yaml`:
-#### Metadata Tools (5 tools)
-- **`d365fo_search_entities`** - Search entities by pattern with advanced filtering and FTS5 search
-- **`d365fo_get_entity_schema`** - Get detailed entity schemas with properties and relationships
-- **`d365fo_search_actions`** - Search available OData actions and functions
-- **`d365fo_search_enums`** - Search system enumerations with filtering
-- **`d365fo_get_enum_info`** - Get detailed enumeration information and values
+```yaml
+profiles:
+  production:
+    base_url: "https://prod.dynamics.com"
+    use_default_credentials: true
+    timeout: 60
+  development:
+    base_url: "https://dev.dynamics.com"
+    client_id: "${D365FO_CLIENT_ID}"
+    client_secret: "${D365FO_CLIENT_SECRET}"
+    tenant_id: "${D365FO_TENANT_ID}"
+    use_cache_first: true
-#### Label Tools (2 tools)
-- **`d365fo_get_label`** - Get single label text by ID with language support
-- **`d365fo_get_labels_batch`** - Get multiple labels efficiently in batch operations
+default_profile: "development"
+```
-### MCP Resources
+### Examples
-The server exposes four types of resources for discovery and access:
+```bash
+# Quick entity discovery
+d365fo-client entities list --pattern "cust.*" --output json
-#### Entity Resources
-Access entity metadata and sample data:
-```
-d365fo://entities/CustomersV3     # Customer entity with metadata and sample data
-d365fo://entities/SalesOrders     # Sales order entity information
-d365fo://entities/Products        # Product entity details
-```
+# Get comprehensive entity information
+d365fo-client entities get CustomersV3 --properties --keys --labels --output yaml
-#### Metadata Resources
-Access system-wide metadata:
-```
-d365fo://metadata/entities        # All data entities metadata (V2 cache)
-d365fo://metadata/actions         # Available OData actions
-d365fo://metadata/enumerations    # System enumerations
-d365fo://metadata/labels          # System labels and translations
-```
+# Search for calculation actions
+d365fo-client metadata actions --pattern "calculate|compute" --output table
-#### Environment Resources
-Access environment status and information:
-```
-d365fo://environment/status       # Environment health and connectivity
-d365fo://environment/version      # Version information (app, platform, build)
-d365fo://environment/cache        # Cache status and statistics V2
+# Test environment connectivity
+d365fo-client version app --verbose
 ```
-#### Query Resources
-Access predefined and templated queries:
-```
-d365fo://queries/customers_recent # Recent customers query template
-d365fo://queries/sales_summary    # Sales summary query with parameters
-```
+For a complete command reference:
-#### Database Resources (New in V2)
-Access metadata database queries:
-```
-d365fo://database/entities        # SQL-based entity searches with FTS5
-d365fo://database/actions         # Action discovery with metadata
-d365fo://database/statistics      # Cache and performance statistics
+```bash
+d365fo-client --help
+d365fo-client entities --help
+d365fo-client metadata --help
 ```
+### Basic Usage
-### Usage Examples
+```python
+import asyncio
+from d365fo_client import D365FOClient, FOClientConfig
-#### Basic Tool Execution
+async def main():
+    # Simple configuration with default credentials
+    config = FOClientConfig(
+        base_url="https://your-fo-environment.dynamics.com",
+        use_default_credentials=True  # Uses Azure Default Credential
+    )
+    async with D365FOClient(config) as client:
+        # Test connection
+        if await client.test_connection():
+            print("✅ Connected successfully!")
+        # Get environment information
+        env_info = await client.get_environment_info()
+        print(f"Environment: {env_info.application_version}")
+        # Search for entities (uses metadata cache v2)
+        customer_entities = await client.search_entities("customer")
+        print(f"Found {len(customer_entities)} customer entities")
+        # Get customers with query options
+        from d365fo_client import QueryOptions
+        options = QueryOptions(
+            select=["CustomerAccount", "Name", "SalesCurrencyCode"],
+            top=10,
+            orderby=["Name"]
+        )
+        customers = await client.get_data("/data/CustomersV3", options)
+        print(f"Retrieved {len(customers['value'])} customers")
-```json
-{
-  "tool": "d365fo_query_entities",
-  "arguments": {
-    "entityName": "CustomersV3",
-    "select": ["CustomerAccount", "Name", "Email"],
-    "filter": "CustomerGroup eq 'VIP'",
-    "top": 10
-  }
-}
+if __name__ == "__main__":
+    asyncio.run(main())
 ```
-#### Entity Schema Discovery
+### Using Convenience Function
-```json
-{
-  "tool": "d365fo_get_entity_schema",
-  "arguments": {
-    "entityName": "CustomersV3",
-    "includeProperties": true,
-    "resolveLabels": true,
-    "language": "en-US"
-  }
-}
+```python
+from d365fo_client import create_client
+# Quick client creation with enhanced defaults
+async with create_client("https://your-fo-environment.dynamics.com") as client:
+    customers = await client.get_data("/data/CustomersV3", top=5)
 ```
-#### Environment Information
+## Configuration
-```json
-{
-  "tool": "d365fo_get_environment_info",
-  "arguments": {}
-}
+### Environment Variable Management (New in v0.3.0)
+The d365fo-client now includes a comprehensive **Pydantic settings model** for type-safe environment variable management:
+```python
+from d365fo_client import D365FOSettings, get_settings
+# Get type-safe settings instance
+settings = get_settings()
+# Access settings with full IntelliSense support
+print(f"Base URL: {settings.base_url}")
+print(f"Log Level: {settings.log_level}")
+print(f"Cache Directory: {settings.cache_dir}")
+# Check configuration state
+if settings.has_client_credentials():
+    print("Client credentials configured")
+startup_mode = settings.get_startup_mode()  # "profile_only", "default_auth", "client_credentials"
+# Convert to environment dictionary for external tools
+env_vars = settings.to_env_dict()
 ```
-### Authentication & Configuration
+**Key Benefits:**
+- **Type Safety**: Automatic validation and type conversion for all 35+ environment variables
+- **IDE Support**: Full IntelliSense and autocompletion for configuration options
+- **Environment Files**: Support for `.env` files in development
+- **Comprehensive Defaults**: Sensible defaults for all configuration options
+- **Validation**: Built-in validation for URLs, ports, timeouts, and other settings
-#### Default Credentials (Recommended)
-Uses Azure Default Credential chain (Managed Identity, Azure CLI, etc.):
+### Authentication Options
-```bash
-export D365FO_BASE_URL="https://your-environment.dynamics.com"
-# No additional auth environment variables needed
-d365fo-mcp-server
+```python
+from d365fo_client import FOClientConfig
+# Option 1: Default Azure credentials (recommended)
+config = FOClientConfig(
+    base_url="https://your-fo-environment.dynamics.com",
+    use_default_credentials=True
+)
+# Option 2: Client credentials
+config = FOClientConfig(
+    base_url="https://your-fo-environment.dynamics.com",
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+    tenant_id="your-tenant-id",
+    use_default_credentials=False
+)
+# Option 3: Azure Key Vault integration (New in v0.2.3)
+config = FOClientConfig(
+    base_url="https://your-fo-environment.dynamics.com",
+    credential_source="keyvault",  # Use Azure Key Vault for credentials
+    keyvault_url="https://your-keyvault.vault.azure.net/"
+)
+# Option 4: With custom settings
+config = FOClientConfig(
+    base_url="https://your-fo-environment.dynamics.com",
+    use_default_credentials=True,
+    verify_ssl=False,  # For development environments
+    timeout=60,  # Request timeout in seconds
+    metadata_cache_dir="./my_cache",  # Custom cache directory
+    use_label_cache=True,  # Enable label caching
+    label_cache_expiry_minutes=120  # Cache for 2 hours
+)
 ```
-#### Explicit Credentials
-For service principal authentication:
+### Legacy Configuration Migration (New in v0.3.0)
+The d365fo-client automatically detects and migrates legacy configuration files:
+- **Automatic Detection**: Identifies legacy configuration patterns (missing `verify_ssl`, outdated field names)
+- **Field Migration**: Updates `cache_dir` → `metadata_cache_dir`, `auth_mode` → `use_default_credentials`
+- **Backup Creation**: Creates backup of original configuration before migration
+- **Seamless Upgrade**: Ensures smooth transition from older versions without manual intervention
+```python
+# Legacy configurations are automatically migrated when FastMCP server starts
+# No manual intervention required - migration happens transparently
+```
+## Core Operations
+### CRUD Operations
+```python
+async with D365FOClient(config) as client:
+    # CREATE - Create new customer (supports composite keys)
+    new_customer = {
+        "CustomerAccount": "US-999",
+        "Name": "Test Customer",
+        "SalesCurrencyCode": "USD"
+    }
+    created = await client.create_data("/data/CustomersV3", new_customer)
+    # READ - Get single customer by key
+    customer = await client.get_data("/data/CustomersV3('US-001')")
+    # UPDATE - Update customer with optimistic concurrency
+    updates = {"Name": "Updated Customer Name"}
+    updated = await client.update_data("/data/CustomersV3('US-001')", updates)
+    # DELETE - Delete customer
+    success = await client.delete_data("/data/CustomersV3('US-999')")
+    print(f"Delete successful: {success}")
+```
+### Advanced Querying
+```python
+from d365fo_client import QueryOptions
+# Complex query with multiple options
+options = QueryOptions(
+    select=["CustomerAccount", "Name", "SalesCurrencyCode", "CustomerGroupId"],
+    filter="SalesCurrencyCode eq 'USD' and contains(Name, 'Corp')",
+    expand=["CustomerGroup"],
+    orderby=["Name desc", "CustomerAccount"],
+    top=50,
+    skip=10,
+    count=True
+)
+result = await client.get_data("/data/CustomersV3", options)
+print(f"Total count: {result.get('@odata.count')}")
+```
+### Action Execution
+```python
+# Unbound action
+result = await client.post_data("/data/calculateTax", {
+    "amount": 1000.00,
+    "taxGroup": "STANDARD"
+})
+# Bound action on entity set
+result = await client.post_data("/data/CustomersV3/calculateBalances", {
+    "asOfDate": "2024-12-31"
+})
+# Bound action on specific entity instance
+result = await client.post_data("/data/CustomersV3('US-001')/calculateBalance", {
+    "asOfDate": "2024-12-31"
+})
+```
+### Metadata Operations
+```python
+# Intelligent metadata synchronization (v2 system)
+sync_manager = await client.get_sync_manager()
+await sync_manager.smart_sync()
+# Search entities with enhanced filtering
+sales_entities = await client.search_entities("sales")
+print("Sales-related entities:", [e.name for e in sales_entities])
+# Get detailed entity information with labels
+entity_info = await client.get_public_entity_info("CustomersV3")
+if entity_info:
+    print(f"Entity: {entity_info.name}")
+    print(f"Label: {entity_info.label_text}")
+    print(f"Data Service Enabled: {entity_info.data_service_enabled}")
+# Search actions with caching
+calc_actions = await client.search_actions("calculate")
+print("Calculation actions:", [a.name for a in calc_actions])
+# Get enumeration information
+enum_info = await client.get_public_enumeration_info("NoYes")
+if enum_info:
+    print(f"Enum: {enum_info.name}")
+    for member in enum_info.members:
+        print(f"  {member.name} = {member.value}")
+```
+### Label Operations
+```python
+# Get specific label (v2 caching system)
+label_text = await client.get_label_text("@SYS13342")
+print(f"Label text: {label_text}")
+# Get multiple labels efficiently
+labels = await client.get_labels_batch([
+    "@SYS13342", "@SYS9490", "@GLS63332"
+])
+for label_id, text in labels.items():
+    print(f"{label_id}: {text}")
+# Enhanced entity info with resolved labels
+entity_info = await client.get_public_entity_info_with_labels("CustomersV3")
+if entity_info.label_text:
+    print(f"Entity display name: {entity_info.label_text}")
+# Access enhanced properties with labels
+for prop in entity_info.enhanced_properties[:5]:
+    if hasattr(prop, 'label_text') and prop.label_text:
+        print(f"{prop.name}: {prop.label_text}")
+```
+## Error Handling
+```python
+from d365fo_client import D365FOClientError, AuthenticationError, ConnectionError
+try:
+    async with D365FOClient(config) as client:
+        customer = await client.get_data("/data/CustomersV3('NON-EXISTENT')")
+except ConnectionError as e:
+    print(f"Connection failed: {e}")
+except AuthenticationError as e:
+    print(f"Authentication failed: {e}")
+except D365FOClientError as e:
+    print(f"Client operation failed: {e}")
+    print(f"Status code: {e.status_code}")
+    print(f"Response: {e.response_text}")
+```
+## Development
+### Setting up Development Environment
 ```bash
-export D365FO_BASE_URL="https://your-environment.dynamics.com"
-export D365FO_CLIENT_ID="your-client-id"
-export D365FO_CLIENT_SECRET="your-client-secret"
-export D365FO_TENANT_ID="your-tenant-id"
-d365fo-mcp-server
+# Clone the repository
+git clone https://github.com/mafzaal/d365fo-client.git
+cd d365fo-client
+# Install with development dependencies using uv
+uv sync --dev
+# Run tests
+uv run pytest
+# Run integration tests
+.\tests\integration\integration-test-simple.ps1 test-sandbox
+# Format code
+uv run black .
+uv run isort .
+# Type checking
+uv run mypy src/
+# Quality checks
+.\make.ps1 quality-check  # Windows PowerShell
+# or
+make quality-check       # Unix/Linux/macOS
 ```
-#### Azure Key Vault Integration (New in v0.2.3)
-For secure credential storage using Azure Key Vault:
+### Project Structure
+```
+d365fo-client/
+├── src/
+│   └── d365fo_client/
+│       ├── __init__.py          # Public API exports
+│       ├── main.py              # CLI entry point
+│       ├── cli.py               # CLI command handlers
+│       ├── client.py            # Enhanced D365FOClient class
+│       ├── config.py            # Configuration management
+│       ├── auth.py              # Authentication management
+│       ├── session.py           # HTTP session management
+│       ├── crud.py              # CRUD operations
+│       ├── query.py             # OData query utilities
+│       ├── metadata.py          # Legacy metadata operations
+│       ├── metadata_api.py      # Metadata API client
+│       ├── metadata_cache.py    # Metadata caching layer V2
+│       ├── metadata_sync.py     # Metadata synchronization V2 with session management
+│       ├── sync_session.py      # Enhanced sync session management (New in v0.2.3)
+│       ├── credential_manager.py # Credential source management (New in v0.2.3)
+│       ├── labels.py            # Label operations V2
+│       ├── profiles.py          # Profile data models
+│       ├── profile_manager.py   # Profile management
+│       ├── models.py            # Data models and configurations
+│       ├── output.py            # Output formatting
+│       ├── utils.py             # Utility functions
+│       ├── exceptions.py        # Custom exceptions
+│       └── mcp/                 # Model Context Protocol server
+│           ├── __init__.py      # MCP server exports
+│           ├── main.py          # MCP server entry point
+│           ├── server.py        # Core MCP server implementation
+│           ├── client_manager.py# D365FO client connection pooling
+│           ├── models.py        # MCP-specific data models
+│           ├── tools/           # MCP tool implementations (12 tools)
+│           │   ├── connection_tools.py
+│           │   ├── crud_tools.py
+│           │   ├── metadata_tools.py
+│           │   └── label_tools.py
+│           ├── resources/       # MCP resource handlers (4 types)
+│           │   ├── entity_handler.py
+│           │   ├── metadata_handler.py
+│           │   ├── environment_handler.py
+│           │   └── query_handler.py
+│           └── prompts/         # MCP prompt templates
+├── tests/                       # Comprehensive test suite
+│   ├── unit/                    # Unit tests (pytest-based)
+│   ├── integration/             # Multi-tier integration testing
+│   │   ├── mock_server/         # Mock D365 F&O API server
+│   │   ├── test_mock_server.py  # Mock server tests
+│   │   ├── test_sandbox.py      # Sandbox environment tests ✅
+│   │   ├── test_live.py         # Live environment tests
+│   │   ├── conftest.py          # Shared pytest fixtures
+│   │   ├── test_runner.py       # Python test execution engine
+│   │   └── integration-test-simple.ps1 # PowerShell automation
+│   └── test_mcp_server.py       # MCP server unit tests ✅
+├── scripts/                     # Metadata discovery scripts
+│   ├── search_data_entities.ps1 # PowerShell entity search
+│   ├── get_data_entity_schema.ps1 # PowerShell schema retrieval
+│   ├── search_enums.py          # Python enumeration search
+│   ├── get_enumeration_info.py  # Python enumeration info
+│   ├── search_actions.ps1       # PowerShell action search
+│   └── get_action_info.py       # Python action information
+├── docs/                        # Comprehensive documentation
+├── pyproject.toml               # Project configuration
+└── README.md                    # This file
+```
+## Configuration Options
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `base_url` | str | Required | D365 F&O base URL |
+| `client_id` | str | None | Azure AD client ID |
+| `client_secret` | str | None | Azure AD client secret |
+| `tenant_id` | str | None | Azure AD tenant ID |
+| `use_default_credentials` | bool | True | Use Azure Default Credential |
+| `credential_source` | str | "environment" | Credential source: "environment", "keyvault" |
+| `keyvault_url` | str | None | Azure Key Vault URL for credential storage |
+| `verify_ssl` | bool | False | Verify SSL certificates |
+| `timeout` | int | 30 | Request timeout in seconds |
+| `metadata_cache_dir` | str | Platform-specific user cache | Metadata cache directory |
+| `use_label_cache` | bool | True | Enable label caching V2 |
+| `label_cache_expiry_minutes` | int | 60 | Label cache expiry time |
+| `use_cache_first` | bool | False | Enable cache-first mode with background sync |
+### Cache Directory Behavior
+By default, the client uses platform-appropriate user cache directories:
-```bash
-export D365FO_BASE_URL="https://your-environment.dynamics.com"
-export D365FO_CREDENTIAL_SOURCE="keyvault"
-export D365FO_KEYVAULT_URL="https://your-keyvault.vault.azure.net/"
-d365fo-mcp-server
-```
+- **Windows**: `%LOCALAPPDATA%\d365fo-client` (e.g., `C:\Users\username\AppData\Local\d365fo-client`)
+- **macOS**: `~/Library/Caches/d365fo-client` (e.g., `/Users/username/Library/Caches/d365fo-client`)
+- **Linux**: `~/.cache/d365fo-client` (e.g., `/home/username/.cache/d365fo-client`)
-#### Advanced Configuration
+You can override this by explicitly setting `metadata_cache_dir`:
-Create a configuration file or set additional environment variables:
+```python
+from d365fo_client import FOClientConfig
-```bash
-# Optional: Logging configuration
-export D365FO_LOG_LEVEL="DEBUG"
+# Use custom cache directory
+config = FOClientConfig(
+    base_url="https://your-fo-environment.dynamics.com",
+    metadata_cache_dir="/custom/cache/path"
+)
-# Optional: Cache settings
-export D365FO_CACHE_DIR="/custom/cache/path"
+# Or get the default cache directory programmatically
+from d365fo_client import get_user_cache_dir
-# Optional: Performance tuning
-export D365FO_CONNECTION_TIMEOUT="60"
-export D365FO_MAX_CONCURRENT_REQUESTS="10"
+cache_dir = get_user_cache_dir("my-app")  # Platform-appropriate cache dir
+config = FOClientConfig(
+    base_url="https://your-fo-environment.dynamics.com",
+    metadata_cache_dir=str(cache_dir)
+)
 ```
-### Integration with AI Assistants
+## Testing
-The MCP server seamlessly integrates with AI assistants and development tools:
+This project includes comprehensive testing at multiple levels to ensure reliability and quality.
-#### Claude Desktop Integration
-Add to your Claude Desktop configuration:
+### Unit Tests
-```json
-{
-  "mcpServers": {
-    "d365fo": {
-      "command": "d365fo-mcp-server",
-      "env": {
-        "D365FO_BASE_URL": "https://your-environment.dynamics.com" //Optional
-      }
-    }
-  }
-}
-```
+Run standard unit tests for core functionality:
-#### VS Code Integration
+```bash
+# Run all unit tests
+uv run pytest
-##### Option 1: Default Credentials (Recommended)
-Add to your VS Code `mcp.json` for GitHub Copilot with MCP:
+# Run with coverage
+uv run pytest --cov=d365fo_client --cov-report=html
-```json
-{
-  "servers": {
-    "d365fo-mcp-server": {
-      "type": "stdio",
-      "command": "uvx",
-      "args": [
-        "--from",
-        "d365fo-client",
-        "d365fo-mcp-server"
-      ],
-      "env": {
-        "D365FO_BASE_URL": "https://your-environment.dynamics.com",
-        "D365FO_LOG_LEVEL": "INFO"
-      }
-    }
-  }
-}
+# Run specific test file
+uv run pytest tests/test_client.py -v
 ```
-##### Option 2: Explicit Credentials
-For environments requiring service principal authentication:
+### Integration Tests
-```json
-{
-  "servers": {
-    "d365fo-mcp-server": {
-      "type": "stdio",
-      "command": "uvx",
-      "args": [
-        "--from",
-        "d365fo-client",
-        "d365fo-mcp-server"
-      ],
-      "env": {
-        "D365FO_BASE_URL": "https://your-environment.dynamics.com",
-        "D365FO_LOG_LEVEL": "DEBUG",
-        "D365FO_CLIENT_ID": "${input:client_id}",
-        "D365FO_CLIENT_SECRET": "${input:client_secret}",
-        "D365FO_TENANT_ID": "${input:tenant_id}"
-      }
-    }
-  },
-  "inputs": [
-    {
-      "id": "tenant_id",
-      "type": "promptString",
-      "description": "Azure AD Tenant ID for D365 F&O authentication",
-      "password": true
-    },
-    {
-      "id": "client_id",
-      "type": "promptString",
-      "description": "Azure AD Client ID for D365 F&O authentication",
-      "password": true
-    },
-    {
-      "id": "client_secret",
-      "type": "promptString",
-      "description": "Azure AD Client Secret for D365 F&O authentication",
-      "password": true
-    }
-  ]
-}
-```
+The project includes a sophisticated multi-tier integration testing framework:
-**Benefits of uvx approach:**
-- Always uses the latest version from the repository
-- No local installation required
-- Automatic dependency management
-- Works across different environments
+#### Quick Start
-#### Custom MCP Clients
-Connect using any MCP-compatible client library:
+```bash
+# Run sandbox integration tests (recommended)
+.\tests\integration\integration-test-simple.ps1 test-sandbox
-```python
-from mcp import Client
+# Run mock server tests (no external dependencies)
+.\tests\integration\integration-test-simple.ps1 test-mock
-async with Client("d365fo-mcp-server") as client:
-    # Discover available tools
-    tools = await client.list_tools()
-    # Execute operations
-    result = await client.call_tool(
-        "d365fo_query_entities",
-        {"entityName": "Customers", "top": 5}
-    )
+# Run with verbose output
+.\tests\integration\integration-test-simple.ps1 test-sandbox -VerboseOutput
 ```
-### Architecture Benefits
+#### Test Levels
-#### For AI Assistants
-- **Standardized Interface**: Consistent MCP protocol access to D365 F&O
-- **Rich Metadata**: Self-describing entities and operations
-- **Type Safety**: Schema validation for all operations
-- **Error Context**: Detailed error information for troubleshooting
+1. **Mock Server Tests** - Fast, isolated tests against a simulated D365 F&O API
+   - No external dependencies
+   - Complete API simulation
+   - Ideal for CI/CD pipelines
-#### For Developers
-- **Minimal Integration**: Standard MCP client libraries
-- **Comprehensive Coverage**: Full D365 F&O functionality exposed
-- **Performance Optimized**: Efficient connection and caching strategies
-- **Well Documented**: Complete API documentation and examples
+2. **Sandbox Tests** ⭐ *(Default)* - Tests against real D365 F&O test environments
+   - Validates authentication
+   - Tests real API behavior
+   - Requires test environment access
-#### For Organizations
-- **Secure Access**: Enterprise-grade authentication (Azure AD, Managed Identity)
-- **Audit Logging**: Complete operation tracking and monitoring
-- **Scalable Design**: Connection pooling and session management
-- **Maintenance Friendly**: Clear architecture and comprehensive test coverage
+3. **Live Tests** - Optional tests against production environments
+   - Final validation
+   - Performance benchmarking
+   - Use with caution
-### Troubleshooting
+#### Configuration
-#### Common Issues
+Set up integration testing with environment variables:
-**Connection Failures**
 ```bash
-# Test connectivity
-d365fo-client get-version --base-url https://your-environment.dynamics.com
+# Copy the template and configure
+cp tests/integration/.env.template tests/integration/.env
-# Check logs
-tail -f ~/.d365fo-mcp/logs/mcp-server.log
+# Edit .env file with your settings:
+INTEGRATION_TEST_LEVEL=sandbox
+D365FO_SANDBOX_BASE_URL=https://your-test.dynamics.com
+D365FO_CLIENT_ID=your-client-id
+D365FO_CLIENT_SECRET=your-client-secret
+D365FO_TENANT_ID=your-tenant-id
 ```
-**Authentication Issues**
+#### Available Commands
 ```bash
-# Verify Azure CLI authentication
-az account show
+# Test environment setup
+.\tests\integration\integration-test-simple.ps1 setup
-# Test with explicit credentials
-export D365FO_CLIENT_ID="your-client-id"
-# ... set other variables
-d365fo-mcp-server
-```
+# Dependency checking
+.\tests\integration\integration-test-simple.ps1 deps-check
-**Performance Issues**
-```bash
-# Enable debug logging
-export D365FO_LOG_LEVEL="DEBUG"
+# Run specific test levels
+.\tests\integration\integration-test-simple.ps1 test-mock
+.\tests\integration\integration-test-simple.ps1 test-sandbox
+.\tests\integration\integration-test-simple.ps1 test-live
-# Adjust connection settings
-export D365FO_CONNECTION_TIMEOUT="120"
-export D365FO_MAX_CONCURRENT_REQUESTS="5"
+# Coverage and reporting
+.\tests\integration\integration-test-simple.ps1 coverage
+# Clean up test artifacts
+.\tests\integration\integration-test-simple.ps1 clean
 ```
-#### Getting Help
+#### Test Coverage
-- **Logs**: Check `~/.d365fo-mcp/logs/mcp-server.log` for detailed error information
-- **Environment**: Use `d365fo_get_environment_info` tool to check system status
-- **Documentation**: See [MCP Implementation Summary](docs/MCP_IMPLEMENTATION_SUMMARY.md) for technical details
-- **Issues**: Report problems at [GitHub Issues](https://github.com/mafzaal/d365fo-client/issues)
+Integration tests cover:
+- ✅ **Connection & Authentication** - Azure AD integration, SSL/TLS validation
+- ✅ **Version Methods** - Application, platform, and build version retrieval
+- ✅ **Metadata Operations** - Entity discovery, metadata API validation
+- ✅ **Data Operations** - CRUD operations, OData query validation
+- ✅ **Error Handling** - Network failures, authentication errors, invalid requests
+- ✅ **Performance** - Response time validation, concurrent operations
+For detailed information, see [Integration Testing Documentation](tests/integration/README.md).
+### Test Results
+Recent sandbox integration test results:
+```
+✅ 17 passed, 0 failed, 2 warnings in 37.67s
+======================================================
+✅ TestSandboxConnection::test_connection_success
+✅ TestSandboxConnection::test_metadata_connection_success
+✅ TestSandboxVersionMethods::test_get_application_version
+✅ TestSandboxVersionMethods::test_get_platform_build_version
+✅ TestSandboxVersionMethods::test_get_application_build_version
+✅ TestSandboxVersionMethods::test_version_consistency
+✅ TestSandboxMetadataOperations::test_download_metadata
+✅ TestSandboxMetadataOperations::test_search_entities
+✅ TestSandboxMetadataOperations::test_get_data_entities
+✅ TestSandboxMetadataOperations::test_get_public_entities
+✅ TestSandboxDataOperations::test_get_available_entities
+✅ TestSandboxDataOperations::test_odata_query_options
+✅ TestSandboxAuthentication::test_authenticated_requests
+✅ TestSandboxErrorHandling::test_invalid_entity_error
+✅ TestSandboxErrorHandling::test_invalid_action_error
+✅ TestSandboxPerformance::test_response_times
+✅ TestSandboxPerformance::test_concurrent_operations
+```
 ## Contributing

d365fo-client 0.2.3__tar.gz → 0.3.0__tar.gz

d365fo-client 0.2.3tar.gz → 0.3.0tar.gz