Signal Agent 🚨

Signal Agent 🚨

Model Context Protocol（MCP）によるインテリジェントな障害イベント処理

本番環境に対応した MCP サーバーとクライアントのシステムです。自動分類、重大度分析、対応策の推奨を通じて、生の障害イベントを実用的なインテリジェンスに変換します。

🎯 Signal Agent とは？

Signal Agent は、インテリジェントな自動化システムの構築における Model Context Protocol（MCP）の力を実証します。高度な分析パイプラインを通じて障害イベントを処理し、次の機能を提供します。

• 🔍 分析：キーワードベースの重大度評価を使用して障害イベントの内容を分析します
• 📊 分類：イベントを運用カテゴリ（データベース、ネットワーク、セキュリティなど）に分類します
• 💡 生成：適切な対応策を推奨します
• 📋 整形：運用チーム向けに、人が読みやすい要約を作成します

✨ 主な機能

🏗️ 本番環境に対応したアーキテクチャ

• 公式 SDK を使用した 標準準拠の MCP 実装
• Pydantic スキーマによる 堅牢な入力検証
• 包括的なエラー処理とログ記録
• トランスポートに依存しない設計（開発時は stdio、本番環境では HTTP ストリーミング可能トランスポート）

🧠 インテリジェントな分析パイプライン

• 検証とエンリッチメントを含む 多段階のイベント処理
• ソース側の評価に依存しない キーワードベースの重大度再計算
• 適切なインシデント振り分けのための 運用分類
• 重大度とイベントタイプに基づく コンテキストに応じた推奨事項

🔧 開発者エクスペリエンス

• 複数のデプロイモード（統合デモ、サーバーのみ、エージェントのみ）
• インタラクティブなテストに対応する MCP Inspector 互換性
• 包括的なログ記録とデバッグサポート
• トランスポートとビジネスロジックの 明確な関心の分離

🚀 クイックスタート

前提条件

• Python 3.8+
• uv（モダンな Python パッケージマネージャー）
• just

インストール

git clone https://github.com/no0ktheali3n/signal-agent.git
cd signal-agent

# Setup environment and dependencies
uv venv                         #first time only

just venv                       #activates venv

just init-install               #qol scripts and copes justfile to root

just sync                       #syncs environment dependencies

デモの実行

# Full integrated demonstration
just run

# Server only (for MCP Inspector testing)  
just run server

# Agent only (launches server subprocess)
just run agent

使用可能なコマンド

just compile      # Lock dependencies
just sync         # Install dependencies  
just upgrade      # Upgrade all dependencies
just activate     # Activate virtual environment
just run [mode]   # Run Signal Agent (demo/server/agent)

🏗️ アーキテクチャ

Signal Agent は、関心事を分離し、容易な進化を可能にする、シンプルでモジュール化されたアーキテクチャを採用しています。

┌─────────────────┐    MCP Protocol    ┌──────────────────┐
│   Signal Agent  │◄──────────────────►│  Signal Server   │
│   (Client)      │     stdio/HTTP     │   (MCP Server)   │
│                 │                    │                  │
│ • Event Loading │                    │ • Tool Registry  │
│ • Result Display│                    │ • Event Analysis │
│ • Demo Workflow │                    │ • Classification │
└─────────────────┘                    └──────────────────┘

コアコンポーネント

🖥️ Signal Server（server/server.py）

• 公式 SDK を使用した MCP 準拠サーバー
• 適切な入力スキーマによる ツール登録
• 多段階処理を備えた イベント分析パイプライン
• TextContent 形式による 標準ベースのレスポンス

🤖 Signal Agent（agent/signal_agent.py）

• stdio トランスポートを使用する MCP クライアント
• イベント処理ワークフローの調整
• 結果の整形と表示
• テストデータを用いた デモ機能

🎛️ メインオーケストレーター（main.py）

• 複数のデプロイモード（デモ、サーバーのみ、エージェントのみ）
• コンポーネントのライフサイクル管理
• 正常なシャットダウン処理

🔧 MCP との統合

サーバーツール

classify_failure_event

インテリジェントな分析パイプラインを通じて障害イベントを処理します。

入力スキーマ：

{
  "event_id": "string",
  "timestamp": "string", 
  "service": "string",
  "severity": "string",
  "message": "string",
  "details": "object (optional)"
}

使用例：

{
  "event_id": "sig_001_db_failure",
  "timestamp": "2024-12-11T14:30:45Z",
  "service": "user-authentication-service",
  "severity": "critical",
  "message": "PostgreSQL connection pool exhausted",
  "details": {
    "pool_size": 20,
    "active_connections": 20,
    "queue_length": 150
  }
}

レスポンス：

{
  "event_id": "sig_001_db_failure",
  "original_severity": "critical",
  "calculated_severity": "critical",
  "classification": "database_issue",
  "recommendation": "Immediate attention required - escalate to on-call engineer",
  "human_readable": "🚨 Signal Alert: sig_001_db_failure...",
  "status": "processed"
}

health_check

サーバーの健全性と接続を確認します。

MCP Inspector でのテスト

# In another terminal, launch MCP Inspector
npx @modelcontextprotocol/inspector uv run python server/server.py

or

just run-inspector

HTTP トランスポートのテスト

