d365fo-client 0.2.2__py3-none-any.whl → 0.2.4__py3-none-any.whl

{d365fo_client-0.2.2.dist-info → d365fo_client-0.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: d365fo-client
-Version: 0.2.2
+Version: 0.2.4
 Summary: Microsoft Dynamics 365 Finance & Operations client
 Author-email: Muhammad Afzaal <mo@thedataguy.pro>
 License-Expression: MIT
@@ -22,6 +22,7 @@ License-File: LICENSE
 Requires-Dist: aiohttp>=3.10.0
 Requires-Dist: aiofiles>=24.1.0
 Requires-Dist: azure-identity>=1.19.0
+Requires-Dist: azure-keyvault-secrets>=4.8.0
 Requires-Dist: requests>=2.32.0
 Requires-Dist: aiosqlite>=0.19.0
 Requires-Dist: cachetools>=6.1.0
@@ -39,1020 +40,1246 @@ 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 and service principal 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
+[![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
-
-```bash
-# Install from PyPI
-pip install d365fo-client
+**🐳 Docker Installation for VS Code:**
 
-# 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
-```
+[![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)
 
-**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.
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/d365fo-client?label=Downloads)](https://pypi.org/project/d365fo-client/)
 
-## Quick Start
+**Also includes a comprehensive Python client library** for Microsoft Dynamics 365 Finance & Operations with OData endpoints, metadata operations, label management, and CLI tools.
 
-## Command Line Interface (CLI)
+## MCP Server Overview
 
-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.
+The 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.
 
-### Usage
+### Key Features
 
-```bash
-# Use the installed CLI command
-d365fo-client [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND] [OPTIONS]
+- **34 comprehensive tools** covering all major D365 F&O operations across 7 functional categories
+- **6 resource types** with comprehensive metadata exposure and discovery capabilities
+- **Production-ready** implementation with proper error handling, authentication, and security validation
+- **Performance optimization** with connection pooling, intelligent caching V2, and session management
+- **Comprehensive testing** with 14 unit tests (100% pass rate) and multi-tier integration testing
+- **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
 
-# Alternative: Module execution
-python -m d365fo_client.main [OPTIONS] COMMAND [ARGS]
-```
+### Quick Start
 
-### Command Categories
+#### Installation and Setup
 
-#### Entity Operations
 ```bash
-# List entities with filtering
-d365fo-client entities list --pattern "customer" --limit 10
+# Install d365fo-client with MCP dependencies
+pip install d365fo-client
 
-# Get entity details and schema
-d365fo-client entities get CustomersV3 --properties --keys --labels
+# 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
 
-# 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
+# Start the MCP server
+d365fo-mcp-server
 ```
 
-#### Metadata Operations
-```bash
-# Search and discover entities
-d365fo-client metadata entities --search "sales" --output json
+#### Integration with AI Assistants
 
-# Get available actions
-d365fo-client metadata actions --pattern "calculate" --limit 5
+##### VS Code Integration (Recommended)
 
-# Enumerate system enumerations
-d365fo-client metadata enums --search "status" --output table
+**Option 1: Default Credentials**
+Add to your VS Code `mcp.json` for GitHub Copilot with MCP:
 
-# Synchronize metadata cache
-d365fo-client metadata sync --force-refresh
+```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"
+      }
+    }
+  }
+}
 ```
 
-#### Version Information
-```bash
-# Get application versions
-d365fo-client version app
-d365fo-client version platform  
-d365fo-client version build
+**Option 2: Explicit Credentials**
+For environments requiring service principal authentication:
+
+```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
+    }
+  ]
+}
 ```
 
