MCP X++ 服务器

一个用于 Microsoft Dynamics 365 Finance & Operations 开发的模型上下文协议（MCP）服务器。该工具通过 MCP 标准实现 D365 对象的创建、修改和分析，支持与各种开发环境集成。

日期： 2025 年 9 月 18 日
状态： 功能可用，支持 VS2022 服务集成和增强的表单创建

最近更新 ✨

2025 年 9 月 19 日 - 安全对象删除功能：

• 🗑️ 新增 delete_xpp_object 工具：安全的 D365 对象删除，支持依赖验证和级联支持

• 🛡️ 依赖保护：如果其他对象依赖于目标对象，则阻止删除，避免破坏性变更

• 🔄 缓存一致性：成功删除后自动更新搜索索引

• ⚡ 高性能：直接元数据提供程序集成，实现最佳速度

• 🌲 级联删除：可选删除子对象（表单部件、表关系等）

• ✅ 全面测试：跨对象类型完成完整的创建/删除周期验证

2025 年 9 月 18 日 - 数组修改与表单创建增强：

• 🚀 新增仅数组修改：execute_object_modification 现在专门使用批量格式，实现一致操作

• 🔄 强制批量处理：单个操作使用包含一个元素的数组 - 不再有连续的单独调用

• 📊 增强响应跟踪：每次操作的成功/失败报告，包含详细计时和错误信息

• 📋 最佳实践文档：清晰的指南，将同一对象的所有修改分组到单次调用中

• 🎯 新增 create_form 工具：专门用于表单创建，支持模式支持和数据源集成

• 🔧 修复 DetailsMaster 模式：通过智能字段控件创建解决验证问题

• 🗄️ 增强数据源支持：灵活的数据源处理（数组、字符串、逗号分隔）

• 📋 模式发现：36 个过滤后的表单模式，包含描述和要求

• ✅ 模式验证：为需要字段控件的模式自动创建字段控件

概述

该 MCP 服务器提供 D365 F&O 开发能力，包括：

• 对象创建：支持 D365 类、表、表单、枚举及 544+ 其他对象类型

• 表单创建：✨ 增强 - 专门用于表单创建，支持模式验证和数据源集成

• 对象删除：✨ 新增 - 安全的对象删除，支持依赖验证和级联支持

• 对象修改：向现有对象添加方法、字段和其他组件

• 对象检查：分析 D365 对象并提取 X++ 源代码

• 代码库搜索：通过模式匹配浏览和搜索 D365 代码库

• MCP 协议：兼容 Claude Desktop、VS Code 及其他 MCP 客户端

架构

系统由两个通过 Windows 命名管道通信的主要组件组成：

MCP X++ 服务器（Node.js/TypeScript）

• 实现模型上下文协议（STDIO）

• 处理对象创建、修改和搜索操作

• 提供文件浏览和代码库索引

• 兼容 Claude Desktop 和 VS Code 等 MCP 客户端

D365 元数据服务（C# .NET 4.8）

• 与 Microsoft 的 D365 程序集集成

• 通过 VS2022 API 处理对象创建和修改

• 为运行时对象发现提供动态反射

• 通过命名管道通信：mcp-xpp-d365-service

该架构支持从各种兼容 MCP 的客户端进行 D365 开发，同时保持与现有 D365 开发工作流的兼容性。

可用工具

服务器为 D365 开发提供 10 个专门工具：

1. create_xpp_object - 创建 D365 对象（类、表、枚举等） - 注意：表单请使用 create_form

2. create_form - ✨ 新增 - 专门用于表单创建，支持模式支持和数据源集成

3. delete_xpp_object - ✨ 新增 - 安全的 D365 对象删除，支持依赖验证和缓存一致性

4. execute_object_modification - ✨ 增强 - 基于数组的对象修改，支持批量处理 - 最佳实践：将同一对象的所有修改分组

5. discover_modification_capabilities - 探索可用的修改方法

6. find_xpp_object - 按名称/类型查找特定对象

7. search_objects_pattern - 支持通配符的模式搜索

8. inspect_xpp_object - 对象分析，支持 X++ 源代码提取

9. get_current_config - 系统配置和状态

