MCP Dataverse

🚀 Dataverse MCP 服务器

Dataverse MCP 服务器是一款专为 Microsoft Dataverse 打造的模型上下文协议（MCP）服务器。借助 Dataverse Web API，它能够实现模式操作，包括创建和更新表、列、关系以及选项集等功能。

✨ 主要特性

• ✅ 管理表和列：支持创建、更新、删除和列出所有列类型（字符串、整数、布尔值、日期时间、选择列表、查找等）的自定义表。
• ✅ 管理关系：在实体之间创建一对多和多对多关系，并具备适当的级联行为。
• ✅ 管理选项集：创建和管理具有自定义选项、颜色和值的全局选项集。
• ✅ 基于解决方案的架构：遵循企业级解决方案管理，具备持久上下文和自动定制前缀。
• ✅ 安全与访问控制：提供完整的安全角色管理、团队操作和业务部门层级管理。
• ✅ WebAPI 调用生成器：为任何 Dataverse 操作生成即用型 HTTP 请求、cURL 命令和 JavaScript 代码。
• ✅ PowerPages WebAPI 生成器：使用 /_api/[logicalEntityName] 格式生成 PowerPages 特定的 WebAPI 调用，并提供 React 示例。
• ✅ PowerPages 配置管理：管理 PowerPages 代码站点的表权限和 WebAPI 站点设置，通过 YAML 文件实现自动化。
• ✅ 模式导出：将完整的解决方案模式导出为 JSON 文件，并支持过滤选项，用于文档和备份。
• ✅ 专业集成：支持 OAuth2 身份验证、全面的错误处理和企业级部署。

📦 安装指南

1. 安装依赖：

npm install

2. 构建服务器：

npm run build

3. 复制构建后的 index.js 文件的完整路径：
   • 服务器将构建到 build/ 目录中。
   • 复制完整的文件路径（例如：/Users/yourname/path/to/mcp-dataverse/build/index.js）。
   • 您将在 MCP 配置文件中使用此路径。
4. 使用复制的路径在 MCP 设置文件中配置 MCP 服务器（有关详细信息，请参阅配置部分）。

💻 使用示例

基础用法

创建自定义表

// 创建一个带有自动命名的新自定义表
// 系统自动生成：
// - 逻辑名称：xyz_project（使用解决方案上下文中的定制前缀）
// - 架构名称：xyz_Project（前缀小写，保留原始大小写，去除空格）
// - 显示集合名称：Projects（自动复数化）
// - 主名称属性：xyz_project_name
await use_mcp_tool("dataverse", "create_dataverse_table", {
  displayName: "Project",
  description: "Custom table for managing projects",
  ownershipType: "UserOwned",
  hasActivities: true,
  hasNotes: true
});

// 带有最少参数的示例（最常见的用法）
await use_mcp_tool("dataverse", "create_dataverse_table", {
  displayName: "Customer Feedback"
});
// 这将创建：
// - 逻辑名称：xyz_customerfeedback
// - 架构名称：xyz_CustomerFeedback（前缀小写，保留原始大小写）
// - 显示集合名称：Customer Feedbacks
// - 主名称属性：xyz_customerfeedback_name

重要提示：在创建表之前，请确保使用 set_solution_context 设置了解决方案上下文，以便提供定制前缀。系统将自动使用活动解决方案发布者的前缀。

向表中添加列

// 具有电子邮件格式和自动命名的字符串列
// 系统自动生成：
// - 逻辑名称：xyz_contactemail（前缀 + 小写，无空格）
// - 架构名称：xyz_ContactEmail（前缀小写，保留原始大小写）
await use_mcp_tool("dataverse", "create_dataverse_column", {
  entityLogicalName: "xyz_project",
  displayName: "Contact Email",
  columnType: "String",
  format: "Email",
  maxLength: 100,
  requiredLevel: "ApplicationRequired"
});

// 具有约束的整数列（生成 xyz_priorityscore）
await use_mcp_tool("dataverse", "create_dataverse_column", {
  entityLogicalName: "xyz_project",
  displayName: "Priority Score",
  columnType: "Integer",
  minValue: 1,
  maxValue: 10,
  defaultValue: 5
});

// 具有自定义标签的布尔列（生成 xyz_isactive）
await use_mcp_tool("dataverse", "create_dataverse_column", {
  entityLogicalName: "xyz_project",
  displayName: "Is Active",
  columnType: "Boolean",
  trueOptionLabel: "Active",
  falseOptionLabel: "Inactive",
  defaultValue: true
});

// 日期时间列（仅日期）（生成 xyz_startdate）
await use_mcp_tool("dataverse", "create_dataverse_column", {
  entityLogicalName: "xyz_project",
  displayName: "Start Date",
  columnType: "DateTime",
  dateTimeFormat: "DateOnly",
  requiredLevel: "ApplicationRequired"
});

// 日期时间列（日期和时间）（生成 xyz_lastmodified）
await use_mcp_tool("dataverse", "create_dataverse_column", {
  entityLogicalName: "xyz_project",
  displayName: "Last Modified",
  columnType: "DateTime",
  dateTimeFormat: "DateAndTime"
});

// 具有本地选项的选择列表列（生成 xyz_status）
await use_mcp_tool("dataverse", "create_dataverse_column", {
  entityLogicalName: "xyz_project",
  displayName: "Status",
  columnType: "Picklist",
  options: [
    { value: 1, label: "Planning" },
    { value: 2, label: "In Progress" },
    { value: 3, label: "On Hold" },
    { value: 4, label: "Completed" }
  ]
});

// 使用全局选项集的选择列表列（生成 xyz_projectcolor）
await use_mcp_tool("dataverse", "create_dataverse_column", {
  entityLogicalName: "xyz_project",
  displayName: "Project Color",
  columnType: "Picklist",
  optionSetName: "xyz_colors"
});

// 查找列（生成 xyz_account）
await use_mcp_tool("dataverse", "create_dataverse_column", {
  entityLogicalName: "xyz_project",
  displayName: "Account",
  columnType: "Lookup",
  targetEntity: "account"
});

// 用于长文本的备注列（生成 xyz_description）
await use_mcp_tool("dataverse", "create_dataverse_column", {
  entityLogicalName: "xyz_project",
  displayName: "Description",
  columnType: "Memo",
  maxLength: 2000,
  requiredLevel: "Recommended"
});

创建关系

// 创建一对多关系
await use_mcp_tool("dataverse", "create_dataverse_relationship", {
  relationshipType: "OneToMany",
  schemaName: "new_account_project",
  referencedEntity: "account",
  referencingEntity: "new_project",
  referencingAttributeLogicalName: "new_accountid",
  referencingAttributeDisplayName: "Account",
  cascadeDelete: "RemoveLink"
});

管理选项集

