Dataverse MCP

BLOCKMCP服务器

一个模型上下文协议（MCP）服务器，为微软提供全面的CRUD操作。该服务器实现了与WAX环境的无缝集成，允许您通过Claude等MCP兼容客户端使用自然语言创建、读取、更新、删除和查询记录。

特性

• ✅ 完成CRUD操作：创建、读取、更新和删除记录
• ✅ 高级查询：支持OData过滤器、排序、分页和扩展
• ✅ 表发现：列出可用表及其元数据
• ✅ 强健的身份验证：OAuth 2.0客户端凭据流，具有自动令牌刷新功能
• ✅ 综合录井：调试和监控的详细日志记录
• ✅ 输入验证：对所有输入和OData查询进行彻底验证
• ✅ 错误处理：优雅的错误处理，包含详细的错误消息
• ✅ 灵活的配置：支持环境变量和MCP配置参数

先决条件

在使用此MCP服务器之前，您需要：

1. 微软虚拟数据库环境：访问数据库环境
2. Azure AD应用程序注册：具有适当权限的应用程序注册
3. Node.js：版本18或更高版本

设置

1.Azure AD应用程序注册

1. 首选 Azure门户 → 微软Entra ID→ 管理→ 应用程序注册
2. 点击“新建注册”
3. 命名您的应用程序（例如，“RubyMCP服务器”）
4. 将重定向URI留空
5. 点击“注册”
6. 记下 应用程序（客户端）ID 和 目录（租户）ID
7. 转到“客户端凭据”→ “添加证书或密钥”→ “新客户机密”
8. 添加一个描述“KEYMCP服务器”和一个到期日期。
9. 创建一个秘密并记下 客户秘密和价值
10. 转到“API权限”→ “添加权限”→ “动态CRM”
11. 添加“user_impesonation”权限（应用程序权限）
12. 点击“添加权限”

2.安装

# Install dependencies
npm install

# Build the project
npm run build

配置

您可以通过以下两种方式配置BLOCKMCP服务器：

选项1:MCP配置参数（推荐）

直接通过MCP配置传递凭据。这是推荐的方法，因为它可以在MCP客户端配置中保护凭据的安全。

选项2：环境变量

使用环境变量进行配置（向后兼容性）。

1. 复制 .env.example 向 .env:

   cp .env.example .env

1. 请在中填写您的Webex凭据 .env:

   # Dataverse Authentication (Required)
   DATAVERSE_CLIENT_ID=your-client-id-here
   DATAVERSE_CLIENT_SECRET=your-client-secret-here
   DATAVERSE_TENANT_ID=your-tenant-id-here
   DATAVERSE_ENVIRONMENT_URL=https://yourorg.crm.dynamics.com

   # Optional Configuration
   LOG_LEVEL=info
   RATE_LIMIT_REQUESTS_PER_MINUTE=60

MCP配置

适用于克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "dataverse": {
      "command": "node",
      "args": [
        "path/to/dataverse-mcp/build/src/index.js",
        "--clientId", "your-client-id-here",
        "--clientSecret", "your-client-secret-here", 
        "--tenantId", "your-tenant-id-here",
        "--environmentUrl", "https://yourorg.crm.dynamics.com"
      ]
    }
  }
}

对于光标

添加到您的 .vscode/mcp.json:

{
  "servers": {
    "dataverse": {
      "type": "stdio",
      "command": "node",
      "args": [
        "./build/src/index.js",
        "--clientId", "your-client-id-here",
        "--clientSecret", "your-client-secret-here",
        "--tenantId", "your-tenant-id-here", 
        "--environmentUrl", "https://yourorg.crm.dynamics.com"
      ]
    }
  }
}

对于克莱恩