10. build_object_index - 索引管理，提升搜索性能

先决条件

• Visual Studio 2022（社区版、专业版或企业版）

• Dynamics 365 开发工具，适用于 Visual Studio 2022

• Node.js（建议使用最新 LTS 版本）

• .NET Framework 4.8（通常随 Windows 包含）

安装

1. 克隆仓库

2. 安装 Node.js 依赖：npm install

3. 运行设置以配置 VS2022 集成：.\tools\build-and-run.ps1 -Action setup

4. 构建项目：.\tools\build-and-run.ps1 -Action build

使用方法

启动服务器

使用以下命令运行 MCP 服务器：

node build/index.js

服务器会自动从您的 VS2022 安装中检测 D365 路径。如需手动配置，请使用：

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

MCP 客户端配置

VS Code

在 .vscode/mcp.json 中配置：

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

Claude Desktop

添加到 Claude Desktop 配置文件：

{
  "mcpServers": {
    "mcp-xpp-server": {
      "command": "node",
      "args": ["path/to/mcp_xpp/build/index.js"]
    }
  }
}

工具参考

对象创建

create_xpp_object

使用 VS2022 服务集成创建 D365 F&O 对象。

⚠️ 重要提示： 对于表单，请使用专门的 create_form 工具，因为它提供专门的模式支持和数据源集成。

参数：

• objectName（字符串，必填）- D365 对象的名称

• objectType（字符串，必填）- 对象类型（AxClass、AxTable、AxEnum 等） - 不包括 AxForm

• layer（字符串，可选）- 应用层（usr、cus、var）

• outputPath（字符串，可选）- 输出目录（默认："Models"）

• publisher（字符串，可选）- 公司名称（默认："YourCompany"）

• version（字符串，可选）- 版本号（默认："1.0.0.0"）

• dependencies（数组，可选）- 模型依赖项

• properties（对象，可选）- 对象特定配置

示例：

create_xpp_object({
  "objectName": "MyCustomClass",
  "objectType": "AxClass",
  "layer": "usr"
})

create_form ✨ 新增

专门用于创建 D365 表单的工具，支持高级模式支持和数据源集成。该工具将表单创建和模式发现合二为一。

参数：

• mode（字符串，必填）- 操作模式：

  • "create" - 使用模式和数据源创建新表单

  • "list_patterns" - 发现可用的 D365 表单模式

• formName（字符串，可选）- 表单名称（mode='create' 时必填）

• patternName（字符串，可选）- 要应用的 D365 表单模式（例如：'SimpleListDetails'、'DetailsMaster'、'Dialog'）

• patternVersion（字符串，可选）- 模式版本（默认：'UX7 1.0'）

• dataSources（数组|字符串，可选）- 表单数据源的表名

• modelName（字符串，可选）- D365 模型/包名称（默认：'ApplicationSuite'）

主要特性：

• 🎯 模式感知：当模式需要时自动添加字段控件（例如：DetailsMaster）

• 🗄️ 灵活的数据源：支持数组、单个字符串或逗号分隔的字符串

• 🔍 模式发现：列出所有 36+ 个可用的 D365 表单模式及其描述

• ✅ 增强验证：通过智能字段控件创建解决模式验证问题

示例：

// 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"
})

技术说明：

• 当提供数据源时，DetailsMaster、SimpleListDetails 和 ListPage 等模式会自动增强字段控件（RecId、Name、Description、Code）

• 模式验证已修复 - 根据模式要求，表单可以带或不带数据源创建

• 该工具使用直接的 VS2022 服务集成，实现最佳 D365 兼容性

delete_xpp_object ✨ 新增

安全删除 D365 F&O 对象，具有全面的依赖验证和缓存一致性。该工具通过删除前验证依赖关系来防止破坏性变更。

参数：

• objectName（字符串，必填）- 要删除的 D365 对象名称

• objectType（字符串，必填）- D365 对象类型（AxClass、AxTable、AxForm、AxEnum 等）

• cascadeDelete（布尔值，可选）- 同时删除依赖对象（默认：false）

主要特性：

• 🛡️ 依赖验证：如果其他对象依赖于目标对象，则阻止删除

