##############
Tips
##############

Github Copilot + Flux MCP Server
====================================

Flux MCP Server
-------------------

FluxMCPServer_ はFluxCDが開発しているMCP(Model Context Protocol)で、AIアシスタント(Github Copilot等)がkubernetesクラスターと対話するための専用ツールです。
Fluxリソース/アプリケーションログ等の調査や、リソースの依存関係の可視化、リソースの操作ができ、最新のFlux公式ドキュメントを使用して、最新情報と推奨事項を提案してくれます。

.. WARNING::

   FluxMCPServerは実験的な機能であり、調査の「補助ツール」としてご利用下さい。

Flux MCP Serverインストール
-----------------------------------

以下、Mac環境のインストール方法です。

環境の前提は以下。

* MacOS(14.7.6)
* VSCode(1.104.0)
* GitHub Copilot plugin(1.370.1783)

.. code-block:: console
   :caption: flux-operator-mcp install

   brew install controlplaneio-fluxcd/tap/flux-operator-mcp

利用しているVSCodeのsettings.jsonと同階層にmcp.jsonを配置します。

.. code-block:: json
   :caption: /Users/<user>/Library/Application Support/Code/User/mcp.json

   {
      "servers": {
         "flux-operator-mcp": {
               "command": "/usr/local/bin/flux-operator-mcp",
               "args": [
                  "serve"
               ],
               "env": {
                  "KUBECONFIG": "/Users/<user>/.kube/config"
               }
         }
      }
   }

VSCodeに設定ができると、 ``VSCodeの拡張機能 > MCPサーバー`` から以下が確認できます。

.. figure:: static/images/flux-operator-mcp.png
   :scale: 50

VSCodeのGithub Copilotを開き、 ``Agent モード`` になっていることを確認して、利用します。

.. figure:: static/images/github-copilot-agent.png
   :scale: 50

Flux MCP Server(リモートSSH)
-----------------------------------

リモートSSHして、VSCodeを利用する場合、以下の設定が必要になります。
拡張機能のGitHub Copilotのインストールは、ローカル端末のみで、リモートSSH側にインストールは不要です。

.. code-block:: json
   :caption: /Users/<user>/Library/Application Support/Code/User/settings.json

   {
      "remote.extensionKind": {
         "*": [
               "workspace"
         ],
         "GitHub.copilot": [
               "ui"
         ],
         "GitHub.copilot-chat": [
               "ui"
         ]
      }
   }

加えて、リモートサーバ側への設定として、コマンドパレット ``MCP: リモート ユーザ構成を開く`` から以下の設定を行います。

.. code-block:: json
   :caption: ~/.vscode-server/data/User/mcp.json

   {
      "servers": {
         "flux-operator-mcp": {
            "command": "/usr/local/bin/flux-operator-mcp",
            "args": [
               "serve"
            ],
            "env": {
               "KUBECONFIG": "/home/user/.kube/config"
            }
         }
      }
   }

FluxMCPの動作確認
-----------------------------------

以下のプロンプトにて、接続可能なkubernetesのコンテキストを表示します。

.. code-block:: txt
   :caption: FluxMCPの動作確認プロンプト

   #flux-operator-mcp
   コンテキスト一覧を表示して

FluxMCPが動作している場合、以下の表示が出力されます。

.. figure:: static/images/flux-mcp-check.png
   :scale: 60

もし、上記の表示が出力されない場合は、 ``VSCodeの拡張機能 > MCPサーバー`` を確認して、FluxMCPの起動を確認します。
FluxMCPが起動していない場合は、 ``サーバーの起動`` をクリックします。

.. figure:: static/images/flux-mcp-start.png
   :scale: 60

FluxMCPの操作制限
-----------------------------------

プロンプトによっては、kubernetesのリソースを変更/削除ができてしまう為、以下の設定を変更して、操作できないように制限を行います。

VSCodeのGithub Copilotを開き、以下のアイコンをクリックします。

.. figure:: static/images/github-copilot-tool.png
   :scale: 80

``ツールの構成`` より、 ``get/search/set`` だけを残します。

.. figure:: static/images/github-copilot-tool-check.png
   :scale: 80

プロンプト例
-----------------------------------

特定のリリース種別でエラーになっているリソースがないか確認する場合は、以下のようなプロンプトで問合せします。

.. code-block:: txt
   :caption: helmreleases調査プロンプト

   #flux-operator-mcp
   helmreleasesでエラーになっている対象はありますか？
   limit 100

.. WARNING::

   リソース数が多い場合は、問合せ件数に制限がかかる場合があるので、リリース数に応じて、limitの数値を調整が必要です。

特定のリソースのエラーを調査したい場合は、以下のようなプロンプトで問合せします。

.. code-block:: txt
   :caption: 特定のリソース調査プロンプト

   #flux-operator-mcp
   kind <リソース種別>
   ns <ネームスペース名>
   name <リソース名>
   のエラーを調査して

FluxMCPのチャットリセット
-----------------------------------

チャット流れから回答する場合があるので、最新の状態を問合せしたい場合は、以下のように新規チャットに切り替えてして、問合せすることをオススメします。

.. figure:: static/images/flux-mcp-reset.png
   :scale: 80

調査事例
-----------------------------------

以下のマニフェストで意図的にエラーの状況にします。
★の設定により、podがエラーになります。
原因としては、Windows Nodeに、Linuxのコンテナイメージをデプロイしようとしている為、エラーになります。

.. code-block:: yaml
   :caption: cron-tmp.yaml

   apiVersion: managed.msp.sbopsv/v1alpha1
   kind: Application
   metadata:
   name: "sample-cronjob"
   namespace: "staging"
   spec:
   chart:
      name: cronjob
      version: "1.1.17"
   settings:
      command:
         - "echo"
         - "AI Test"
      restartPolicy: "OnFailure"
      parallelism: 3
      completions: 1
      schedule: "0 * * * *"
      timeZone: "Asia/Tokyo"
      completionMode: "NonIndexed"
      concurrencyPolicy: "Allow"
      suspend: false
      successfulJobsHistoryLimit: 1
      failedJobsHistoryLimit: 1
      image:
         repository: "busybox" ★
         tag: "1.35"
      nodeSelector:
         kubernetes.io/os: windows ★
      tolerations:
         - effect: NoExecute
         key: os
         operator: Equal
         value: win

以下のように、調査結果と対策案を提示してくれます。

.. figure:: static/images/flux-mcp-pod-error.png
   :scale: 70

次に、修正すべきファイルを特定します。

.. WARNING::

   VSCodeで該当のマニフェストが存在するリポジトリを開いている必要があります。

.. figure:: static/images/flux-mcp-pod-error-file.png
   :scale: 50

次に、ファイルの修正案を提示してもらいます。

.. figure:: static/images/flux-mcp-pod-error-file-fix.png
   :scale: 50

.. _`FluxMCPServer`: https://fluxcd.control-plane.io/mcp/