MCPサーバ - zai-mcp-serverのソースを表示

== 概要 ==
zai-mcp-serverは、GLM-5モデルを活用した画像・動画分析機能を提供するMCP (Model Context Protocol) サーバである。<br>
<br>
OpenCode環境において、このサーバを導入することで、単純な画像説明から高度な技術図面の理解、エラー診断、UIデザインからのコード生成まで、幅広い視覚分析タスクを実行できる。<br>
<br>
OpenCodeには標準で <u>look_at</u> という画像分析ツールが搭載されているが、zai-mcp-serverはより特化した機能を提供する。<br>
例えば、スクリーンショットからのテキスト抽出 (OCR)、エラー画面の診断、UIスクリーンショットからのコード生成等、特定のタスクに最適化された専用ツールが用意されている。<br>
<br>
これらのツールは、ローカルファイルパスまたはURLを指定して使用できる。<br>
各ツールには <code>prompt</code> パラメータがあり、分析の指示を詳細に記述することにより、より精度の高い結果が得られる。<br>
<br>
設定は、<u>opencode.json</u> ファイルにMCPサーバ設定を追加するだけで完了する。<br>
APIキーは z.ai から取得できる。<br>
<br><br>

== ツール一覧 ==
zai-mcp-serverが提供するツールの一覧を以下に示す。<br>
<br>
<center>
{| class="wikitable"
|+ zai-mcp-server ツール一覧
! ツール名 !! 用途
|-
| ui_to_artifact || UIスクリーンショットからコード、プロンプト、仕様、説明を生成する。
|-
| extract_text_from_screenshot || スクリーンショットからテキストを抽出する (OCR)。
|-
| diagnose_error_screenshot || エラー画面やスタックトレースを診断する。
|-
| understand_technical_diagram || 技術図面 (アーキテクチャ図、UML、ER図、フローチャート) を理解する。
|-
| analyze_data_visualization || チャート、グラフ、ダッシュボードを分析する。
|-
| ui_diff_check || 2つのUIスクリーンショットを比較する。
|-
| analyze_image || 汎用的な画像分析を行う (他の特化ツールが合わない場合のフォールバック)。
|-
| analyze_video || 動画の内容を分析する。
|}
</center>
<br><br>

== look_at との使い分け ==
OpenCodeには <u>look_at</u> というビルトインの画像分析ツールが存在する。<br>
<br>
zai-mcp-serverツールと <u>look_at</u> の使い分けの基準を以下に示す。<br>
<br>
==== look_atを使用する場合 ====
* PDF、画像、図の一般的な分析・要約
*: ドキュメントからの情報抽出
*: 「この画像は何？」というシンプルな質問
<br>
==== zai-mcp-serverツールを使用する場合 ====
* 特化したタスク (OCR、UIからコード生成、エラー診断等)
*: より精度の高い分析が必要な場合
*: 動画の分析が必要な場合
<br><br>

== 共通パラメータ ==
全てのツールで共通するパラメータを以下に示す。<br>
<br>
<center>
{| class="wikitable"
|+ 共通パラメータ
! パラメータ !! 必須 !! 説明
|-
| <code>image_source</code> || ○ || 画像のローカルパス または URL
|-
| <code>prompt</code> || ○ || 何をしてほしいかの指示を記述する。
|}
</center>
<br>
動画分析ツール (<u>analyze_video</u>) の場合は、<code>image_source</code> の代わりに <code>video_source</code> を使用する。<br>
<br><br>

== 各ツールの詳細 ==
==== ui_to_artifact ====
UIスクリーンショットからコード、プロンプト、仕様書、または説明文を生成するツールである。<br>
<br>
===== パラメータ =====
<center>
{| class="wikitable"
|+ ui_to_artifact パラメータ
! パラメータ !! 値 !! 説明
|-
| <code>image_source</code> || 画像パス or URL || UIスクリーンショットの画像を指定する。
|-
| <code>output_type</code> || <code>code</code> || フロントエンドコードを生成する。
|- 
| || <code>prompt</code> || AIプロンプトを生成する。
|-
| || <code>spec</code> || デザイン仕様書を生成する。
|-
| || <code>description</code> || 自然言語による説明を生成する。
|-
| <code>prompt</code> || 文字列 || 生成に関する詳細な指示を記述する。
|}
</center>
<br>
===== 使用例 =====
 image_source: "/home/user/ui-mockup.png"
 output_type: "code"
 prompt: "Reactコンポーネントとして実装してください。Tailwind CSSを使用。"
