Pingera Mcp

Pingera MCP サーバー

Pingera 監視サービス向けの Model Context Protocol（MCP）サーバーです。AI モデルと監視データをシームレスに統合します。

特長

• モジュール型アーキテクチャ：明確に抽象化された、独立した Pingera API クライアントライブラリ
• 柔軟な動作モード：読み取り専用モードまたは読み書きモードで実行可能
• MCP ツール：ツール（list_pages、get_page_details、test_connection）を通じて監視操作を実行
• 堅牢なエラー処理：カスタム例外階層による包括的なエラー処理
• リアルタイムデータ：Pingera API v1 と直接連携し、ライブ監視データを取得
• 型安全性：データの検証とシリアル化に Pydantic モデルを使用
• 設定可能：環境変数に基づく設定管理

クイックスタート

前提条件

• Python 3.10+
• UV パッケージマネージャー
• Pingera API キー：app.pingera.ruで取得できます

インストールとセットアップ

# Install dependencies
uv sync

# Set up your API key (required)
# Add PINGERA_API_KEY to your environment 

# Run the server
python -m pingera_mcp

サーバーはデフォルトで読み取り専用モードで起動し、Pingera API に接続します。

動作モード

Pingera MCP サーバーは、2 つのトランスポートモードに対応しています。

1. Stdio モード（デフォルト）

Claude Desktop やその他の stdio ベースの MCP クライアントとのローカル連携に使用します。認証は環境変数で設定します。

# Run in stdio mode (default)
python -m pingera_mcp

2. HTTP/SSE モード

Server-Sent Events を使用した HTTP 経由のウェブアクセスを可能にします。リモートクライアント、ウェブアプリケーション、プログラムからのアクセスに最適です。

# Configure SSE mode
export TRANSPORT_MODE=sse
export HTTP_HOST=0.0.0.0
export HTTP_PORT=5000

# Run in SSE mode
python -m pingera_mcp

サーバーには http://0.0.0.0:5000/sse でアクセスできます。

SSE モードでの認証

SSE モードでは、Authorization ヘッダーを使用した次の 2 つの認証方式に対応しています。

1. API キー認証（テストに推奨）：

   Authorization: YOUR_API_KEY
   

2. JWT Bearer トークン認証：

   Authorization: Bearer YOUR_JWT_TOKEN
   

ツールの選択的な公開

SSE モードでは、X-MCP-Tools ヘッダーを使用して、クライアントが利用できるツールを制御できます。AI エージェントが実行できる操作を限定したり、異なるアクセスレベルを設けたりする場合に便利です。

例：読み取り専用のページツールに限定する場合：

client = MultiServerMCPClient({
    "pingera": {
        "url": "http://0.0.0.0:5000/sse",
        "transport": "sse",
        "headers": {
            "Authorization": "YOUR_API_KEY",
            "X-MCP-Tools": "list_pages,get_page_details,list_component_groups"
        }
    }
})

X-MCP-Tools ヘッダーには、ツール名をカンマ区切りで指定します。指定したツールのみがクライアントに公開されます。ヘッダーを省略すると、現在のサーバーモード（読み取り専用または読み書き）に対応するすべてのツールが利用可能になります。

注：ツールのフィルタリングは、サーバーの動作モードに従います。ヘッダーで指定しても、読み取り専用モードでは書き込み操作のツールは公開されません。

例：SSE モード用 Python クライアント

import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient

async def main():
    client = MultiServerMCPClient({
        "pingera": {
            "url": "http://0.0.0.0:5000/sse",
            "transport": "sse",
            "headers": {
                "Authorization": "YOUR_API_KEY",  # or "Bearer YOUR_JWT_TOKEN"
            }
        }
    })
    
    # Get available tools
    tools = await client.get_tools()
    print(f"Available tools: {len(tools)}")

asyncio.run(main())

SSE モードの設定オプション

• TRANSPORT_MODE - HTTP/SSE モードを有効にするには sse を設定します（デフォルト：stdio）
• HTTP_HOST - バインドするホスト（デフォルト：0.0.0.0）
• HTTP_PORT - リッスンするポート（デフォルト：5000）
• REQUIRE_AUTH_HEADER - Authorization ヘッダーを必須にするかどうか（デフォルト：false）