-#### Label Operations
-```bash
-# Resolve single label
-d365fo-client labels resolve "@SYS13342"
+**Option 3: Docker Integration**
+For containerized environments and enhanced isolation:
 
-# Search labels by pattern
-d365fo-client labels search "customer" --language "en-US"
+```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
+    }
+  ]
+}
 ```
 
-### Global Options
-
-- `--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)
+**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`)
 
-### Configuration Profiles
+**Prerequisites:**
+- Docker installed and running
+- Access to Docker Hub or GitHub Container Registry
+- Network access for pulling the container image
 
-Create reusable configurations in `~/.d365fo-client/config.yaml`:
+##### Claude Desktop Integration
 
-```yaml
-profiles:
-  production:
-    base_url: "https://prod.dynamics.com"
-    use_default_credentials: true
-    timeout: 60
-    
-  development:
-    base_url: "https://dev.dynamics.com" 
-    client_id: "${AZURE_CLIENT_ID}"
-    client_secret: "${AZURE_CLIENT_SECRET}"
-    tenant_id: "${AZURE_TENANT_ID}"
-    use_cache_first: true
+Add to your Claude Desktop configuration:
 
-default_profile: "development"
+```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"
+      }
+    }
+  }
+}
 ```
 
-### Examples
+**Benefits of uvx approach:**
+- Always uses the latest version from the repository
+- No local installation required  
+- Automatic dependency management
+- Works across different environments
 
-```bash
-# Quick entity discovery
-d365fo-client entities list --pattern "cust.*" --output json
+#### Alternative: Programmatic Usage
 
-# Get comprehensive entity information
-d365fo-client entities get CustomersV3 --properties --keys --labels --output yaml
+```python
+from d365fo_client.mcp import D365FOMCPServer
 
-# Search for calculation actions
-d365fo-client metadata actions --pattern "calculate|compute" --output table
+# Create and run server with custom configuration
+config = {
+    "default_environment": {
+        "base_url": "https://your-environment.dynamics.com",
+        "use_default_credentials": True
+    }
+}
 
-# Test environment connectivity
-d365fo-client version app --verbose
+server = D365FOMCPServer(config)
+await server.run()
 ```
 
-For a complete command reference:
-
-```bash
-d365fo-client --help
-d365fo-client entities --help
-d365fo-client metadata --help
-```
-### Basic Usage
+#### Custom MCP Clients
+Connect using any MCP-compatible client library:
 
 ```python
-import asyncio
-from d365fo_client import D365FOClient, FOClientConfig
+from mcp import Client
 
-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 Client("d365fo-mcp-server") as client:
+    # Discover available tools
+    tools = await client.list_tools()
     
-    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())
+    # Execute operations
+    result = await client.call_tool(
+        "d365fo_query_entities",
+        {"entityName": "Customers", "top": 5}
+    )
 ```
 
-### Using Convenience Function
-
-```python
-from d365fo_client import create_client
+#### Docker Deployment
 
-# 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)
-```
+For containerized environments and production deployments:
 
-## Configuration
+**Pull the Docker Image:**
+```bash
+# Pull from GitHub Container Registry
+docker pull ghcr.io/mafzaal/d365fo-client:latest
 
-### Authentication Options
+# Or pull a specific version
+docker pull ghcr.io/mafzaal/d365fo-client:v0.2.3
+```
 
-```python
-from d365fo_client import FOClientConfig
+**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
+```
 
-# Option 1: Default Azure credentials (recommended)
-config = FOClientConfig(
-    base_url="https://your-fo-environment.dynamics.com",
-    use_default_credentials=True
-)
+**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:
+```
 
-# 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
-)
+**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)
 
-# Option 3: 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
-)
-```
+### Architecture Benefits
 
-## Core Operations
+#### 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
 
-### CRUD Operations
+#### 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
 
-```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}")
-```
+#### 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
 
-### Advanced Querying
+### Troubleshooting
 
-```python
-from d365fo_client import QueryOptions
+#### Common Issues
 
-# 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
-)
+**Connection Failures**
+```bash
+# Test connectivity
+d365fo-client version app --base-url https://your-environment.dynamics.com
 
-result = await client.get_data("/data/CustomersV3", options)
-print(f"Total count: {result.get('@odata.count')}")
+# Check logs
+tail -f ~/.d365fo-mcp/logs/mcp-server.log
 ```
 
