mcp_xpp by ccampora - MCP Server

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:

create_xpp_object - Create D365 objects (classes, tables, enums, etc.) - Note: Use create_form for forms
create_form - ✨ NEW - Specialized form creation with pattern support and datasource integration
delete_xpp_object - ✨ NEW - Safe D365 object deletion with dependency validation and cache consistency
execute_object_modification - ✨ ENHANCED - Array-based object modification with batch processing - BEST PRACTICE: Group all modifications for same object
discover_modification_capabilities - Explore available modification methods
find_xpp_object - Find specific objects by name/type
search_objects_pattern - Pattern search with wildcard support
inspect_xpp_object - Object analysis with X++ source code extraction
get_current_config - System configuration and status
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

Clone the repository
Install Node.js dependencies: npm install
Run setup to configure VS2022 integration: .\tools\build-and-run.ps1 -Action setup
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:

Fork the repository
Create a feature branch
Make your changes with appropriate tests
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.

ccampora/mcp_xpp

MCP X++ Server

Recent Updates ✨

Overview

Architecture

MCP X++ Server (Node.js/TypeScript)

D365 Metadata Service (C# .NET 4.8)

Available Tools

Prerequisites

Installation

Usage

Starting the Server

MCP Client Configuration

VS Code

Claude Desktop

Tool Reference

Object Creation

create_xpp_object

create_form ✨ NEW

delete_xpp_object ✨ NEW

Object Discovery

find_xpp_object

search_objects_pattern

inspect_xpp_object

Object Modification

execute_object_modification ✨ ENHANCED WITH BATCH PROCESSING

discover_modification_capabilities

System Management

get_current_config

build_object_index

Supported Object Types

Build Scripts

Example Workflows

Creating a New Class

Searching and Analyzing Objects

Technical Details

Performance Characteristics

File Type Support

Security

Troubleshooting

Common Issues

Getting Help

Contributing

License

Disclaimer

`create_xpp_object`

`create_form` ✨ NEW

`delete_xpp_object` ✨ NEW

`find_xpp_object`

`search_objects_pattern`

`inspect_xpp_object`

`execute_object_modification` ✨ ENHANCED WITH BATCH PROCESSING

`discover_modification_capabilities`

`get_current_config`

`build_object_index`