MCPサーバ - zai-mcp-server
概要
zai-mcp-serverは、GLM-5モデルを活用した画像・動画分析機能を提供するMCP (Model Context Protocol) サーバである。
OpenCode環境において、このサーバを導入することで、単純な画像説明から高度な技術図面の理解、エラー診断、UIデザインからのコード生成まで、幅広い視覚分析タスクを実行できる。
OpenCodeには標準で look_at という画像分析ツールが搭載されているが、zai-mcp-serverはより特化した機能を提供する。
例えば、スクリーンショットからのテキスト抽出 (OCR)、エラー画面の診断、UIスクリーンショットからのコード生成等、特定のタスクに最適化された専用ツールが用意されている。
これらのツールは、ローカルファイルパスまたはURLを指定して使用できる。
各ツールには prompt パラメータがあり、分析の指示を詳細に記述することにより、より精度の高い結果が得られる。
設定は、opencode.json ファイルにMCPサーバ設定を追加するだけで完了する。
APIキーは z.ai から取得できる。
ツール一覧
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 | 動画の内容を分析する。 |
look_at との使い分け
OpenCodeには look_at というビルトインの画像分析ツールが存在する。
zai-mcp-serverツールと look_at の使い分けの基準を以下に示す。
look_atを使用する場合
- PDF、画像、図の一般的な分析・要約
- ドキュメントからの情報抽出
- 「この画像は何？」というシンプルな質問
zai-mcp-serverツールを使用する場合
- 特化したタスク (OCR、UIからコード生成、エラー診断等)
- より精度の高い分析が必要な場合
- 動画の分析が必要な場合
共通パラメータ
全てのツールで共通するパラメータを以下に示す。
| パラメータ | 必須 | 説明 |
|---|---|---|
image_source |
○ | 画像のローカルパス または URL |
prompt |
○ | 何をしてほしいかの指示を記述する。 |
動画分析ツール (analyze_video) の場合は、image_source の代わりに video_source を使用する。
各ツールの詳細
ui_to_artifact
UIスクリーンショットからコード、プロンプト、仕様書、または説明文を生成するツールである。
パラメータ
| パラメータ | 値 | 説明 |
|---|---|---|
image_source |
画像パス or URL | UIスクリーンショットの画像を指定する。 |
output_type |
code |
フロントエンドコードを生成する。 |
prompt |
AIプロンプトを生成する。 | |
spec |
デザイン仕様書を生成する。 | |
description |
自然言語による説明を生成する。 | |
prompt |
文字列 | 生成に関する詳細な指示を記述する。 |
使用例
image_source: "/home/user/ui-mockup.png" output_type: "code" prompt: "Reactコンポーネントとして実装してください。Tailwind CSSを使用。"
このツールはUIデザインのモックアップ画像から実装コードを生成する場合に使用する。
extract_text_from_screenshot
スクリーンショットからテキストを抽出するOCRツールである。
パラメータ
| パラメータ | 説明 |
|---|---|
image_source |
スクリーンショットの画像パス or URL |
prompt |
テキスト抽出の指示を記述する。 |
programming_language |
(任意) コードが含まれる場合、プログラミング言語を指定する。 例: python、javascript、java空欄の場合は自動検出される。 |
使用例
image_source: "/home/user/terminal-output.png" prompt: "ターミナル出力のテキストを抽出してください。" programming_language: ""
このツールはターミナル出力、ドキュメント、コードのスクリーンショットからテキストを抽出する場合に使用する。
diagnose_error_screenshot
エラー画面やスタックトレースを診断し、解決策を提案するツールである。
パラメータ
| パラメータ | 説明 |
|---|---|
image_source |
エラー画面の画像パス or URL |
prompt |
エラーに関する質問や診断の指示を記述する。 |
context |
(任意) エラーが発生した状況の追加情報を記述する。 例: 「npm install実行時に発生」 |
使用例
image_source: "/home/user/error-stacktrace.png" prompt: "このエラーの原因と解決策を教えてください。" context: "npm install 実行時に発生しました。"
このツールはエラーメッセージやスタックトレースの画像から原因を特定し、解決策を得る場合に使用する。
understand_technical_diagram
技術図面 (アーキテクチャ図、UML、ER図、フローチャート等) を理解・説明するツールである。
パラメータ
| パラメータ | 説明 |
|---|---|
image_source |
技術図面の画像パス or URL |
prompt |
図面から何を理解したいかの指示を記述する。 |
diagram_type |
(任意) 図面の種類を指定する。architecture / flowchart / uml / er-diagram / sequence空欄の場合は自動検出される。 |
使用例
image_source: "/home/user/system-architecture.png" prompt: "各コンポーネントの役割とデータフローを説明してください。" diagram_type: "architecture"
このツールはシステム構成図、データベース設計図、シーケンス図等の技術図面を理解する場合に使用する。
analyze_data_visualization
チャート、グラフ、ダッシュボード等のデータ可視化を分析するツールである。
パラメータ
| パラメータ | 説明 |
|---|---|
image_source |
データ可視化の画像パス or URL |
prompt |
何を抽出・分析したいかの指示を記述する。 |
analysis_focus |
(任意) 分析の焦点を指定する。trends (傾向) / anomalies (異常値) / comparisons (比較) / performance metrics (パフォーマンス指標)空欄の場合は包括的な分析が行われる。 |
使用例
image_source: "/home/user/sales-chart.png" prompt: "売上の傾向と異常値を分析してください。" analysis_focus: "trends"
このツールは売上グラフ、パフォーマンスダッシュボード、統計チャート等のデータ可視化を分析する場合に使用する。
ui_diff_check
2つのUIスクリーンショットを比較し、視覚的な差異を特定するツールである。
パラメータ
| パラメータ | 説明 |
|---|---|
expected_image_source |
期待値 (基準) となるUI画像のパス or URL |
actual_image_source |
実装されたUI画像のパス or URL |
prompt |
比較の観点や注目点の指示を記述する。 |
使用例
expected_image_source: "/home/user/design-mockup.png" actual_image_source: "/home/user/implementation-screenshot.png" prompt: "デザインとの差異を具体的に指摘してください。"
このツールはデザインモックアップと実装の比較、UIのリグレッションテストに使用する。
analyze_image
汎用的な画像分析ツールである。
他の特化ツールが適合しない場合のフォールバックとして使用する。
パラメータ
| パラメータ | 説明 |
|---|---|
image_source |
画像のパス or URL |
prompt |
分析の指示を詳細に記述する。 |
使用例
image_source: "/home/user/photo.jpg" prompt: "この画像に写っているものを詳しく説明してください。"
このツールは一般的な画像の説明、写真の分析等に使用する。
analyze_video
動画の内容を分析するツールである。
パラメータ
| パラメータ | 説明 |
|---|---|
video_source |
動画のパス or URL 対応形式: MP4、MOV、M4V 最大ファイルサイズ: 8[MB] |
prompt |
何を分析・理解したいかの指示を記述する。 |
使用例
video_source: "/home/user/demo.mp4" prompt: "動画内で行われている操作手順をステップごとに説明してください。"
このツールはデモ動画の分析、操作手順の抽出、シーンの理解等に使用する。
クイックリファレンス
タスク別の推奨ツールを以下に示す。
| やりたいこと | 推奨ツール |
|---|---|
| UIデザインからコード生成 | ui_to_artifact (output_type: "code")
|
| エラー画面の原因を知りたい | diagnose_error_screenshot |
| 画像からテキストを抽出 | extract_text_from_screenshot |
| システム図を理解したい | understand_technical_diagram |
| グラフからトレンドを読む | analyze_data_visualization |
| デザインと実装を比較 | ui_diff_check |
| 動画の内容を理解 | analyze_video |
| その他の画像分析 | analyze_image または look_at |
設定方法
opencode.jsonへの追加
zai-mcp-serverを使用するには、opencode.jsonファイル の mcp フィールドに設定を追加する。
{
"$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"
}
}
}
}
Node.js v22以降が必要となる。
また、キャッシュされた古いバージョンが使用される場合があるため、挙動がおかしい時は @z_ai/mcp-server@latest を指定、または、npxキャッシュを削除する。
# npxキャッシュの削除方法 npx clear-npx-cache または ## キャッシュの場所を確認 ## 一般的に、~/.npm/_npx に npxキャッシュが存在する npm config get cache rm -rf ~/.npm/_npx ## キャッシュを削除した後、最新バージョンが取得する npx -y @z_ai/mcp-server
APIキーの取得
APIキーは z.ai から取得できる。
設定の確認
設定が正しく追加されている場合、OpenCode起動時にzai-mcp-serverが読み込まれ、ツール一覧に zai-mcp-server_* 形式のツールが表示される。
注意事項
- 動画ファイルは最大8[MB]まで対応している。
- 大きなファイルは事前に圧縮または分割することを推奨する。
- 各ツールは特定の用途に最適化されている。
- 適切なツールを選択することで、より精度の高い結果が得られる。
promptパラメータは詳細に記述するほど、期待通りの結果が得やすくなる。
- 具体的な指示を含めることを推奨する。
関連情報
