mcp_xpp

# MCP X++ Server A Model Context Protocol (MCP) server for Microsoft Dynamics 365 Finance & Operations development. This tool enables D365 object creation, modification, and analysis through the MCP standard, allowing integration with various development environments. **Date:** September 18, 2025 **Status:** Functional with VS2022 service integration and enhanced form creation ## Recent Updates ✨ **September 19, 2025 - Safe Object Deletion Feature:** - 🗑️ **NEW delete_xpp_object Tool**: Safe D365 object deletion with dependency validation and cascade support - 🛡️ **Dependency Protection**: Prevents deletion if other objects depend on target, avoiding breaking changes - 🔄 **Cache Consistency**: Automatic search index updates after successful deletions - ⚡ **High Performance**: Direct metadata provider integration with ISingleKeyedMetadataProvider.Delete - 🌲 **Cascade Deletion**: Optional deletion of child objects (form parts, table relations, etc.) - ✅ **Comprehensive Testing**: Full create/delete cycle validation across object types **September 18, 2025 - Array Modifications & Form Creation Enhancements:** - 🚀 **NEW Array-Only Modifications**: `execute_object_modification` now exclusively uses batch format for consistent operations - 🔄 **Enforced Bulk Processing**: Single operations use array with one element - no more consecutive separate calls - 📊 **Enhanced Response Tracking**: Per-operation success/failure reporting with detailed timing and error messages - 📋 **Best Practice Documentation**: Clear guidance to group all modifications for same object into single call - 🎯 **NEW create_form Tool**: Specialized form creation with pattern support and datasource integration - 🔧 **DetailsMaster Pattern Fixed**: Resolved validation issues through intelligent field control creation - 🗄️ **Enhanced DataSource Support**: Flexible datasource handling (arrays, strings, comma-separated) - 📋 **Pattern Discovery**: 36 filtered form patterns with descriptions and requirements - ✅ **Pattern Validation**: Automatic field control creation for patterns requiring them ## Overview This MCP server provides D365 F&O development capabilities including: - **Object Creation**: Support for D365 classes, tables, forms, enums, and 544+ other object types - **Form Creation**: ✨ **Enhanced** - Specialized form creation with pattern validation and datasource integration - **Object Deletion**: ✨ **NEW** - Safe object deletion with dependency validation and cascade support - **Object Modification**: Add methods, fields, and other components to existing objects - **Object Inspection**: Analyze D365 objects and extract X++ source code - **Codebase Search**: Browse and search through D365 codebases with pattern matching - **MCP Protocol**: Compatible with Claude Desktop, VS Code, and other MCP clients ## Architecture The system consists of two main components communicating through Windows Named Pipes: ### MCP X++ Server (Node.js/TypeScript) - Implements the Model Context Protocol (STDIO) - Handles object creation, modification, and search operations - Provides file browsing and codebase indexing - Compatible with MCP clients like Claude Desktop and VS Code ### D365 Metadata Service (C# .NET 4.8) - Integrates with Microsoft's D365 assemblies - Handles object creation and modification through VS2022 APIs - Provides dynamic reflection for runtime object discovery - Communicates via Named Pipe: `mcp-xpp-d365-service` The architecture enables D365 development from various MCP-compatible clients while maintaining compatibility with existing D365 development workflows. ## Available Tools The server provides 10 specialized tools for D365 development: 1. **create_xpp_object** - Create D365 objects (classes, tables, enums, etc.) - *Note: Use create_form for forms* 2. **create_form** - ✨ **NEW** - Specialized form creation with pattern support and datasource integration 3. **delete_xpp_object** - ✨ **NEW** - Safe D365 object deletion with dependency validation and cache consistency 4. **execute_object_modification** - ✨ **ENHANCED** - Array-based object modification with batch processing - **BEST PRACTICE**: Group all modifications for same object 5. **discover_modification_capabilities** - Explore available modification methods 6. **find_xpp_object** - Find specific objects by name/type 7. **search_objects_pattern** - Pattern search with wildcard support 8. **inspect_xpp_object** - Object analysis with X++ source code extraction 9. **get_current_config** - System configuration and status 10. **build_object_index** - Index management for search performance ## Prerequisites - **Visual Studio 2022** (Community, Professional, or Enterprise) - **Dynamics 365 Development Tools** for Visual Studio 2022 - **Node.js** (latest LTS version recommended) - **.NET Framework 4.8** (typically included with Windows) ## Installation 1. Clone the repository 2. Install Node.js dependencies: `npm install` 3. Run setup to configure VS2022 integration: `.\tools\build-and-run.ps1 -Action setup` 4. Build the project: `.\tools\build-and-run.ps1 -Action build` ## Usage ### Starting the Server Run the MCP server using: ```bash node build/index.js ``` The server automatically detects D365 paths from your VS2022 installation. For manual configuration, use: ```bash node build/index.js --xpp-path "C:\path\to\PackagesLocalDirectory" ``` ### MCP Client Configuration #### VS Code Configure in `.vscode/mcp.json`: ```json { "servers": { "mcp-xpp-server": { "command": "node", "args": ["./build/index.js"], "cwd": "${workspaceFolder}", "type": "stdio" } } } ``` #### Claude Desktop Add to Claude Desktop configuration file: ```json { "mcpServers": { "mcp-xpp-server": { "command": "node", "args": ["path/to/mcp_xpp/build/index.js"] } } } ``` ## Tool Reference ### Object Creation #### `create_xpp_object` Creates D365 F&O objects using VS2022 service integration. ⚠️ **Important:** For creating forms, use the dedicated `create_form` tool instead as it provides specialized pattern support and datasource integration. **Parameters:** - `objectName` (string) - Name of the D365 object - `objectType` (string) - Object type (AxClass, AxTable, AxEnum, etc.) - *Excludes AxForm* - `layer` (string, optional) - Application layer (usr, cus, var) - `outputPath` (string, optional) - Output directory (default: "Models") - `publisher` (string, optional) - Company name (default: "YourCompany") - `version` (string, optional) - Version number (default: "1.0.0.0") - `dependencies` (array, optional) - Model dependencies - `properties` (object, optional) - Object-specific configuration **Example:** ```javascript create_xpp_object({ "objectName": "MyCustomClass", "objectType": "AxClass", "layer": "usr" }) ``` #### `create_form` ✨ **NEW** Specialized tool for creating D365 forms with advanced pattern support and datasource integration. This tool combines form creation and pattern discovery in one interface. **Parameters:** - `mode` (string, required) - Operation mode: - `"create"` - Create a new form with patterns and datasources - `"list_patterns"` - Discover available D365 form patterns - `formName` (string, optional) - Form name (required when mode='create') - `patternName` (string, optional) - D365 form pattern to apply (e.g., 'SimpleListDetails', 'DetailsMaster', 'Dialog') - `patternVersion` (string, optional) - Pattern version (default: 'UX7 1.0') - `dataSources` (array|string, optional) - Table names for form datasources - `modelName` (string, optional) - D365 model/package name (default: 'ApplicationSuite') **Key Features:** - 🎯 **Pattern-Aware**: Automatically adds field controls when patterns require them (e.g., DetailsMaster) - 🗄️ **Flexible DataSources**: Supports arrays, single strings, or comma-separated strings - 🔍 **Pattern Discovery**: Lists all 36+ available D365 form patterns with descriptions - ✅ **Enhanced Validation**: Resolves pattern validation issues through intelligent field control creation **Examples:** ```javascript // Discover available patterns create_form({"mode": "list_patterns"}) // Create simple list form with datasource create_form({ "mode": "create", "formName": "MyCustomerListForm", "patternName": "SimpleListDetails", "dataSources": ["CustTable"] }) // Create DetailsMaster form with multiple datasources create_form({ "mode": "create", "formName": "MySalesOrderForm", "patternName": "DetailsMaster", "patternVersion": "UX7 1.0", "dataSources": ["SalesTable", "SalesLine", "CustTable"], "modelName": "MyCustomModel" }) // Create dialog form without datasources create_form({ "mode": "create", "formName": "MyConfirmationDialog", "patternName": "Dialog" }) ``` **Technical Notes:** - Patterns like DetailsMaster, SimpleListDetails, and ListPage automatically get enhanced with field controls (RecId, Name, Description, Code) when datasources are provided - Pattern validation has been fixed - forms can be created with or without datasources depending on pattern requirements - The tool uses direct VS2022 service integration for optimal D365 compatibility #### `delete_xpp_object` ✨ **NEW** Safely deletes D365 F&O objects with comprehensive dependency validation and cache consistency. This tool prevents breaking changes by validating dependencies before deletion. **Parameters:** - `objectName` (string, required) - Name of the D365 object to delete - `objectType` (string, required) - D365 object type (AxClass, AxTable, AxForm, AxEnum, etc.) - `cascadeDelete` (boolean, optional) - Delete dependent objects too (default: false) **Key Features:** - 🛡️ **Dependency Validation**: Prevents deletion if other objects depend on the target - 🗑️ **Safe Deletion**: Uses D365's ISingleKeyedMetadataProvider.Delete for proper cleanup - 🔄 **Cache Consistency**: Automatically updates search index after successful deletion - ⚡ **Fast Performance**: Direct metadata provider integration for optimal speed - 🌲 **Cascade Support**: Optional deletion of child objects (forms with parts/controls, etc.) **Examples:** ```javascript // Delete a custom class delete_xpp_object({ "objectName": "MyCustomClass", "objectType": "AxClass" }) // Delete a table with cascade (removes dependent field groups, relations, etc.) delete_xpp_object({ "objectName": "MyTestTable", "objectType": "AxTable", "cascadeDelete": true }) // Delete a form (will fail if dependencies exist without cascade) delete_xpp_object({ "objectName": "MyCustomForm", "objectType": "AxForm" }) ``` **Response Format:** ```json { "success": true, "message": "Successfully deleted object: MyCustomClass (AxClass)", "objectName": "MyCustomClass", "objectType": "AxClass", "cascadeDelete": false, "dependenciesRemoved": [], "cacheUpdate": "Success", "performance": "156ms" } ``` **⚠️ Safety Notes:** - **HIGH RISK OPERATION**: Deletion is permanent and cannot be undone - Always verify dependencies with `find_xpp_object` before deletion - Use `cascadeDelete: false` (default) for maximum safety - Test deletions in development environments first - Tool will fail safely if dependencies exist without cascade flag - Cache updates ensure immediate search consistency after deletion **Common Object Types:** - `AxClass` - X++ classes and business logic - `AxTable` - Data tables and schema - `AxForm` - User interface forms - `AxEnum` - Enumerations and value lists - `AxEdt` - Extended data types - `AxView` - Database views - `AxQuery` - Data queries - `AxReport` - SSRS reports ### Object Discovery #### `find_xpp_object` Locates X++ objects by name with optional filtering. **Parameters:** - `objectName` (string, required) - Name of the X++ object - `objectType` (string, optional) - Filter by object type - `model` (string, optional) - Filter by D365 model/package name #### `search_objects_pattern` Searches D365 objects using wildcard patterns. **Parameters:** - `pattern` (string, required) - Search pattern with wildcards (*, ?) - `objectType` (string, optional) - Filter by object type - `model` (string, optional) - Filter by D365 model/package name - `limit` (number, optional) - Maximum results (default: 50) - `format` (string, optional) - Output format: 'text' or 'json' #### `inspect_xpp_object` Analyzes D365 objects with multiple inspection modes. **Parameters:** - `objectName` (string, required) - Name of the X++ object - `objectType` (string, optional) - D365 object type - `inspectionMode` (string, optional) - Inspection level: - `summary` - Fast overview with collection counts - `properties` - All object properties with descriptions - `collection` - Specific collection items (requires collectionName) - `xppcode` - Extract X++ source code (requires codeTarget) - `collectionName` (string, optional) - Required when inspectionMode='collection' - `codeTarget` (string, optional) - Required when inspectionMode='xppcode': - `methods` - Extract all method source code - `specific-method` - Single method (requires methodName) - `event-handlers` - Event handler methods only - `methodName` (string, optional) - Required when codeTarget='specific-method' - `maxCodeLines` (number, optional) - Limit lines of source code per method - `filterPattern` (string, optional) - Wildcard filter for results **Examples:** ```javascript // Get object summary inspect_xpp_object({"objectName": "CustTable", "inspectionMode": "summary"}) // Extract specific method source code inspect_xpp_object({ "objectName": "SalesLine", "objectType": "AxTable", "inspectionMode": "xppcode", "codeTarget": "specific-method", "methodName": "validateWrite" }) ``` ### Object Modification #### `execute_object_modification` ✨ **ENHANCED WITH BATCH PROCESSING** Executes modification methods on existing D365 objects with array-based batch processing. **Always use array format** - single operations use array with one element. **📋 BEST PRACTICE**: Group ALL modifications for the same object into ONE call instead of making separate calls. This provides better performance, error handling, and transactional integrity. **Parameters:** - `objectType` (string, required) - D365 object type (e.g., 'AxTable', 'AxClass', 'AxForm') - `objectName` (string, required) - Name of existing object to modify - `modifications` (array, required) - Array of modification operations: - `methodName` (string, required) - Modification method to execute - `parameters` (object, required) - Method-specific parameters including: - `concreteType` (string, required) - Exact type from discover_modification_capabilities - `Name` (string) - Field/object name (use 'Name' not 'fieldName') - Other D365-specific parameters as required **✅ Features:** - **Per-operation tracking**: Each operation returns individual success/failure status - **Detailed error reporting**: Clear validation messages for failed operations - **Sequential processing**: Operations execute in order with timing information - **Batch efficiency**: Multiple operations in single service call **Examples:** ✅ **Single field (array with one element):** ```javascript execute_object_modification({ "objectType": "AxTable", "objectName": "CustTable", "modifications": [ { "methodName": "AddField", "parameters": { "concreteType": "AxTableFieldString", "Name": "MyCustomField", "Label": "My Custom Field", "HelpText": "Custom field description", "SaveContents": "Yes", "Mandatory": "No", "AllowEditOnCreate": "Yes", "AllowEdit": "Yes", "Visible": "Yes", "AosAuthorization": "None", "MinReadAccess": "Auto", "IgnoreEDTRelation": "No", "Null": "Yes", "IsSystemGenerated": "No", "IsManuallyUpdated": "No", "IsObsolete": "No", "GeneralDataProtectionRegulation": "None", "SysSharingType": "Duplicate" } } ] }) ``` ⭐ **Multiple fields in one batch (PREFERRED):** ```javascript execute_object_modification({ "objectType": "AxTable", "objectName": "CustTable", "modifications": [ { "methodName": "AddField", "parameters": { "concreteType": "AxTableFieldString", "Name": "CustomerCategory", "Label": "Customer Category", "HelpText": "Customer classification category", "SaveContents": "Yes", "Mandatory": "No", "AllowEditOnCreate": "Yes", "AllowEdit": "Yes", "Visible": "Yes", "AosAuthorization": "None", "MinReadAccess": "Auto", "IgnoreEDTRelation": "No", "Null": "Yes", "IsSystemGenerated": "No", "IsManuallyUpdated": "No", "IsObsolete": "No", "GeneralDataProtectionRegulation": "None", "SysSharingType": "Duplicate" } }, { "methodName": "AddField", "parameters": { "concreteType": "AxTableFieldInt", "Name": "CustomerPriority", "Label": "Customer Priority", "HelpText": "Priority level for customer", "SaveContents": "Yes", "Mandatory": "No", "AllowEditOnCreate": "Yes", "AllowEdit": "Yes", "Visible": "Yes", "AosAuthorization": "None", "MinReadAccess": "Auto", "IgnoreEDTRelation": "No", "Null": "Yes", "IsSystemGenerated": "No", "IsManuallyUpdated": "No", "IsObsolete": "No", "GeneralDataProtectionRegulation": "None", "SysSharingType": "Duplicate" } } ] }) ``` **📊 Response Format:** The tool returns detailed per-operation results: ```json { "summary": "2 succeeded, 1 failed (3 total)", "targetObject": "AxTable:CustTable", "operations": [ { "methodName": "AddField", "success": true, "processingTime": "371ms", "message": "Successfully executed AddField on AxTable:CustTable" }, { "methodName": "AddField", "success": false, "processingTime": "0ms", "error": "Parameter validation failed: Missing required parameters" } ] } ``` **💡 Tips:** - Use `discover_modification_capabilities` first to get exact parameter requirements - All D365 table fields require parameters like `SaveContents`, `Mandatory`, etc. - Group related modifications together for better performance - Check individual operation results for debugging failed operations #### `discover_modification_capabilities` Discovers available modification methods for D365 object types. **Parameters:** - `objectType` (string, required) - D365 object type to analyze ### System Management #### `get_current_config` Returns comprehensive server configuration and status information. #### `build_object_index` Builds or updates the searchable object index. **Parameters:** - `objectType` (string, optional) - Specific object type to index - `forceRebuild` (boolean, optional) - Force complete rebuild ## Supported Object Types Common D365 object types supported: - **AxClass** - X++ classes - **AxTable** - Data tables - **AxForm** - User interface forms - **AxEnum** - Enumerations - **AxEdt** - Extended data types - **AxView** - Database views - **AxQuery** - Data queries - **AxReport** - SSRS reports - **AxMenuItemDisplay** - Menu items - **AxDataEntityView** - OData entities The system supports 544+ object types total. ## Build Scripts The `build-and-run.ps1` script provides unified project management: ```powershell # Setup VS2022 integration .\tools\build-and-run.ps1 -Action setup # Build both TypeScript and C# components .\tools\build-and-run.ps1 -Action build # Run the MCP server .\tools\build-and-run.ps1 -Action run -Target mcp # Run the C# service .\tools\build-and-run.ps1 -Action run -Target csharp # Run tests .\tools\build-and-run.ps1 -Action test # Clean builds .\tools\build-and-run.ps1 -Action clean ``` ## Example Workflows ### Creating a New Class ```bash # Create a custom class create_xpp_object { "objectName": "MyBusinessLogic", "objectType": "AxClass", "layer": "usr" } # Add a method to the class execute_object_modification { "objectType": "AxClass", "objectName": "MyBusinessLogic", "methodName": "AddMethod", "parameters": { "methodName": "processData", "returnType": "void", "source": "public void processData() { }" } } ``` ### Searching and Analyzing Objects ```bash # Find customer-related objects search_objects_pattern { "pattern": "Cust*", "objectType": "AxTable", "limit": 20 } # Analyze a specific table inspect_xpp_object { "objectName": "CustTable", "objectType": "AxTable", "inspectionMode": "summary" } # Extract method source code inspect_xpp_object { "objectName": "CustTable", "objectType": "AxTable", "inspectionMode": "xppcode", "codeTarget": "specific-method", "methodName": "validateWrite" } ``` ## Technical Details ### Performance Characteristics - Object indexing: Processes 70K+ objects in ~30 seconds - Query response time: <50ms for most operations - Search operations: Sub-second response for large codebases - Memory usage: Optimized SQLite-based caching ### File Type Support - `.xpp` - X++ source files - `.xml` - Metadata and configuration files - `.json` - Configuration files - Other D365 development files ### Security - Path validation prevents directory traversal - Operations restricted to configured D365 codebase - File size limits for resource management - Input validation on all parameters ## Troubleshooting ### Common Issues **"VS2022 extension not found"** - Ensure Dynamics 365 Development Tools are installed in VS2022 - Run the setup script: `.\tools\build-and-run.ps1 -Action setup` **"Named pipe connection failed"** - Check that the C# service is running - Verify Windows firewall settings - Ensure .NET Framework 4.8 is installed **"Object not found" errors** - Build the object index: `build_object_index` - Verify D365 codebase path configuration - Check that the object exists in the specified model **"Pattern validation failed" for forms** - ✅ **RESOLVED**: This issue has been fixed in the latest version - Forms with patterns like DetailsMaster now automatically include required field controls - Use the `create_form` tool instead of `create_xpp_object` for better form creation **"Form creation without datasources fails"** - Most patterns work fine without datasources (e.g., DetailsMaster, Dialog patterns) - Use `create_form` with `"mode": "list_patterns"` to see pattern requirements - DataSources are optional for most patterns but enhance functionality when provided ### Getting Help - Check the `logs/` folder for detailed error information - Use `get_current_config` to verify system configuration - Report issues on the GitHub repository ## Contributing This project welcomes contributions. Please: 1. Fork the repository 2. Create a feature branch 3. Make your changes with appropriate tests 4. Submit a pull request Note that APIs may change as the project evolves. ## License MIT License - see LICENSE file for details. ## Disclaimer This software is provided "as is" without warranty. It is intended for research and development purposes only, not for production use. **Important Notes:** - Requires Visual Studio 2022 and D365 development tools - Integration with Microsoft APIs is not officially supported - Features may change or break between versions - Use at your own risk in development environments only Report issues or contribute improvements through the GitHub repository.