Azure Kusto MCP 服务器

这是一个连接到 Azure Kusto 的模型上下文协议（MCP）服务器，使AI助手能够探索数据模式并执行KQL查询。

功能

• Azure Kusto 集成：安全地连接到 Azure Kusto 集群
• 模式探索：将表模式作为资源暴露给AI助手
• 查询执行：运行KQL查询和分析结果的工具
• 数据分析辅助：内置提示以完成常见的数据分析任务
• VS Code 集成：在VS Code中交互配置连接细节

要求

• Python 3.9+
• 对 Azure Kusto 集群的访问权限
• 安装了 GitHub Copilot 或 Copilot Chat 扩展的 VS Code（用于MCP支持）
• 必需的Python包（通过设置脚本自动安装）

快速设置（推荐）

使用VS Code集成设置MCP服务器最简单的方法：

python setup-mcp.py

此脚本将：

1. 安装所有必需的依赖项
2. 创建必要的VS Code集成配置
3. 提供启动服务器的说明

手动安装

1. 克隆仓库：

git clone https://github.com/yourusername/kusto-mcp-server.git
cd kusto-mcp-server

2. 安装所需的依赖项：

pip install -r requirements.txt

3. （可选）配置环境变量： 在根目录下创建一个.env文件，并添加以下变量：

AZURE_KUSTO_CLUSTER=https://<your-cluster>.kusto.windows.net
AZURE_KUSTO_DATABASE=<your-database>

创建 mcp.json 配置文件

mcp.json 文件是配置MCP服务器与VS Code集成所必需的。如果你手动设置或设置脚本没有创建这个文件，请按照以下步骤操作：

1. 在工作区的.vscode目录下创建一个名为mcp.json的新文件（如果该目录不存在，请创建它）
2. 向文件中添加以下内容：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "kusto-cluster",
      "description": "Azure Kusto 集群URL（例如，https://mycluster.kusto.windows.net）",
      "default": ""
    },
    {
      "type": "promptString",
      "id": "kusto-database",
      "description": "Azure Kusto 数据库名称",
      "default": ""
    }
  ],
  "servers": {
    "Azure Kusto MCP": {
      "type": "stdio",
      "command": "${command:python.interpreterPath}",
      "args": ["${workspaceFolder}/src/kusto_mcp/server.py"],
      "env": {
        "AZURE_KUSTO_CLUSTER": "${input:kusto-cluster}",
        "AZURE_KUSTO_DATABASE": "${input:kusto-database}",
        "PYTHONPATH": "${workspaceFolder}"
      }
    }
  }
}

3. 如果需要，自定义配置：
   • 如果你需要使用特定的Python解释器路径，请更改command
   • 如果你的服务器脚本位于其他位置，请修改args
   • 如有需要，添加额外的环境变量
   • 注意${workspaceFolder}和${command:python.interpreterPath}是VS Code变量，会被自动替换为相应的路径

此配置包括每次启动服务器时都会询问的输入提示，使得切换不同的数据库变得容易。

VS Code 集成

要在VS Code中使用MCP服务器：

1. 确保你已经运行了设置脚本：python setup-mcp.py 或者手动创建了mcp.json文件
2. 在VS Code中安装GitHub Copilot或Copilot Chat扩展
3. 打开命令面板（Ctrl+Shift+P）
4. 运行"MCP: 使用配置启动服务器"
5. 从列表中选择"Azure Kusto MCP"
6. 当提示时，输入你的Kusto集群URL和数据库名称

MCP服务器将启动并与你的Copilot Chat会话连接，允许你：

• 使用connect工具连接到Kusto集群
• 浏览表模式
• 执行查询
• 分析数据

不使用VS Code运行服务器

直接启动MCP服务器：

python -m src.kusto_mcp.server

如果你还没有在.env文件中配置连接，服务器将在需要时提示你输入连接详情。

认证

此服务器使用Azure的DefaultAzureCredential进行认证，支持：

1. 环境变量
2. 管理身份
3. Azure CLI凭证
4. Azure PowerShell凭证
5. 作为备用方案的交互式浏览器认证

确保你在连接前至少使用其中一种方法进行认证。

资源类型

服务器公开以下资源：

• kusto/tables - 当前数据库中的所有表列表
• kusto/schema/{table_name} - 特定表的模式
• kusto/sample - 示例KQL查询及其解释
• kusto/connection - 当前连接信息

工具

提供以下工具：

• connect - 连接到Azure Kusto集群和数据库
• connection_status - 检查当前连接状态
• execute_query - 运行KQL查询
• analyze_data - 执行查询并分析结果
• optimize_query - 获取查询优化建议

工具使用指南

Kusto MCP服务器提供了多个工具来与Azure Kusto交互。以下是每个工具的有效使用方法：

Connect 工具

connect工具建立到Azure Kusto集群和数据库的连接。

在Copilot Chat中的用法：

我需要连接到我的Kusto集群

此工具将提示你输入：

• 集群URL（例如，https://yourcluster.kusto.windows.net）
• 数据库名称

