Mcp Dataverse

MCP Dataverse

---

---

为什么选择 MCP Dataverse？

AI Agent 会臆造架构、猜测列名，还会构建错误的 OData 查询。此服务通过 Model Context Protocol，让它们能够实时访问你的 Dataverse 环境，包括架构、记录、元数据和解决方案。

• 三种身份验证模式——设备代码（本地）、客户端凭据（CI/CD）、托管标识（Azure 托管）
• 兼容任何 MCP 客户端——VS Code、Claude、Cursor、Windsurf、Gemini、Codex CLI
• 原子化工具——每个工具专注做好一件事；由 AI 选择合适的工具
• 结构化输出——每个响应都会以文本和 MCP structuredContent 的形式返回 {summary, data, suggestions}（所有核心工具均声明了 outputSchema）
• 安全护栏——每个工具都会声明只读或破坏性提示；风险最高的操作需要显式设置 confirm: true
• 加密令牌缓存——使用 AES-256-GCM 缓存凭据，避免出现在工具输出中

---

安装

npx mcp-dataverse install

交互式向导会配置你的环境、在 VS Code 中注册服务，并在 2 分钟内完成 Microsoft 账户身份验证。

需要 Node.js 20+。其他客户端（Claude、Cursor、Windsurf……）的配置方法请参阅多客户端配置。

更新

npx mcp-dataverse update

无需重新配置——向导只会检查现有设置并显示更改内容。npx 会在每次运行时自动获取最新版本，因此只需重启 MCP 客户端即可使用新工具。

---

身份验证

共有三种模式，可根据服务的运行位置选择：

模式	适用场景
设备代码（默认）	本地开发——交互式 Microsoft 登录，令牌缓存在磁盘上
客户端凭据	无人值守场景：CI/CD、Docker、Azure 服务——authMethod: "client-credentials" + 应用注册
托管标识	Azure 托管环境（App Service、Container Apps）——无需密钥，使用 authMethod: "managed-identity"

**设备代码快速入门：**首次调用工具时会触发身份验证。

1. 打开 View → Output → MCP——屏幕上会显示登录代码
2. 前往 https://microsoft.com/devicelogin，输入代码，并使用工作账户登录
3. 令牌会以加密形式缓存，之后每次启动都无需操作

客户端凭据和托管标识的配置方法，请参阅身份验证文档。

---

功能

类别	数量	描述
元数据	9	表、架构、关系、选项集、实体键
查询	3	OData、FetchXML、分页检索
CRUD	6	获取、创建、更新、删除、更新或插入、分配
关系	4	关联、批量关联、取消关联、查询关联
操作与函数	6	已绑定和未绑定的 Dataverse 操作与函数
批处理	1	以原子方式执行最多 1000 项操作
解决方案	2	发布自定义项、创建站点地图
搜索	1	全文相关性搜索
用户与团队	4	用户、角色、团队、角色分配
RBAC	7	角色权限：列出、分配、移除、添加、替换、获取、团队
文件	2	上传/下载文件和图像列
审计与跟踪	3	审计日志、插件跟踪日志、工作流跟踪日志
批注	2	备注和文件附件
自定义	4	自定义操作、插件、环境变量、连接引用
属性	4	创建、更新、删除列；查找列类型
架构（写入）	2	创建自定义表和关系
记录访问权限	4	检查、授予、撤销记录共享权限；合并记录
辅助功能	2	工具路由器、工具标签
+ 更多	…	增量同步、模拟身份、视图、业务部门、重复检测

→ 完整功能参考

---

HTTP 传输

以 HTTP 服务的形式运行，以供多个客户端使用：

MCP_TRANSPORT=http MCP_HTTP_PORT=3000 MCP_HTTP_SECRET=mysecret node dist/server.js

环境变量	默认值	描述
MCP_TRANSPORT	stdio	http 启用 HTTP 传输
MCP_HTTP_PORT	3000	监听端口（/mcp 端点，/health 探测端点）
MCP_HTTP_SECRET / BEARER_TOKEN	—	用于入站身份验证的静态 bearer 令牌
ENTRA_TENANT_ID + ENTRA_CLIENT_ID	—	将入站令牌验证为 Entra v2.0 JWT（自动启用 RFC 9728 发现）
MCP_HTTP_SESSION_TTL_MS	1800000	空闲会话逐出超时（30 分钟；0 表示禁用）
MCP_HTTP_REQUIRE_AUTH	—	true = 未配置入站身份验证时拒绝启动
MCP_HTTP_CORS_ORIGIN	*	允许的 CORS 来源 — 部署到托管环境时请限制此项
MCP_HTTP_JSON_RESPONSE	true	JSON 响应（false = SSE 流式传输）

使用 VS Code / Copilot 连接：

{
  "servers": {
    "dataverse": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer mysecret"
      }
    }
  }
}

---

故障排除

症状	解决方法
未显示登录提示	打开 视图 → 输出 → MCP — 设备代码会显示在那里
No MSAL accounts found	运行 npx mcp-dataverse-auth，然后重启服务
Authentication timed out	重启 MCP 服务 — 系统会自动生成新的代码
Agent 模式下未显示服务	运行 npx mcp-dataverse install 或 npx mcp-dataverse doctor
HTTP 错误	运行 npx mcp-dataverse doctor 以诊断配置和连接问题

---

性能提示

MCP Dataverse 的设计力求全面，但大多数 AI 模型在上下文中使用较少的工具时效果最佳。请在客户端的工具选择器（例如 VS Code 聊天面板）中取消选择不需要的工具，让 Agent 保持专注并快速响应。

---

路线图

版本	功能	状态
v0.4	HTTP 传输 + 属性管理 + 架构一致性	✅ 已发布
v0.5	企业身份验证（客户端凭据、托管标识、Entra JWT）	✅ 已发布
v0.6	MCP 提示词（5 个模板）+ MCP 资源（4 个）	✅ 已发布
v0.7	架构写入（创建表/关系）+ 记录访问（共享、合并）	✅ 已发布（v0.7.5）

→ 完整路线图

---

许可证

MIT © Ali Taggaz