// 创建全局选项集
await use_mcp_tool("dataverse", "create_dataverse_optionset", {
  name: "new_priority",
  displayName: "Priority Levels",
  options: [
    { value: 1, label: "Low", color: "#00FF00" },
    { value: 2, label: "Medium", color: "#FFFF00" },
    { value: 3, label: "High", color: "#FF0000" }
  ]
});

管理安全角色

// 创建新的安全角色
await use_mcp_tool("dataverse", "create_dataverse_role", {
  name: "Project Manager",
  description: "Role for project managers with specific permissions",
  appliesTo: "Project management team members",
  isAutoAssigned: false,
  isInherited: "1",
  summaryOfCoreTablePermissions: "Read/Write access to project-related tables"
});

// 获取安全角色信息
await use_mcp_tool("dataverse", "get_dataverse_role", {
  roleId: "role-guid-here"
});

// 列出安全角色
await use_mcp_tool("dataverse", "list_dataverse_roles", {
  customOnly: true,
  includeManaged: false,
  top: 20
});

// 向角色添加权限
await use_mcp_tool("dataverse", "add_privileges_to_role", {
  roleId: "role-guid-here",
  privileges: [
    { privilegeId: "privilege-guid-1", depth: "Global" },
    { privilegeId: "privilege-guid-2", depth: "Local" }
  ]
});

// 将角色分配给用户
await use_mcp_tool("dataverse", "assign_role_to_user", {
  roleId: "role-guid-here",
  userId: "user-guid-here"
});

// 将角色分配给团队
await use_mcp_tool("dataverse", "assign_role_to_team", {
  roleId: "role-guid-here",
  teamId: "team-guid-here"
});

// 获取角色权限
await use_mcp_tool("dataverse", "get_role_privileges", {
  roleId: "role-guid-here"
});

管理团队

// 创建新团队
await use_mcp_tool("dataverse", "create_dataverse_team", {
  name: "Development Team",
  description: "Team for software development activities",
  administratorId: "admin-user-guid-here",
  teamType: "0", // 所有者团队
  membershipType: "0", // 成员和来宾
  emailAddress: "devteam@company.com"
});

// 获取团队信息
await use_mcp_tool("dataverse", "get_dataverse_team", {
  teamId: "team-guid-here"
});

// 列出团队并进行过滤
await use_mcp_tool("dataverse", "list_dataverse_teams", {
  teamType: "0", // 仅所有者团队
  excludeDefault: true,
  top: 20
});

// 向团队添加成员
await use_mcp_tool("dataverse", "add_members_to_team", {
  teamId: "team-guid-here",
  memberIds: ["user-guid-1", "user-guid-2", "user-guid-3"]
});

// 获取团队成员
await use_mcp_tool("dataverse", "get_team_members", {
  teamId: "team-guid-here"
});

// 从团队中移除成员
await use_mcp_tool("dataverse", "remove_members_from_team", {
  teamId: "team-guid-here",
  memberIds: ["user-guid-1", "user-guid-2"]
});

// 更新团队属性
await use_mcp_tool("dataverse", "update_dataverse_team", {
  teamId: "team-guid-here",
  name: "Updated Development Team",
  description: "Updated description for the development team",
  emailAddress: "newdevteam@company.com"
});

// 将所有者团队转换为访问团队
await use_mcp_tool("dataverse", "convert_owner_team_to_access_team", {
  teamId: "owner-team-guid-here"
});

管理业务部门

// 创建具有综合信息的新业务部门
await use_mcp_tool("dataverse", "create_dataverse_businessunit", {
  name: "Sales Division",
  description: "Business unit for sales operations",
  divisionName: "Sales",
  emailAddress: "sales@company.com",
  costCenter: "SALES-001",
  creditLimit: 100000,
  parentBusinessUnitId: "parent-bu-guid-here",
  // 地址信息
  address1_name: "Sales Office",
  address1_line1: "123 Business Street",
  address1_city: "New York",
  address1_stateorprovince: "NY",
  address1_postalcode: "10001",
  address1_country: "United States",
  address1_telephone1: "+1-555-0123",
  address1_fax: "+1-555-0124",
  // 网站和其他详细信息
  webSiteUrl: "https://sales.company.com",
  stockExchange: "NYSE",
  tickerSymbol: "COMP"
});

// 获取业务部门信息
await use_mcp_tool("dataverse", "get_dataverse_businessunit", {
  businessUnitId: "business-unit-guid-here"
});

// 列出业务部门并进行过滤
await use_mcp_tool("dataverse", "list_dataverse_businessunits", {
  filter: "isdisabled eq false",
  orderby: "name asc",
  top: 20
});

// 更新业务部门属性
await use_mcp_tool("dataverse", "update_dataverse_businessunit", {
  businessUnitId: "business-unit-guid-here",
  name: "Updated Sales Division",
  description: "Updated description for sales operations",
  emailAddress: "newsales@company.com",
  creditLimit: 150000,
  // 更新地址信息
  address1_line1: "456 New Business Avenue",
  address1_telephone1: "+1-555-9999"
});

// 获取业务部门层次结构
await use_mcp_tool("dataverse", "get_businessunit_hierarchy", {
  businessUnitId: "business-unit-guid-here"
});

// 更改业务部门父级（重组）
await use_mcp_tool("dataverse", "set_businessunit_parent", {
  businessUnitId: "child-bu-guid-here",
  parentBusinessUnitId: "new-parent-bu-guid-here"
});

// 获取业务部门中的用户
await use_mcp_tool("dataverse", "get_businessunit_users", {
  businessUnitId: "business-unit-guid-here",
  includeSubsidiaryUsers: false // 设置为 true 以包括子业务部门的用户
});

// 获取业务部门中的团队
await use_mcp_tool("dataverse", "get_businessunit_teams", {
  businessUnitId: "business-unit-guid-here",
  includeSubsidiaryTeams: true // 包括子业务部门的团队
});

// 删除业务部门（确保不存在依赖项）
await use_mcp_tool("dataverse", "delete_dataverse_businessunit", {
  businessUnitId: "business-unit-guid-here"
});

导出解决方案模式

// 仅导出自定义模式（默认设置）
// 将表、列和选项集导出到 JSON 文件
// 注意：关系导出尚未实现
await use_mcp_tool("dataverse", "export_solution_schema", {
  outputPath: "my-solution-schema.json"
});

// 包含系统实体进行全面文档导出
await use_mcp_tool("dataverse", "export_solution_schema", {
  outputPath: "complete-schema.json",
  includeSystemTables: true,
  includeSystemColumns: true,
  includeSystemOptionSets: true
});

// 导出用于生产的压缩 JSON
await use_mcp_tool("dataverse", "export_solution_schema", {
  outputPath: "schema-minified.json",
  prettify: false
});

// 导出到特定目录并使用自定义设置
await use_mcp_tool("dataverse", "export_solution_schema", {
  outputPath: "exports/solution-backup.json",
  includeSystemTables: false,
  includeSystemColumns: false,
  includeSystemOptionSets: false,
  prettify: true
});