注：SSE モードでは、次のいずれかの方法で認証情報を指定できます。

• 環境変数（PINGERA_API_KEY または PINGERA_JWT_TOKEN）で指定し、フォールバックとして使用する
• リクエストごとに Authorization ヘッダーで送信する（推奨）

REQUIRE_AUTH_HEADER=true の場合、サーバーは有効な Authorization ヘッダーを含むリクエストのみを受け付けます。

Claude Desktop との連携

この MCP サーバーを Claude Desktop で使用するには、Claude Desktop の設定で構成する必要があります。

インストール

まず、UV を使用してパッケージをグローバルにインストールします。

uv tool install pingera-mcp-server

設定

Claude Desktop の設定ファイルを開きます。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

次の設定を追加します。

{
  "mcpServers": {
    "pingera": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "pingera-mcp-server",
        "--python",
        "3.10",
        "python",
        "-m",
        "pingera_mcp"
      ],
      "env": {
        "PINGERA_API_KEY": "your_api_key_here",
        "PINGERA_MODE": "read_only",
        "PINGERA_BASE_URL": "https://api.pingera.ru/v1",
        "PINGERA_TIMEOUT": "30",
        "PINGERA_MAX_RETRIES": "3",
        "PINGERA_DEBUG": "false",
        "PINGERA_SERVER_NAME": "Pingera MCP Server"
      }
    }
  }
}

必須の環境変数

• PINGERA_API_KEY - Pingera API キー（必須）

オプションの環境変数

• PINGERA_MODE - 動作モード：read_only（デフォルト）または read_write
• PINGERA_BASE_URL - API エンドポイント（デフォルト：https://api.pingera.ru/v1）
• PINGERA_TIMEOUT - リクエストのタイムアウト（秒）（デフォルト：30）
• PINGERA_MAX_RETRIES - 最大再試行回数（デフォルト：3）
• PINGERA_DEBUG - デバッグログを有効にします（デフォルト：false）
• PINGERA_SERVER_NAME - サーバーの表示名（デフォルト：Pingera MCP Server）

Claude Desktop の再起動

設定ファイルを更新したら、Claude Desktop を再起動して新しい MCP サーバーを読み込みます。これで、Claude のインターフェースから Pingera の監視データに直接アクセスできるようになります。

インストールの確認

設定が完了したら、Claude に次のように尋ねることができます。

• 「自分のステータスページとその名前を教えてください」
• 「ID が ... のページの詳細を表示してください」
• 「チェック ... で最後に失敗したのはいつですか？」
• 「URL が https:// のウェブサイトで簡単な合成チェックを実行してください」

設定

環境変数を使用してサーバーを設定します。

# Required (for stdio mode or as fallback in SSE mode)
PINGERA_API_KEY=your_api_key_here
# OR
PINGERA_JWT_TOKEN=your_jwt_token_here

# Transport Mode
TRANSPORT_MODE=stdio              # stdio (default) or sse

# SSE Mode Configuration (only used when TRANSPORT_MODE=sse)
HTTP_HOST=0.0.0.0                 # Host to bind to
HTTP_PORT=5000                     # Port to listen on
REQUIRE_AUTH_HEADER=false         # Require Authorization header

# Optional
PINGERA_MODE=read_only                    # read_only or read_write
PINGERA_BASE_URL=https://api.pingera.ru/v1
PINGERA_TIMEOUT=30
PINGERA_MAX_RETRIES=3
PINGERA_DEBUG=false
PINGERA_SERVER_NAME=Pingera MCP Server

MCP ツール

AI エージェントが利用できるツール：

ページ管理

• list_pages - 監視対象ページのページネーション付き一覧を取得します
  • パラメーター：page、per_page、status
• get_page_details - 特定のページの詳細情報を取得します
  • パラメーター：page_id

コンポーネント管理

• list_component_groups - 監視対象組織のすべてのコンポーネントグループを一覧表示します
• get_component_details - 特定のコンポーネントの詳細情報を取得します
  • パラメーター：component_id

監視チェック

• list_checks - すべての監視チェック（HTTP、TCP、ping など）を一覧表示します
  • パラメーター：page、page_size、status、check_type
• get_check_details - 特定のチェックの詳細情報を取得します
  • パラメーター：check_id

