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. 在倉庫中創建問題。