PowerPlatform MCP Server 使用说明

项目简介

PowerPlatform MCP Server 是一个基于 Model Context Protocol (MCP) 构建的后端服务，旨在为 LLM 客户端（如 Cursor、Claude App 和 GitHub Copilot）提供对 Microsoft Power Platform (也称为 Dataverse 或 Dynamics 365) 环境的智能访问。通过此 MCP 服务器，LLM 应用可以安全、便捷地获取 PowerPlatform 中的实体元数据、记录，并利用预定义的 Prompt 模板与 PowerPlatform 数据进行交互，从而实现上下文感知的增强功能。

主要功能点

实体元数据探索：检索和展示 PowerPlatform 实体的详细元数据信息，包括属性、关系、选项集等。
OData 查询支持：允许通过 OData 查询表达式检索 PowerPlatform 记录，支持高级过滤和排序。
关系映射：提供实体关系（一对多、多对多）的可视化信息，帮助理解数据模型。
Prompt 模板：内置多种 Prompt 模板，用于生成关于 PowerPlatform 实体的结构化、上下文丰富的描述信息，方便 LLM 理解和利用。
记录访问：根据实体名称和 ID 获取特定记录的详细数据。
全局选项集：检索全局选项集的定义，了解可用选项及其含义。

安装步骤

环境准备：确保已安装 Node.js 和 npm。

全局安装 (推荐)：

npm install -g powerplatform-mcp

或 直接运行 (无需安装)：

npx powerplatform-mcp

服务器配置 (MCP 客户端配置)

要将 PowerPlatform MCP Server 与 MCP 客户端连接，您需要在客户端中配置服务器信息。以下是配置示例（JSON 格式）：

{
  "servers": [
    {
      "name": "powerplatform-mcp-server",
      "command": "powerplatform-mcp",
      "args": [],
      "transports": [
        {
          "type": "stdio"
        }
      ],
      "capabilities": [
        "tools",
        "prompts"
      ]
    }
  ]
}

配置参数说明:

'name': 服务器名称，您可以自定义，例如 "powerplatform-mcp-server"。
'command': 启动 PowerPlatform MCP Server 的命令，通常为 'powerplatform-mcp'（如果全局安装）或 'npx powerplatform-mcp'（直接运行）。
'args': 启动命令的参数，本服务器无需额外参数，因此为空数组 '[]'。
'transports': 指定服务器使用的传输协议，这里使用 'stdio' (标准输入输出)。
'capabilities': 声明服务器提供的能力，包括 'tools' (工具) 和 'prompts' (Prompt 模板)。

环境变量配置:

在启动 PowerPlatform MCP Server 之前，请务必设置以下环境变量，以便服务器连接到您的 PowerPlatform 环境：

export POWERPLATFORM_URL=https://yourenvironment.crm.dynamics.com  # 您的 PowerPlatform 组织 URL
export POWERPLATFORM_CLIENT_ID=your-azure-app-client-id      # 您的 Azure 应用客户端 ID
export POWERPLATFORM_CLIENT_SECRET=your-azure-app-client-secret # 您的 Azure 应用客户端密钥
export POWERPLATFORM_TENANT_ID=your-azure-tenant-id          # 您的 Azure 租户 ID

请将上述示例中的占位符替换为您的 PowerPlatform 环境的实际信息。这些环境变量是 PowerPlatformService 连接到 Dataverse API 所必需的凭据。

基本使用方法

启动服务器：在终端中运行 'powerplatform-mcp' 或 'npx powerplatform-mcp' 命令启动服务器。
配置 MCP 客户端：将上述提供的 JSON 配置添加到您的 MCP 客户端配置中。
使用工具和 Prompt：在 MCP 客户端中，您可以使用以下工具和 Prompt 类型与 PowerPlatform MCP Server 交互：

工具 (Tools):
- 'get-entity-metadata': 获取实体元数据。参数: 'entityName' (实体逻辑名称)。
- 'get-entity-attributes': 获取实体所有属性。参数: 'entityName' (实体逻辑名称)。
- 'get-entity-attribute': 获取特定属性的元数据。参数: 'entityName' (实体逻辑名称), 'attributeName' (属性逻辑名称)。
- 'get-entity-relationships': 获取实体关系。参数: 'entityName' (实体逻辑名称)。
- 'get-global-option-set': 获取全局选项集定义。参数: 'optionSetName' (选项集名称)。
- 'get-record': 获取指定记录。参数: 'entityNamePlural' (实体复数名称), 'recordId' (记录 ID)。
- 'query-records': 查询记录。参数: 'entityNamePlural' (实体复数名称), 'filter' (OData 过滤器), 'maxRecords' (最大记录数，可选)。
- 'use-powerplatform-prompt': 使用预定义 Prompt 模板。参数: 'promptType' (Prompt 类型: 'ENTITY_OVERVIEW', 'ATTRIBUTE_DETAILS', 'QUERY_TEMPLATE', 'RELATIONSHIP_MAP'), 'entityName' (实体逻辑名称), 'attributeName' (属性逻辑名称，'ATTRIBUTE_DETAILS' 类型需要)。
Prompt 类型 (用于 'use-powerplatform-prompt' 工具):
- 'ENTITY_OVERVIEW': 实体概览
- 'ATTRIBUTE_DETAILS': 属性详情
- 'QUERY_TEMPLATE': 查询模板
- 'RELATIONSHIP_MAP': 关系映射
示例 (在 MCP 客户端中调用):
- 获取 "account" 实体的概览:
```
await mcpClient.invoke("use-powerplatform-prompt", { promptType: "ENTITY_OVERVIEW", entityName: "account" });
```
- 获取 "account" 实体 "revenue" 属性的详情:
```
await mcpClient.invoke("use-powerplatform-prompt", { promptType: "ATTRIBUTE_DETAILS", entityName: "account", attributeName: "revenue" });
```
- 获取 "contact" 实体的关系映射:
```
await mcpClient.invoke("use-powerplatform-prompt", { promptType: "RELATIONSHIP_MAP", entityName: "contact" });
```
- 查询 "accounts" 实体中名称包含 "Contoso" 的记录:
```
await mcpClient.invoke("query-records", { entityNamePlural: "accounts", filter: "contains(name, 'Contoso')" });
```

请参考仓库 README.md 文件获取更详细的使用示例和说明。

关键词