• 🗑️ 安全删除：使用 D365 的 ISingleKeyedMetadataProvider.Delete 进行正确清理

• 🔄 缓存一致性：成功删除后自动更新搜索索引

• ⚡ 快速性能：直接元数据提供程序集成，实现最佳速度

• 🌲 级联支持：可选删除子对象（带部件/控件的表单等）

示例：

// 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"
})

响应格式：

{
  "success": true,
  "message": "Successfully deleted object: MyCustomClass (AxClass)",
  "objectName": "MyCustomClass",
  "objectType": "AxClass",
  "cascadeDelete": false,
  "dependenciesRemoved": [],
  "cacheUpdate": "Success",
  "performance": "156ms"
}

⚠️ 安全说明：

• 高风险操作：删除是永久性的，无法撤销

• 删除前始终使用 find_xpp_object 验证依赖关系

• 使用 cascadeDelete: false（默认值）以获得最大安全性

• 先在开发环境中测试删除操作

• 如果存在依赖关系且未设置级联标志，工具将安全失败

• 缓存更新确保删除后搜索立即可见

常见对象类型：

• AxClass - X++ 类和业务逻辑

• AxTable - 数据表和架构

• AxForm - 用户界面表单

• AxEnum - 枚举和值列表

• AxEdt - 扩展数据类型

• AxView - 数据库视图

• AxQuery - 数据查询

• AxReport - SSRS 报表

对象发现

find_xpp_object

按名称定位 X++ 对象，支持可选过滤。

参数：

• objectName（字符串，必填）- X++ 对象的名称

• objectType（字符串，可选）- 按对象类型过滤

• model（字符串，可选）- 按 D365 模型/包名称过滤

search_objects_pattern

使用通配符模式搜索 D365 对象。

参数：

• pattern（字符串，必填）- 带通配符的搜索模式（*、?）

• objectType（字符串，可选）- 按对象类型过滤

• model（字符串，可选）- 按 D365 模型/包名称过滤

• limit（数字，可选）- 最大结果数（默认：50）

• format（字符串，可选）- 输出格式：'text' 或 'json'

inspect_xpp_object

使用多种检查模式分析 D365 对象。

参数：

• objectName（字符串，必填）- X++ 对象的名称

• objectType（字符串，可选）- D365 对象类型

• inspectionMode（字符串，可选）- 检查级别：

  • summary - 快速概览，包含集合计数

  • properties - 所有对象属性及描述

  • collection - 特定集合项（需要 collectionName）

  • xppcode - 提取 X++ 源代码（需要 codeTarget）

• collectionName（字符串，可选）- 当 inspectionMode='collection' 时必填

• codeTarget（字符串，可选）- 当 inspectionMode='xppcode' 时必填：

  • methods - 提取所有方法源代码

  • specific-method - 单个方法（需要 methodName）

  • event-handlers - 仅事件处理方法

• methodName（字符串，可选）- 当 codeTarget='specific-method' 时必填

• maxCodeLines（数字，可选）- 限制每个方法的源代码行数

• filterPattern（字符串，可选）- 结果的通配符过滤器

示例：

// 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"
})

对象修改

execute_object_modification ✨ 增强 - 支持批量处理

对现有 D365 对象执行修改方法，支持基于数组的批量处理。始终使用数组格式 - 单个操作使用包含一个元素的数组。

📋 最佳实践：将同一对象的所有修改分组到一次调用中，而不是进行多次单独调用。这可以提供更好的性能、错误处理和事务完整性。

参数：

• objectType (string, required) - D365 对象类型 (例如，'AxTable'、'AxClass'、'AxForm')

• objectName (string, required) - 要修改的现有对象的名称

• modifications (array, required) - 修改操作数组：

  • methodName (string, required) - 要执行的修改方法

  • parameters (object, required) - 方法特定参数，包括：

    • concreteType (string, required) - 来自 discover_modification_capabilities 的精确类型

    • Name (string) - 字段/对象名称 (使用 'Name' 而不是 'fieldName')

    • 其他 D365 特定参数 (根据需要)

✅ 功能：

• 逐操作跟踪：每个操作返回各自的成功/失败状态

• 详细错误报告：为失败的操作提供清晰的验证消息

