Azure Observability MCP Server

Azure可观察性MCP服务器

使用模型上下文协议 （MCP） 服务器查询和分析 Azure 中的应用日志 应用洞察 e Azure监控日志目的是展示 语义工具 对于代理/LLM调查服务的健康，错误，回归和故障相关性 不写 KQL.

______________________________________________________________________

高层建筑

Cliente MCP (Cursor, Claude, etc.)  →  Servidor MCP  →  Tools (semânticas)  →  AzureAppInsightsClient  →  Azure Logs (KQL)

• 服务器显示 工具 高级参数（service_name, timespan, operation_id等等）。
• 这些工具在内部安装 KQL 并调用 Azure 客户端。 没有显示 KQL raw 工具 默认（避免注射和过滤）。
• 身份验证： OAuth2 客户端证书 （请输入ID）设置通过 环境变量.

详细的诊断文档和路线图： docs/MCP_OBSERVABILITY_REVIEW.md.

______________________________________________________________________

如何配置

1. 环境变量

复制 .env.example 段落 .env 并填写：

\* 必填项 两者之一: AZURE_WORKSPACE_ID （日志分析） 或 AZURE_APP_ID （应用见解）。客户端使用不同的范围和端点，视情况而定。

2. Azure 上的权限

• 帕拉 应用洞察应用程序注册许可 应用洞察数据阅读器 （或同等角色）在资源/资源组中。
• 帕拉 日志分析应用程序注册许可 日志分析阅读器 没有工作空间。
• 最低特权原则：使用专门用于读取日志的注册应用程序，而无需写权限或其他功能。

3. 依赖关系

pip install -r requirements.txt

______________________________________________________________________

工具列表和示例

工具由 MCP 方法列出 tools/list下面：名称，描述，参数和调用示例。

日志（应用程序洞察/日志分析）

应用服务（日志流）

调用示例（JSON-RPC 2.0）

列表工具：

{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

最近的错误（ 过去 1 小时， API 服务） ：

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ai_errors_recent","arguments":{"service_name":"api","timespan":"PT1H"}}}

慢请求（>1s，最后2h）：

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"ai_requests_slow","arguments":{"service_name":"api","timespan":"PT2H","duration_threshold_ms":1000}}}

跟踪操作id：

{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"ai_trace_by_operation","arguments":{"operation_id":"abc123","timespan":"PT24H"}}}

日志流（10秒，最多50行）：

{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"appservice_logstream_tail","arguments":{"duration_seconds":10,"max_lines":50}}}

答案格式（ 当前状态）

的 答案 tools/call 作为字段中的 JSON 文本发送 content[0].text内容是一个具有：

• 日志删除工具： tool, query, timespan, result. 字段 result 包含 Azure API 的原始 JSON tables每一个与 columns e rows).\

*注意：正在转换为标准化格式 summary, tables （截断）和 evidence --ver docs/MCP_OBSERVABILITY_REVIEW.md e docs/TODOS.md.*

• appservice_logstream_tail： tool, duration_seconds, max_lines, contains, lines （字符串数组）。

______________________________________________________________________

限制与安全

当前状态

• KQL原始值： 没有可接受任意 KQL 的工具 。所有查询都是内部安装的。这降低了注射和过滤的风险。
• 时间跨度： 接受为字符串（例如：PT1H，P30D）； 没有上限 如今，代理可以请求非常大的窗口，并超载API。建议：在下一个版本中应用限制（例如：P30D）。
• 行数 ： 当前 KQL 查询 不使用 takeAPI可以返回数千行。建议： 添加 take （例如：5000）并记录限制。
• 凭据 ： 环境变量中的秘密客户端；不提交 .env对于 Azure 中的生产，请在路线图中考虑 Managed Identity。
• 多工作空间： 每个进程只有一个工作区或应用程序；代码中没有 allowlist 工作区。

路线图（Roadmap）

• 在 JSON Schema 中验证参数 call_tool.
• 所有查询的最大时间跨度（例如：P30D）和行限制（例如：5000）。
• LLM使用的标准化响应器（摘要+截断表）。
• 如果将来有工具 query_raw_kql: 默认禁用 （env）， KQL 动词允许列表， 严格行限制， 清理.查看 docs/MCP_OBSERVABILITY_REVIEW.md e docs/TODOS.md.

______________________________________________________________________

如何旋转

Servidor MCP（JSON-RPC 2.0——建议使用光标/克劳德桌面）

python -m src.mcp_protocol_server

服务器读取 stdin 并写入 stdout（每条消息一行 JSON）。配置 MCP 客户端以将此命令用作服务器进程。

简单的 MCP 服务器（用于测试的 JSON 行）

python -m src.mcp_stdio_server

消息示例 ：

{"type": "list_tools"}
{"type": "call_tool", "name": "ai_errors_recent", "arguments": {"service_name":"api","timespan":"PT1H"}}

测试 CLI（无 MCP 客户端）

python -m src.cli_test --tool ai_errors_recent --arg service_name=api --arg timespan=PT1H

JSON 中的参数：

python -m src.cli_test --tool ai_requests_slow --args-json '{"service_name":"api","timespan":"PT1H","duration_threshold_ms":500}'

______________________________________________________________________

故障排除

______________________________________________________________________

项目结构和下一步

• 当前结构 ： src/ 包含 mcp_server.py, mcp_protocol_server.py, azure_appinsights.py, appservice_logstream.py, tools/logs_tools.py, tools/appservice_tools.py, cli_test.py.
• 发展建议 （粘贴/模块）： docs/STRUCTURE.md — 包括 guards/, queries/, models/, auth/等等。
• 执行计划和所有： docs/TODOS.md 增量任务（防护栏，标准化响应，新的语义工具，测试，审计）。

三步路线图（摘要）：

1. 约2周： 限制（ timespan， row limit） ， 参数验证， 标准化响应， 工具 get_top_exceptions.
2. 4-6周： 相关性（trace_request、correlate_failures）， compare_windows，百分比，模块 queries/.
3. 8-12周： detect_anomalies可选缓存、审计、单元测试和合同测试。

完整详情在 docs/MCP_OBSERVABILITY_REVIEW.md.