// 仅导出与解决方案定制前缀匹配的表
await use_mcp_tool("dataverse", "export_solution_schema", {
  outputPath: "prefix-only-schema.json",
  includeSystemTables: false,
  includeSystemColumns: false,
  includeSystemOptionSets: false,
  prefixOnly: true,
  prettify: true
});

模式导出功能：

• 模式捕获：导出表、列和全局选项集（关系导出尚未实现）。
• 灵活过滤：选择包含或排除系统实体。
• 解决方案上下文感知：在设置上下文时自动包含解决方案元数据。
• 全面元数据：捕获所有实体属性和列类型。
• JSON 格式：提供人类可读或压缩输出选项。
• 目录创建：如果输出目录不存在，则自动创建。

示例输出结构：

{
  "metadata": {
    "exportedAt": "2025-07-26T17:30:00.000Z",
    "solutionUniqueName": "xyzsolution",
    "solutionDisplayName": "XYZ Test Solution",
    "publisherPrefix": "xyz",
    "includeSystemTables": false,
    "includeSystemColumns": false,
    "includeSystemOptionSets": false
  },
  "tables": [
    {
      "logicalName": "xyz_project",
      "displayName": "Project",
      "schemaName": "xyz_Project",
      "ownershipType": "UserOwned",
      "isCustomEntity": true,
      "columns": [
        {
          "logicalName": "xyz_name",
          "displayName": "Name",
          "attributeType": "String",
          "maxLength": 100,
          "isPrimaryName": true
        }
      ]
    }
  ],
  "globalOptionSets": [
    {
      "name": "xyz_priority",
      "displayName": "Priority Levels",
      "isGlobal": true,
      "options": [
        { "value": 1, "label": "Low" },
        { "value": 2, "label": "High" }
      ]
    }
  ]
}

注意：关系导出功能计划在未来版本中发布。

WebAPI 调用生成器

WebAPI 调用生成器工具可帮助开发人员通过生成具有正确 URL、标头和请求正文的完整 HTTP 请求来构建正确的 Dataverse WebAPI 调用。这对于以下方面特别有用：

• 学习 WebAPI 语法：了解不同操作如何转换为 HTTP 调用。
• 调试 API 问题：生成参考调用以与您的实现进行比较。
• 文档编写：为团队成员或 API 文档创建示例。
• 测试：获取即用型 cURL 命令和 JavaScript fetch 示例。

// 生成简单的检索操作
await use_mcp_tool("dataverse", "generate_webapi_call", {
  operation: "retrieve",
  entitySetName: "accounts",
  entityId: "12345678-1234-1234-1234-123456789012",
  select: ["name", "emailaddress1", "telephone1"]
});

// 生成带有过滤和排序的多记录检索操作
await use_mcp_tool("dataverse", "generate_webapi_call", {
  operation: "retrieveMultiple",
  entitySetName: "contacts",
  select: ["fullname", "emailaddress1"],
  filter: "statecode eq 0 and contains(fullname,'John')",
  orderby: "fullname asc",
  top: 10,
  count: true
});

// 生成带有返回首选项的创建操作
await use_mcp_tool("dataverse", "generate_webapi_call", {
  operation: "create",
  entitySetName: "accounts",
  data: {
    name: "Test Account",
    emailaddress1: "test@example.com",
    telephone1: "555-1234"
  },
  prefer: ["return=representation"],
  includeAuthHeader: true
});

// 生成带有条件标头的更新操作
await use_mcp_tool("dataverse", "generate_webapi_call", {
  operation: "update",
  entitySetName: "accounts",
  entityId: "12345678-1234-1234-1234-123456789012",
  data: {
    name: "Updated Account Name",
    telephone1: "555-5678"
  },
  ifMatch: "*"
});

// 生成关系关联操作
await use_mcp_tool("dataverse", "generate_webapi_call", {
  operation: "associate",
  entitySetName: "accounts",
  entityId: "12345678-1234-1234-1234-123456789012",
  relationshipName: "account_primary_contact",
  relatedEntitySetName: "contacts",
  relatedEntityId: "87654321-4321-4321-4321-210987654321"
});

// 生成绑定操作调用
await use_mcp_tool("dataverse", "generate_webapi_call", {
  operation: "callAction",
  actionOrFunctionName: "WinOpportunity",
  entitySetName: "opportunities",
  entityId: "11111111-1111-1111-1111-111111111111",
  parameters: {
    Status: 3,
    Subject: "Won Opportunity"
  }
});

// 生成未绑定函数调用
await use_mcp_tool("dataverse", "generate_webapi_call", {
  operation: "callFunction",
  actionOrFunctionName: "WhoAmI",
  includeAuthHeader: true
});

// 生成带有参数的函数调用
await use_mcp_tool("dataverse", "generate_webapi_call", {
  operation: "callFunction",
  actionOrFunctionName: "GetTimeZoneCodeByLocalizedName",
  parameters: {
    LocalizedStandardName: "Pacific Standard Time",
    LocaleId: 1033
  }
});

输出特性：

• 完整的 HTTP 请求：方法、URL、标头和正文。
• cURL 命令：可直接执行的命令行示例。
• JavaScript Fetch：可复制粘贴的 JavaScript 代码。
• 解决方案上下文：自动包含当前解决方案标头。
• 身份验证占位符：可选的 Bearer 令牌占位符。
• OData 查询构建：正确编码复杂的过滤表达式。

示例输出：

HTTP Method: GET
URL: https://yourorg.crm.dynamics.com/api/data/v9.2/accounts(12345678-1234-1234-1234-123456789012)?$select=name,emailaddress1,telephone1

Headers:
  Content-Type: application/json
  Accept: application/json
  OData-MaxVersion: 4.0
  OData-Version: 4.0
  MSCRM.SolutionUniqueName: xyzsolution

--- 附加信息 ---
操作类型: retrieve
实体集: accounts
实体 ID: 12345678-1234-1234-1234-123456789012

Curl 命令:
curl -X GET \
  "https://yourorg.crm.dynamics.com/api/data/v9.2/accounts(12345678-1234-1234-1234-123456789012)?$select=name,emailaddress1,telephone1" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "OData-MaxVersion: 4.0" \
  -H "OData-Version: 4.0" \
  -H "MSCRM.SolutionUniqueName: xyzsolution"

JavaScript Fetch 示例:
fetch('https://yourorg.crm.dynamics.com/api/data/v9.2/accounts(12345678-1234-1234-1234-123456789012)?$select=name,emailaddress1,telephone1', {
  method: 'GET',
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "OData-MaxVersion": "4.0",
    "OData-Version": "4.0",
    "MSCRM.SolutionUniqueName": "xyzsolution"
  }
})
.then(response => response.json())
.then(data => console.log(data));

支持的操作：

