Linux診断MCPサーバー - 講義デモ

オリジナルの MCPDemo 教育用リポジトリをPython/Linux向けに翻案したものです。このリポジトリは、公開教育フローにおけるマイルストーン4の同等性に到達しました。コンパクトなシステム調査、Linuxプロセスの詳細調査、リソースとしてのログスナップショット、ワークフロープロンプト、および /mcp 上でのHTTP経由の認証付きMCPが含まれます。

このデモの内容

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

• ✅ ツール: get_system_info、get_process_list、get_process_by_id、get_process_by_name 用の読み取り専用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を使用

• ✅ 複数のテスト手法

• ⏳ 引き出し（Elicitation）、サンプリング、ルートは後日予定

クイックスタート

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. システム、プロセス、ログスナップショットのフローを実行

7. 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"
      }
    }
  }
}

Inspectorが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 - 特定のPIDの詳細なLinuxプロセス情報を返します

• get_process_by_name - プロセス名に対するページングされた詳細なプロセス情報を返します

  • デフォルトは page_number=1

  • デフォルトは page_size=5

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

ログスナップショット

• 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} - 保存されたスナップショットから特定のページを読み取ります

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

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

• キャプチャされた行

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

プロンプト

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

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

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

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

プロジェクト

src/mcp_linux_diag_server/server.py

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

src/mcp_linux_diag_server/client.py

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

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

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

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

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

テスト手法

基本的な講義フローの基礎となっているマイルストーン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
│           ├── 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）、サンプリング、ルート

ライセンス

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

リソース

• Model Context Protocol

• MCP Inspector

• Azure OpenAI

• オリジナルのC# MCPDemo