CloudOps MCP

CloudOps MCPは、Model Context Protocolサーバーであり、運用インフラストラクチャのコンテキスト（ログ、メトリクス、デプロイメント、ヘルス）を、少数の型付けされた制限付きツールを通じてAIエージェントに公開します。

存在理由

インシデントを調査するエージェントには、運用コンテキストが必要です。最近何が変わったか、エラーレートはどうか、ログには何が書かれているか。クラウドAPIへの無制限のアクセスは必要なく、根本原因を判断するものでもありません。

CloudOps MCPは、この2つの間に位置します。

Cloud APIs / observability systems
        |
Provider adapters
        |
Normalized operational domain
        |
Deterministic services
        |
MCP tools
        |
AI agent

各レイヤーはさらに正規化し、エージェントが要求できる範囲を狭めます。プロバイダーアダプターは、ベンダーAPIを共有ドメインモデルに変換します。サービスは、すべてのプロバイダーに対して同じ方法で、決定論的に境界、順序付け、集約を適用します。MCPツールは、それを小さな型付けされたサーフェスとして公開します。

CloudOps MCPは、運用上の事実を返し、根本原因の結論は返しません。ツールは「エラーレートが14:06に0.4%から8%に上昇しました」と言うことができますが、「デプロイメントが障害を引き起こしました」とは言いません。その判断は、CloudOps MCPが証拠として提供する事実に基づいて、エージェントに委ねられます。

Related MCP server: cloud-chat-assistant

機能

6つのツール、すべて読み取り専用で制限付きです。

get_operational_snapshotは、他の5つのツールが使用するのと同じプリミティブサービスを構成し、4つの独立したクエリをすべて同時に実行します。プロバイダーと直接通信することはなく、1つのセクションが利用不可であっても全体として失敗することはありません。各セクションは自身のステータスを報告します。

設計原則

• 設計上、読み取り専用。 プロバイダーインターフェースは変更メソッドを公開しません。書き込みAPIへのコードパスはありません。

• プロバイダーに依存しないサービスID。 サービスは(service, environment)で識別されます。ベンダー固有の識別子（CloudWatchロググループ、Kubernetesオブジェクト名など）はプロバイダーバインディング内部に留まり、公開契約の一部になることはありません。

• 標準的で拡張可能なメトリクス。 error_rate、latency_p99などの名前は、ベンダーのものではなく、当社のものです。標準名から実際のメトリクスへのマッピングは、サービスごとの設定に存在します。語彙はオープンであり、固定された列挙型ではありません。

• 制限付きクエリ。 すべてのテレメトリクエリには、時間範囲の上限と件数の上限があります。呼び出し元はより少ないデータを要求することはできますが、無制限のデータを要求することはできません。

• 明示的なデータ可用性。 すべてのコレクションは、SUCCESS、EMPTY、PARTIAL、またはFAILEDのいずれかを報告します。欠落データが「正常」または「何も起こらなかった」として暗黙的に扱われることはありません。

• 可用性と結果を分離。 NOT_CONFIGURED（プロバイダーが配線されていない）とEMPTY（クエリは成功したが、一致するものがゼロ）は異なる状態であり、混同されることはありません。

• 内部を漏洩させない来歴。 個々の結果は、プロバイダーアダプターが提供する場合、providerとsourceを保持します。プロバイダーを呼び出すために使用される内部参照は、公開出力にコピーされることはありません。

• すべてUTC。 すべてのタイムスタンプはタイムゾーン対応でUTCに正規化されます。ナイーブな日時はモデル境界で拒否されます。

• MCPサーバー内にLLMなし。 ログコンテンツの要約、分類、推論は行われません。ログメッセージは、不透明で信頼できないテキストとして扱われます。

• 因果推論なし。 ツールは何がいつ変わったかを報告します。理由の解釈はエージェントに委ねられます。

クイックスタート：フェイクモード

フェイクモードはデフォルトであり、CloudOps MCPを試すための主要な方法です。クラウドアカウントは必要ありません。

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

サーバーを実行します（stdioトランスポート）：

python -m cloudops_mcp.server

または、パッケージがコンソールスクリプトとともにインストールされている場合：

