Linux Diagnostics MCP Server - 講義デモ

オリジナルの MCPDemo 教育用リポジトリをPython/Linux向けに適合させたものです。このリポジトリは、公開教育フローにおけるマイルストーン7のパリティに到達しました。コンパクトなシステム調査、Linuxプロセスの詳細調査、リソースとしてのログスナップショット、ワークフロープロンプト、/mcp 上でのHTTP経由の認証付きMCP、プロセス終了前の明示的な確認（elicitation）、サンプリング支援によるLinux診断、および許可されたルートの /proc および /sys スナップショットが含まれます。

このデモの内容

この講義デモには以下が含まれます：

• ✅ ツール: get_system_info、get_process_list、get_process_by_id、get_process_by_name、および確認（elicitation）ゲート付きの kill_process 用のLinux診断ツール

• ✅ リソース: ページング可能な syslog://snapshot/... ログスナップショットリソース

• ✅ プロンプト: エラー分析、CPU調査、セキュリティレビュー、健全性診断のためのMCPワークフロープロンプト

• ✅ HTTPトランスポート: http://127.0.0.1:5000/mcp 上でのストリーミング可能なMCP

• ✅ APIキー認証: X-API-Key ヘッダーまたは ?apiKey=secure-mcp-key

• ✅ AIチャットクライアント: ローカルHTTPサーバーを起動し、モデルがMCPツール、プロンプト、リソースを呼び出せるようにし、ターミナルでのローカルフォーム確認を処理するPython Azure OpenAIクライアント

• ✅ Python 3.12実装（公式MCP Python SDKを使用）

• ✅ 複数のテスト手法

• ✅ マイルストーン5: kill_process のための確認（elicitation）

• ✅ マイルストーン6: サンプリング支援によるLinux診断

• ✅ マイルストーン7: 読み取り専用 /proc および /sys スナップショットのためのルート

Related MCP server: troubleshooting-mcp-server

クイックスタート

1. インストール

サーバーのみのインストール:

python3 -m pip install --user --break-system-packages -e .

講義用チャットクライアントの追加機能のインストール:

python3 -m pip install --user --break-system-packages -e '.[llm]'

2. クイックスモークテスト (LLMなし)

python3 scripts/smoke_test.py

このスクリプトは以下のことを行います:

1. ローカルHTTP MCPサーバーを起動

2. APIキーなしで 401 Unauthorized になることを確認

3. /mcp でMCP初期化ハンドシェイクを実行

4. mcp-session-id フローがリクエスト間で機能することを確認

5. ツール、プロンプト、リソーステンプレートを検出

6. システム、プロセス、ログスナップショット、procスナップショット、およびサンプリング支援診断フローを実行

7. クライアントが確認（elicitation）サポートをアドバタイズしていない場合に kill_process が安全に失敗することを確認

8. Azure OpenAI設定が欠落している場合に講義用チャットクライアントが安全に失敗することを確認

3. サーバーを手動で実行

python3 -m mcp_linux_diag_server

サーバーは以下でリッスンします:

• エンドポイント: http://127.0.0.1:5000/mcp

• デモ用APIキー: secure-mcp-key

4. MCP InspectorまたはVS Code MCP設定でテスト

1つのターミナルでサーバーを起動し、上記のHTTPエンドポイントを使用して接続します。

このリポジトリには、必要なヘッダーを含む .vscode/mcp.json が含まれています:

{
  "servers": {
    "linux-diag-demo": {
      "url": "http://127.0.0.1:5000/mcp",
      "headers": {
        "X-API-Key": "secure-mcp-key"
      }
    }
  }
}

インスペクターがURLを直接受け入れる場合は、このクエリ文字列形式も機能します:

http://127.0.0.1:5000/mcp?apiKey=secure-mcp-key

5. 講義用チャットクライアントの使用

サンプル環境ファイルをコピーし、ローカルのAzure OpenAI設定を入力します:

cp .env.example .env.local
$EDITOR .env.local
python3 -m mcp_linux_diag_server.client --prompt "Summarize this machine."

オリジナルの.NET認証フローをより厳密にミラーリングするには、以下を設定します:

MCP_DEMO_AZURE_OPENAI_USE_DEFAULT_CREDENTIAL=true

そしてAPIキーを省略します。

インタラクティブチャットを実行:

python3 -m mcp_linux_diag_server.client

または単一のプロンプトを実行:

python3 -m mcp_linux_diag_server.client --prompt "What is the system information?"

ツール

システム情報

• get_system_info - コンパクトなLinuxまたはWSLシステムスナップショットを返します

  • ホスト名

  • 現在のユーザー

  • Linuxディストリビューションの説明

  • カーネルリリース

  • アーキテクチャ

  • 論理CPU数

  • Pythonランタイム

  • 現在の作業ディレクトリ

  • 稼働時間

  • ロードアベレージ

  • メモリの概要

  • WSL検出フラグ

プロセス調査

• get_process_list - 名前とPIDを含む実行中プロセスの軽量リストを返します

• get_process_by_id - 1つのPIDの詳細なLinuxプロセス情報を返します

• get_process_by_name - プロセス名の詳細なプロセス情報をページングして返します

  • デフォルトは page_number=1

  • デフォルトは page_size=5

  • オリジナルのデモの「リストが先、詳細が後」という教育フローを維持

• kill_process - 明示的な確認（elicitation）の後にのみLinuxプロセスを終了します

  • process_id が省略された場合、サーバーはCPU消費量の多いプロセスをサンプリングし、クライアントに1つ選択するように求めます

  • サーバーは常に CONFIRM PID {pid} という入力された確認フレーズを要求します

  • 講義用クライアントは、stdin/stdoutがインタラクティブな場合、ターミナルでこれらのプロンプトをローカルに処理します

