Skip to content

AGENTS.md

Latest commit

 

History

History
535 lines (451 loc) · 12.9 KB

AGENTS.md

File metadata and controls

535 lines (451 loc) · 12.9 KB
Raw

AI Agent Guide for D365FO MCP Server

This guide is specifically designed for AI agents and assistants to effectively interact with Microsoft Dynamics 365 Finance & Operations through the d365fo-client MCP server. It provides structured workflows, best practices, and common patterns for successful automation and integration.

Architecture Overview

The d365fo-client MCP server provides 49 comprehensive tools organized across 9 functional categories, implemented using a modern FastMCP mixin-based architecture for enhanced performance and maintainability. All tools are available through standardized MCP protocol interactions regardless of the underlying implementation.

Quick Start for AI Agents

Essential First Steps

  1. Test Connectivity: Always start with d365fo_test_connection to verify environment access
  2. Get Environment Info: Use d365fo_get_environment_info to understand the D365FO environment capabilities
  3. Explore Available Entities: Use d365fo_search_entities to discover relevant data entities for your tasks
// Step 1: Test connection
{
  "tool": "d365fo_test_connection",
  "arguments": {}
}

// Step 2: Get environment information
{
  "tool": "d365fo_get_environment_info",
  "arguments": {}
}

// Step 3: Search for relevant entities
{
  "tool": "d365fo_search_entities",
  "arguments": {
    "pattern": "customer",
    "limit": 10
  }
}

Core Workflows for AI Agents

1. Data Discovery and Exploration

Use Case: Understanding available data structures and relationships

// Discover entities by business area
{
  "tool": "d365fo_search_entities",
  "arguments": {
    "pattern": "sales|customer|invoice",
    "category": "Master",
    "limit": 20
  }
}

// Get detailed schema for specific entity
{
  "tool": "d365fo_get_entity_schema",
  "arguments": {
    "entityName": "CustomersV3",
    "includeProperties": true,
    "includeKeys": true,
    "resolveLabels": true
  }
}

// Search for related actions
{
  "tool": "d365fo_search_actions",
  "arguments": {
    "pattern": "customer",
    "limit": 10
  }
}

2. Data Querying and Analysis

Use Case: Retrieving and analyzing business data

// Query customers with filtering
{
  "tool": "d365fo_query_entities",
  "arguments": {
    "entityName": "CustomersV3",
    "select": ["CustomerAccount", "Name", "CustomerGroup", "Email"],
    "filter": "CustomerGroup eq 'VIP'",
    "top": 50
  }
}

// Get specific customer record
{
  "tool": "d365fo_get_entity_record",
  "arguments": {
    "entityName": "CustomersV3",
    "key": "US-001",
    "select": ["CustomerAccount", "Name", "Address", "ContactInfo"]
  }
}

// Query related sales orders
{
  "tool": "d365fo_query_entities",
  "arguments": {
    "entityName": "SalesOrderHeaders",
    "select": ["SalesOrderNumber", "CustomerAccount", "TotalAmount", "OrderDate"],
    "filter": "CustomerAccount eq 'US-001'",
    "orderby": "OrderDate desc",
    "top": 20
  }
}

3. Data Management Operations

Use Case: Creating, updating, and managing business records

// Create new customer
{
  "tool": "d365fo_create_entity_record",
  "arguments": {
    "entityName": "CustomersV3",
    "data": {
      "CustomerAccount": "US-999",
      "Name": "New Customer Corp",
      "CustomerGroup": "Standard",
      "Email": "contact@newcustomer.com"
    }
  }
}

// Update customer information
{
  "tool": "d365fo_update_entity_record",
  "arguments": {
    "entityName": "CustomersV3",
    "key": "US-999",
    "data": {
      "Email": "updated@newcustomer.com",
      "Name": "Updated Customer Corp"
    }
  }
}

// Execute business action
{
  "tool": "d365fo_call_action",
  "arguments": {
    "entityName": "CustomersV3",
    "actionName": "ValidateCustomer",
    "parameters": {
      "CustomerAccount": "US-999"
    }
  }
}

4. Metadata and System Management

Use Case: Understanding system configuration and capabilities

// Search system enumerations
{
  "tool": "d365fo_search_enumerations",
  "arguments": {
    "search": "status",
    "limit": 10
  }
}