<br>
このツールはUIデザインのモックアップ画像から実装コードを生成する場合に使用する。<br>
<br>
==== extract_text_from_screenshot ====
スクリーンショットからテキストを抽出するOCRツールである。<br>
<br>
===== パラメータ =====
<center>
{| class="wikitable"
|+ extract_text_from_screenshot パラメータ
! パラメータ !! 説明
|-
| <code>image_source</code> || スクリーンショットの画像パス or URL
|-
| <code>prompt</code> || テキスト抽出の指示を記述する。
|-
| <code>programming_language</code> || (任意) コードが含まれる場合、プログラミング言語を指定する。<br>例: <code>python</code>、<code>javascript</code>、<code>java</code><br>空欄の場合は自動検出される。
|}
</center>
<br>
===== 使用例 =====
 image_source: "/home/user/terminal-output.png"
 prompt: "ターミナル出力のテキストを抽出してください。"
 programming_language: ""
<br>
このツールはターミナル出力、ドキュメント、コードのスクリーンショットからテキストを抽出する場合に使用する。<br>
<br>
==== diagnose_error_screenshot ====
エラー画面やスタックトレースを診断し、解決策を提案するツールである。<br>
<br>
===== パラメータ =====
<center>
{| class="wikitable"
|+ diagnose_error_screenshot パラメータ
! パラメータ !! 説明
|-
| <code>image_source</code> || エラー画面の画像パス or URL
|-
| <code>prompt</code> || エラーに関する質問や診断の指示を記述する。
|-
| <code>context</code> || (任意) エラーが発生した状況の追加情報を記述する。<br>例: 「npm install実行時に発生」
|}
</center>
<br>
===== 使用例 =====
 image_source: "/home/user/error-stacktrace.png"
 prompt: "このエラーの原因と解決策を教えてください。"
 context: "npm install 実行時に発生しました。"
<br>
このツールはエラーメッセージやスタックトレースの画像から原因を特定し、解決策を得る場合に使用する。<br>
<br>
==== understand_technical_diagram ====
技術図面 (アーキテクチャ図、UML、ER図、フローチャート等) を理解・説明するツールである。<br>
<br>
===== パラメータ =====
<center>
{| class="wikitable"
|+ understand_technical_diagram パラメータ
! パラメータ !! 説明
|-
| <code>image_source</code> || 技術図面の画像パス or URL
|-
| <code>prompt</code> || 図面から何を理解したいかの指示を記述する。
|-
| <code>diagram_type</code> || (任意) 図面の種類を指定する。<br><code>architecture</code> / <code>flowchart</code> / <code>uml</code> / <code>er-diagram</code> / <code>sequence</code><br>空欄の場合は自動検出される。
|}
</center>
<br>
===== 使用例 =====
 image_source: "/home/user/system-architecture.png"
 prompt: "各コンポーネントの役割とデータフローを説明してください。"
 diagram_type: "architecture"
<br>
このツールはシステム構成図、データベース設計図、シーケンス図等の技術図面を理解する場合に使用する。<br>
<br>
==== analyze_data_visualization ====
チャート、グラフ、ダッシュボード等のデータ可視化を分析するツールである。<br>
<br>
===== パラメータ =====
<center>
{| class="wikitable"
|+ analyze_data_visualization パラメータ
! パラメータ !! 説明
|-
| <code>image_source</code> || データ可視化の画像パス or URL
|-
| <code>prompt</code> || 何を抽出・分析したいかの指示を記述する。
|-
| <code>analysis_focus</code> || (任意) 分析の焦点を指定する。<br><code>trends</code> (傾向) / <code>anomalies</code> (異常値) / <code>comparisons</code> (比較) / <code>performance metrics</code> (パフォーマンス指標)<br>空欄の場合は包括的な分析が行われる。
|}
</center>
<br>
===== 使用例 =====
 image_source: "/home/user/sales-chart.png"
 prompt: "売上の傾向と異常値を分析してください。"
 analysis_focus: "trends"
<br>
このツールは売上グラフ、パフォーマンスダッシュボード、統計チャート等のデータ可視化を分析する場合に使用する。<br>
<br>
==== ui_diff_check ====
2つのUIスクリーンショットを比較し、視覚的な差異を特定するツールである。<br>
<br>
===== パラメータ =====
<center>
{| class="wikitable"
|+ ui_diff_check パラメータ
! パラメータ !! 説明
|-
| <code>expected_image_source</code> || 期待値 (基準) となるUI画像のパス or URL
|-
| <code>actual_image_source</code> || 実装されたUI画像のパス or URL
|-
| <code>prompt</code> || 比較の観点や注目点の指示を記述する。
|}
</center>
<br>
===== 使用例 =====
 expected_image_source: "/home/user/design-mockup.png"
 actual_image_source: "/home/user/implementation-screenshot.png"
 prompt: "デザインとの差異を具体的に指摘してください。"
<br>
このツールはデザインモックアップと実装の比較、UIのリグレッションテストに使用する。<br>
<br>
==== analyze_image ====
汎用的な画像分析ツールである。<br>
他の特化ツールが適合しない場合のフォールバックとして使用する。<br>
<br>
===== パラメータ =====
<center>
{| class="wikitable"
|+ analyze_image パラメータ
! パラメータ !! 説明
|-
| <code>image_source</code> || 画像のパス or URL
|-
| <code>prompt</code> || 分析の指示を詳細に記述する。
|}
</center>
<br>
===== 使用例 =====
 image_source: "/home/user/photo.jpg"
 prompt: "この画像に写っているものを詳しく説明してください。"