-### Action Execution
+**Authentication Issues**
+```bash
+# Verify Azure CLI authentication
+az account show
 
-```python
-# Unbound action
-result = await client.post_data("/data/calculateTax", {
-    "amount": 1000.00,
-    "taxGroup": "STANDARD"
-})
+# Test with explicit credentials
+export D365FO_CLIENT_ID="your-client-id"
+# ... set other variables
+d365fo-mcp-server
+```
 
-# Bound action on entity set
-result = await client.post_data("/data/CustomersV3/calculateBalances", {
-    "asOfDate": "2024-12-31"
-})
+**Performance Issues**
+```bash
+# Enable debug logging
+export D365FO_LOG_LEVEL="DEBUG"
 
-# Bound action on specific entity instance  
-result = await client.post_data("/data/CustomersV3('US-001')/calculateBalance", {
-    "asOfDate": "2024-12-31"
-})
+# Adjust connection settings
+export D365FO_CONNECTION_TIMEOUT="120"
+export D365FO_MAX_CONCURRENT_REQUESTS="5"
 ```
 
-### Metadata Operations
+#### Getting Help
 
-```python
-# Intelligent metadata synchronization (v2 system)
-sync_manager = await client.get_sync_manager()
-await sync_manager.smart_sync()
+- **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)
 
-# Search entities with enhanced filtering
-sales_entities = await client.search_entities("sales")
-print("Sales-related entities:", [e.name for e in sales_entities])
+### MCP Tools
 
-# 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}")
+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`** - Advanced OData querying with filters, selections, pagination, and performance optimization
+- **`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).**
 
-# Search actions with caching
-calc_actions = await client.search_actions("calculate")
-print("Calculation actions:", [a.name for a in calc_actions])
+### MCP Resources
 
-# 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}")
-```
+The server exposes four types of resources for discovery and access:
 
-### Label Operations
+#### 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
+```
 
-```python
-# Get specific label (v2 caching system)
-label_text = await client.get_label_text("@SYS13342")
-print(f"Label text: {label_text}")
+#### 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
+```
 
-# 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}")
+#### 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
+```
 
-# 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}")
+#### Query Resources
+Access predefined and templated queries:
+```
+d365fo://queries/customers_recent # Recent customers query template
+d365fo://queries/sales_summary    # Sales summary query with parameters
+```
 
-# 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}")
+#### 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
 ```
 
-## Error Handling
+### Usage Examples
 
-```python
-from d365fo_client import D365FOClientError, AuthenticationError, ConnectionError
+#### Basic Tool Execution
 
-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}")
+```json
+{
+  "tool": "d365fo_query_entities",
+  "arguments": {
+    "entityName": "CustomersV3",
+    "select": ["CustomerAccount", "Name", "Email"],
+    "filter": "CustomerGroup eq 'VIP'",
+    "top": 10
+  }
+}
 ```
 
-## Development
+#### Entity Schema Discovery
 
-### Setting up Development Environment
+```json
+{
+  "tool": "d365fo_get_entity_schema", 
+  "arguments": {
+    "entityName": "CustomersV3",
+    "includeProperties": true,
+    "resolveLabels": true,
+    "language": "en-US"
+  }
+}
+```
 
-```bash
-# Clone the repository
-git clone https://github.com/mafzaal/d365fo-client.git
-cd d365fo-client
+#### Environment Information
 
-# Install with development dependencies using uv
-uv sync --dev
+```json
+{
+  "tool": "d365fo_get_environment_info",
+  "arguments": {}
+}
+```
 
-# Run tests
-uv run pytest
+### Authentication & Configuration
 
-# Run integration tests
-.\tests\integration\integration-test-simple.ps1 test-sandbox
+#### Default Credentials (Recommended)
+Uses Azure Default Credential chain (Managed Identity, Azure CLI, etc.):
 