• 顺序处理：操作按顺序执行并带有计时信息

• 批量效率：在单个服务调用中执行多个操作

示例：

✅ 单字段 (单元素数组)：

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"
      }
    }
  ]
})

⭐ 批量处理多个字段 (首选)：

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"
      }
    }
  ]
})

📊 响应格式： 该工具返回每个操作的详细结果：

{
  "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"
    }
  ]
}

💡 提示：

• 首先使用 discover_modification_capabilities 获取精确的参数要求

• 所有 D365 表字段都需要 SaveContents、Mandatory 等参数

• 将相关修改分组到一起以获得更好的性能

• 检查各操作的结果以调试失败的操作

discover_modification_capabilities

发现 D365 对象类型可用的修改方法。

参数：

• objectType (string, required) - 要分析的 D365 对象类型

系统管理

get_current_config

返回全面的服务器配置和状态信息。

build_object_index

构建或更新可搜索的对象索引。

参数：

• objectType (string, optional) - 要索引的特定对象类型

• forceRebuild (boolean, optional) - 强制完全重建

支持的对象类型

支持的常见 D365 对象类型：

• AxClass - X++ 类

• AxTable - 数据表

• AxForm - 用户界面窗体

• AxEnum - 枚举

• AxEdt - 扩展数据类型

• AxView - 数据库视图

• AxQuery - 数据查询

• AxReport - SSRS 报表

• AxMenuItemDisplay - 菜单项

• AxDataEntityView - OData 实体

系统总共支持 544+ 种对象类型。

构建脚本

build-and-run.ps1 脚本提供统一的项目管理：

# 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

示例工作流

创建新类

# 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() { }"
  }
}

搜索和分析对象

# 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"
}

技术细节

性能特征

• 对象索引：在 ~30 秒内处理 70K+ 个对象

• 查询响应时间：大多数操作 <50ms

• 搜索操作：大型代码库亚秒级响应

• 内存使用：优化的基于 SQLite 的缓存

文件类型支持

• .xpp - X++ 源文件

• .xml - 元数据和配置文件

• .json - 配置文件

• 其他 D365 开发文件

安全性

• 路径验证可防止目录遍历

• 操作仅限于已配置的 D365 代码库

• 用于资源管理的文件大小限制

• 对所有参数进行输入验证

故障排除

常见问题

"VS2022 extension not found"

• 确保 VS2022 中已安装 Dynamics 365 Development Tools

• 运行安装脚本：.\tools\build-and-run.ps1 -Action setup

"Named pipe connection failed"

• 检查 C# 服务是否正在运行

• 验证 Windows 防火墙设置

• 确保已安装 .NET Framework 4.8

"Object not found" 错误

• 构建对象索引：build_object_index

• 验证 D365 代码库路径配置

• 检查对象是否存在于指定的模型中

表单的 "Pattern validation failed" 错误

• ✅ 已解决：此问题已在最新版本中修复

• 具有 DetailsMaster 等模式的表单现在会自动包含必需的字段控件

• 使用 create_form 工具而不是 create_xpp_object，以获得更好的表单创建效果

"Form creation without datasources fails"

• 大多数模式在没有数据源的情况下也能正常工作 (例如，DetailsMaster、Dialog 模式)

• 使用带有 "mode": "list_patterns" 的 create_form 查看模式要求

• 对于大多数模式，数据源是可选的，但提供数据源可以增强功能

获取帮助

• 查看 logs/ 文件夹以获取详细的错误信息

• 使用 get_current_config 验证系统配置

• 在 GitHub 仓库中报告问题

贡献

本项目欢迎贡献。请：

1. Fork 该仓库

2. 创建功能分支

3. 进行更改并编写适当的测试

4. 提交 pull request

请注意，随着项目的发展，API 可能会发生变化。

许可证

MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

免责声明

本软件按"原样"提供，不附带任何担保。它仅用于研究和开发目的，不用于生产用途。

重要说明：

• 需要 Visual Studio 2022 和 D365 开发工具

• 与 Microsoft API 的集成不受官方支持

• 功能在版本之间可能会发生变化或失效

• 仅在开发环境中使用，风险自负

通过 GitHub 仓库报告问题或贡献改进。