MCP ロギング NL クエリ サーバー
このプロジェクトは、開発者とAIエージェントが自然言語を使用してGoogle Cloud Loggingにクエリを実行できるModel Context Protocol（MCP）サーバーを提供します。このサーバーは、Vertex AI Gemini 2.5を使用して自然言語クエリをGoogle Cloud Loggingクエリ言語（LQL）に変換し、Cloud Loggingにクエリを実行して結果を返します。
特徴
- Vertex AI Gemini 2.5 を使用した自然言語から LQL への翻訳
- 柔軟なログクエリ: 監視対象リソース、ログ名、重大度、時間などでフィルタリング
- 簡単に統合できる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 は含まれているものを無視します (リポジトリを参照)
展開
Google Cloud Run で実行
このサーバーをGoogle Cloud Runにデプロイすると、完全に管理されたスケーラブルなソリューションを実現できます。
手順:
- Docker イメージをビルドします。
gcloud builds submit --tag gcr.io/YOUR_PROJECT_ID/mcp-logging-server
- 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 ) に置き換えます。 - 環境変数を設定する:
- Cloud Run デプロイ UI または
--set-env-varsフラグを使用して、以下を指定します。VERTEX_PROJECT=your-gcp-project-idVERTEX_LOCATION=us-central1 (またはあなたのリージョン)
- 資格：
- 適切な IAM ロール (Logging 閲覧者、Vertex AI ユーザー) を持つ Cloud Run サービス アカウントを使用することを推奨します。
- 通常、デフォルト以外のサービス アカウント キーを使用しない限り、Cloud Run で
GOOGLE_APPLICATION_CREDENTIALS設定する必要はありません。
- IAM 権限:
- Cloud Run サービス アカウントに次の内容があることを確認します。
roles/logging.viewerroles/aiplatform.user
- サービスへのアクセス:
- デプロイ後、Cloud Run はサービス URL (例:
https://mcp-logging-server-xxxxxx.a.run.app ) を提供します。 - API リクエストではこれを
$MCP_BASE_URLとして使用します。
Google Cloud 認証の設定
このプロジェクトでは、Logging および Vertex AI API にアクセスするために Google Cloud アプリケーションのデフォルト認証情報 (ADC) が必要です。
資格情報を設定する手順:
- サービス アカウントを作成します。
- キーを作成してダウンロードする:
- サービス アカウントで、「キーの管理」→「キーの追加」→「新しいキーの作成」(JSON を選択) をクリックします。
- JSON キー ファイルをコンピューターにダウンロードします。
- 環境変数を設定します。
- ターミナルで、環境変数をダウンロードしたキーのパスに設定します。
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"
/path/to/your/service-account-key.json実際のパスに置き換えます。
- (オプション) プロジェクトと場所を設定します。
- 次のものも必要になる場合があります:
export VERTEX_PROJECT=your-gcp-project-id
export VERTEX_LOCATION=us-central1
- 認証の確認:
- 認証が機能していることを確認するには、単純な
gcloudまたは Python クライアント呼び出しを実行します。 DefaultCredentialsErrorが表示された場合は、環境変数とファイル パスを確認してください。
前提条件
- Python 3.9以上
- Logging と Vertex AI API が有効になっている Google Cloud プロジェクト
- Logging Viewer と Vertex AI ユーザーの権限を持つサービス アカウント
- 環境変数を設定します。
VERTEX_PROJECT : GCP プロジェクト IDVERTEX_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 の管理アクティビティ監査ログを検索する
- 「ユニコーン」という単語を含むログを検索
- ユニコーンとフェニックスの両方が描かれた丸太を探す
- textPayloadにunicornとphoenixの両方が含まれるログを見つける
- textPayload に「unicorn phoenix」というフレーズが含まれているログを検索します
- Cloud Run サービス「my-service」の昨日のログを表示します
- 過去30分間のログを表示
- GKE で request_log を含む logName のログを表示する
- 正規表現を使用して、pod_name が foo または bar に一致するログを表示します。
- 重大度が WARNING 以上の Compute Engine のログを表示します
- us-central1 の Cloud SQL インスタンスのログを表示する
- 「支払い」を含む Pub/Sub トピックのログを表示する
- 2つのタイムスタンプ間のログエントリのログを表示する
- jsonPayload.message が正規表現 'foo.*bar' に一致するログを表示する
- labels.env が prod ではない場合のログを表示する
その他の LQL の例については、公式ドキュメントを参照してください。
ライセンス
アパッチ 2.0