-# Format code
-uv run black .
-uv run isort .
+```bash
+export D365FO_BASE_URL="https://your-environment.dynamics.com"
+# No additional auth environment variables needed
+d365fo-mcp-server
+```
 
-# Type checking
-uv run mypy src/
+#### Explicit Credentials
+For service principal authentication:
 
-# Quality checks
-.\make.ps1 quality-check  # Windows PowerShell
-# or
-make quality-check       # Unix/Linux/macOS
+```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
 ```
 
-### Project Structure
+#### Azure Key Vault Integration (New in v0.2.3)
+For secure credential storage using Azure Key Vault:
 
-```
-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
-│       ├── 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
+```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
 ```
 
-## Configuration Options
+#### Advanced Configuration
 
-| 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 |
-| `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 |
+Create a configuration file or set additional environment variables:
 
-### Cache Directory Behavior
+```bash
+# Optional: Logging configuration
+export D365FO_LOG_LEVEL="DEBUG"
 
-By default, the client uses platform-appropriate user cache directories:
+# Optional: Cache settings
+export D365FO_CACHE_DIR="/custom/cache/path"
 
-- **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`)
+# Optional: Performance tuning
+export D365FO_CONNECTION_TIMEOUT="60"
+export D365FO_MAX_CONCURRENT_REQUESTS="10"
+```
 
-You can override this by explicitly setting `metadata_cache_dir`:
+## Python Client Library
 
-```python
-from d365fo_client import FOClientConfig
+### Features
 
-# Use custom cache directory
-config = FOClientConfig(
-    base_url="https://your-fo-environment.dynamics.com",
-    metadata_cache_dir="/custom/cache/path"
-)
+- 🔗 **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
 
-# Or get the default cache directory programmatically
-from d365fo_client import get_user_cache_dir
+### Installation
 
-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)
-)
+```bash
+# Install from PyPI
+pip install d365fo-client
+
+# 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
+
+# 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
 ```
 
-## Testing
+**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.
 
-This project includes comprehensive testing at multiple levels to ensure reliability and quality.
+**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`
 
-### Unit Tests
+Please update your environment variables accordingly when upgrading.
 
-Run standard unit tests for core functionality:
+## Python Client Quick Start
 
-```bash
-# Run all unit tests
-uv run pytest
+## Command Line Interface (CLI)
 
-# Run with coverage
-uv run pytest --cov=d365fo_client --cov-report=html
+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.
 
-# Run specific test file
-uv run pytest tests/test_client.py -v
-```
+### Usage
 
-### Integration Tests
+```bash
+# Use the installed CLI command
+d365fo-client [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND] [OPTIONS]
 
-The project includes a sophisticated multi-tier integration testing framework:
+# Alternative: Module execution
+python -m d365fo_client.main [OPTIONS] COMMAND [ARGS]
+```
 
-#### Quick Start
+### Command Categories
 
+#### Entity Operations
 ```bash
-# Run sandbox integration tests (recommended)
-.\tests\integration\integration-test-simple.ps1 test-sandbox
+# List entities with filtering
+d365fo-client entities list --pattern "customer" --limit 10
 
-# Run mock server tests (no external dependencies)
-.\tests\integration\integration-test-simple.ps1 test-mock
+# Get entity details and schema
+d365fo-client entities get CustomersV3 --properties --keys --labels
 
-# Run with verbose output
-.\tests\integration\integration-test-simple.ps1 test-sandbox -VerboseOutput
+# 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
 ```
 
-#### Test Levels
+#### Metadata Operations
+```bash
+# Search and discover entities
+d365fo-client metadata entities --search "sales" --output json
 
-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
+# Get available actions
+d365fo-client metadata actions --pattern "calculate" --limit 5
 
-2. **Sandbox Tests** ⭐ *(Default)* - Tests against real D365 F&O test environments
-   - Validates authentication
-   - Tests real API behavior
-   - Requires test environment access
-
-3. **Live Tests** - Optional tests against production environments
-   - Final validation
-   - Performance benchmarking
-   - Use with caution
+# Enumerate system enumerations
+d365fo-client metadata enums --search "status" --output table
 
