MCP Dataverse

🚀 Dataverse MCP Server

Microsoft Dataverse用のモデルコンテキストプロトコル（MCP）サーバーです。Dataverse Web APIを使用して、テーブル、列、リレーションシップ、オプションセットの作成や更新などのスキーマ操作を可能にします。

🚀 クイックスタート

このDataverse MCP Serverは、Dataverseのスキーマ管理を容易にするためのツールです。以下に、基本的な使い方を説明します。まずは前提条件を満たし、セットアップとインストールを行い、その後で各種操作を試してみましょう。

✨ 主な機能

✅ テーブルと列の管理 - すべての列タイプ（文字列、整数、ブール値、日付時刻、ピックリスト、ルックアップなど）を持つカスタムテーブルの作成、更新、削除、および一覧表示が可能です。 ✅ リレーションシップの管理 - エンティティ間の1対多および多対多のリレーションシップを、適切なカスケード動作で作成できます。 ✅ オプションセットの管理 - カスタムオプション、色、および値を持つグローバルオプションセットを作成および管理できます。 ✅ ソリューションベースのアーキテクチャ - 永続的なコンテキストと自動的なカスタマイズ接頭辞を備えたエンタープライズグレードのソリューション管理が可能です。 ✅ セキュリティとアクセス制御 - 完全なセキュリティロール管理、チーム操作、およびビジネスユニット階層管理ができます。 ✅ WebAPI呼び出しジェネレーター - 任意のDataverse操作に対して、すぐに使用できるHTTPリクエスト、cURLコマンド、およびJavaScriptコードを生成します。 ✅ PowerPages WebAPIジェネレーター - /_api/[論理エンティティ名]形式を使用して、PowerPages固有のWebAPI呼び出しを生成します。Reactの例も含まれています。 ✅ PowerPages構成管理 - YAMLファイルの自動化により、PowerPagesコードサイトのテーブル権限とWebAPIサイト設定を管理します。 ✅ スキーマエクスポート - ドキュメント化とバックアップのために、フィルタリングオプション付きで完全なソリューションスキーマを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"
});

リレーションシップの作成

// 1対多のリレーションシップを作成
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呼び出しジェネレーター

// 単純な取得操作を生成
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フェッチ: コピーアンドペースト可能なJavaScriptコード
• ソリューションコンテキスト: 自動的に現在のソリューションヘッダーを含めます
• 認証プレースホルダー: オプションのベアラートークンプレースホルダー
• ODataクエリ構築: 複雑なフィルター式の適切なエンコーディング

出力の例:

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