# Terminal 1: Start HTTP server
just run-server-http

# Terminal 2: Test with HTTP agent
just run-agent-http

# Or test with direct commands
python main.py server --transport http
python main.py agent --transport http

Inspector では、インタラクティブなツールテスト用のウェブインターフェースが http://localhost:#### に表示されます。

📊 分析パイプライン

Signal Agent は、高度な多段階パイプラインを通じてイベントを処理します。

1. 入力検証

• JSON の解析と構造の検証
• Pydantic モデルの適用
• 必須フィールドの確認

2. 重大度分析

• キーワードベースの内容分析
• 重大度を示す指標とのパターンマッチング
• ソース側の評価から独立した再計算

3. イベントの分類

• 運用カテゴリの判定
• 次の項目のパターンマッチング：
  • データベースの問題
  • ネットワークの問題
  • リソースの制約
  • セキュリティインシデント
  • サービス障害

4. 推奨事項の生成

• コンテキストに応じた対応案の提示
• 深刻度に基づくエスカレーションルール
• 標準化された運用手順

5. 概要のフォーマット

• 人が読みやすい形式での結果のまとめ
• 構造化された表示形式
• 運用ダッシュボードとの互換性

🎯 ユースケース

🏢 エンタープライズ運用

• インシデント対応の自動化 - イベントのインテリジェントなトリアージとルーティング
• 運用インテリジェンス - パターン認識とトレンド分析
• チームの連携 - 標準化されたコミュニケーションとエスカレーション

🔧 開発ワークフロー

• モニタリングとの統合 - Sentry、Datadog などのアラートを処理
• CI/CD の強化 - 障害の分析とレポートを自動化
• 品質保証 - エラーの体系的な分類と追跡

📚 学習と研究

• MCP プロトコルの例 - リファレンス実装のパターン
• AI 統合パターン - インテリジェントな自動化アーキテクチャ
• プロトコル標準 - MCP サーバー開発のベストプラクティス

🛠️ 開発

プロジェクト構成

signal-agent/
├── server/
│   └── server.py          # MCP server implementation
├── agent/
│   └── signal_agent.py    # MCP client implementation
├── main.py                # System orchestrator
├── events/
│   └── test_payload.json  # Demo event data
├── docs/                  # Documentation
└── examples/              # Usage examples

テストの実行

# Test server with MCP Inspector (stdio)
just run-inspector

# Test HTTP server and agent
just run-server-http &    # Background streamable-HTTP MCP server
just run-agent-http       # streamable-HTTP agent test / listener 

エージェントには、手動テスト用の HTTP リスナーと、MCP サーバーと連携する MCP クライアントという、2 つの役割があります。

手動でテストするには、エージェントを実行し、オプション 3 を選択してリスナーを起動します。

サーバーは localhost:8000 で実行され、リスナーは localhost:8001 で実行されます。

手動でテストするには（最新の更新でメインオーケストレーターが動作しないため）、chaos_agent を実行します。

#runs chaos agent to run 10 events with 1.5 second delay between event
python agent/chaos_agent.py --count 10 --delay 1.5

イベントは SQLite を使用して signals_events.db にローカル保存されます。

次に、別のエージェントを実行します。

just run-agent-http

これで、エージェントを MCP クライアントとして使用し、MCP サーバーと連携して、サーバーのツールを利用できます。これにより、コマンドラインインターフェイスから signal_events.db をクエリし、イベントに関するデータを取得できます。

コード品質

• コードベース全体にわたる型ヒント
• デバッグのための包括的なログ記録
• 適切な縮退動作を伴うエラー処理
• すべてのパブリックインターフェイスに関するドキュメント

🚀 進化のロードマップ

Signal Agent は、より高度なインシデント対応システムの基盤となります。

🎯 現在の状態（v1.1.0）

• ✅ 標準に準拠した MCP の実装
• ✅ インテリジェントなイベント分析
• ✅ デュアルトランスポート対応（stdio + HTTP streamable）
• ✅ 本番環境に対応したアーキテクチャ
• ✅ justfile による自動化を含む最新の開発ワークフロー

🔮 今後の進化

• 🌐 分散デプロイメント向けのHTTP トランスポート
• 📊 複数のモニタリング統合（Sentry、Datadog、Raygun）
• 🤖 パターン認識を強化する機械学習
• 🏢 MSP 環境向けのエンタープライズ機能

🤝 貢献

貢献を歓迎します！このプロジェクトは MCP のベストプラクティスを示し、コミュニティ向けのリファレンスとして機能します。

貢献できる分野

• さまざまなイベントタイプに対応した追加の分析パターン
• トランスポートの実装（SSE、WebSocket）
• 一般的なモニタリングツールとの統合例
• ドキュメントの改善とチュートリアル

📄 ライセンス

MIT License — 詳細は LICENSE を参照してください。

🔗 リンク

• Model Context Protocol - MCP の公式ドキュメント
• MCP Python SDK - 公式 Python 実装

🙏 謝辞

公式の Model Context Protocol SDK を使用し、現代の運用におけるインテリジェントな自動化の必要性に着想を得て構築されています。

---

Signal Agent - MCP の力を活用し、生の障害イベントを実用的なインテリジェンスへと変換します。🚨➡️🧠