cloudops-mcp

サーバーはMCP over stdioで通信し、もう一方の端にクライアントを期待します。Pythonから直接、公式SDKのクライアントを使用して試すには：

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    params = StdioServerParameters(command="python", args=["-m", "cloudops_mcp.server"])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])

            result = await session.call_tool(
                "get_operational_snapshot",
                {"service": "checkout-api", "environment": "production"},
            )
            print(result.structured_content)

asyncio.run(main())

フェイクシナリオ

CLOUDOPS_MCP_SCENARIOでシナリオを選択します（デフォルトはhealthy）：

CLOUDOPS_MCP_SCENARIO=bad_deploy python -m cloudops_mcp.server

bad_deployは、固定タイムスタンプで3つの相関する事実をシードします。デプロイメント、その数分後のメトリクスシフト、そしてその直後のタイムアウトログラインです。CloudOps MCPはこれら3つの事実のみを報告します。デプロイメントがエラーを引き起こしたとは主張しません。その推論は、利用するエージェントに完全に委ねられます。

AWS CloudWatchモード

pip install -e ".[aws]"        # runtime only
pip install -e ".[dev,aws]"    # development

CLOUDOPS_MCP_MODE=aws CLOUDOPS_MCP_CONFIG=/path/to/cloudops.toml cloudops-mcp

完全な設定例については、examples/aws-cloudwatch.tomlを参照してください。プレースホルダーのみを使用しており、実際のアカウントID、ARN、または資格情報はそのファイルに含まれていません。

資格情報はすべて、boto3の標準プロバイダーチェーン（AWS_PROFILE、AWS_REGION / AWS_DEFAULT_REGION、環境資格情報、またはIAMロール）から取得されます。CloudOps MCPは、アクセスキーやシークレットを読み取り、保存、またはログに記録することはありません。

AWSモードで実装されているもの：

• ログ: CloudWatch Logs FilterLogEvents。

• メトリクス: CloudWatch GetMetricData（MetricStatクエリのみ）。

まだ実装されていません：AWSバックアップのデプロイメントとヘルス。これらのセクションなしで設定されたサービスは、他の設定されていない機能と同様に、単にNOT_CONFIGUREDを報告します。設定スキーマ、ページネーション動作、制限事項については、docs/aws.mdを参照してください。

AWS IAM

この統合のための最小読み取り専用ポリシー（架空のアカウントとロググループ）：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "logs:FilterLogEvents",
      "Resource": "arn:aws:logs:us-east-1:123456789012:log-group:/aws/lambda/checkout-api"
    },
    {
      "Effect": "Allow",
      "Action": "cloudwatch:GetMetricData",
      "Resource": "*"
    }
  ]
}

FilterLogEventsは、特定のロググループARNにスコープできます。この統合が発行するMetricStatクエリの場合、GetMetricDataにはAWSのIAM認可モデルにリソースレベルのスコープがないため、そのステートメントはResource: "*"を使用します。これはAPIのプロパティであり、ここでの選択ではありません。

制限付きクエリ

すべての制限付き結果は、requested_boundsとapplied_boundsの両方を報告するため、呼び出し元は正確に何が制限されたかを確認できます。リクエストをハードキャップに制限することは、PARTIALと同じではありません。制限されたが完全に満たされたクエリは、依然としてSUCCESSです。PARTIALは、抽出自体が不完全であることがわかっていることを意味します。たとえば、プロバイダーがページネーションを行い、適用されたウィンドウ内のすべての一致を使い果たす前に停止した場合などです。

データ可用性セマンティクス

2つの直交する質問が、決して1つにまとめられることはありません。

1. このサービスに対して機能が設定されていますか？（CONFIGURED / NOT_CONFIGURED）

2. クエリが実行された場合、何が起こりましたか？（SUCCESS / EMPTY / PARTIAL / FAILED）

ヘルスプロバイダーが設定されていないサービスのヘルスチェックは、NOT_CONFIGUREDであり、EMPTYでもFAILEDでもありません。時間枠内で正当に何も見つからなかったログクエリは、EMPTYであり、FAILEDではありません。使用可能なものを返す前にレート制限に達したメトリクス呼び出しは、理由とともにFAILEDであり、黙って空のデータではありません。