// Get enumeration values
{
  "tool": "d365fo_get_enumeration_fields",
  "arguments": {
    "enumerationName": "CustVendorBlocked",
    "resolveLabels": true
  }
}

// Get installed modules
{
  "tool": "d365fo_get_installed_modules",
  "arguments": {}
}

5. Reporting and Document Management

Use Case: Generating and downloading business documents

// Download customer invoice
{
  "tool": "d365fo_download_customer_invoice",
  "arguments": {
    "invoiceId": "INV-001",
    "format": "PDF",
    "profile": "default"
  }
}

// Download sales confirmation
{
  "tool": "d365fo_download_sales_confirmation",
  "arguments": {
    "salesOrderNumber": "SO-001",
    "format": "PDF",
    "profile": "default"
  }
}

// Generate custom SRS report
{
  "tool": "d365fo_download_srs_report",
  "arguments": {
    "reportName": "CustomerStatement",
    "parameters": {
      "CustomerAccount": "US-001",
      "FromDate": "2024-01-01",
      "ToDate": "2024-12-31"
    },
    "format": "PDF"
  }
}

Advanced Patterns for AI Agents

Profile-Based Multi-Environment Operations

Use Case: Working with multiple D365FO environments (dev, test, prod)

// List available profiles
{
  "tool": "d365fo_list_profiles",
  "arguments": {}
}

// Test specific environment
{
  "tool": "d365fo_test_profile_connection",
  "arguments": {
    "profileName": "production"
  }
}

// Query data from specific environment
{
  "tool": "d365fo_query_entities",
  "arguments": {
    "entityName": "CustomersV3",
    "profile": "production",
    "top": 10
  }
}

Database Analysis and Insights

Use Case: Advanced data analysis and metadata exploration

// Get database schema overview
{
  "tool": "d365fo_get_database_schema",
  "arguments": {
    "includeEntityRelationships": true,
    "profile": "default"
  }
}

// Execute analytical queries
{
  "tool": "d365fo_execute_sql_query",
  "arguments": {
    "query": "SELECT name, entity_category, data_service_enabled FROM data_entities WHERE entity_category = 'Master' ORDER BY name LIMIT 20",
    "profile": "default"
  }
}

// Get performance statistics
{
  "tool": "d365fo_get_database_statistics",
  "arguments": {
    "includePerformanceMetrics": true,
    "profile": "default"
  }
}

Synchronization and Cache Management

Use Case: Managing metadata synchronization and cache optimization

// Start metadata sync
{
  "tool": "d365fo_start_sync",
  "arguments": {
    "strategy": "incremental",
    "profile": "default"
  }
}

// Monitor sync progress
{
  "tool": "d365fo_get_sync_progress",
  "arguments": {
    "sessionId": "sync-session-123",
    "profile": "default"
  }
}

// Get sync history
{
  "tool": "d365fo_get_sync_history",
  "arguments": {
    "limit": 10,
    "profile": "default"
  }
}

Best Practices for AI Agents

1. Error Handling and Resilience

  • Always check connection first: Use d365fo_test_connection before starting workflows
  • Handle authentication errors: Retry with different profiles if authentication fails
  • Validate entity names: Use d365fo_search_entities to verify entity existence before operations
  • Check for required fields: Use d365fo_get_entity_schema to understand mandatory fields before creating records

2. Performance Optimization

  • Use appropriate filters: Apply $filter parameters to reduce data transfer
  • Limit result sets: Always use top parameter for large queries
  • Select specific fields: Use select parameter to retrieve only needed columns
  • Cache metadata: Leverage the built-in metadata caching for repeated operations

3. Data Integrity

  • Validate before updates: Check existing record state before modifications
  • Use ETags for concurrency: Leverage optimistic concurrency control where available
  • Understand relationships: Use d365fo_get_entity_schema to understand foreign key relationships
  • Test in non-production: Always test complex operations in development environments first

4. Security and Compliance

  • Use appropriate profiles: Separate development, test, and production profiles
  • Validate permissions: Check that the current user has appropriate permissions for operations
  • Audit operations: Log significant data changes for compliance requirements
  • Secure credentials: Use profile-based authentication rather than embedding credentials

Common Integration Scenarios

Customer Relationship Management