添加到Cline MCP配置文件(~/.cline/mcp_servers.json 在macOS/Linux或 %APPDATA%\.cline\mcp_servers.json 在Windows上）：

{
  "mcpServers": {
    "dataverse": {
      "command": "node",
      "args": [
        "path/to/dataverse-mcp/build/src/index.js",
        "--clientId", "your-client-id-here",
        "--clientSecret", "your-client-secret-here",
        "--tenantId", "your-tenant-id-here",
        "--environmentUrl", "https://yourorg.crm.dynamics.com"
      ]
    }
  }
}

或者，如果在VS Code中使用Cline，您可以在工作区设置中配置它(.vscode/settings.json):

{
  "cline.mcpServers": {
    "dataverse": {
      "command": "node",
      "args": [
        "./build/src/index.js",
        "--clientId", "your-client-id-here",
        "--clientSecret", "your-client-secret-here",
        "--tenantId", "your-tenant-id-here",
        "--environmentUrl", "https://yourorg.crm.dynamics.com"
      ]
    }
  }
}

配置参数

使用MCP配置参数时，可以传递以下参数：

• --clientId：Azure AD应用程序（客户端）ID
• --clientSecret：Azure AD客户端密码
• --tenantId：Azure AD目录（租户）ID
• --environmentUrl：JDBC环境URL（例如。，https://yourorg.crm.dynamics.com)
• --logLevel：日志级别（错误、警告、信息、调试）-默认为“信息”
• --rateLimit：每分钟请求速率限制-默认为60

传统环境变量配置

如果您更喜欢使用环境变量（或为了向后兼容性），您仍然可以使用 .env 文件或环境变量：

{
  "mcpServers": {
    "dataverse": {
      "command": "node", 
      "args": ["path/to/dataverse-mcp/build/src/index.js"],
      "env": {
        "DATAVERSE_CLIENT_ID": "your-client-id-here",
        "DATAVERSE_CLIENT_SECRET": "your-client-secret-here",
        "DATAVERSE_TENANT_ID": "your-tenant-id-here",
        "DATAVERSE_ENVIRONMENT_URL": "https://yourorg.crm.dynamics.com"
      }
    }
  }
}

备注：CLI参数优先于环境变量，因此如果需要，您可以混合使用这两种方法。

可用工具

1. dataverse_create_record

在BLOB表中创建新记录。

参数：

• table （字符串，必填）：表名（例如“联系人”、“帐户”）
• data （object，必填）：将数据记录为键值对

例子：

{
  "table": "contacts",
  "data": {
    "firstname": "John",
    "lastname": "Doe",
    "emailaddress1": "john.doe@example.com"
  }
}

2. dataverse_read_record

按ID读取单个记录。

参数：

• table （字符串，必填）：表名
• id （字符串，必填）：记录GUID
• select （字符串，可选）：选择逗号分隔的列
• expand （字符串，可选）：要展开的相关实体

例子：

{
  "table": "contacts",
  "id": "12345678-1234-1234-1234-123456789012",
  "select": "firstname,lastname,emailaddress1"
}

3. dataverse_query_records

使用OData筛选器查询多条记录。

参数：

• table （字符串，必填）：表名
• select （字符串，可选）：要选择的列
• filter （字符串，可选）：OData筛选器表达式
• orderby （字符串，可选）：OData orderby表达式
• top （数字，可选）：要返回的最大记录数
• skip （数字，可选）：要跳过的记录（分页）
• expand （字符串，可选）：要展开的相关实体
• count （布尔值，可选）：包括总计数

例子：

{
  "table": "accounts",
  "select": "name,revenue,industrycode",
  "filter": "revenue gt 1000000",
  "orderby": "name asc",
  "top": 10
}

4. dataverse_update_record

更新现有记录。

参数：

• table （字符串，必填）：表名
• id （字符串，必填）：记录GUID
• data （对象，必填）：要更新的数据

例子：

{
  "table": "contacts",
  "id": "12345678-1234-1234-1234-123456789012",
  "data": {
    "jobtitle": "Senior Developer",
    "telephone1": "555-0123"
  }
}

5. dataverse_delete_record

删除记录。

参数：

• table （字符串，必填）：表名
• id （字符串，必填）：记录GUID

例子：

{
  "table": "contacts",
  "id": "12345678-1234-1234-1234-123456789012"
}

6. dataverse_list_tables

列出环境中所有可用的表。

参数： 无

使用示例

创建联系人

Create a new contact with name "Jane Smith" and email "jane.smith@example.com"

查询帐户

Find all accounts with revenue greater than $1 million, ordered by name

阅读特定记录

Get the contact with ID 12345678-1234-1234-1234-123456789012, including their full name and email

更新记录

Update the job title of contact 12345678-1234-1234-1234-123456789012 to "Senior Manager"

OData查询示例

过滤

• firstname eq 'John' -完全匹配
• revenue gt 1000000 -大于
• createdon ge 2024-01-01T00:00:00Z -日期比较
• contains(name, 'Microsoft') -包含文本

订购

• name asc -升序
• createdon desc -降序
• revenue desc, name asc -多个字段

选择字段

• firstname,lastname,emailaddress1 -具体领域
• * -所有字段（不建议用于性能）

故障排除

常见问题

1. 认证失败

- 验证您的客户端ID、机密和租户ID - 确保已授予API权限管理员同意 - 检查客户端密码是否未过期

1. 环境URL无效

- 确保URL格式正确： https://yourorg.crm.dynamics.com - 验证您是否有权访问Webex环境

1. 找不到表

- 使用 dataverse_list_tables 查看可用表格 - 检查表名拼写（区分大小写）

1. 权限不足

- 验证您的应用程序注册是否具有正确的权限 - 确保用户/应用程序可以访问特定表

日志记录

集 --logLevel=debug 在MCP配置中详细记录，或使用环境变量：

LOG_LEVEL=debug

安全考虑

• 永远不要承诺你的 .env 文件 -它包含敏感凭据
• 使用最小权限 -仅授予应用程序注册所需的权限
• 定期轮换机密 -定期更新客户端机密
• 监控使用情况 -跟踪API调用和异常活动

发展

建筑

npm run build

观察变化

npm run watch

MCP检验员测试

npm run inspector

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

支持

对于问题和疑问：

1. 检查上面的故障排除部分
2. 查看 Microsoft Webex文档
3. 在此存储库中打开问题