-#### Configuration
+# Synchronize metadata cache
+d365fo-client metadata sync --force-refresh
+```
 
-Set up integration testing with environment variables:
+#### Version Information
+```bash
+# Get application versions
+d365fo-client version app
+d365fo-client version platform  
+d365fo-client version build
+```
 
+#### Label Operations
 ```bash
-# Copy the template and configure
-cp tests/integration/.env.template tests/integration/.env
+# Resolve single label
+d365fo-client labels resolve "@SYS13342"
 
-# Edit .env file with your settings:
-INTEGRATION_TEST_LEVEL=sandbox
-D365FO_SANDBOX_BASE_URL=https://your-test.dynamics.com
-AZURE_CLIENT_ID=your-client-id
-AZURE_CLIENT_SECRET=your-client-secret
-AZURE_TENANT_ID=your-tenant-id
+# Search labels by pattern
+d365fo-client labels search "customer" --language "en-US"
 ```
 
-#### Available Commands
+### Global Options
 
-```bash
-# Test environment setup
-.\tests\integration\integration-test-simple.ps1 setup
+- `--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)
 
-# Dependency checking
-.\tests\integration\integration-test-simple.ps1 deps-check
+### Configuration Profiles
 
-# 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
+Create reusable configurations in `~/.d365fo-client/config.yaml`:
 
-# Coverage and reporting
-.\tests\integration\integration-test-simple.ps1 coverage
+```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
 
-# Clean up test artifacts
-.\tests\integration\integration-test-simple.ps1 clean
+default_profile: "development"
 ```
 
-#### Test Coverage
+### Examples
 
-Integration tests cover:
+```bash
+# Quick entity discovery
+d365fo-client entities list --pattern "cust.*" --output json
 
-- ✅ **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
+# Get comprehensive entity information
+d365fo-client entities get CustomersV3 --properties --keys --labels --output yaml
 
-For detailed information, see [Integration Testing Documentation](tests/integration/README.md).
+# Search for calculation actions
+d365fo-client metadata actions --pattern "calculate|compute" --output table
 
-### Test Results
+# Test environment connectivity
+d365fo-client version app --verbose
+```
 
-Recent sandbox integration test results:
+For a complete command reference:
+
+```bash
+d365fo-client --help
+d365fo-client entities --help
+d365fo-client metadata --help
 ```
-✅ 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
+### 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())
 ```
 
-## Model Context Protocol (MCP) Server
+### Using Convenience Function
 
-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.
+```python
+from d365fo_client import create_client
 
-### Overview
+# 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)
+```
 
-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
+## Configuration
 
-### Quick Start
+### Authentication Options
 
-#### Installation and Setup
+```python
+from d365fo_client import FOClientConfig
 
-```bash
-# Install d365fo-client with MCP dependencies
-pip install d365fo-client
+# Option 1: Default Azure credentials (recommended)
+config = FOClientConfig(
+    base_url="https://your-fo-environment.dynamics.com",
+    use_default_credentials=True
+)
 
-# Set up environment variables
-export D365FO_BASE_URL="https://your-environment.dynamics.com"
-export AZURE_CLIENT_ID="your-client-id"          # Optional with default credentials
-export AZURE_CLIENT_SECRET="your-client-secret"  # Optional with default credentials  
-export AZURE_TENANT_ID="your-tenant-id"          # Optional with default credentials
+# 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
+)
 
-# Start the MCP server
-d365fo-mcp-server
+# 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
+)
 ```
 
-#### Alternative: Programmatic Usage
+## Core Operations
 
-```python
-from d365fo_client.mcp import D365FOMCPServer
+### CRUD Operations
 