• retrieve：按 ID 获取单个记录。
• retrieveMultiple：使用 OData 查询多个记录。
• create：创建新记录。
• update：更新现有记录（PATCH）。
• delete：删除记录。
• associate：在记录之间创建关系。
• disassociate：删除记录之间的关系。
• callAction：执行 Dataverse 操作（绑定/未绑定）。
• callFunction：执行 Dataverse 函数（绑定/未绑定）。

高级特性：

• OData 查询选项：$select、$filter、$orderby、$top、$skip、$expand、$count。
• Prefer 标头：return=representation、odata.include-annotations=*。
• 条件更新：If-Match、If-None-Match 标头。
• 模拟：支持 MSCRMCallerID 标头。
• 解决方案上下文：自动包含 MSCRM.SolutionUniqueName 标头。

PowerPages WebAPI 生成器

PowerPages WebAPI 生成器使用 PowerPages WebAPI 格式 /_api/[logicalEntityName]s 为 PowerPages 单页应用程序（SPA）创建 API 调用。此工具专为在 PowerPages 环境中构建现代 React、Angular 或 Vue 应用程序的开发人员而设计。

与标准 Dataverse WebAPI 的主要区别：

• URL 格式：使用 /_api/[logicalEntityName]s 而不是 /api/data/v9.2/[entitySetName]（注意：自动添加 's' 后缀）。
• 身份验证：与 PowerPages 身份验证上下文和请求验证令牌集成。
• 客户端侧聚焦：针对基于浏览器的应用程序进行了优化，并提供 React 组件示例。
• PowerPages 安全：遵循 PowerPages 表权限和 Web 角色。

// 生成 PowerPages 多记录检索操作
await use_mcp_tool("dataverse", "generate_powerpages_webapi_call", {
  operation: "retrieveMultiple",
  logicalEntityName: "cr7ae_creditcardses",
  select: ["cr7ae_name", "cr7ae_type", "cr7ae_features"],
  filter: "cr7ae_type eq 'Premium'",
  orderby: "cr7ae_name asc",
  top: 10,
  baseUrl: "https://contoso.powerappsportals.com",
  includeAuthContext: true
});

// 生成带有请求验证令牌的 PowerPages 创建操作
await use_mcp_tool("dataverse", "generate_powerpages_webapi_call", {
  operation: "create",
  logicalEntityName: "cr7ae_creditcardses",
  data: {
    cr7ae_name: "New Premium Card",
    cr7ae_type: "Premium",
    cr7ae_features: "Cashback, Travel Insurance"
  },
  baseUrl: "https://contoso.powerappsportals.com",
  requestVerificationToken: true
});

// 生成 PowerPages 单记录检索操作
await use_mcp_tool("dataverse", "generate_powerpages_webapi_call", {
  operation: "retrieve",
  logicalEntityName: "contacts",
  entityId: "12345678-1234-1234-1234-123456789012",
  select: ["fullname", "emailaddress1", "telephone1"],
  baseUrl: "https://yoursite.powerappsportals.com"
});

// 生成带有自定义标头的高级场景调用
await use_mcp_tool("dataverse", "generate_powerpages_webapi_call", {
  operation: "retrieveMultiple",
  logicalEntityName: "contacts",
  select: ["fullname", "emailaddress1"],
  filter: "contains(fullname,'John')",
  customHeaders: {
    "X-Custom-Header": "PowerPages-API",
    "X-Client-Version": "1.0"
  }
});

输出特性：

• PowerPages URL 格式：正确构建 /_api/[logicalEntityName]s 端点（自动添加 's' 后缀）。
• 请求验证令牌：自动处理 POST/PATCH/DELETE 操作的令牌。
• JavaScript 示例：带有错误处理的即用型 fetch 代码。
• React 组件：完整的 React 钩子示例，用于数据获取。
• 身份验证上下文：PowerPages 用户上下文和令牌管理。
• OData 查询支持：全面支持 OData 查询参数，并进行正确编码。

示例输出：

// PowerPages WebAPI 调用
const fetchData = async () => {
  // 获取请求验证令牌
  const token = document.querySelector('input[name="__RequestVerificationToken"]')?.value;

  try {
    const response = await fetch('/_api/cr7ae_creditcardses', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        '__RequestVerificationToken': token
      },
      body: JSON.stringify({
        "cr7ae_name": "New Premium Card",
        "cr7ae_type": "Premium",
        "cr7ae_features": "Cashback, Travel Insurance"
      })
    });

    if (!response.ok) {
      throw new Error(`HTTP 错误！状态码：${response.status}`);
    }

    const createdRecord = await response.json();
    console.log('创建的记录：', createdRecord);
    return createdRecord;
  } catch (error) {
    console.error('错误：', error);
    throw error;
  }
};

React 组件示例：

// React 钩子示例
import React, { useState, useEffect } from 'react';

const CreditCardsList = () => {
  const [records, setRecords] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const fetchRecords = async () => {
      try {
        const response = await fetch('/_api/cr7ae_creditcardses?$select=cr7ae_name,cr7ae_type');
        const data = await response.json();
        setRecords(data.value);
      } catch (error) {
        console.error('获取记录时出错：', error);
      } finally {
        setLoading(false);
      }
    };

    fetchRecords();
  }, []);

  if (loading) return <div>加载中...</div>;

  return (
    <div>
      <h2>信用卡列表</h2>
      {records.map((record, index) => (
        <div key={record.cr7ae_creditcardsesid || index}>
          <h3>{record.cr7ae_name}</h3>
          <p>类型：{record.cr7ae_type}</p>
        </div>
      ))}
    </div>
  );
};

身份验证上下文集成：

// 访问 PowerPages 中的用户信息
const user = window["Microsoft"]?.Dynamic365?.Portal?.User;
const userName = user?.userName || "";
const firstName = user?.firstName || "";
const lastName = user?.lastName || "";
const isAuthenticated = userName !== "";

// 获取身份验证令牌（如果需要）
const getToken = async () => {
  try {
    const token = await window.shell.getTokenDeferred();
    return token;
  } catch (error) {
    console.error('获取令牌时出错：', error);
    return null;
  }
};

PowerPages 特定特性：

• 请求验证令牌：自动处理 __RequestVerificationToken 标头，以确保安全操作。
• 身份验证集成：内置 PowerPages 用户上下文访问。
• 适用于 React：提供完整的 React 组件示例，包括钩子和状态管理。
• 错误处理：针对 PowerPages 环境提供全面的错误处理模式。
• 安全合规：遵循 PowerPages 表权限和 Web 角色安全。
• SPA 优化：专为单页应用程序开发模式设计。

此工具对于需要在维护 PowerPages 安全和身份验证模式的同时与 Dataverse 数据进行交互的 PowerPages 开发人员构建现代 SPA 至关重要。

📚 详细文档

功能

本 MCP 服务器为 Dataverse 模式管理提供了全面的工具：