アラートルール

• list_alert_rules - すべてのアラートルールとそのトリガー条件を一覧表示します

ハートビート監視

• list_heartbeats - cron ジョブとスケジュールされたタスクのすべてのハートビート監視を一覧表示します
  • パラメーター：page、page_size、status

インシデント管理

• list_incidents - すべてのインシデントと現在のステータスを一覧表示します
  • パラメーター：page、page_size、status

接続テスト

• test_pingera_connection - API 接続をテストします

書き込み操作

読み書きモード（PINGERA_MODE=read_write）でのみ利用できます。

ページ管理

• create_page - 新しいステータスページを作成します
  • パラメーター：name（必須）、subdomain、domain、url、language
• update_page - 既存のステータスページ設定を更新します
  • パラメーター：page_id（必須）、name、subdomain、domain、url、language、追加の kwargs
• patch_page - 特定のページフィールドを部分的に更新します
  • パラメーター：page_id（必須）、特定のフィールド用の kwargs
• delete_page - ステータスページを完全に削除します
  • パラメーター：page_id（必須）

コンポーネント管理

• create_component - 新しいコンポーネントまたはコンポーネントグループを作成します
  • パラメーター：page_id（必須）、name（必須）、description、group、group_id、only_show_if_degraded、position、showcase、status
• update_component - 既存のコンポーネント設定を更新します
  • パラメーター：page_id（必須）、component_id（必須）、name、description、group、group_id、only_show_if_degraded、position、showcase、status、追加の kwargs
• patch_component - 特定のコンポーネントフィールドを部分的に更新します
  • パラメーター：page_id（必須）、component_id（必須）、特定のフィールド用の kwargs
• delete_component - コンポーネントを完全に削除します
  • パラメーター：page_id（必須）、component_id（必須）

監視チェック

• create_check - 新しい監視チェックを作成します
  • パラメーター：check_data（チェック設定を含む dict）
• update_check - 既存の監視チェックを更新します
  • パラメーター：check_id（必須）、check_data（更新後の設定を含む dict）
• delete_check - 監視チェックを完全に削除します
  • パラメーター：check_id（必須）
• pause_check - 監視チェックを一時停止します
  • パラメーター：check_id（必須）
• resume_check - 一時停止中の監視チェックを再開します
  • パラメーター：check_id（必須）

アラートルール

• create_alert - 新しいアラートルールを作成します
  • パラメーター：alert_data（アラート設定を含む dict）
• update_alert - 既存のアラートルールを更新します
  • パラメーター：alert_id（必須）、alert_data（更新後の設定を含む dict）
• delete_alert - アラートルールを完全に削除します
  • パラメーター：alert_id（必須）

ハートビート管理

• create_heartbeat - 新しいハートビートモニターを作成します
  • パラメーター：heartbeat_data（ハートビート設定を含む dict）
• update_heartbeat - 既存のハートビートモニターを更新します
  • パラメーター：heartbeat_id（必須）、heartbeat_data（更新後の設定を含む dict）
• delete_heartbeat - ハートビートモニターを完全に削除します
  • パラメーター：heartbeat_id（必須）
• send_heartbeat_ping - ハートビートに手動で ping を送信します
  • パラメーター：heartbeat_id（必須）

インシデント管理

• create_incident - ステータスページに新しいインシデントを作成します
  • パラメーター：page_id（必須）、incident_data（インシデントの詳細を含む dict）
• update_incident - 既存のインシデントの詳細を更新します
  • パラメーター：page_id（必須）、incident_id（必須）、incident_data（更新後の詳細を含む dict）
• delete_incident - インシデントを完全に削除します
  • パラメーター：page_id（必須）、incident_id（必須）
• add_incident_update - インシデントにステータス更新を追加します
  • パラメーター：page_id（必須）、incident_id（必須）、update_data（更新の詳細を含む dict）
• update_incident_update - 既存のインシデント更新を編集します
  • パラメーター：page_id（必須）、incident_id（必須）、update_id（必須）、update_data（更新後の内容を含む dict）
• delete_incident_update - 特定のインシデント更新を削除します
  • パラメーター：page_id（必須）、incident_id（必須）、update_id（必須）

アクセス制御モード

