Azure权限MCP服务器
Azure权限的模型上下文协议（MCP）服务器-使用AI轻松管理您的数据目录
将您的AI助手连接到Azure权限，以搜索、读取和更新数据目录元数据，包括表和列描述。
⚠️ 重要通知
仅供开发使用：此MCP服务器仅供您组织内的开发人员使用。请勿将这些工具用于批准的开发环境之外的外部应用程序或场景。
需要用户同意：所有访问或修改数据的工具都需要明确的用户授权和同意。在批准之前，用户必须了解正在访问哪些数据以及正在采取哪些行动。
生产注意事项：对于生产部署，请根据组织的安全策略实施额外的安全控制、审核日志记录和适当的访问限制。
快速开始
# 1. Login to Azure
az login
# 2. Install and build
npm install && npm run build
# 3. Create .env file
cat > .env << EOF
PURVIEW_ENDPOINT=https://your-purview-account.purview.azure.com
AUTH_METHOD=cli
EOF
# 4. Add to Claude Desktop config
# Edit: ~/Library/Application Support/Claude/claude_desktop_config.json{
"mcpServers": {
"purview": {
"command": "node",
"args": ["/absolute/path/to/purview-mcp-server/dist/index.js"],
"env": {
"PURVIEW_ENDPOINT": "https://your-purview-account.purview.azure.com",
"AUTH_METHOD": "cli"
}
}
}
}就是这样！重新启动Claude Desktop并开始使用权限。
看 QUICKSTART.md 了解详细的分步说明。
特性
✅ 搜索与发现 -在权限目录中查找表、列和资源 ✅ 读取元数据 -通过GUID或限定名获取详细信息 ✅ 更新说明 -修改表和列描述（userDescription字段） ✅ 批量操作 -从CSV或JSON文件上传描述 ✅ 智能重试逻辑 -失败请求的自动指数回退 ✅ 灵活的身份验证 -Azure CLI（最简单）、交互式浏览器或服务主体
先决条件
- Node.js 18岁或以上
- Azure命令行界面 已安装(安装指南)
- Azure权限 具有访问权限的帐户
- 权限权限 -您的帐户需要“数据管理员”角色
认证
选项1:Azure CLI（推荐）🎯
最简单的方法-使用您现有的Azure登录！
az login配置：
PURVIEW_ENDPOINT=https://your-account.purview.azure.com
AUTH_METHOD=cli✅ 无需服务负责人 ✅ 没有秘密需要管理 ✅ 使用您的Azure帐户
选项2：交互式浏览器
首次使用时打开浏览器进行身份验证。
配置：
PURVIEW_ENDPOINT=https://your-account.purview.azure.com
AUTH_METHOD=interactive
AZURE_TENANT_ID=your-tenant-id # Optional选项3：服务负责人
用于生产部署和自动化。
# Create service principal
az ad sp create-for-rbac --name "purview-mcp-sp" --role Contributor配置：
PURVIEW_ENDPOINT=https://your-account.purview.azure.com
AUTH_METHOD=service-principal
AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret重要提示： 在权限中为服务主体分配“数据管理员”角色：
- Azure 门户→ 权限帐户→ 数据平面访问
- 添加角色分配→ 数据管理员→ 选择您的服务负责人
安装
# Clone or download this repository
cd purview-mcp-server
# Install dependencies
npm install
# Build the project
npm run build
# Test it (optional)
npm run dev配置
创建.env文件
cp .env.example .env使用您的设置编辑.env
最低配置（Azure CLI）：
PURVIEW_ENDPOINT=https://your-purview-account.purview.azure.com
AUTH_METHOD=cli所有选项：
# Required
PURVIEW_ENDPOINT=https://your-purview-account.purview.azure.com
# Authentication (choose one)
AUTH_METHOD=cli # Default: Azure CLI
# AUTH_METHOD=interactive # Browser login
# AUTH_METHOD=service-principal # Service Principal
# Only for service-principal auth
# AZURE_TENANT_ID=your-tenant-id
# AZURE_CLIENT_ID=your-client-id
# AZURE_CLIENT_SECRET=your-client-secret
# Optional
LOG_LEVEL=infoMCP客户端设置
克劳德桌面
macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"purview": {
"command": "node",
"args": ["/absolute/path/to/purview-mcp-server/dist/index.js"],
"env": {
"PURVIEW_ENDPOINT": "https://your-account.purview.azure.com",
"AUTH_METHOD": "cli"
}
}
}
}⚠️ 重要提示：
- 使用 绝对路径 给你的
dist/index.js文件 - 跑
az login启动Claude Desktop之前 - 配置更改后重新启动Claude Desktop
可用工具
🔍 搜索实体
在权限目录中搜索资产。
参数：
keywords（必填）-搜索词entityType（可选）-按类型筛选（例如，“azure_sql_table”、“azure_sql_column”）limit（可选）-最大结果（默认值：50）
Claude中的示例用法：
Search for all tables containing "customer" in Purview📄 通过guid获取实体
通过GUID获取实体的详细元数据。
参数：
guid（必需）-实体GUID
例子：
Get metadata for Purview entity with GUID: abc123...📄 按限定名获取实体
按限定名获取详细的元数据。
参数：
qualifiedName（必填）-限定名称（例如，“mssql://server/db/schema/table")typeName（可选）-用于精确搜索的实体类型
例子：
Get metadata for table: mssql://myserver.database.windows.net/mydb/dbo/customers✏️ 更新描述
更新表或列的userDescription字段。
参数：
guid（必需）-实体GUIDdescription（必填）-新的描述文本（支持HTML）
例子：
Update the description for entity abc123 to "Customer master data table"📦 从csv批量更新
从CSV内容批量更新描述。
参数：
csvContent（必填）-CSV，带列：限定名称、名称、描述、类型名称、guiddryRun（可选）-默认值：true（无需更改即可验证）
CSV格式：
qualifiedName,name,description,typeName,guid
mssql://server/db/schema/table,Table,Table description,azure_sql_table,
mssql://server/db/schema/table#col1,Col1,Column description,azure_sql_column,例子：
Bulk update descriptions from this CSV:
[paste CSV content]
Set dryRun to false to apply changes.📦 从json批量更新
从JSON数组批量更新描述。
参数：
jsonContent（必填）-JSON实体更新数组dryRun（可选）-默认值：true
JSON格式：
[
{
"qualifiedName": "mssql://server/db/schema/table",
"typeName": "azure_sql_table",
"description": "Customer data table"
}
]用法示例
搜索和更新工作流
You: Search for tables with "sales" in the name
Claude: [Uses search-entities tool]
Found 5 tables with "sales":
1. SalesOrders (GUID: abc123...)
2. SalesCustomers (GUID: def456...)
...
You: Update the description for SalesOrders to "Main sales transaction table"
Claude: [Uses update-description tool with GUID abc123]
Successfully updated description!批量更新工作流
You: I have a CSV file with 100 table descriptions. Can you update them?
Claude: Please paste the CSV content.
You: [pastes CSV]
qualifiedName,name,description,typeName
mssql://server/db/dbo/Customers,Customers,Customer master data,azure_sql_table
...
Claude: [Uses bulk-update-from-csv with dryRun=true]
Validation results: Would update 100 entities. Ready to apply?
You: Yes, apply the changes
Claude: [Uses bulk-update-from-csv with dryRun=false]
Processed 100 entities: 98 successful, 2 failed关键概念
限定名称
权限实体的唯一标识符：
- Azure SQL表：
mssql://server.database.windows.net/database/schema/table - Azure SQL列：
mssql://server.database.windows.net/database/schema/table#columnName - 蜂巢表：
default.table_name@cluster
实体类型
权限中的常见类型：
azure_sql_table-Azure SQL表azure_sql_column-Azure SQL列azure_data_explorer_table-ADX桌子azure_data_explorer_column-ADX柱hive_table-Hive表hive_column-Hive列
描述字段
- 描述 -扫描生成的系统（只读）
- 用户描述 -用户提供的描述（这是更新的内容）
高级功能
重试逻辑
- 指数退避自动重试
- 检索网络错误、速率限制和服务器错误
- 最多3次重试尝试，延迟逐渐增加
批处理
- 批量操作每批处理50个实体
- 进度记录到控制台
- 单个故障不会停止批次
错误处理
- 详细的错误消息
- 收集和报告的更新失败
- 更改前的验证
故障排除
身份验证问题
Azure CLI身份验证：
# Check if logged in
az account show
# Re-login
az login
# Clear cache if needed
az account clear && az login验证权限权限：
- 转到Azure门户
- 导航到您的权限帐户
- 检查“数据平面访问”
- 确保你有“数据管理员”的角色
常见错误
“缺少必需的环境变量：PURVIEW_ENDPOINT”
- 创建
.env使用您的权限端点创建文件
“找不到实体”
- 首先使用搜索实体查找正确的限定名
- 验证实体是否存在于权限目录中
“身份验证失败”
- 对于CLI：运行
az login - 对于交互式：检查租户ID是否正确
- 对于服务主体：验证凭据和角色
服务器未出现在Claude中
- 在配置中使用绝对路径（不是相对路径）
- 检查Claude日志是否有错误
- 完全重新启动克劳德桌面
速率限制
如果达到速率限制：
- 减少批量操作中的批量大小
- 服务器自动重试并回退
- 增加大型操作之间的延迟
发展
# Run in development mode
npm run dev
# Build
npm run build
# Run built version
npm start
# Watch mode (auto-rebuild)
npm run watch项目结构
purview-mcp-server/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── config.ts # Configuration & auth settings
│ ├── purview/
│ │ ├── client.ts # Purview client with auth
│ │ ├── entities.ts # Entity CRUD operations
│ │ ├── search.ts # Search operations
│ │ └── bulk.ts # Bulk operations
│ ├── tools/
│ │ └── index.ts # MCP tool handlers
│ ├── utils/
│ │ ├── errors.ts # Error handling
│ │ ├── retry.ts # Retry logic
│ │ └── csv.ts # CSV parsing
│ └── types/
│ └── index.ts # TypeScript types
├── examples/
│ ├── sample-descriptions.csv
│ └── sample-descriptions.json
├── dist/ # Built JavaScript
├── .env # Your config (not in git)
├── .env.example # Template
├── package.json
├── tsconfig.json
├── README.md # This file
└── QUICKSTART.md # Quick start guide安全说明
- 永不承诺
.env文件到版本控制 - 使用Azure CLI身份验证进行开发
- 使用服务负责人进行生产，并进行适当的秘密管理
- 定期轮换服务主体机密
- 授予所需的最低权限（仅限数据管理员角色）
资源
重要文件
许可证
麻省理工学院
贡献
欢迎投稿！请打开问题或PR。
支持
对于问题或疑问：
- 检查 故障排除 章节
- 审查 QUICKSTART.md
- 在GitHub上打开一个问题：
- 错误消息 - 您的配置（编辑机密！） - 重现步骤
______________________________________________________________________
由以下材料制成❤️ 适用于Azure权限用户