认证通过Azure的DefaultAzureCredential自动处理。

示例：

连接到名为"MyDatabase"的Kusto数据库，在集群"analytics.kusto.windows.net"上

Connection Status 工具

connection_status工具显示当前连接详情。

在Copilot Chat中的用法：

检查我当前的Kusto连接

示例输出：

✅ 已连接到Azure Kusto。
        
- **集群**：https://analytics.kusto.windows.net
- **数据库**：MyDatabase

Execute Query 工具

execute_query工具针对已连接的数据库运行KQL查询。

在Copilot Chat中的用法：

运行这个KQL查询：<你的查询在这里>

示例：

运行这个KQL查询：StormEvents | where State == "FLORIDA" | take 10

对于大型结果集（>100行），工具将返回摘要和前10行。

Analyze Data 工具

analyze_data工具执行查询并对结果进行分析。

在Copilot Chat中的用法：

分析这个查询：<你的查询在这里>

你可以指定分析类型：

• summary（默认）：关于数据的基本统计
• stats：详细的统计分析，包括相关性
• plot_ready：帮助可视化数据的信息

示例：

使用stats分析类型分析这个查询：StormEvents | summarize count() by State | top 10 by count_

Optimize Query 工具

optimize_query工具提供改进KQL查询的建议。

在Copilot Chat中的用法：

优化这个KQL查询：<你的查询在这里>

示例：

优化这个KQL查询：
StormEvents
| project *
| where StartTime > ago(7d)
| sort by StartTime desc

高级使用场景

探索表模式

要探索可用的表及其模式：

这个数据库中有哪些表？

要查看特定表的模式：

展示StormEvents表的模式

时间序列分析

对于基于时间的数据分析：

帮我分析StormEvents表中StartTime列的时间趋势

相关性分析

查找列之间的关系：

在StormEvents表中查找DamageProperty和DeathsDirect之间的相关性

数据质量检查

验证数据质量：

检查StormEvents表中的空值和异常值

查询构建逐步指导

对于复杂的查询，你可以请求指导：

我需要构建一个按州显示风暴事件的查询，包含损害金额，并限制为最昂贵的前10个事件。你能帮我构建吗？

最佳实践

1. 始终先连接：在尝试运行查询之前使用connect工具
2. 验证连接：如果你不确定连接状态，使用connection_status工具
3. 从小查询开始：使用take或limit操作符测试查询，然后再在大数据集上运行
4. 使用分析工具：analyze_data工具可以轻松提供有价值的见解
5. 请求优化：对于长时间运行或复杂的查询，使用optimize_query工具

KQL 查询示例

这里有一些KQL查询示例，帮助你入门：

// 简单过滤
StormEvents 
| where State == "FLORIDA" 
| take 10

// 聚合
StormEvents
| summarize EventCount=count() by State
| order by EventCount desc
| take 10

// 时间过滤
StormEvents
| where StartTime > ago(30d)
| summarize EventCount=count() by bin(StartTime, 1d)
| render timechart

// 联接示例
StormEvents
| where EventType == "Tornado"
| join (
    StormEvents 
    | where EventType == "Flood"
    | project State, FloodTime=StartTime
) on State
| project State, TornadoTime=StartTime, FloodTime
| take 10

解决MCP配置问题

如果你遇到MCP配置问题：

1. 缺少mcp.json：如上所述，在.vscode目录下手动创建文件
2. 配置未显示：确保mcp.json文件格式正确且位于.vscode目录下
3. 服务器无法连接：检查mcp.json文件中指定的主机名和端口是否可用
4. Copilot未检测到服务器：在创建或修改mcp.json文件后重启VS Code

常见问题的解决方法

除了前面提到的一般故障排除技巧外，这里还有一些特定工具问题的具体解决方案：

Connect 工具问题

• 错误："连接失败"：验证你的Azure凭据有效且你有权访问指定的集群和数据库
• 超时错误：检查网络连接和防火墙设置
• 认证失败：确保你已使用az login登录Azure或具有有效的环境凭据

查询执行问题

• 大型查询超时：添加过滤器或时间约束以减少数据量
• 语法错误：使用optimize_query工具检查并修复查询语法
• 缺失列：在查询之前使用模式探索验证列名

数据分析问题

• 空分析结果：确保查询返回数据后再进行分析
• 相关性错误：检查数据中至少包含两个数值列以进行相关性分析
• 可视化准备：对于plot_ready分析，包括分类和数值列以获得最佳效果

与AI助手的使用

此MCP服务器旨在与支持模型上下文协议的AI助手一起使用。服务器提供了对Azure Kusto数据的结构化访问，使AI助手能够：

1. 浏览可用的表和模式
2. 执行只读的KQL查询
3. 分析查询结果
4. 提供数据分析指导

安全注意事项

• 服务器使用Azure的DefaultAzureCredential进行安全认证
• 只有具有适当权限的用户才能访问Kusto集群
• 凭据不会由服务器本身存储

许可

MIT许可