サーバーは、次の 2 つのレベルのアクセス制御をサポートしています。

読み取り専用モード（デフォルト）

• 監視データにアクセスします
• ステータスページとその設定を表示します
• API 接続をテストします
• 変更操作はできません

読み書きモード

• 読み取り専用モードのすべての機能
• ステータスページ、チェック、アラート、ハートビートなどのリソースを作成、更新、削除します
• チェックを実行し、結果を取得します
• インシデントと通知を管理します

書き込み操作を有効にするには、PINGERA_MODE=read_write を設定します。

注：アクセス制御モードはトランスポートモードとは独立しています。stdio または SSE トランスポートのどちらでも、サーバーを読み書きモードで実行できます。

アーキテクチャ

Pingera API クライアントライブラリ

pingera/ に配置されているこのモジュール式ライブラリは、次を提供します。

• PingeraClient：認証とエラー処理を備えた主要な API クライアント
• モデル：型安全な API レスポンスのための Pydantic データモデル
• 例外：エラー処理のためのカスタム例外階層

MCP サーバーの実装

• FastMCP フレームワーク：最新の MCP サーバー実装
• リソース管理：監視データへの構造化されたアクセス
• ツール登録：AI エージェント向けの実行可能な操作
• 設定：環境変数に基づく設定管理

テスト

テストスイートの実行

すべてのテストを実行します：

uv run pytest

詳細な出力を表示してテストを実行します：

uv run pytest -v

特定のテストファイルを実行します：

uv run pytest tests/test_models.py
uv run pytest tests/test_config.py
uv run pytest tests/test_mcp_server.py

カバレッジを計測してテストを実行します：

uv run pytest --cov=pingera --cov=config --cov=mcp_server

テスト構成

テストスイートには以下が含まれます：

• ユニットテスト：個々のコンポーネント（モデル、設定、クライアント）のテスト
• 統合テスト：MCP サーバーの機能テスト
• モックテスト：シミュレートした API レスポンスを使用したテスト

MCP Inspector を使用したテスト

MCP Inspector は、MCP サーバーを対話的にテストできる Web インターフェースを提供する、公式のデバッグツールです。利用可能なリソースの確認、ツールの実行、サーバーのレスポンスのリアルタイムでの検査ができます。

Inspector のセットアップ

1. mcp.json 設定ファイルを作成します：

{
  "mcpServers": {
    "pingera": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "pingera-mcp-server",
        "--python",
        "3.10",
        "python",
        "-m",
        "pingera_mcp"
      ],
      "env": {
        "PINGERA_API_KEY": "your_pingera_api_key",
        "PINGERA_MODE": "read_only",
        "PINGERA_BASE_URL": "https://api.pingera.ru/v1",
        "PINGERA_TIMEOUT": "30",
        "PINGERA_MAX_RETRIES": "3",
        "PINGERA_DEBUG": "false"
      }
    }
  }
}

2. Inspector を実行します：

npx @modelcontextprotocol/inspector --config mcp.json

3. ブラウザーで指定された URL（通常は http://localhost:6274）を開きます

Inspector の使用方法

Inspector では以下の操作ができます：

• Resources タブ：利用可能な監視データリソースを閲覧します
• Tools タブ：list_pages、get_page_details などの MCP ツールを実行します
• Logs タブ：Inspector とサーバー間の詳細な通信ログを確認します
• 対話型テスト：ツールのパラメーターをテストし、リアルタイムのレスポンスを確認します

Claude Desktop やその他の MCP クライアントと連携してデプロイする前に、MCP サーバーの統合をテストする方法として推奨されています。

mcp_client.py による手動テスト

mcp_client.py は Gemini モデルを使用し、MCP サーバーと連携してさまざまなツールを実行します。これはあくまで一例であり、ほかの任意の大規模言語モデルを使用するよう簡単に変更できます。

python mcp_client.py "Show me my status pages"

エラー処理

システムには包括的なエラー処理が含まれています：

• PingeraError：すべてのクライアントエラーの基底例外
• PingeraAPIError：ステータスコードを含む API レスポンスエラー
• PingeraAuthError：認証エラー
• PingeraConnectionError：ネットワーク接続の問題
• PingeraTimeoutError：リクエストのタイムアウト処理