表操作

• create_dataverse_table - 创建新的自定义表
• get_dataverse_table - 检索表元数据
• update_dataverse_table - 更新表属性
• delete_dataverse_table - 删除自定义表
• list_dataverse_tables - 列出带有过滤选项的表

列操作

• create_dataverse_column - 创建各种类型的列（请参阅下面的支持的列类型）
• get_dataverse_column - 检索列元数据
• update_dataverse_column - 更新列属性
• delete_dataverse_column - 删除自定义列
• list_dataverse_columns - 列出表的所有列

关系操作

• create_dataverse_relationship - 创建一对多或多对多关系
• get_dataverse_relationship - 检索关系元数据
• delete_dataverse_relationship - 删除自定义关系
• list_dataverse_relationships - 列出带有过滤的关系

选项集操作

• create_dataverse_optionset - 创建全局选项集
• get_dataverse_optionset - 检索选项集元数据
• update_dataverse_optionset - 更新选项集（添加/更新/删除选项）
• delete_dataverse_optionset - 删除自定义选项集
• list_dataverse_optionsets - 列出选项集
• get_dataverse_optionset_options - 获取特定选项集的选项

解决方案与发布者操作

• create_dataverse_publisher - 创建带有前缀的自定义发布者
• get_dataverse_publisher - 检索发布者元数据
• list_dataverse_publishers - 列出带有过滤的发布者
• create_dataverse_solution - 创建与发布者关联的解决方案
• get_dataverse_solution - 检索解决方案元数据
• list_dataverse_solutions - 列出带有发布者详细信息的解决方案
• set_solution_context - 设置模式操作的活动解决方案
• get_solution_context - 查看当前解决方案上下文
• clear_solution_context - 移除解决方案上下文

安全角色操作

• create_dataverse_role - 创建新的安全角色
• get_dataverse_role - 检索安全角色元数据
• update_dataverse_role - 更新安全角色属性
• delete_dataverse_role - 删除自定义安全角色
• list_dataverse_roles - 列出带有过滤选项的安全角色
• add_privileges_to_role - 向安全角色添加权限
• remove_privilege_from_role - 从安全角色中移除权限
• replace_role_privileges - 替换安全角色的所有权限
• get_role_privileges - 检索安全角色的所有权限
• assign_role_to_user - 将安全角色分配给用户
• remove_role_from_user - 从用户中移除安全角色
• assign_role_to_team - 将安全角色分配给团队
• remove_role_from_team - 从团队中移除安全角色

团队操作

• create_dataverse_team - 创建具有各种类型和配置的新团队
• get_dataverse_team - 检索团队元数据和详细信息
• update_dataverse_team - 更新团队属性和设置
• delete_dataverse_team - 删除团队
• list_dataverse_teams - 列出带有过滤选项的团队
• add_members_to_team - 将用户添加为团队成员
• remove_members_from_team - 从团队中移除用户
• get_team_members - 检索团队的所有成员
• convert_owner_team_to_access_team - 将所有者团队转换为访问团队

业务部门操作

• create_dataverse_businessunit - 创建具有综合地址和联系信息的新业务部门
• get_dataverse_businessunit - 检索业务部门元数据和详细信息
• update_dataverse_businessunit - 更新业务部门属性、地址和设置
• delete_dataverse_businessunit - 删除业务部门
• list_dataverse_businessunits - 列出带有过滤和排序选项的业务部门
• get_businessunit_hierarchy - 检索业务部门的层次结构
• set_businessunit_parent - 更改层次结构中的父业务部门
• get_businessunit_users - 获取与业务部门关联的用户（可选包括子业务部门）
• get_businessunit_teams - 获取与业务部门关联的团队（可选包括子业务部门）

模式导出操作

• export_solution_schema - 将解决方案模式导出为 JSON 文件，包括表、列和全局选项集。支持按定制前缀过滤，仅导出特定于解决方案的实体。注意：关系导出尚未实现。

WebAPI 调用生成器

• generate_webapi_call - 为 Dataverse 操作生成完整的 WebAPI 调用，包括 URL、标头和请求正文。支持所有主要操作（检索、创建、更新、删除、关联、解除关联、操作、函数），并提供 OData 查询选项，以多种格式（HTTP、cURL、JavaScript fetch）输出。

PowerPages WebAPI 生成器

• generate_powerpages_webapi_call - 使用 /_api/[logicalEntityName] 格式生成 PowerPages 特定的 WebAPI 调用。包括请求验证令牌处理、身份验证上下文、React 组件示例以及 PowerPages 特定的单页应用程序开发功能。

PowerPages 配置管理