<br>
このツールは一般的な画像の説明、写真の分析等に使用する。<br>
<br>
==== analyze_video ====
動画の内容を分析するツールである。<br>
<br>
===== パラメータ =====
<center>
{| class="wikitable"
|+ analyze_video パラメータ
! パラメータ !! 説明
|-
| <code>video_source</code> || 動画のパス or URL<br>対応形式: MP4、MOV、M4V<br>最大ファイルサイズ: 8[MB]
|-
| <code>prompt</code> || 何を分析・理解したいかの指示を記述する。
|}
</center>
<br>
===== 使用例 =====
 video_source: "/home/user/demo.mp4"
 prompt: "動画内で行われている操作手順をステップごとに説明してください。"
<br>
このツールはデモ動画の分析、操作手順の抽出、シーンの理解等に使用する。<br>
<br><br>

== クイックリファレンス ==
タスク別の推奨ツールを以下に示す。<br>
<br>
<center>
{| class="wikitable"
|+ タスク別推奨ツール
! やりたいこと !! 推奨ツール
|-
| UIデザインからコード生成 || ui_to_artifact (<code>output_type: "code"</code>)
|-
| エラー画面の原因を知りたい || diagnose_error_screenshot
|-
| 画像からテキストを抽出 || extract_text_from_screenshot
|-
| システム図を理解したい || understand_technical_diagram
|-
| グラフからトレンドを読む || analyze_data_visualization
|-
| デザインと実装を比較 || ui_diff_check
|-
| 動画の内容を理解 || analyze_video
|-
| その他の画像分析 || analyze_image または <u>look_at</u>
|}
</center>
<br><br>

== 設定方法 ==
==== opencode.jsonへの追加 ====
zai-mcp-serverを使用するには、<u>opencode.jsonファイル</u> の <code>mcp</code> フィールドに設定を追加する。<br>
<br>
 <syntaxhighlight lang="json">
 {
   "$schema": "https://opencode.ai/config.json",
   "mcp": {
     "zai-mcp-server": {
       "type": "local",
       "command": ["npx", "-y", "@z_ai/mcp-server"],
       "environment": {
         "Z_AI_API_KEY": "<Z.AIのAPIキー>",
         "Z_AI_MODE": "ZAI"
       }
     }
   }
 }
 </syntaxhighlight>
<br>
Node.js v22以降が必要となる。<br>
また、キャッシュされた古いバージョンが使用される場合があるため、挙動がおかしい時は <code>@z_ai/mcp-server@latest</code> を指定、または、npxキャッシュを削除する。<br>
<br>
 # npxキャッシュの削除方法
 
 npx clear-npx-cache
 
 または
 
 ## キャッシュの場所を確認
 ## 一般的に、~/.npm/_npx に npxキャッシュが存在する
 npm config get cache
 rm -rf ~/.npm/_npx
 
 ## キャッシュを削除した後、最新バージョンが取得する
 npx -y @z_ai/mcp-server
<br>
==== APIキーの取得 ====
APIキーは [https://z.ai z.ai] から取得できる。<br>
<br>
==== 設定の確認 ====
設定が正しく追加されている場合、OpenCode起動時にzai-mcp-serverが読み込まれ、ツール一覧に <code>zai-mcp-server_*</code> 形式のツールが表示される。<br>
<br><br>

== 注意事項 ==
* 動画ファイルは最大8[MB]まで対応している。<br>
*: 大きなファイルは事前に圧縮または分割することを推奨する。
*: <br>
* 各ツールは特定の用途に最適化されている。<br>
*: 適切なツールを選択することで、より精度の高い結果が得られる。
*: <br>
* <code>prompt</code> パラメータは詳細に記述するほど、期待通りの結果が得やすくなる。<br>
*: 具体的な指示を含めることを推奨する。
<br><br>

== 関連情報 ==
* [https://z.ai Z.AIの公式サイト]
<br><br>


{{#seo:
|title={{PAGENAME}} : Exploring Electronics and SUSE Linux | MochiuWiki
|keywords=MochiuWiki,Mochiu,Wiki,Mochiu Wiki,zai-mcp-server,GLM-5,画像分析,OCR,UI分析,動画分析,AI,OpenCode,MCP
|description={{PAGENAME}} - GLM-5モデルを使用した画像・動画分析ツールの使い方と設定方法 | This page is {{PAGENAME}} in our wiki about electronic circuits and SUSE Linux
|image=/resources/assets/MochiuLogo_Single_Blue.png
}}

__FORCETOC__
[[カテゴリ:設定]]