ヘッダー:
  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('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の複数取得操作を生成
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/[論理エンティティ名]sエンドポイントの構築 (自動的な's'接尾辞)
• リクエスト検証トークン: POST/PATCH/DELETE操作の自動トークン処理
• JavaScriptの例: エラーハンドリング付きのすぐに使用できるフェッチコード
• 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のテーブル権限とウェブロールのセキュリティを尊重
• SPA最適化: シングルページアプリケーション開発パターン用に設計

サポートされる操作:

• retrieve - IDで単一のレコードを取得
• retrieveMultiple - ODataフィルタリングで複数のレコードをクエリ
• create - リクエスト検証トークン付きで新しいレコードを作成
• update - トークン処理付きで既存のレコードを更新 (PATCH)
• delete - 適切な認証でレコードを削除

このツールは、PowerPagesのセキュリティと認証パターンを維持しながら、Dataverseデータとやり取りする現代的なSPAを構築するPowerPages開発者に不可欠です。

高度な使用法

PowerPages構成管理

manage_powerpages_webapi_configツールは、PowerPagesコードサイトのテーブル権限とWebAPIサイト設定を管理するのに役立ちます。.powerpages-siteディレクトリ構造内のYAMLファイルの構成を自動化し、PowerPagesアプリケーションのWebAPIアクセスの設定と保守を容易にします。

設定状態の確認

{
  "operation": "status"
}

サンプル出力:

PowerPages WebAPI構成の状態:

WebAPI構成:
✅ WebAPIが有効になっています (Webapi/cr7ae_creditcardses/Enabled = true)
✅ WebAPIフィールドが構成されています (Webapi/cr7ae_creditcardses/Fields = cr7ae_name,cr7ae_type,cr7ae_limit)

ウェブロール:
✅ 認証済みユーザーロールが存在します
✅ 匿名ユーザーロールが存在します

テーブル権限:
✅ cr7ae_creditcardsesの認証済みユーザーに対する権限が構成されています
  - 読み取り: ✅, 作成: ✅, 書き込み: ✅, 削除: ❌
  - スコープ: グローバル

テーブルのWebAPIを有効にする

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

結果:

• .powerpages-site/sitesetting.ymlをWebAPI設定で更新します
• 指定されたテーブルの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を作成します
• ウェブロールに対する詳細な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

ウェブロール (合計2つ):
- 認証済みユーザー (ID: 12345678-1234-1234-1234-123456789012)
- 匿名ユーザー (ID: 87654321-4321-4321-4321-210987654321)

テーブル権限 (合計1つ):
- cr7ae_creditcardses_authenticated_users.yml
  テーブル: cr7ae_creditcardses, ロール: 認証済みユーザー
  権限: 読み取り ✅, 作成 ✅, 書き込み ✅, 削除 ❌
  スコープ: グローバル

操作内容

状態

現在のPowerPages WebAPI構成の包括的な概要を提供します。具体的には、以下の内容が含まれます。

• テーブルのWebAPI有効化状態
• 構成されたフィールドと権限
• ウェブロールの定義
• テーブル権限の概要

WebAPIを構成する

特定のテーブルのWebAPIアクセスを有効にするか構成します。

• tableName (必須): テーブルの論理名
• fields (オプション): WebAPI呼び出しで許可するフィールド名の配列
• enabled (オプション): WebAPIアクセスを有効または無効にするブール値

テーブル権限を作成する

ウェブロールに対する詳細なテーブル権限を作成します。

• tableName (必須): テーブルの論理名
• webRoleName (必須): ウェブロールの名前
• permissions (必須): 読み取り、作成、書き込み、削除のブール値を持つオブジェクト
• scope (オプション): 権限のスコープ (グローバル、コンタクト、アカウント、自己、親など)

構成を一覧表示する

すべての現在の構成を一覧表示します。具体的には、以下の内容が含まれます。

• 値付きのサイト設定
• ID付きのウェブロール
• 詳細な権限の内訳付きのテーブル権限

PowerPagesコードサイトの統合

このツールは、標準のディレクトリ構造に従うPowerPagesコードサイトで動作するように設計されています。

your-powerpages-project/
├── .powerpages-site/
│   ├── sitesetting.yml          # WebAPIおよびその他のサイト設定
│   ├── webrole.yml             # ウェブロールの定義
│   └── 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呼び出しを処理するように適切に構成されます。

📚 ドキュメント

前提条件

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

認証

サーバーはAzure ADを使用したクライアント資格情報フロー（サーバー間認証）を使用します。これにより、以下のことが可能になります。

• ユーザーの操作なしでの安全な認証
• アプリケーションレベルのアクセス許可
• 自動化シナリオに適している
• トークンの自動更新

エラーハンドリング

サーバーには包括的なエラーハンドリングが含まれています。

• 認証エラー - 無効な資格情報または期限切れのトークン
• APIエラー - コード付きのDataverse固有のエラーメッセージ
• 検証エラー - パラメータの検証と型チェック
• ネットワークエラー - 接続とタイムアウトのハンドリング

セキュリティに関する考慮事項

1. シークレットを安全に保管する - クライアントシークレットをバージョン管理にコミットしないでください。
2. 環境変数を使用する - 環境変数を通じてシークレットを構成します。
3. 最小限の特権の原則 - 必要なアクセス許可のみを付与します。
4. 使用状況を監視する - API呼び出しと認証試行を追跡します。
5. 定期的にシークレットをローテーションする - クライアントシークレットを定期的に更新します。

トラブルシューティング

一般的な問題

1. 認証失敗
   • クライアントID、シークレット、およびテナントIDを確認します。
   • アプリ登録が適切に構成されていることを確認します。
2. 許可が拒否されました
   • アプリケーションユーザーが存在することを確認する: Dataverseであなたのアプリ登録用にアプリケーションユーザーが作成されていることを確認し