Harvester MCP Server

Harvester MCP サーバー

重要

これはコミュニティプロジェクトであり、Harvester による公式サポートはありません。Harvester が公式にサポートしている MCP サーバーをお探しの場合は、harvester/harvester-mcp-server をご利用ください。

Harvester HCI 用の Model Context Protocol（MCP）サーバーです。Claude Desktop、Cursor などの AI アシスタントが、MCP プロトコルを通じて Harvester クラスターと連携できるようにします。

概要

Harvester MCP Server は、Harvester HCI 専用に設計された、Model Context Protocol（MCP） の Go 実装です。Claude Desktop や Cursor などの AI アシスタントが、Harvester 固有の CRD を備えた Kubernetes クラスターである Harvester クラスターに対して CRUD 操作を実行できます。

ワークフロー

以下の図は、Harvester MCP Server が AI アシスタントと Harvester クラスターをどのようにつなぐかを示しています。

graph LR;
    subgraph "AI Assistants"
        A[Claude Desktop] --> C[MCP Client];
        B[Cursor IDE] --> C;
    end
    
    subgraph "Harvester MCP Server"
        C --> D[MCP Server];
        D --> E[Resource Handler];
        E --> F[Formatter Registry];
        F -->|Get Formatter| G[Core Resource Formatters];
        F -->|Get Formatter| H[Harvester Resource Formatters];
    end
    
    subgraph "Kubernetes / Harvester"
        G --> I[Kubernetes API];
        H --> I;
        I --> J[Harvester Cluster];
    end
    
    style A fill:#f9f,stroke:#333,stroke-width:2px;
    style B fill:#f9f,stroke:#333,stroke-width:2px;
    style D fill:#bbf,stroke:#333,stroke-width:2px;
    style J fill:#bfb,stroke:#333,stroke-width:2px;

動作の仕組み

1. LLM との連携：Claude Desktop や Cursor などの AI アシスタントが、MCP プロトコルを介して Harvester MCP Server に接続します。
2. リクエストの処理：MCP サーバーは AI アシスタントから自然言語のリクエストを受け取り、具体的な Kubernetes 操作に変換します。
3. リソースの処理：リソースハンドラーが、要求されたリソースの種類と操作を特定します。
4. フォーマッターの選択：フォーマッターレジストリーが、リソースの種類に適したフォーマッターを選択します。
5. API との連携：サーバーが Harvester クラスターの Kubernetes API と連携します。
6. レスポンスの整形：結果を LLM が利用しやすい、人が読みやすいテキスト形式に整えます。
7. ユーザーへの提示：整形されたレスポンスが AI アシスタントに返され、ユーザーに提示されます。

このアーキテクチャにより、AI アシスタントは自然言語を通じて Harvester クラスターと連携でき、複雑な Kubernetes 操作をユーザーにとってより利用しやすくします。

機能

• Kubernetes のコアリソース：

  • Pod：一覧表示、取得、削除
  • Deployment：一覧表示、取得
  • Service：一覧表示、取得
  • Namespace：一覧表示、取得
  • Node：一覧表示、取得
  • カスタムリソース定義（CRD）：一覧表示

• Harvester 固有のリソース：

  • 仮想マシン：一覧表示、取得
  • イメージ：一覧表示
  • ボリューム：一覧表示
  • ネットワーク：一覧表示

• ユーザーエクスペリエンスの向上：

  • すべてのリソースを人が読みやすい形式で出力
  • 名前空間またはステータスごとにリソースを自動グループ化
  • 関連性の高い情報を含む簡潔な概要
  • リソースを詳細に確認できる詳細表示

要件

• Go 1.23 以降
• 有効な kubeconfig を使用した Harvester クラスターへのアクセス

インストール

ソースから

# Clone the repository
git clone https://github.com/starbops/harvester-mcp-server.git
cd harvester-mcp-server

# Build
make build

# Run
./bin/harvester-mcp-server

Go Install を使用

go install github.com/starbops/harvester-mcp-server/cmd/harvester-mcp-server@latest

設定

サーバーは、以下の順序で Kubernetes の設定を自動的に検索します。

1. クラスター内の設定（Kubernetes クラスター内で実行されている場合）
2. --kubeconfig フラグで指定されたパス
3. KUBECONFIG 環境変数で指定されたパス
4. デフォルトの場所 ~/.kube/config

コマンドラインフラグ