• manage_powerpages_webapi_config - 管理 PowerPages 代码站点的表权限和 WebAPI 站点设置。自动配置 .powerpages-site 目录结构中的 YAML 文件，包括 sitesetting.yml、webrole.yml 和 table-permissions/*.yml 文件，并提供全面的状态检查和配置管理。

基于解决方案的架构

MCP 服务器遵循 Microsoft Dataverse 最佳实践，实现了企业级解决方案管理。

主要优势

• 专业的模式命名：使用基于发布者的定制前缀。
• 解决方案关联：所有模式更改自动与活动解决方案关联。
• ALM 支持：支持在不同环境中进行适当的解决方案打包和部署。
• 持久上下文：解决方案上下文通过 .mcp-dataverse 文件在服务器重启后仍然保留。
• 企业治理：支持多个发布者和解决方案，并进行适当的隔离。

解决方案工作流程

1. 创建发布者：定义组织的定制前缀。
2. 创建解决方案：将解决方案与发布者关联，以组织模式。
3. 设置上下文：激活解决方案以进行后续操作。
4. 创建模式：所有表、列和选项集自动使用发布者的前缀。
5. 部署：导出解决方案以部署到其他环境。

示例：XYZ 组织设置

// 1. 创建带有 "xyz" 前缀的发布者
await use_mcp_tool("dataverse", "create_dataverse_publisher", {
  friendlyName: "XYZ Test Publisher",
  uniqueName: "xyzpublisher",
  customizationPrefix: "xyz",
  customizationOptionValuePrefix: 20000,
  description: "Publisher for XYZ organization"
});

// 2. 创建与发布者关联的解决方案
await use_mcp_tool("dataverse", "create_dataverse_solution", {
  friendlyName: "XYZ Test Solution",
  uniqueName: "xyzsolution",
  publisherUniqueName: "xyzpublisher",
  description: "Main solution for XYZ customizations"
});

// 3. 设置解决方案上下文（在服务器重启后仍然保留）
await use_mcp_tool("dataverse", "set_solution_context", {
  solutionUniqueName: "xyzsolution"
});

// 4. 创建模式对象 - 它们自动使用 "xyz" 前缀
await use_mcp_tool("dataverse", "create_dataverse_table", {
  logicalName: "xyz_project",        // 自动使用 xyz 前缀
  displayName: "XYZ Project",
  displayCollectionName: "XYZ Projects"
});

await use_mcp_tool("dataverse", "create_dataverse_column", {
  entityLogicalName: "xyz_project",
  logicalName: "xyz_description",    // 自动使用 xyz 前缀
  displayName: "Description",
  columnType: "Memo"
});

持久解决方案上下文

服务器自动将解决方案上下文持久化到项目根目录中的 .mcp-dataverse 文件：

{
  "solutionUniqueName": "xyzsolution",
  "solutionDisplayName": "XYZ Test Solution",
  "publisherUniqueName": "xyzpublisher",
  "publisherDisplayName": "XYZ Test Publisher",
  "customizationPrefix": "xyz",
  "lastUpdated": "2025-07-26T08:27:56.966Z"
}

持久化的好处：

• 无上下文丢失：解决方案上下文在服务器重启后仍然保留。
• 即时生产力：开发人员可以立即继续工作。
• 一致的前缀：无需记住和重新设置解决方案上下文。
• 团队隔离：每个开发人员可以拥有自己的解决方案上下文（该文件被 git 忽略）。

支持的列类型

MCP 服务器支持所有主要的 Dataverse 列类型，并提供全面的配置选项。下表显示了实现状态和测试验证：

列类型	状态	测试情况	描述	关键参数
字符串	✅ 已实现	✅ 已验证	具有格式选项的文本字段	maxLength, format (电子邮件、文本、文本区域、URL、电话)
整数	✅ 已实现	✅ 已验证	具有约束的整数	minValue, maxValue, defaultValue
小数	✅ 已实现	⚠️ 未测试	具有精度的小数	precision, minValue, maxValue, defaultValue
货币	✅ 已实现	⚠️ 未测试	货币值	precision, minValue, maxValue
布尔值	✅ 已实现	✅ 已验证	具有自定义标签的真/假值	trueOptionLabel, falseOptionLabel, defaultValue
日期时间	✅ 已实现	✅ 已验证	日期和时间字段	dateTimeFormat (仅日期、日期和时间)
选择列表	✅ 已实现	✅ 已验证	选择字段（本地和全局）	options (本地)，optionSetName (全局)
查找	✅ 已实现	✅ 已验证	对其他表的引用	targetEntity
备注	✅ 已实现	⚠️ 未测试	长文本字段	maxLength
双精度浮点数	✅ 已实现	⚠️ 未测试	浮点数	precision, minValue, maxValue
大整数	✅ 已实现	⚠️ 未测试	大整数值	无

列类型详细信息

字符串列 ✅ 已测试

• 格式：电子邮件、文本、文本区域、URL、电话。
• 最大长度：可配置（默认值：100）。
• 默认值：支持。
• 示例：员工姓名、电子邮件地址、电话号码。

整数列 ✅ 已测试

• 约束：最小/最大值验证。
• 默认值：支持。
• 示例：年龄、数量、0 - 100 范围内的分数。

布尔列 ✅ 已测试

• 自定义标签：可配置的真/假选项标签。
• 默认值：支持。
• 示例：“活动/非活动”、“是/否”、“启用/禁用”。

日期时间列 ✅ 已测试

• 仅日期：没有时间组件的日期（例如，入职日期、生日）。
• 日期和时间：具有时区处理的完整时间戳（例如，上次登录时间、创建日期）。
• 行为：使用用户本地时区行为。

选择列表列 ✅ 已测试

• 本地选项集：与列一起创建内联选项。
• 全局选项集：按名称引用现有的全局选项集。
• 颜色支持：选项可以关联颜色。
• 示例：状态（活动、非活动）、优先级（高、中、低）。

查找列 ✅ 已测试

• 目标实体：指定要引用的表。
• 关系：自动创建底层关系。
• 示例：客户查找、账户引用。

测试的列场景

以下特定场景已成功测试和验证：

1. 字符串列创建 ✅
   • 具有默认设置的基本文本字段。
   • 电子邮件格式验证。
   • 自定义最大长度约束。
2. 整数列创建 ✅
   • 具有最小/最大约束（0 - 100 范围）的数字字段。
   • 默认值分配。
3. 布尔列创建 ✅
   • 自定义真/假标签（“活动”/“非活动”）。
   • 默认值配置。
4. 日期时间列创建 ✅
   • 用于入职日期的仅日期格式。
   • 用于登录时间戳的日期和时间格式。
5. 选择列表列创建 ✅
   • 具有自定义选项的本地选项集。
   • 使用现有“颜色”选项集的全局选项集引用。
6. 查找列创建 ✅
   • 跨表引用（MCP 测试 2 → MCP 测试）。
   • 自动关系创建。

列操作状态

操作	状态	描述
创建	✅ 完全测试	所有列类型及特定类型的参数
读取	✅ 已实现	检索列元数据和配置
更新	✅ 已实现	修改显示名称、描述、必需级别
删除	✅ 已测试	从表中移除自定义列
列表	✅ 已实现	列出表的所有列并支持过滤

先决条件

1. Dataverse 环境 - 您需要访问 Microsoft Dataverse 环境。
2. Azure 应用注册 - 具有适当权限的 Azure AD 应用注册。
3. 客户端凭据 - 用于身份验证的客户端 ID、客户端密钥和租户 ID。

设置

1. Azure 应用注册

1. 访问 Azure 门户。
2. 导航到 Azure Active Directory > 应用注册。
3. 点击 新建注册。
4. 提供名称（例如，“Dataverse MCP Server”）。
5. 选择 仅此组织目录中的账户。
6. 点击 注册。

2. 创建客户端密钥

1. 转到 证书和机密。
2. 点击 新建客户端密钥。
3. 提供描述和过期时间。
4. 点击 添加。
5. 立即复制密钥值（您将无法再次查看该值）。

3. 在 Dataverse 中创建应用程序用户

关键步骤：您必须在 Dataverse 环境中创建应用程序用户并分配适当的权限。

1. 导航到 Dataverse 管理中心
   • 访问 Power Platform 管理中心。
   • 选择您的环境。
   • 转到 设置 > 用户 + 权限 > 应用程序用户。
2. 创建应用程序用户
   • 点击 + 新应用用户。
   • 点击 + 添加应用。
   • 搜索并选择您的 Azure 应用注册（按客户端 ID）。
   • 输入 业务部门（通常是根业务部门）。
   • 点击 创建。
3. 分配安全角色
   • 选择新创建的应用程序用户。
   • 点击 管理角色。
   • 根据您的需求分配适当的安全角色：
     • 系统管理员：完全访问权限（建议用于开发/测试）。
     • 系统定制者：无需数据访问的模式操作。
     • 自定义角色：为生产使用创建特定权限。
4. 验证应用程序用户状态
   • 确保应用程序用户已 启用。
   • 验证其类型为 应用程序（而不是 用户）。
   • 注意 应用程序 ID 与您的 Azure 应用注册客户端 ID 匹配。

4. 获取所需信息

您将需要：

• 租户 ID：在 Azure AD > 概述中找到。
• 客户端 ID：在您的应用注册 > 概述中找到。
• 客户端密钥：您刚刚创建的密钥。
• Dataverse URL：您的 Dataverse 环境 URL（例如，https://yourorg.crm.dynamics.com）。

配置

服务器支持灵活的环境变量配置，优先级如下（从高到低）：

1. MCP 环境变量（最高优先级）
2. 系统环境变量
3. .env 文件变量（最低优先级）

选项 1：使用 .env 文件（推荐用于 MCP 服务器开发）

服务器会自动从项目根目录的 .env 文件中加载环境变量。这是在为 MCP 服务器做出贡献或进行修改时推荐的方法。

1. 创建您的 .env 文件：

cp .env.example .env

2. 在 MCP 设置文件中添加以下配置：

{
  "mcpServers": {
    "dataverse": {
      "command": "node",
      "args": ["/path/to/mcp-dataverse/build/index.js"],
      "disabled": false,
      "alwaysAllow": [],
      "disabledTools": [],
      "timeout": 900
    }
  }
}

注意：timeout 设置增加到 900 秒（15 分钟），以适应较长时间运行的操作，如模式导出，可能需要处理大量元数据。

选项 2：使用 MCP 环境变量（推荐用于正常使用）

您可以直接在 MCP 设置中配置环境变量。这是在使用 MCP Dataverse 工具进行开发活动时推荐的正常使用方法。这些变量将覆盖 .env 文件中的任何值：

{
  "mcpServers": {
    "dataverse": {
      "command": "node",
      "args": ["/path/to/mcp-dataverse/build/index.js"],
      "env": {
        "DATAVERSE_URL": "https://yourorg.crm.dynamics.com",
        "DATAVERSE_CLIENT_ID": "your-client-id",
        "DATAVERSE_CLIENT_SECRET": "your-client-secret",
        "DATAVERSE_TENANT_ID": "your-tenant-id"
      },
      "disabled": false,
      "alwaysAllow": [],
      "disabledTools": [],
      "timeout": 900
    }
  }
}

选项 3：混合配置

您还可以使用组合方法，将常见设置放在 .env 文件中，而敏感或特定于环境的设置通过 MCP 进行覆盖：

.env 文件：

DATAVERSE_URL=https://dev-org.crm.dynamics.com
DATAVERSE_TENANT_ID=common-tenant-id

MCP 设置（生产覆盖）：

{
  "mcpServers": {
    "dataverse": {
      "command": "node",
      "args": ["/path/to/mcp-dataverse/build/index.js"],
      "env": {
        "DATAVERSE_URL": "https://prod-org.crm.dynamics.com",
        "DATAVERSE_CLIENT_ID": "prod-client-id",
        "DATAVERSE_CLIENT_SECRET": "prod-client-secret"
      },
      "disabled": false,
      "alwaysAllow": [],
      "disabledTools": [],
      "timeout": 900
    }
  }
}

PowerPages 配置管理

manage_powerpages_webapi_config 工具可帮助管理 PowerPages 代码站点的表权限和 WebAPI 站点设置。它自动配置 .powerpages-site 目录结构中的 YAML 文件，使您更轻松地为 PowerPages 应用程序设置和维护 WebAPI 访问权限。

主要特性

• 自动 YAML 管理：创建和更新 sitesetting.yml、webrole.yml 和表权限文件。
• WebAPI 配置：启用具有适当站点设置的 WebAPI 访问。
• 表权限：管理特定表和 Web 角色的细粒度权限。
• 状态检查：提供当前配置的全面状态。
• PowerPages 代码站点集成：与 .powerpages-site 目录结构无缝协作。

操作示例

检查配置状态

{
  "operation": "status"
}

示例输出：

PowerPages WebAPI 配置状态:

WebAPI 配置:
✅ WebAPI 已启用 (Webapi/cr7ae_creditcardses/Enabled = true)
✅ WebAPI 字段已配置 (Webapi/cr7ae_creditcardses/Fields = cr7ae_name,cr7ae_type,cr7ae_limit)

Web 角色:
✅ 已存在经过身份验证的用户角色
✅ 已存在匿名用户角色

表权限:
✅ 已为经过身份验证的用户配置 cr7ae_creditcardses 权限
  - 读取: ✅, 创建: ✅, 写入: ✅, 删除: ❌
  - 范围: 全局

为表启用 WebAPI

{
  "operation": "configure-webapi",
  "tableName": "cr7ae_creditcardses",
  "fields": ["cr7ae_name", "cr7ae_type", "cr7ae_limit", "cr7ae_isactive"],
  "enabled": true
}

结果：

• 使用 WebAPI 设置更新 .powerpages-site/sitesetting.yml。
• 为指定表启用 WebAPI 访问。
• 配置 WebAPI 操作的允许字段。

创建表权限

{
  "operation": "create-table-permission",
  "tableName": "cr7ae_creditcardses",
  "webRoleName": "Authenticated Users",
  "permissions": {
    "read": true,
    "create": true,
    "write": true,
    "delete": false
  },
  "scope": "Global"
}

结果：

• 创建 .powerpages-site/table-permissions/cr7ae_creditcardses_authenticated_users.yml。
• 为 Web 角色配置特定的 CRUD 权限。
• 设置适当的范围（全局、联系人、账户、自身、父级等）。

列出当前配置

{
  "operation": "list-configurations"
}

示例输出：

当前 PowerPages 配置:

站点设置 (共 3 项):
- Webapi/cr7ae_creditcardses/Enabled = true
- Webapi/cr7ae_creditcardses/Fields = cr7ae_name,cr7ae_type,cr7ae_limit
- Authentication/Registration/Enabled = true

Web 角色 (共 2 项):
- 经过身份验证的用户 (ID: 12345678-1234-1234-1234-123456789012)
- 匿名用户 (ID: 87654321-4321-4321-4321-210987654321)

表权限 (共 1 项):
- cr7ae_creditcardses_authenticated_users.yml
  表: cr7ae_creditcardses, 角色: 经过身份验证的用户
  权限: 读取 ✅, 创建 ✅, 写入 ✅, 删除 ❌
  范围: 全局

操作说明

status

提供当前 PowerPages WebAPI 配置的全面概述，包括：

• 表的 WebAPI 启用状态。
• 配置的字段和权限。
• Web 角色定义。
• 表权限摘要。

configure-webapi

为特定表启用或配置 WebAPI 访问：

• tableName（必需）：表的逻辑名称。
• fields（可选）：允许在 WebAPI 调用中使用的字段名称数组。
• enabled（可选）：布尔值，用于启用/禁用 WebAPI 访问。

create-table-permission

为 Web 角色创建细粒度的表权限：

• tableName（必需）：表的逻辑名称。
• webRoleName（必需）：Web 角色的名称。
• permissions（必需）：包含读取、创建、写入、删除布尔值的对象。
• scope（可选）：权限范围（全局、联系人、账户、自身、父级等）。

list-configurations

列出所有当前配置，包括：

• 具有其值的站点设置。
• 带有 ID 的 Web 角色。
• 具有详细权限细分的表权限。

PowerPages 代码站点集成

此工具旨在与遵循标准目录结构的 PowerPages 代码站点配合使用：

your-powerpages-project/
├── .powerpages-site/
│   ├── sitesetting.yml          # WebAPI 和其他站点设置
│   ├── webrole.yml             # Web 角色定义
│   └── table-permissions/      # 单个权限文件
│       ├── cr7ae_creditcardses_authenticated_users.yml
│       └── contact_anonymous_users.yml
├── src/                        # 您的 React 组件
└── package.json

示例工作流程

1. 检查当前状态：

   {"operation": "status"}
   

2. 为您的自定义表启用 WebAPI：

   {
     "operation": "configure-webapi",
     "tableName": "cr7ae_creditcardses",
     "fields": ["cr7ae_name", "cr7ae_type", "cr7ae_limit"],
     "enabled": true
   }
   

3. 创建表权限：

   {
     "operation": "create-table-permission",
     "tableName": "cr7ae_creditcardses",
     "webRoleName": "Authenticated Users",
     "permissions": {
       "read": true,
       "create": true,
       "write": true,
       "delete": false
     },
     "scope": "Global"
   }
   

4. 验证配置：

   {"operation": "list-configurations"}
   

5. 与 PowerPages WebAPI 生成器一起使用：

   {
     "operation": "retrieveMultiple",
     "logicalEntityName": "cr7ae_creditcardses",
     "select": ["cr7ae_name", "cr7ae_type", "cr7ae_limit"]
   }
   

此工作流程可确保您的 PowerPages 代码站点正确配置为处理自定义表的 WebAPI 调用，并具有适当的安全权限。

身份验证

服务器使用 客户端凭据流（服务器到服务器身份验证）与 Azure AD 进行身份验证。这提供了：

• 无需用户交互的安全身份验证。
• 应用程序级别的权限。
• 适用于自动化场景。
• 令牌刷新处理。

错误处理

服务器包括全面的错误处理：

• 身份验证错误 - 无效的凭据或过期的令牌。
• API 错误 - 具有代码的 Dataverse 特定错误消息。
• 验证错误 - 参数验证和类型检查。
• 网络错误 - 连接和超时处理。

安全注意事项

1. 安全存储机密 - 切勿将客户端密钥提交到版本控制。
2. 使用环境变量 - 通过环境变量配置机密。
3. 最小权限原则 - 仅授予必要的权限。
4. 监控使用情况 - 跟踪 API 调用和身份验证尝试。
5. 定期轮换机密 - 定期更新客户端密钥。

故障排除

常见问题

1. 身份验证失败
   • 验证客户端 ID、密钥和租户 ID。
   • 检查应用注册是否正确配置。
2. 权限被拒绝
   • 验证应用程序用户是否存在：检查是否已在 Dataverse 中为您的应用注册创建了应用程序用户。
   • 检查安全角色：确保应用程序用户具有适当的安全角色：
     • 系统管理员：进行完整模式操作所需。
     • 系统定制者：进行表/列操作的最低要求。
     • 环境制造者：可能需要进行解决方案操作。
   • 验证用户状态：确保应用程序用户已启用且未禁用。
   • 检查业务部门：验证应用程序用户是否分配到正确的业务部门。
   • 验证客户端 ID：确认 Dataverse 中的应用程序 ID 与您的 Azure 应用注册客户端 ID 匹配。
3. 实体未找到
   • 验证实体逻辑名称是否正确。
   • 检查实体是否存在于目标环境中。
4. 无效的列类型
   • 查看文档中支持的列类型。
   • 验证特定列类型的必需参数。

调试模式

设置环境变量 DEBUG=true 以进行详细日志记录：

DEBUG=true node build/index.js

API 参考

有关每个工具的详细参数信息，请参考源代码中的工具定义：

• - 表操作
• - 列操作
• - 关系操作
• - 选项集操作
• - 解决方案和发布者操作
• - 安全角色操作
• - 团队操作
• - 业务部门操作
• - 模式导出操作
• - WebAPI 调用生成器操作
• - PowerPages WebAPI 生成器操作
• - PowerPages 配置管理操作

解决方案管理最佳实践

发布者配置

创建发布者时，请遵循以下准则：

• 唯一前缀：使用 2 - 8 个字符的前缀来标识您的组织。
• 选项值范围：使用不重叠的范围（例如，一个发布者使用 10000 - 19999，另一个使用 20000 - 29999）。
• 描述性名称：为发布者和解决方案使用清晰、专业的名称。

解决方案上下文管理

// 检查当前上下文
await use_mcp_tool("dataverse", "get_solution_context", {});

// 切换到不同的解决方案
await use_mcp_tool("dataverse", "set_solution_context", {
  solutionUniqueName: "anothersolution"
});

// 清除上下文（移除持久化文件）
await use_mcp_tool("dataverse", "clear_solution_context", {});

环境升级

1. 开发：在开发环境中使用解决方案上下文创建和测试模式更改。
2. 导出：使用 Power Platform CLI 或管理中心导出解决方案。
3. 导入：将解决方案部署到测试/生产环境。
4. 验证：验证所有自定义项是否使用了正确的前缀。

Git 集成

.mcp-dataverse 文件会自动从版本控制中排除：

# MCP Dataverse 上下文文件
.mcp-dataverse

这允许每个开发人员维护自己的解决方案上下文，同时防止意外共享特定于环境的设置。

🔧 技术细节

身份验证

服务器采用 Azure AD 的客户端凭据流（服务器到服务器身份验证），具备安全认证、应用级权限、适配自动化场景以及处理令牌刷新等特性，确保无需用户交互即可实现安全认证。

错误处理

服务器设置了全面的错误处理机制，涵盖身份验证错误（如无效凭证或过期令牌）、API 错误（Dataverse 特定错误消息及代码）、验证错误（参数验证和类型检查）以及网络错误（连接和超时处理）。

安全考量

为保障系统安全，需安全存储密钥，避免提交至版本控制；通过环境变量配置密钥；遵循最小权限原则，仅授予必要权限；监控 API 调用和认证尝试；定期更新客户端密钥。

持久化解决方案上下文

服务器借助 .mcp-dataverse 文件持久化解决方案上下文，确保服务器重启后上下文依然保留，为开发人员提供持续的工作环境，避免上下文丢失。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

支持

若您遇到问题或有疑问，请按以下步骤操作：

1. 查看故障排除部分。
2. 查阅 Dataverse Web API 文档。
3. 在仓库中创建问题。