内容
# Dataverse MCP 服务器
[](https://pypi.org/project/dataverse-mcp/)
[](https://pypi.org/project/dataverse-mcp/)
[](LICENSE)
一个 [MCP](https://modelcontextprotocol.io/) 服务器，为 AI 代理提供结构化的 Microsoft Dataverse 访问能力 — 查询记录、批量插入/更新数据、检查元数据、管理模式、分析组件依赖、管理模型驱动的应用表单、视图和应用、管理安全角色、团队和用户、审计用户访问、管理插件跟踪日志、管理自定义 API，以及探索 Power Platform 环境。
使用 [FastMCP](https://github.com/modelcontextprotocol/python-sdk)、`httpx` 和 Dataverse OData v4.0 Web API 构建。通过 **stdio** 通信，支持 Claude、GitHub Copilot 和任何 MCP 兼容的客户端。
---
## 快速开始
**1. 安装 uv**
```bash
pip install uv
```
**2. 配置** — 添加到您的 MCP 客户端配置：
**Claude** (`claude_desktop_config.json` 或 `.claude/settings.json`):
```json
{
"mcpServers": {
"dataverse-mcp": {
"command": "uvx",
"args": ["dataverse-mcp"],
"env": {
"DATAVERSE_AUTH_TYPE": "interactive"
}
}
}
}
```
**GitHub Copilot** (`.vscode/mcp.json`):
```json
{
"servers": {
"dataverse-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["dataverse-mcp"],
"env": {
"DATAVERSE_AUTH_TYPE": "interactive"
}
}
}
}
```
**3. 登录**
首次使用时，服务器会打开浏览器进行交互式登录。会话被缓存并在重启期间重用（参见 `DATAVERSE_TOKEN_CACHE_PERSIST`），因此只要令牌有效，您就不会再次收到提示。
就这样。您的 AI 代理现在可以查询您的 Dataverse 环境。
> 如果您更喜欢使用现有的 Azure CLI 会话？将 `DATAVERSE_AUTH_TYPE` 设置为 `azure_cli` 并运行 `az login`。
---
## 安装
### 安装 uv
`uvx` 由 [uv](https://docs.astral.sh/uv/) 提供。如果您没有安装它，请先安装：
```bash
pip install uv
```
### 从 PyPI 运行（推荐）
```bash
uvx dataverse-mcp
```
`uvx` 在隔离环境中下载并运行软件包 — 无需虚拟环境管理。
### 从本地代码仓库运行
```bash
git clone https://github.com/ryanmichaeljames/dataverse-mcp.git
cd dataverse-mcp
uv sync
```
这会创建 `.venv`。使用本地源 MCP 配置（参见 [客户端设置](#客户端设置)）指向它。无需构建步骤 — 代码更改会在下一次服务器启动时生效。
---
## 配置
在 MCP 服务器条目的 `env` 块中设置这些配置项。该项目不使用 `.env` 文件。
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `DATAVERSE_AUTH_TYPE` | `interactive` | 身份验证方法：`interactive`（推荐）或 `azure_cli` |
| `DATAVERSE_ALLOW_WRITE` | `false` | 设置为 `true` 以注册创建、更新、关联、合并和模式突变工具 |
| `DATAVERSE_ALLOW_DELETE` | `false` | 设置为 `true` 以注册删除和解除关联工具 |
| `DATAVERSE_TOOLS` | — | 以逗号分隔的工具类别列表，用于注册（例如 `core,schema,security`）。当未设置或为空时，所有类别都会注册。`core` 始终注册，无论如何。未知类别名称会记录为警告并忽略。参见下面的 [工具类别](#工具类别)。 |
| `DATAVERSE_WHITELIST` | — | 允许的环境主机名列表（例如 `yourorg.crm.dynamics.com,yourorg-uat.crm.dynamics.com`）。设置后，工具调用任何不在列表中的环境都会被拒绝。当为空时，**所有** 环境都被允许 — 参见下面的警告。将视为 **必需的强化步骤**，适用于任何非本地或共享部署 |
| `DATAVERSE_REQUIRE_WHITELIST` | `false` | 当为 `true` 时，关闭失败：如果 `DATAVERSE_WHITELIST` 为空，**每个** 工具调用都会被拒绝，因此不会为未经批准的主机颁发承载令牌。推荐用于共享/多租户部署。无效值会回退到 `false`，并记录警告 |
| `DATAVERSE_FILE_BASE_DIR` | — | 可选目录，用于限制解决方案导出/导入文件路径（`output_path` / `input_path` 在 `dataverse_export_solution`、`dataverse_import_solution`、`dataverse_stage_and_upgrade_solution` 上）。设置后，任何解析到此目录外部的路径 — 包括 `..` 遍历或绝对路径到其他位置 — 都会被拒绝。限制了任意位置文件写入/读取的爆炸半径（例如，提示注入有效载荷，引导代理覆盖启动脚本或读取 SSH 密钥）。当未设置时，路径不受限制（以前的行为）。推荐用于非本地或共享部署 |
| `DATAVERSE_AUTH_TIMEOUT_SECONDS` | `30` | 等待凭证获取的最大秒数（例如 `az login` 令牌获取）之前失败，并带有可操作的身份验证错误。在慢速网络或 MFA 繁重的环境中操作时增加。当在慢速网络或 MFA 繁重的环境中操作时增加。无效或非正值会回退到 `30` |
| `DATAVERSE_TOKEN_CACHE_PERSIST` | `true` | 控制 `interactive` 身份验证是否将其 MSAL 令牌缓存持久保存到磁盘，以便服务器在重启后无需新的浏览器提示而生存（只要刷新令牌有效）。设置为 `false` 以禁用并恢复到仅内存的行为。无效值会回退到 `true`，并记录警告。对 `azure_cli` 身份验证无效。 |
| `DATAVERSE_TOKEN_CACHE_ALLOW_UNENCRYPTED` | `false` | 当为 `true` 时，允许将 MSAL 令牌缓存写入磁盘而不进行 OS 级加密。仅在没有 Secret Service 的无头 Linux 主机上需要（例如 GNOME 密钥环 / libsecret）。**刷新令牌是长期凭证 — 仅在受信任的受控主机上启用此功能。** 启动时记录警告。无效值会回退到 `false`。 |
| `DATAVERSE_TOKEN_CACHE_PROFILE` | — | 可选名称，用于隔离 `interactive` 令牌缓存及其 `AuthenticationRecord` 边车，按配置文件隔离。设置不同的值在每个会话中运行并发服务器，登录到 **不同的租户/帐户**，而不会相互覆盖缓存。必须仅使用 `[A-Za-z0-9_-]`；任何其他字符都会快速失败并产生静默清理。空/未设置使用共享的默认文件名。对 `azure_cli` 身份验证无效。 |
> [!WARNING]
> **留空 `DATAVERSE_WHITELIST` 是有风险的。** 工具接受每个调用的 `dataverse_url`，而服务器为提供的环境颁发承载令牌。没有白名单，泄露或行为不端的代理可以引导您的凭证指向 *任何* Dataverse 环境。设置 `DATAVERSE_WHITELIST` 为您打算使用的特定环境主机名，以便服务器拒绝其他环境。对于共享或多租户主机，还要设置 `DATAVERSE_REQUIRE_WHITELIST=true`，这样服务器在白名单意外留空时关闭失败，而不是在白名单为空时颁发令牌。
### 身份验证
| 方法 | 描述 |
| --- | --- |
| `interactive`（默认，推荐） | 打开浏览器进行交互式登录。支持 MFA 和按帐户隔离，无需单独的 CLI 登录。会话在服务器重启期间持续（参见 `DATAVERSE_TOKEN_CACHE_PERSIST`）：第一次启动会打开浏览器；后续重启会在刷新令牌有效时静默重用缓存的刷新令牌。 |
| `azure_cli` | 使用您的活动 `az login` 会话。有用在 CI 中或浏览器不可用且已存在 Azure CLI 会话时。需要安装并登录 Azure CLI。 |
> [!NOTE]
> **交互式身份验证持久性。** 当 `DATAVERSE_TOKEN_CACHE_PERSIST=true`（默认值）时，MSAL 令牌缓存使用您的 OS 秘密存储（Windows DPAPI、macOS 密钥环、Linux libsecret）存储在磁盘上。在没有 libsecret 的无头 Linux 上，第一次令牌获取将快速失败并报错。设置 `DATAVERSE_TOKEN_CACHE_ALLOW_UNENCRYPTED=true` 以允许在这些主机上使用纯文本缓存，并参见上面的安全警告。
> [!NOTE]
> **同时运行多个租户/帐户。** 默认缓存和边车文件名按主机共享，因此两个 `interactive` 会话登录到不同的租户/帐户将相互覆盖彼此的固定帐户。给每个会话一个不同的 `DATAVERSE_TOKEN_CACHE_PROFILE`（例如 `prod`、`dev`），以保持它们的缓存和 `AuthenticationRecord` 边车单独。
#### 示例：两个租户并存
注册两个服务器条目，每个条目都有自己的 `DATAVERSE_TOKEN_CACHE_PROFILE`。配置文件是 *租户范围* 的缓存键 — 每个条目登录一次（其自己的浏览器提示），然后静默重启为自己的帐户，同时工具仍然接收每个调用的具体 `dataverse_url`。配置文件永远不会冲突。
**Claude** (`claude_desktop_config.json` 或 `.claude/settings.json`):
```json
{
"mcpServers": {
"dataverse-prod": {
"command": "uvx",
"args": ["dataverse-mcp"],
"env": {
"DATAVERSE_AUTH_TYPE": "interactive",
"DATAVERSE_TOKEN_CACHE_PROFILE": "prod"
}
},
"dataverse-dev": {
"command": "uvx",
"args": ["dataverse-mcp"],
"env": {
"DATAVERSE_AUTH_TYPE": "interactive",
"DATAVERSE_TOKEN_CACHE_PROFILE": "dev"
}
}
}
}
```
**GitHub Copilot** (`.vscode/mcp.json`):
```json
{
"servers": {
"dataverse-prod": {
"type": "stdio",
"command": "uvx",
"args": ["dataverse-mcp"],
"env": {
"DATAVERSE_AUTH_TYPE": "interactive",
"DATAVERSE_TOKEN_CACHE_PROFILE": "prod"
}
},
"dataverse-dev": {
"type": "stdio",
"command": "uvx",
"args": ["dataverse-mcp"],
"env": {
"DATAVERSE_AUTH_TYPE": "interactive",
"DATAVERSE_TOKEN_CACHE_PROFILE": "dev"
}
}
}
}
```
每个配置文件映射到一个租户/帐户登录；代理在每个工具调用上传递目标 `dataverse_url`。省略 `DATAVERSE_TOKEN_CACHE_PROFILE`（或留空）适用于单租户设置 — 使用原始共享缓存文件名。
### 安全防护
大多数写入和删除工具 **默认不注册**，因此除非显式启用，否则它们对代理不可见。一个例外是 `dataverse_execute_batch`，它始终可见，但除非 `DATAVERSE_ALLOW_WRITE=true`，否则拒绝非 GET 操作。这可以防止在您只需要读取或检查数据而不允许写入时发生意外突变。
```json
{
"servers": {
"dataverse-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["dataverse-mcp"],
"env": {
"DATAVERSE_AUTH_TYPE": "interactive",
"DATAVERSE_ALLOW_WRITE": "true",
"DATAVERSE_ALLOW_DELETE": "true"
}
}
}
}
```
每个标志都是独立的 — 只需设置 `DATAVERSE_ALLOW_WRITE=true` 以允许创建和更新，同时保持删除禁用。
### 可靠性和限制
这些行为是内置的，不需要配置：
- **自动重试** — 请求被 Dataverse 服务保护限制或遇到瞬时网关错误时自动重试；只读请求也在超时和连接失败时重试。
- **响应大小上限** — 大于 5 MB 的响应被替换为错误，要求代理使用 `select`、`top` 或 `filter` 缩小查询。
- **一致的错误** — 每个工具返回 JSON；失败的形状为 `{"error": true, "message": "..."}`，包含 Dataverse 错误代码和长度限制的消息。
- **服务器端分页** — 列表工具从 Dataverse 请求合适大小的页面，而不是完整的 5,000 条记录页面。
---
## 客户端设置
### Claude
#### Claude 桌面版
添加到 `claude_desktop_config.json`：
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"dataverse-mcp": {
"command": "uvx",
"args": ["dataverse-mcp"],
"env": {
"DATAVERSE_AUTH_TYPE": "interactive"
}
}
}
}
```
#### Claude 代码
通过 CLI 添加：
```bash
claude mcp add dataverse-mcp --env DATAVERSE_AUTH_TYPE=interactive uvx dataverse-mcp
```
或直接添加到 `.claude/settings.json`（项目）或 `~/.claude/settings.json`（用户）：
```json
{
"mcpServers": {
"dataverse-mcp": {
"command": "uvx",
"args": ["dataverse-mcp"],
"env": {
"DATAVERSE_AUTH_TYPE": "interactive"
}
}
}
}
```
#### 从本地代码仓库运行
```json
{
"mcpServers": {
"dataverse-mcp-local": {
"command": "C:\\path\\to\\dataverse-mcp\\.venv\\Scripts\\python.exe",
"args": ["-m", "dataverse_mcp.server"],
"env": {
"PYTHONPATH": "C:\\path\\to\\dataverse-mcp\\src",
"DATAVERSE_AUTH_TYPE": "interactive"
}
}
}
}
```
---
### GitHub Copilot
添加到 `.vscode/mcp.json`：
#### 从 PyPI 运行
```json
{
"servers": {
"dataverse-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["dataverse-mcp"],
"env": {
"DATAVERSE_AUTH_TYPE": "interactive"
}
}
}
}
```
#### 从本地代码仓库运行
```json
{
"servers": {
"dataverse-mcp-local": {
"type": "stdio",
"command": "C:\\path\\to\\dataverse-mcp\\.venv\\Scripts\\python.exe",
"args": ["-m", "dataverse_mcp.server"],
"env": {
"PYTHONPATH": "C:\\path\\to\\dataverse-mcp\\src",
"DATAVERSE_AUTH_TYPE": "interactive"
}
}
}
}
```
---
### 多环境目标
单个服务器实例可以针对任何 Dataverse 组织 — 在每个工具调用上传递 `dataverse_url`:
```json
{
"dataverse_url": "https://yourorg.crm.dynamics.com",
"entity_set_name": "accounts",
"select": ["name", "accountid"],
"top": 10
}
```
`dataverse_url` 每个工具调用都需要。 使用 `dataverse_list_environments` 发现可用的环境，如果您尚未知道 URL。
## 工具
**184 个工具** 按以下域名分组。每个工具返回 JSON 并在每个调用时需要 `dataverse_url`。
**Gate** 列显示何时注册了工具：
| Gate | 含义 |
| --- | --- |
| `default` | 始终注册（读取和安全查询）。 |
| `write` | 仅当 `DATAVERSE_ALLOW_WRITE=true` 注册。 |
| `delete` | 仅当 `DATAVERSE_ALLOW_DELETE=true` 注册。 |
> `dataverse_execute_batch` 是 `default` 但除非 `DATAVERSE_ALLOW_WRITE=true`，否则拒绝非 GET 操作。
### 工具类别
使用 `DATAVERSE_TOOLS` 注册仅您的代理需要的工具类别。这缩小了可见的工具列表并减少了令牌开销。
| 类别 | 工具 | 描述 |
| --- | --- | --- |
| `core` | 18 | 环境内省 + 所有记录 CRUD（始终注册） |
| `schema` | 32 | 表/列/关系/选择/备用密钥元数据 |
| `solutions` | 20 | 解决方案和发布者管理、解决方案组件、历史、导入/导出 ALM、依赖分析 |
| `flows` | 8 | 云流 + 经典进程列表和激活/停用 |
| `forms` | 6 | 模型驱动的表单管理 |
| `views` | 7 | 保存的查询 / 视图管理 |
| `apps` | 10 | Canvas 和模型驱动的应用管理 |
| `connections` | 5 | 连接引用管理 |
| `variables` | 8 | 环境变量定义和值 |
| `plugins` | 33 | 插件程序集、类型、步骤、步骤图像、包、跟踪日志 |
| `security` | 16 | 安全角色、团队、用户、业务单元、复合访问审计、审计历史 |
| `jobs` | 3 | 异步操作（系统作业）监视和取消 |
| `webresources` | 5 | Web 资源（JS/HTML/CSS/图像）CRUD — 分段，不是始终开启 |
| `customapis` | 13 | 自定义 API、请求参数和响应属性管理 |
`core` 始终注册，即使未列出。 当 `DATAVERSE_TOOLS` 未设置或为空时，所有类别都会注册（当前默认行为）。类别门控与 `DATAVERSE_ALLOW_WRITE` 和 `DATAVERSE_ALLOW_DELETE` 组合：仅当其类别启用且其写入/删除标志（如果有）设置时，才注册工具。
### 环境和身份
| 工具 | Gate | 描述 |
| --- | --- | --- |
| `dataverse_list_environments` | default | 列出调用者可访问的 Power Platform 环境 |
| `dataverse_whoami` | default | 返回调用者的 `UserId`、`BusinessUnitId`、`OrganizationId` |
| `dataverse_get_entity_sets` | default | 从服务文档中列出 OData EntitySet 名称 |
| `dataverse_retrieve_user_privileges` | default | 列出分配给用户的权限 |
| `dataverse_retrieve_principal_access` | default | 检查用户对特定记录的访问权限 |
### 安全管理
| 工具 | Gate | 描述 |
|------|------|-------------|
| `dataverse_list_security_roles` | default | 列出安全角色，可选过滤和分页 |
| `dataverse_get_security_role` | default | 通过GUID获取一个安全角色 |
| `dataverse_list_teams` | default | 列出团队，可选过滤和分页 |
| `dataverse_get_team` | default | 通过GUID获取一个团队 |
| `dataverse_list_users` | default | 列出系统用户，可选过滤和分页 |
| `dataverse_get_user` | default | 通过GUID获取一个系统用户 |
| `dataverse_list_business_units` | default | 列出业务单元，可选过滤和分页 |
| `dataverse_audit_user_access` | default | 综合报告：用户身份、直接角色、团队成员资格 + 团队角色、有效权限、可选记录级访问检查 |
| `dataverse_list_audit` | default | 查询 `audits` 实体集，可选OData过滤、选择、排序和顶部；返回审计元数据行 |
| `dataverse_get_audit_details` | default | 通过绑定的 `RetrieveAuditDetails` 函数获取单个审计记录的完整前后详细信息 |
| `dataverse_retrieve_record_change_history` | default | 通过 `RetrieveRecordChangeHistory` 检索单个记录的完整审计变更历史；返回结构化的 `AuditDetailCollection` |
| `dataverse_assign_security_role` | write | 将安全角色分配给用户或团队 |
| `dataverse_remove_security_role` | write | 从用户或团队中删除安全角色 |
| `dataverse_add_team_members` | write | 将一个或多个用户添加到团队 |
| `dataverse_remove_team_members` | write | 从团队中删除一个或多个用户 |
| `dataverse_set_user_state` | write | 启用或禁用系统用户 (`isdisabled`) |
### 异步作业
| 工具 | Gate | 描述 |
|------|------|-------------|
| `dataverse_list_async_operations` | default | 列出系统作业（asyncoperations），可选按 statecode/statuscode/operationtype 过滤 |
| `dataverse_get_async_operation` | default | 通过GUID获取一个系统作业 |
| `dataverse_cancel_async_operation` | write | 取消正在运行或等待的系统作业（PATCH statecode=3/statuscode=32） |
### Web 资源
| 工具 | Gate | 描述 |
|------|------|-------------|
| `dataverse_list_web_resources` | default | 列出Web资源，可选按类型和/或名称子字符串过滤 |
| `dataverse_get_web_resource` | default | 通过GUID获取一个Web资源；`include_content=true` 添加 base64 内容字段 |
| `dataverse_create_web_resource` | write | 创建一个Web资源（名称、类型、base64 内容）；调用 `dataverse_publish_customizations` 之后 |
| `dataverse_update_web_resource` | write | PATCH 内容、显示名称或描述；调用 `dataverse_publish_customizations` 之后 |
| `dataverse_delete_web_resource` | delete | 通过GUID永久删除一个非托管Web资源 |
### 记录和数据
| 工具 | Gate | 描述 |
|------|------|-------------|
| `dataverse_query_table` | default | 查询记录，带过滤、选择、排序、展开、顶部 |
| `dataverse_execute_fetchxml` | default | 执行 FetchXML 查询（连接、聚合、分页 cookie） |
| `dataverse_get_record` | default | 通过实体集名称和GUID获取一个记录 |
| `dataverse_count_records` | default | 统计表中的行数，可选过滤 |
| `dataverse_aggregate_table` | default | 聚合（求和、平均值、最小值、最大值、计数distinct）带可选分组 |
| `dataverse_execute_batch` | default | 在一个 `$batch` 中运行最多 1,000 个OData操作（仅限GET，除非启用写入） |
| `dataverse_bulk_upsert` | write | 通过 `$batch` PATCH 插入/更新多个记录；自动检测主键或使用 `key_columns` 进行替代键插入；每行结果 |
| `dataverse_create_record` | write | 创建一个记录并返回其新的GUID |
| `dataverse_update_record` | write | 部分更新一个记录（PATCH） |
| `dataverse_associate_records` | write | 通过集合值导航属性关联两个记录 |
| `dataverse_merge_records` | write | 将从属记录合并到目标记录（帐户、联系人、线索、事件） |
| `dataverse_delete_record` | delete | 永久删除一个记录 |
| `dataverse_disassociate_records` | delete | 删除两个记录之间的关联 |
### 表和列
| 工具 | Gate | 描述 |
|------|------|-------------|
| `dataverse_list_tables` | default | 列出表，可选元数据过滤 |
| `dataverse_get_table_metadata` | default | 获取一个表的完整架构详细信息 |
| `dataverse_list_columns` | default | 列出一个表的列，可选类型过滤 |
| `dataverse_get_column` | default | 获取一个列的完整元数据，包括类型特定属性 |
| `dataverse_create_table` | write | 创建一个自定义表（所有权类型、主键属性） |
| `dataverse_update_table` | write | 更新表的显示名称或描述 |
| `dataverse_create_column` | write | 向表中添加一个类型化的列（支持备注、布尔值，带自定义标签，和 Picklist/MultiSelectPicklist 绑定到全局选择） |
| `dataverse_update_column` | write | 替换一个列，通过完整的PUT（先使用 `dataverse_get_column` 获取） |
| `dataverse_publish_customizations` | write | 通过 `PublishXml` 发布架构更改（针对实体/选项集/关系/Web资源ID）或 `PublishAllXml` |
| `dataverse_delete_table` | delete | 永久删除一个自定义表及其所有数据 |
| `dataverse_delete_column` | delete | 永久删除一个自定义列及其所有数据 |
### 关系
| 工具 | Gate | 描述 |
|------|------|-------------|
| `dataverse_list_relationships` | default | 列出一个表的或整个环境的关联 |
| `dataverse_get_relationship` | default | 通过架构名称获取一个关联的完整元数据 |
| `dataverse_check_relationship_eligibility` | default | 检查一个表是否可以参与关联 |
| `dataverse_create_one_to_many_relationship` | write | 创建一个1:N关联及其查找列 |
| `dataverse_create_many_to_many_relationship` | write | 创建一个N:N关联及其交叉表 |
| `dataverse_create_multi_table_lookup` | write | 创建一个多态查找，引用多个表 |
| `dataverse_update_relationship` | write | 替换一个关联，通过完整的PUT（先使用 `dataverse_get_relationship` 获取） |
| `dataverse_delete_relationship` | delete | 删除一个自定义关联，依据MetadataId |
### 选择（选项集）
| 工具 | Gate | 描述 |
|------|------|-------------|
| `dataverse_list_choices` | default | 列出全局选择（选项集） |
| `dataverse_get_choice` | default | 通过名称或MetadataId获取一个全局选择及其选项 |
| `dataverse_list_choice_column_options` | default | 获取Picklist或MultiSelectPicklist列的选项 |
| `dataverse_create_choice` | write | 创建一个全局选择，带有初始选项 |
| `dataverse_update_choice` | write | 替换一个全局选择，通过完整的PUT（先使用 `dataverse_get_choice` 获取） |
| `dataverse_add_choice_option` | write | 向全局或本地选择添加一个选项 |
| `dataverse_update_choice_option` | write | 更新一个选项的显示标签 |
| `dataverse_reorder_choice_options` | write | 重新排序选择中的所有选项 |
| `dataverse_delete_choice` | delete | 删除一个全局选择，依据逻辑名称 |
| `dataverse_delete_choice_option` | delete | 从全局或本地选择中删除一个选项 |
### 替代键
| 工具 | Gate | 描述 |
|------|------|-------------|
| `dataverse_list_alternate_keys` | default | 列出表上的 `EntityKeyMetadata` 定义；返回 `SchemaName`、`LogicalName`、`KeyAttributes`、`EntityKeyIndexStatus` 和 `IsManaged` |
| `dataverse_create_alternate_key` | write | 通过 `SchemaName`、`DisplayName` 和属性列表创建替代键；轮询 `EntityKeyIndexStatus` 直到变为“Active”后再使用进行插入/更新 |
| `dataverse_delete_alternate_key` | delete | 通过逻辑名称删除替代键；删除底层SQL索引 |
### 解决方案和发布者
| 工具 | Gate | 描述 |
|------|------|-------------|
| `dataverse_list_solutions` | default | 列出解决方案，可选过滤和分页 |
| `dataverse_get_solution` | default | 通过唯一名称或GUID获取一个解决方案 |
| `dataverse_list_solution_components` | default | 列出解决方案中的组件，可选类型过滤 |
| `dataverse_get_solution_history` | default | 通过GUID获取一个解决方案历史记录（导入/升级/导出操作） |
| `dataverse_list_solution_histories` | default | 列出解决方案历史记录，可选按解决方案GUID或唯一名称过滤；`msdyn_suboperation` 区分更新（`3`）和升级-删除组件（`5`） |
| `dataverse_create_publisher` | write | 创建一个发布者，带有自定义前缀 |
| `dataverse_update_publisher` | write | 通过GUID更新发布者字段 |
| `dataverse_create_solution` | write | 创建一个解决方案（发布者绑定、版本） |
| `dataverse_update_solution` | write | 通过GUID或唯一名称更新解决方案字段 |
| `dataverse_update_solution_version` | write | 仅更新解决方案的版本 |
| `dataverse_add_component_to_solution` | write | 通过 `AddSolutionComponent` 将组件添加到解决方案 |
| `dataverse_remove_component_from_solution` | delete | 通过 `RemoveSolutionComponent` 从解决方案中删除组件 |
| `dataverse_export_solution` | default | 导出一个解决方案为base64 zip；通过 `output_path` 写入磁盘适用于大解决方案（无组织变体 - 无写入标志要求） |
| `dataverse_import_solution` | write | 异步导入解决方案通过 `ImportSolutionAsync`；提供zip为内联base64（`customization_file`）或本地路径（`input_path`）；返回 `import_job_id` 以轮询。`hold_for_upgrade=false` 执行 **更新** （覆盖 - 不删除新版本中删除的组件）。对于真正的升级，请使用 `dataverse_stage_and_upgrade_solution` 或 `hold_for_upgrade=true` 然后 `dataverse_delete_and_promote_solution` |
| `dataverse_stage_and_upgrade_solution` | write | 通过 `StageAndUpgradeAsync` 进行单步解决方案 **升级** - 阶段为保持，删除过时组件，并在单个异步操作中进行升级；通过 `customization_file` 或 `input_path` 提供zip；返回 `import_job_id`、`async_operation_id`、`import_job_key` |
| `dataverse_delete_and_promote_solution` | write | 通过 `DeleteAndPromote` 进行两步应用升级 - 升级保持的 `_Upgrade` 解决方案并删除过时组件（与 `dataverse_import_solution` + `hold_for_upgrade=true` 配对）；同步，返回 `solution_id` |
| `dataverse_get_import_job` | default | 通过GUID获取一个importjob - 返回进度、completedon、solutionname；添加 `include_data=true` 获取结果XML（包括删除阶段的组件错误，如 `8004F037`）失败时 |
| `dataverse_list_import_jobs` | default | 列出importjobs，可选按解决方案唯一名称过滤，按 createdon desc排序 |
| `dataverse_clone_solution_as_patch` | write | 通过绑定的 `CloneAsPatch` 操作将解决方案克隆为补丁；通过GUID或唯一名称解析父级 |
| `dataverse_analyze_dependencies` | default | 分析组件依赖项：`blocking_delete`（阻止删除）、`dependents`（依赖于它）或 `required`（它需要的）；将组件类型代码解析为名称 |
> **文件系统I/O注意。** `dataverse_export_solution` 可以在提供 `output_path` 时将解码的.zip写入本地路径。 `dataverse_import_solution` 可以在提供 `input_path` 时读取本地.zip。两个路径都在运行MCP服务器的机器上解析。对于大于~3 MB的解决方案（内联base64阈值），请使用 `output_path` / `input_path`。
### 云流和进程
| 工具 | Gate | 描述 |
|------|------|-------------|
| `dataverse_get_cloud_flows` | default | 查询云流，可选限定为解决方案 |
| `dataverse_enable_cloud_flow` | write | 通过工作流ID启用一个流 |
| `dataverse_batch_enable_cloud_flows` | write | 在一个 `$batch` 中启用多个流，每个项目的结果 |
| `dataverse_disable_cloud_flow` | write | 通过工作流ID禁用一个流 |
| `dataverse_batch_disable_cloud_flows` | write | 在一个 `$batch` 中禁用多个流，每个项目的结果 |
| `dataverse_list_processes` | default | 从 `workflow` 实体列出经典进程（工作流、业务规则、操作、BPF）；可按类别和类型过滤 |
| `dataverse_activate_process` | write | 激活一个经典进程（设置statecode=1/Activated）；幂等 |
| `dataverse_deactivate_process` | write | 停用一个经典进程（设置statecode=0/Draft）；幂等 |
### 表单
| 工具 | Gate | 描述 |
|------|------|-------------|
| `dataverse_list_forms` | default | 列出一个表的表单，可选表单类型过滤 |
| `dataverse_get_form` | default | 获取表单的布局为tabs → sections → controls树 |
| `dataverse_validate_formxml` | default | 验证FormXml对抗XSD；传递 `formxml` 进行干预 |
| `dataverse_set_formxml` | write | 替换并发布表单的FormXml；返回 `formxml_backup` 以恢复 |
| `dataverse_add_form_control` | write | 向表单添加列控件（自动解析classid） |
| `dataverse_remove_form_control` | write | 通过逻辑名称删除列控件 |
### 视图
| 工具 | Gate | 描述 |
|------|------|-------------|
| `dataverse_list_views` | default | 列出一个表的保存视图（savedquery），可选查询类型过滤 |
| `dataverse_get_view` | default | 获取视图的FetchXml、LayoutXml和列列表 |
| `dataverse_validate_view` | default | 验证视图的FetchXml和LayoutXml |
| `dataverse_create_view` | write | 创建一个保存视图，带有FetchXml和LayoutXml |
| `dataverse_update_view` | write | 更新视图的FetchXml、LayoutXml、名称或描述 |
| `dataverse_add_view_column` | write | 向视图的LayoutXml添加列 |
| `dataverse_remove_view_column` | write | 从视图的LayoutXml中删除列 |
### 模型驱动的应用
| 工具 | Gate | 描述 |
|------|------|-------------|
| `dataverse_list_apps` | default | 列出应用；`include_unpublished=true` 包括草稿 |
| `dataverse_get_app` | default | 获取应用的属性和按类型分组的组件 |
| `dataverse_validate_app` | default | 通过 `ValidateApp` 验证应用（显示缺少的站点地图等） |
| `dataverse_create_app` | write | 创建应用（站点地图、组件、验证、发布） |
| `dataverse_update_app` | write | 更新应用的名称或描述 |
| `dataverse_add_app_components` | write | 向应用添加表、表单、视图、图表或BPF |
| `dataverse_remove_app_components` | write | 从应用中删除组件 |
| `dataverse_set_app_sitemap` | write | 创建或替换应用的导航站点地图 |
| `dataverse_publish_app` | write | 发布应用以使其对用户可见 |
| `dataverse_assign_app_role` | write | 关联或取消关联安全角色与应用 |
### 连接引用
| 工具 | Gate | 描述 |
|------|------|-------------|
| `dataverse_list_connection_references` | default | 列出连接引用，可选连接器/状态/OData过滤 |
| `dataverse_get_connection_reference` | default | 通过GUID或逻辑名称获取一个 |
| `dataverse_create_connection_reference` | write | 创建一个，可选连接和解决方案关联 |
| `dataverse_update_connection_reference` | write | 赋值/清除连接，更新字段，或与解决方案关联 |
| `dataverse_delete_connection_reference` | delete | 删除一个非托管连接引用 |
### 环境变量 - 定义
| 工具 | Gate | 描述 |
|------|------|-------------|
| `dataverse_get_environment_variables` | default | 列出定义与当前值；可选解决方案过滤或单个记录名称查找（架构名称/显示名称） |
| `dataverse_create_environment_variable` | write | 创建定义和可选初始值 |
| `dataverse_update_environment_variable` | write | 更新定义字段和/或更新当前值 |
| `dataverse_delete_environment_variable` | delete | 删除定义、值记录或两者 |
### 环境变量 - 值
| 工具 | Gate | 描述 |
|------|------|-------------|
| `dataverse_get_environment_variable_values` | default | 通过值GUID、定义GUID或定义名称获取值记录 |
| `dataverse_create_environment_variable_value` | write | 创建一个绑定到定义的值记录（通过GUID或名称） |
| `dataverse_update_environment_variable_value` | write | PATCH 现有值记录通过值GUID、定义GUID或定义名称 |
| `dataverse_delete_environment_variable_value` | delete | 仅删除值记录（重置为默认值）通过值GUID、定义GUID或定义名称 |
### 插件注册
| 工具 | 网关 | 描述 |
|------|------|-------------|
| `dataverse_list_plugin_assemblies` | 默认 | 列出已注册的插件程序集 |
| `dataverse_get_plugin_assembly` | 默认 | 获取一个插件程序集 |
| `dataverse_list_plugin_packages` | 默认 | 列出 NuGet 插件包 |
| `dataverse_get_plugin_package` | 默认 | 获取一个插件包 |
| `dataverse_list_plugin_types` | 默认 | 列出程序集中的插件类型（类） |
| `dataverse_get_plugin_type` | 默认 | 获取一个插件类型 |
| `dataverse_list_plugin_steps` | 默认 | 列出 SDK 消息处理步骤注册 |
| `dataverse_get_plugin_step` | 默认 | 获取一个处理步骤 |
| `dataverse_list_plugin_step_images` | 默认 | 列出步骤的预/后实体映像 |
| `dataverse_get_plugin_step_image` | 默认 | 获取一个步骤映像 |
| `dataverse_list_sdk_messages` | 默认 | 列出 SDK 消息（创建、更新、...）- 引用 |
| `dataverse_get_sdk_message` | 默认 | 获取一个 SDK 消息 |
| `dataverse_list_sdk_message_filters` | 默认 | 列出 SDK 消息过滤器（消息/实体组合）- 引用 |
| `dataverse_get_sdk_message_filter` | 默认 | 获取一个 SDK 消息过滤器 |
| `dataverse_create_plugin_assembly` | 写入 | 注册一个插件程序集 |
| `dataverse_update_plugin_assembly` | 写入 | 更新一个插件程序集 |
| `dataverse_create_plugin_package` | 写入 | 注册一个插件包 |
| `dataverse_update_plugin_package` | 写入 | 更新一个插件包 |
| `dataverse_create_plugin_type` | 写入 | 注册一个插件类型 |
| `dataverse_update_plugin_type` | 写入 | 更新一个插件类型 |
| `dataverse_create_plugin_step` | 写入 | 注册一个 SDK 消息处理步骤 |
| `dataverse_update_plugin_step` | 写入 | 更新一个处理步骤 |
| `dataverse_create_plugin_step_image` | 写入 | 注册一个步骤映像 |
| `dataverse_update_plugin_step_image` | 写入 | 更新一个步骤映像 |
| `dataverse_delete_plugin_assembly` | 删除 | 删除一个插件程序集 |
| `dataverse_delete_plugin_package` | 删除 | 删除一个插件包 |
| `dataverse_delete_plugin_type` | 删除 | 删除一个插件类型 |
| `dataverse_delete_plugin_step` | 删除 | 删除一个处理步骤 |
| `dataverse_delete_plugin_step_image` | 删除 | 删除一个步骤映像 |
### 插件跟踪和统计
| 工具 | 网关 | 描述 |
|------|------|-------------|
| `dataverse_list_plugin_type_statistics` | 默认 | 每个插件类型的运行时性能统计（执行次数、失败率、崩溃） |
| `dataverse_get_plugin_trace_log_setting` | 默认 | 获取整个组织的跟踪日志详细程度（关闭/异常/全部） |
| `dataverse_list_plugin_trace_logs` | 默认 | 列出带有过滤器的跟踪日志（类、消息、实体、操作、仅错误、时间窗口） |
| `dataverse_set_plugin_trace_log_setting` | 写入 | 设置整个组织的跟踪日志详细程度（`关闭`、`异常`、`全部`） |
### 自定义 API
| 工具 | 网关 | 描述 |
|------|------|-------------|
| `dataverse_list_custom_apis` | 默认 | 列出自定义 API，可选过滤器和分页 |
| `dataverse_get_custom_api` | 默认 | 获取一个自定义 API，包含其请求参数和响应属性 |
| `dataverse_create_custom_api` | 写入 | 创建一个自定义 API（无绑定、实体绑定或实体集合绑定） |
| `dataverse_update_custom_api` | 写入 | 更新自定义 API 的可变字段（显示名称、描述、可见性、允许的步骤类型） |
| `dataverse_delete_custom_api` | 删除 | 永久删除一个自定义 API 及其子参数和属性 |
| `dataverse_list_custom_api_request_parameters` | 默认 | 列出自定义 API 的请求参数 |
| `dataverse_create_custom_api_request_parameter` | 写入 | 向自定义 API 添加一个类型化的请求参数 |
| `dataverse_update_custom_api_request_parameter` | 写入 | 更新请求参数的可变字段 |
| `dataverse_delete_custom_api_request_parameter` | 删除 | 删除一个请求参数 |
| `dataverse_list_custom_api_response_properties` | 默认 | 列出自定义 API 的响应属性 |
| `dataverse_create_custom_api_response_property` | 写入 | 向自定义 API 添加一个类型化的响应属性 |
| `dataverse_update_custom_api_response_property` | 写入 | 更新响应属性的可变字段 |
| `dataverse_delete_custom_api_response_property` | 删除 | 删除一个响应属性 |
---
## 开发
```bash
# 安装依赖
uv sync
# 运行 MCP 检查器（交互式测试）
uv run mcp dev src/dataverse_mcp/server.py
# 直接运行服务器
uv run python -m dataverse_mcp.server
# 编译检查
uv run python -m py_compile src/dataverse_mcp/server.py
```
在 VS Code 中重启 MCP 服务器以获取新的源代码。
---
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器