Usage:
  harvester-mcp-server [flags]

Flags:
  -h, --help                help for harvester-mcp-server
      --kubeconfig string   Path to the kubeconfig file (default is $KUBECONFIG or $HOME/.kube/config)
      --log-level string    Log level (debug, info, warn, error, fatal, panic) (default "info")

例

特定の kubeconfig ファイルを使用する場合：

harvester-mcp-server --kubeconfig=/path/to/kubeconfig.yaml

KUBECONFIG 環境変数を使用する場合：

export KUBECONFIG=$HOME/config.yaml
harvester-mcp-server

デバッグログを有効にする場合：

harvester-mcp-server --log-level=debug

Claude Desktop での使用

1. Claude Desktop をインストールします
2. Claude Desktop の設定ファイル（~/Library/Application\ Support/Claude/claude_desktop_config.json など）を開きます
3. Harvester MCP サーバーを mcpServers セクションに追加します。

{
  "mcpServers": {
    "harvester": {
      "command": "/path/to/harvester-mcp-server",
      "args": ["--kubeconfig", "/path/to/kubeconfig.yaml", "--log-level", "info"]
    }
  }
}

4. Claude Desktop を再起動します
5. Harvester MCP ツールが Claude で利用できるようになります

Claude Desktop 向けのクエリ例

Harvester MCP サーバーを Claude Desktop で設定すると、次のような質問をできます。

• 「Harvester クラスターにはノードがいくつありますか？」
• 「cattle-system 名前空間内のすべての Pod を一覧表示してください」
• 「cattle-system 名前空間にある rancher-789c976c6-xbvmd という名前の Pod の詳細を表示してください」
• 「default 名前空間内のすべての仮想マシンを一覧表示してください」
• 「harvester-system 名前空間では、どのサービスが実行されていますか？」

開発

プロジェクト構成

• cmd/harvester-mcp-server：メインアプリケーションのエントリーポイント
• pkg/client：Kubernetes クライアントの実装
• pkg/cmd：Cobra を使用した CLI コマンドの実装
• pkg/mcp：MCP サーバーの実装
• pkg/kubernetes：Kubernetes リソース向けの統合リソースハンドラー
• pkg/tools：Harvester リソースを操作するための従来のツール実装

リソースの処理

このプロジェクトでは、Kubernetes リソースを処理するために統合的なアプローチを採用しています。

1. pkg/kubernetes/resources.go ファイルには、すべてのリソースタイプに共通する操作を提供する ResourceHandler が含まれています。

   • 適切な名前空間処理を伴うリソースの一覧表示
   • 名前によるリソースの詳細取得
   • リソースの作成と更新
   • リソースの削除

2. pkg/kubernetes/formatters*.go ファイルには、さまざまなリソースタイプ向けのフォーマッターが含まれています。

   • 各フォーマッターは、生の Kubernetes オブジェクトを人が読みやすいテキストに変換します
   • リソース固有の詳細を抽出し、一貫した方法で整形します
   • 標準の Kubernetes リソースと Harvester 固有のリソースの両方に、カスタムフォーマッターがあります

3. pkg/kubernetes/types.go ファイルでは、わかりやすいリソースタイプ名を Kubernetes の GroupVersionResource オブジェクトに対応付けています。

   • コード内で簡単な名前を使ってリソースを参照できます
   • リソースタイプの定義を一元管理します

新しいツールの追加

新しいツールを追加するには、次の手順に従います。

1. 新しいリソースタイプの場合は、pkg/kubernetes/types.go に追加します
2. フォーマッターファイルのいずれかで、そのリソース用のフォーマッターを実装します
3. 統合リソースハンドラーを使用して、pkg/mcp/server.go の registerTools メソッドでツールを登録します

フォーマット関数

各リソースタイプには、次の2つのフォーマット関数があります。

1. formatXList：名前空間ごとにグループ化し、簡潔な情報とともにリソースの一覧を整形します
2. formatX：単一のリソースを詳細情報とともに整形します

ライセンス

このプロジェクトは Apache License 2.0 の下でライセンスされています。詳細については、LICENSE ファイルを参照してください。

謝辞

• Harvester HCI：このプロジェクトの基盤
• mark3labs/mcp-go：Model Context Protocol 向けの Go SDK
• manusa/kubernetes-mcp-server：Kubernetes MCP サーバーのリファレンス実装