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:

node build/index.js

The server automatically detects D365 paths from your VS2022 installation. For manual configuration, use:

node build/index.js --xpp-path "C:\path\to\PackagesLocalDirectory"

MCP Client Configuration

VS Code

Configure in .vscode/mcp.json:

{
  "servers": {
    "mcp-xpp-server": {
      "command": "node",
      "args": ["./build/index.js"],
      "cwd": "${workspaceFolder}",
      "type": "stdio"
    }
  }
}

Claude Desktop

Add to Claude Desktop configuration file:

{
  "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:

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:

// 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:

// 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:

{
  "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:

// 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):

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):

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:

{
  "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:

# 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

# 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

# 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.