-# Create and run server with custom configuration
-config = {
-    "default_environment": {
-        "base_url": "https://your-environment.dynamics.com",
-        "use_default_credentials": True
+```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}")
+```
 
-server = D365FOMCPServer(config)
-await server.run()
+### 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')}")
 ```
 
-### MCP Tools
+### Action Execution
 
-The server provides 12 comprehensive tools organized into functional categories:
+```python
+# Unbound action
+result = await client.post_data("/data/calculateTax", {
+    "amount": 1000.00,
+    "taxGroup": "STANDARD"
+})
 
-#### Connection Tools (2 tools)
-- **`d365fo_test_connection`** - Test environment connectivity and health
-- **`d365fo_get_environment_info`** - Get comprehensive environment details, versions, and statistics
+# Bound action on entity set
+result = await client.post_data("/data/CustomersV3/calculateBalances", {
+    "asOfDate": "2024-12-31"
+})
 
-#### 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
+# Bound action on specific entity instance  
+result = await client.post_data("/data/CustomersV3('US-001')/calculateBalance", {
+    "asOfDate": "2024-12-31"
+})
+```
 
-#### 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
+### Metadata Operations
 
-#### 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
+```python
+# Intelligent metadata synchronization (v2 system)
+sync_manager = await client.get_sync_manager()
+await sync_manager.smart_sync()
 
-### MCP Resources
+# Search entities with enhanced filtering
+sales_entities = await client.search_entities("sales")
+print("Sales-related entities:", [e.name for e in sales_entities])
 
-The server exposes four types of resources for discovery and access:
+# 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}")
 
-#### 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
-```
+# Search actions with caching
+calc_actions = await client.search_actions("calculate")
+print("Calculation actions:", [a.name for a in calc_actions])
 
-#### 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
+# 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}")
 ```
 
-#### 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
-```
+### Label Operations
 
-#### Query Resources
-Access predefined and templated queries:
-```
-d365fo://queries/customers_recent # Recent customers query template
-d365fo://queries/sales_summary    # Sales summary query with parameters
-```
+```python
+# Get specific label (v2 caching system)
+label_text = await client.get_label_text("@SYS13342")
+print(f"Label text: {label_text}")
 
-#### 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
+# 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}")
 ```
 
-### Usage Examples
+## Error Handling
 
-#### Basic Tool Execution
+```python
+from d365fo_client import D365FOClientError, AuthenticationError, ConnectionError
 
-```json
-{
-  "tool": "d365fo_query_entities",
-  "arguments": {
-    "entityName": "CustomersV3",
-    "select": ["CustomerAccount", "Name", "Email"],
-    "filter": "CustomerGroup eq 'VIP'",
-    "top": 10
-  }
-}
+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}")
 ```
 
-#### Entity Schema Discovery
+## Development
 
-```json
-{
-  "tool": "d365fo_get_entity_schema", 
-  "arguments": {
-    "entityName": "CustomersV3",
-    "includeProperties": true,
-    "resolveLabels": true,
-    "language": "en-US"
-  }
-}
+### Setting up Development Environment
+
+```bash
+# 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
 ```
 
-#### Environment Information
+### Project Structure
 
-```json
-{
-  "tool": "d365fo_get_environment_info",
-  "arguments": {}
-}
+```
+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
 ```
 
-### Authentication & Configuration
+## Configuration Options
 
-#### Default Credentials (Recommended)
-Uses Azure Default Credential chain (Managed Identity, Azure CLI, etc.):
+| 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 |
 
-```bash
-export D365FO_BASE_URL="https://your-environment.dynamics.com"
-# No additional auth environment variables needed
-d365fo-mcp-server
-```
+### Cache Directory Behavior
 
-#### Explicit Credentials
-For service principal authentication:
+By default, the client uses platform-appropriate user cache directories:
 
-```bash
-export D365FO_BASE_URL="https://your-environment.dynamics.com"
-export AZURE_CLIENT_ID="your-client-id"
-export AZURE_CLIENT_SECRET="your-client-secret"
-export AZURE_TENANT_ID="your-tenant-id"
-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 AZURE_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