AI导哈

自然语言日志查询服务

一个基于Vertex AI Gemini 2.5的MCP服务器，可将自然语言查询转换为Google Cloud Logging查询语言(LQL)，并提供REST API接口。

  • by srtux
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 srtux/mcp

使用说明

MCP日志NL查询服务器

该项目提供了一个模型上下文协议（MCP）服务器，允许开发人员和AI代理使用自然语言查询Google Cloud Logging。服务器使用Vertex AI Gemini 2.5将自然语言查询翻译成谷歌云日志查询语言（LQL），然后查询云日志并返回结果。

特性

  • 自然语言到LQL的翻译 使用顶点AI Gemini 2.5
  • 灵活的日志查询：筛选受监视的资源、日志名称、严重性、时间等
  • REST API 便于集成
  • 准备部署 Google Cloud Run或GKE

API使用

端点

1.自然语言查询

POST /logs/nl_query

请求：

{
  "query": "Show me all error logs from yesterday for my Cloud Run service 'my-service'",
  "max_results": 20
}

答复：

{
  "lql": "resource.type = \"cloud_run_revision\" AND resource.labels.service_name = \"my-service\" AND severity = ERROR AND timestamp >= \"2025-04-17T00:00:00Z\" AND timestamp < \"2025-04-18T00:00:00Z\"",
  "entries": [ ... log entries ... ]
}

2.LQL过滤器查询

POST /logs/query

请求：

{
  "filter": "resource.type=\"cloud_run_revision\" AND severity=ERROR",
  "max_results": 20
}

答复：

{
  "lql": "resource.type=\"cloud_run_revision\" AND severity=ERROR",
  "entries": [ ... log entries ... ]
}

OpenAPI和工具

  • OpenAPI/Swagger文档可在 /docs 和 /openapi.json 跑步时。
  • 这两个端点也可以作为代理框架（Smithery、Claude Desktop等）的MCP工具被发现。

curl命令示例

curl -X POST $MCP_BASE_URL/logs/nl_query -H 'Content-Type: application/json' -d '{"query": "Show error logs for my Cloud Run service", "max_results": 2}'

curl -X POST $MCP_BASE_URL/logs/query -H 'Content-Type: application/json' -d '{"filter": "resource.type=\"cloud_run_revision\" AND severity=ERROR", "max_results": 2}'

测试

  • 示例测试脚本： test_main.py （见回购）

.gitignore

  • 标准Python忽略包含（见repo）

部署

在Google Cloud Run上运行

您可以将此服务器部署到 谷歌云运行 一个完全托管、可扩展的解决方案。

步骤：

  1. 构建Docker镜像：

    gcloud builds submit --tag gcr.io/YOUR_PROJECT_ID/mcp-logging-server

  2. 部署到云运行：

    gcloud run deploy mcp-logging-server \
  --image gcr.io/YOUR_PROJECT_ID/mcp-logging-server \
  --platform managed \
  --region YOUR_REGION \
  --allow-unauthenticated \
  --port 8080

    替换 YOUR_PROJECT_ID 和 YOUR_REGION 使用您的实际GCP项目ID和地区（例如。， us-central1).

  3. 设置环境变量：

    • 在Cloud Run部署UI中或使用 --set-env-vars 标志，提供：
      • VERTEX_PROJECT=your-gcp-project-id
      • VERTEX_LOCATION=us-central1 （或您所在的地区）
    • 资格证书：
      • 更倾向于使用具有正确IAM角色（日志查看器、Vertex AI用户）的Cloud Run服务帐户。
      • 您通常不需要设置 GOOGLE_APPLICATION_CREDENTIALS 除非使用非默认服务帐户密钥，否则请在Cloud Run上运行。

  4. IAM权限：

    • 确保Cloud Run服务帐户具有：
      • roles/logging.viewer
      • roles/aiplatform.user

  5. 访问服务：

    • 部署后Cloud Run将提供服务URL（例如。， https://mcp-logging-server-xxxxxx.a.run.app).
    • 将此用作您的 $MCP_BASE_URL 在API请求中。

谷歌云身份验证设置

此项目需要Google Cloud应用程序默认凭据（ADC）才能访问日志记录和顶点AI API。

设置凭据的步骤：

  1. 创建服务帐户：
  2. 创建并下载密钥：
    • 在服务帐户中，单击“管理密钥”→ “添加密钥”→ “创建新密钥”（选择JSON）。
    • 将JSON密钥文件下载到您的计算机。
  3. 设置环境变量：
    • 在终端中，将环境变量设置为下载密钥的路径：
      export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"
    • 替换 /path/to/your/service-account-key.json 与实际路径。
  4. （可选）设置项目和位置：
    • 您可能还需要：
      export VERTEX_PROJECT=your-gcp-project-id
export VERTEX_LOCATION=us-central1
  5. 验证身份验证：
    • 运行一个简单 gcloud 或Python客户端调用，以确保身份验证正常工作。
    • 如果你看到 DefaultCredentialsError，检查您的环境变量和文件路径。

先决条件

  • Python 3.9+
  • 启用日志记录和Vertex AI API的Google Cloud项目
  • 具有日志查看器和Vertex AI用户权限的服务帐户
  • 设置环境变量：
    • VERTEX_PROJECT：您的GCP项目ID
    • VERTEX_LOCATION：顶点AI区域（默认值： us-central1)
    • GOOGLE_APPLICATION_CREDENTIALS：服务帐户JSON密钥文件的路径

地方发展

pip install -r requirements.txt
export VERTEX_PROJECT=your-project-id
export VERTEX_LOCATION=us-central1
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
python main.py

部署到云端运行

gcloud builds submit --tag gcr.io/$VERTEX_PROJECT/mcp-logging-server
 gcloud run deploy mcp-logging-server \
    --image gcr.io/$VERTEX_PROJECT/mcp-logging-server \
    --platform managed \
    --region $VERTEX_LOCATION \
    --allow-unauthenticated

自然语言查询示例

  • 显示Kubernetes集群的所有日志
  • 显示来自计算引擎和AWS EC2实例的错误日志
  • 查找项目“我的项目”的管理员活动审核日志
  • 查找包含单词“独角兽”的日志
  • 找到同时有独角兽和凤凰的原木
  • 查找textPayload同时包含独角兽和凤凰的日志
  • 查找textPayload包含短语“独角兽凤凰”的日志
  • 显示Cloud Run服务“我的服务”昨天的日志
  • 显示最近30分钟的日志
  • 在GKE中显示包含request_log的logName日志
  • 使用正则表达式显示pod_name与foo或bar匹配的日志
  • 显示严重性为警告或更高的计算引擎日志
  • 在us-central中显示Cloud SQL实例的日志1
  • 显示包含“付款”的发布/子主题的日志
  • 显示两个时间戳之间的日志条目的日志
  • 显示jsonPayload.message与正则表达式'foo.*bar'匹配的日志
  • 显示labels.env不是prod的日志

有关更多LQL示例，请参阅 官方文件.

许可证

Apache 2.0

相关 MCP