構造化MCP出力

すべてのツールは、型付けされた引数を受け取り、型付けされたPydanticモデルを返します。公式のPython MCP SDKは、その戻り値の型から直接structuredContentとツールの出力スキーマを導出します。ツールの応答は、テキストブロックにラップされたJSON文字列ではなく、実際の構造化データです。

アーキテクチャ

flowchart TD
    subgraph Providers
        Fake[Fake providers]
        AWS[AWS CloudWatch providers]
    end

    Fake --> Services
    AWS --> Services

    Registry[ServiceRegistry] --> Services

    subgraph Services[Deterministic services]
        Catalog[catalog_service]
        Health[health_service]
        Deploy[deployment_service]
        Logs[logs_service]
        Metrics[metrics_service]
        Snapshot[snapshot_service]
    end

    Snapshot --> Deploy
    Snapshot --> Logs
    Snapshot --> Metrics
    Snapshot --> Health

    Services --> Tools[MCP tools]
    Tools --> Agent[AI agent]

get_operational_snapshotはプリミティブサービスを構成します。それらをバイパスしたり、プロバイダーと直接通信したりすることはありません。完全な技術的詳細については、docs/architecture.mdを参照してください。

テスト

• 決定論的なフェイクシナリオは、ツールの全サーフェスをエンドツーエンドでテストします。

• プロバイダーレイヤーのテストでは、意図的に誤動作するスタブプロバイダー（誤った順序付け、無視された境界）を使用して、サービスレイヤーが適切に動作するプロバイダーだけでなく、出力自体を防御することを証明します。

• AWSプロバイダーテストでは、小さなスタブCloudWatchクライアントを使用します。実際のAWS呼び出し、moto、LocalStackは使用しません。

• 1つのテストでは、実際のMCP SDKクライアントをインプロセスサーバーに対して駆動し、内部ロジックだけでなく、プロトコル境界自体（ツール発見、構造化出力）を確認します。

ruff check src tests
mypy src tests --strict
pytest -q

現在の制限事項

• AWSのライブ検証は、型付き設定解析、スタブ化されたクライアントテスト、および実際のMCPクライアント/サーバー境界で行われていますが、実際のAWSアカウントに対してはまだ行われていません。これにはユーザーが選択したリソースが必要であり、意図的に自動化されていません。CloudOps MCPは、アカウントを自動的に発見またはプローブしません。

• AWSバックアップのデプロイメントまたはヘルスプロバイダーはまだありません。

• stdioトランスポートのみで、リモートMCPはありません。

• サービスレジストリは静的で設定に基づいており、クラウドアカウントからのサービスの自動発見はありません。

• 変更、修復、または書き込みパスは一切ありません。

ロードマップ

• 既存のプロバイダーへの追加の読み取り専用機能。

• 2つ目の実際のプロバイダー。複数のベンダーに対して正規化境界をテストします。

• リモートトランスポート。デプロイメントシナリオで実際に必要とされる場合。

• インシデント対応エージェントによる消費。これは汎用MCPクライアントの一例です。CloudOps MCPは特定のコンシューマーに結合されていません。

セキュリティ

• プロバイダーインターフェースにミューテーションメソッドは一切ありません。

• シェル実行やクラウドCLIのサブプロセス呼び出しはありません。

• 最小特権のIAM：logs:FilterLogEvents と cloudwatch:GetMetricData のみで、「念のため」のリクエストは一切ありません。

• 標準のAWS認証チェーンのみ使用し、カスタム認証処理はありません。

• 内部プロバイダー参照（ロググループ名、CloudWatchディメンション）はツール出力に一切表示されません。

• ログコンテンツは信頼できない不透明なテキストとして扱われ、解析、実行、解釈されることはありません。

• 予期しない障害はツール境界でサニタイズされ、固定の汎用メッセージのみが境界を越え、生の例外文字列は決して渡されません。

• すべてのテレメトリクエリは範囲制限されており、プロバイダーAPIとエージェントのコンテキストウィンドウの両方を保護します。

ライセンス

MIT、LICENSE を参照してください。