MCP Logging NL Query Server

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

特性

• 自然语言到LQL的转换 使用Vertex 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 & 工具

• 运行时在 /docs 和 /openapi.json 提供OpenAPI/Swagger文档。
• 两个端点也可以作为MCP工具被代理框架（如Smithery, Claude Desktop等）发现。

示例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忽略项（见仓库）

部署

在Google Cloud Run上运行

您可以将此服务器部署到Google Cloud Run，以获得完全托管且可扩展的解决方案。

步骤：

1. 构建Docker镜像：

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

2. 部署到Cloud Run：

   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角色（Logging Viewer, Vertex AI User）的Cloud Run服务账号。
     • 通常不需要在Cloud Run上设置 GOOGLE_APPLICATION_CREDENTIALS，除非使用非默认的服务账号密钥。

4. IAM权限：

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

5. 访问服务：

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

Google Cloud身份验证设置

该项目需要Google Cloud应用程序默认凭据（ADC）来访问Logging和Vertex AI API。

设置凭据的步骤：

1. 创建服务账号：
   • 前往 Google Cloud Console → IAM & Admin → 服务账号。
   • 选择您的项目。
   • 创建或选择一个具有以下权限的服务账号：日志查看者 和 Vertex AI 用户。
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+
• 启用了 Logging 和 Vertex AI API 的 Google Cloud 项目
• 具有日志查看者和 Vertex AI 用户权限的服务账号
• 设置环境变量：
  • VERTEX_PROJECT：您的 GCP 项目 ID
  • VERTEX_LOCATION：Vertex 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

部署到 Cloud Run

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 集群的所有日志
• 显示来自 Compute Engine 和 AWS EC2 实例的错误日志
• 查找项目 my-project 的管理员活动审核日志
• 查找包含单词 unicorn 的日志
• 查找同时包含 unicorn 和 phoenix 的日志
• 查找 textPayload 中同时包含 unicorn 和 phoenix 的日志
• 查找 textPayload 中包含短语 'unicorn phoenix' 的日志
• 显示昨天 Cloud Run 服务 'my-service' 的日志
• 显示最近 30 分钟的日志
• 显示 GKE 中 logName 包含 request_log 的日志
• 使用正则表达式显示 pod_name 匹配 foo 或 bar 的日志
• 显示严重性为 WARNING 或更高的 Compute Engine 日志
• 显示 us-central1 中的 Cloud SQL 实例日志
• 显示 Pub/Sub 主题包含 'payments' 的日志
• 显示在两个时间戳之间的日志条目
• 显示 jsonPayload.message 匹配正则表达式 'foo.*bar' 的日志
• 显示 labels.env 不是 prod 的日志

更多 LQL 示例，请参阅官方文档。

许可证

Apache 2.0