• troubleshoot_linux_diagnostics - サンプリングを使用して、自然言語のLinux診断の質問を検証済みの /proc または /sys 読み取りに変換します

  • サーバーは、何かを読み取る前に、サンプリングされたパスとフィールドを許可リストと照合して検証します

  • 正確なPython適合: サンプリングされたクエリは、WQLではなく、単一の安全な PATH または PATH | grep FIELD 行です

  • サーバーは再度サンプリングを行い、観察結果をユーザーに要約します

• create_proc_snapshot - 許可された /proc または /sys パスから不変の読み取り専用スナップショットを作成し、リソースURIを返します

  • ファイルスナップショットは行ごとにコンテンツをページングします

  • ディレクトリスナップショットはシンボリックリンクをたどらずに決定論的な子メタデータをページングします

  • 何かを読み取る前に明示的に許可されたルートを強制します

• request_proc_access - 確認（elicitation）を使用して、追加の /proc または /sys ルートへの読み取り専用アクセスを要求します

  • 承認されたルートをサーバーのメモリ内許可リストに追加します

  • ブロックされたスナップショット試行の前に、モデルがプロアクティブにアクセスを要求できるようにします

ログスナップショット

• create_log_snapshot - 一般的なLinuxログファイルから不変のスナップショットを作成し、リソースURIを返します

  • system、security、kernel、package ロググループをサポート

  • オプションの filter_text でスナップショットを一致する行に絞り込みます

  • ベースリソースURIとページングされたリソーステンプレートを返します

リソース

• syslog://snapshot/{snapshot_id} - デフォルトのページングで保存されたLinuxログスナップショットを読み取ります

• syslog://snapshot/{snapshot_id}?limit={limit}&offset={offset} - 保存されたスナップショットから特定のページを読み取ります

• proc://snapshot/{snapshot_id} - デフォルトのページングで保存されたproc/sysスナップショットを読み取ります

• proc://snapshot/{snapshot_id}?limit={limit}&offset={offset} - 保存されたproc/sysスナップショットから特定のページを読み取ります

すべてのリソース読み取りは以下を返します:

• スナップショットメタデータ

• キャプチャされたエントリ

• ページングメタデータ (total_count, returned_count, limit, offset, has_more, next_offset)

プロンプト

• AnalyzeRecentApplicationErrors - エラーに焦点を当てたログ分析ワークフロー

• ExplainHighCpu - CPU負荷の高いプロセスとLinuxログを関連付けます

• DetectSecurityAnomalies - 不審なプロセスと認証/セキュリティログの証拠をレビューします

• DiagnoseSystemHealth - エンドツーエンドのシステム健全性ワークフロー

• TroubleshootLinuxComponent - エージェントを troubleshoot_linux_diagnostics に誘導する集中的な詳細調査ワークフロー

プロジェクト

src/mcp_linux_diag_server/server.py

マイルストーン1〜7の診断ツール、リソース、ワークフロープロンプトを公開する認証済みHTTP MCPサーバー。

src/mcp_linux_diag_server/client.py

以下の機能を持つ講義用チャットクライアント:

• ローカルHTTPサーバーの起動

• デモAPIキーを使用したストリーミング可能なHTTP経由での接続

• モデルのヘルパーツールとしてMCPプロンプト/リソースAPIを公開

• モデルが kill_process をトリガーしたときにローカルターミナルでMCPフォーム確認を実行

• サーバーが安全なLinux診断クエリと要約を合成できるようにMCPサンプリングリクエストを実行

• ブロックされたパスをスナップショットする前にproc/sysアクセスを要求するようにモデルを指導

• ツール呼び出しターンの実行

テスト手法

ベースの講義フローを支えるマイルストーン1の検証チェックリストについては、M1_VALIDATION_GUIDE.md を参照してください。

プロジェクト構造

MCPPythonDemo/
├── README.md
├── LICENSE.txt
├── pyproject.toml
├── .env.example
├── .vscode/
│   └── mcp.json
├── scripts/
│   └── smoke_test.py
├── src/
│   └── mcp_linux_diag_server/
│       ├── __main__.py
│       ├── client.py
│       ├── http_config.py
│       ├── server.py
│       └── tools/
│           ├── log_snapshots.py
│           ├── proc_snapshots.py
│           ├── processes.py
│           └── system_info.py
├── tests/
│   ├── http_harness.py
│   ├── test_client.py
│   ├── test_m1_smoke.py
│   ├── test_m2_smoke.py
│   ├── test_m3_smoke.py
│   ├── test_m4_http.py
│   ├── test_log_snapshots.py
│   ├── test_processes.py
│   └── test_system_info.py

要件

• Python 3.12+

• mcp[cli]

• 講義用チャットクライアントを実行する場合のみAzure OpenAI

マイルストーン

✅ マイルストーン1 - stdio経由の最小限の診断ツールと講義用チャットクライアント ✅ マイルストーン2 - プロセス調査 ✅ マイルストーン3 - ログスナップショットリソースとプロンプト ✅ マイルストーン4 - HTTPトランスポートとセキュリティ ✅ マイルストーン5 - 確認（elicitation）ベースの kill_process ✅ マイルストーン6 - サンプリング支援によるLinux診断 ✅ マイルストーン7 - ルートとproc/sysスナップショット

ライセンス

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

リソース

• Model Context Protocol

• MCP Inspector

• Azure OpenAI

• オリジナルのC# MCPDemo