// Complete customer onboarding workflow
[
  {
    "tool": "d365fo_search_entities",
    "arguments": {"pattern": "customer", "category": "Master"}
  },
  {
    "tool": "d365fo_get_entity_schema",
    "arguments": {"entityName": "CustomersV3", "includeProperties": true}
  },
  {
    "tool": "d365fo_create_entity_record",
    "arguments": {
      "entityName": "CustomersV3",
      "data": {
        "CustomerAccount": "NEW-001",
        "Name": "New Customer",
        "CustomerGroup": "Standard"
      }
    }
  },
  {
    "tool": "d365fo_get_entity_record",
    "arguments": {"entityName": "CustomersV3", "key": "NEW-001"}
  }
]

Financial Reporting

// Generate comprehensive financial report
[
  {
    "tool": "d365fo_query_entities",
    "arguments": {
      "entityName": "GeneralJournalEntries",
      "filter": "AccountingDate ge datetime'2024-01-01' and AccountingDate le datetime'2024-12-31'",
      "select": ["AccountNum", "TransactionAmount", "AccountingDate"],
      "top": 1000
    }
  },
  {
    "tool": "d365fo_download_srs_report",
    "arguments": {
      "reportName": "FinancialStatement",
      "parameters": {"FiscalYear": "2024"},
      "format": "PDF"
    }
  }
]

Supply Chain Management

// Inventory and procurement analysis
[
  {
    "tool": "d365fo_query_entities",
    "arguments": {
      "entityName": "InventoryOnHand",
      "select": ["ItemNumber", "AvailableQuantity", "WarehouseId"],
      "filter": "AvailableQuantity lt 10"
    }
  },
  {
    "tool": "d365fo_query_entities",
    "arguments": {
      "entityName": "PurchaseOrders",
      "filter": "PurchaseOrderStatus eq 'Open'",
      "select": ["PurchaseOrderNumber", "VendorAccount", "TotalAmount"]
    }
  }
]

Troubleshooting Guide for AI Agents

Common Issues and Solutions

  1. Connection Failures

    // Test with explicit timeout
{
  "tool": "d365fo_test_connection",
  "arguments": {"timeout": 120}
}

  2. Entity Not Found Errors

    // Search for similar entities
{
  "tool": "d365fo_search_entities",
  "arguments": {"pattern": "partial_name"}
}

  3. Authentication Issues

    // List and test profiles
{
  "tool": "d365fo_list_profiles",
  "arguments": {}
}

  4. Data Validation Errors

    // Get entity schema for validation rules
{
  "tool": "d365fo_get_entity_schema",
  "arguments": {"entityName": "EntityName", "includeProperties": true}
}

Performance Monitoring

// Monitor server performance
{
  "tool": "d365fo_get_server_performance",
  "arguments": {}
}

// Check database statistics
{
  "tool": "d365fo_get_database_statistics",
  "arguments": {"includePerformanceMetrics": true}
}

Tool Reference Quick Guide

Essential Tools for Every AI Agent

  • d365fo_test_connection - Always start here
  • d365fo_get_environment_info - Understand the environment
  • d365fo_search_entities - Discover available data
  • d365fo_query_entities - Primary data retrieval
  • d365fo_get_entity_schema - Understand data structures

Data Operations

  • d365fo_get_entity_record - Retrieve specific records
  • d365fo_create_entity_record - Create new records
  • d365fo_update_entity_record - Modify existing records
  • d365fo_delete_entity_record - Remove records
  • d365fo_call_action - Execute business logic

Advanced Operations

  • d365fo_execute_sql_query - Custom analytical queries
  • d365fo_download_srs_report - Generate reports
  • d365fo_start_sync - Manage metadata synchronization
  • d365fo_get_labels_batch - Multi-language support

Profile Management

  • d365fo_list_profiles - See available environments
  • d365fo_test_profile_connection - Validate environment access
  • d365fo_create_profile - Set up new environments

Success Patterns

  1. Start Small: Begin with simple queries before complex operations
  2. Understand the Schema: Always explore entity schemas before data operations
  3. Use Filters Wisely: Apply appropriate filters to manage data volume
  4. Test Incrementally: Validate each step of complex workflows
  5. Monitor Performance: Use performance tools to optimize operations
  6. Handle Errors Gracefully: Implement robust error handling and recovery
  7. Document Workflows: Keep track of successful patterns for reuse

This guide provides AI agents with the knowledge and patterns needed to effectively leverage the full capabilities of the D365FO MCP server for automation, integration, and analysis tasks.