VisionAgent MCP Server

VisionAgent MCP サーバー

ベータ – v0.1
このプロジェクトは早期アクセスであり、v1.0 までは破壊的変更が行われる可能性があります。

VisionAgent MCP サーバー v0.1 - 概要

現代の LLM の「エージェント」は、Model Context Protocol (MCP) を通じて外部ツールを呼び出します。VisionAgent MCP は、STDIN/STDOUT 上でローカルに動作する軽量なサイドカー型 MCP サーバーであり、MCP 互換クライアント（Claude Desktop、Cursor、Cline など）からの各ツール呼び出しを、Landing AI の VisionAgent REST API への認証済み HTTPS リクエストに変換します。レスポンスの JSON と、画像やマスクがある場合はそれらもモデルにストリーミングで返されるため、カスタムの REST コードを書いたり追加の SDK を読み込んだりすることなく、エディタから自然言語でコンピュータビジョンや文書解析のコマンドを実行できます。

📸 デモ

https://github.com/user-attachments/assets/2017fa01-0e7f-411c-a417-9f79562627b7

🧰 対応ユースケース（v0.1）

VisionAgent が新しいエンドポイントをリリースするたびに npm run generate-tools を実行してください。このスクリプトは最新の OpenAPI 仕様を取得し、ローカルのツールマップを自動的に再生成します。

🗺 目次

1. クイックスタート
2. 設定
3. プロンプトの例
4. アーキテクチャとフロー
5. 開発者ガイド
6. トラブルシューティング
7. コントリビューション
8. セキュリティとプライバシー

🚀 クイックスタート

VisionAgent API キーを取得する

VisionAgent API キーをお持ちでない場合は、アカウントを作成し、API キーを取得してください。

# 1  Install
npm install -g vision-tools-mcp

# 2  Configure your MCP client with the following settings:
{
  "mcpServers": {
    "VisionAgent": {
      "command": "npx",
      "args": ["vision-tools-mcp"],
      "env": {
        "VISION_AGENT_API_KEY": "<YOUR_API_KEY>",
        "OUTPUT_DIRECTORY": "/path/to/output/directory",
        "IMAGE_DISPLAY_ENABLED": "true" # or false, see below
      }
    }
  }
}

3. MCP 対応クライアントを開きます。
4. street.png をダウンロードします（このディレクトリの assets フォルダーから取得するか、任意のテスト画像を選択できます）。
5. 以下のプロンプト（または任意のプロンプト）を貼り付けます:

Detect all traffic lights in /path/to/mcp/vision-agent-mcp/assets/street.png

お使いのクライアントがインラインリソースをサポートしている場合は、バウンディングボックスのオーバーレイが表示されます。そうでない場合は、PNG が出力ディレクトリに保存され、チャットにそのパスが表示されます。

前提条件

⚙️ 設定

MCP クライアントの設定例（VS Code / Cursor 用の .mcp.json）

{
  "mcpServers": {
    "VisionAgent": {
      "command": "npx",
      "args": ["vision-tools-mcp"],
      "env": {
        "VISION_AGENT_API_KEY": "912jkefief09jfjkMfoklwOWdp9293jefklwfweLQWO9jfjkMfoklwDK",
        "OUTPUT_DIRECTORY": "/Users/me/documents/mcp/test",
        "IMAGE_DISPLAY_ENABLED": "false"
      }
    }
  }
}

Cursor のように画像表示機能を持たない MCP クライアントでは、IMAGE_DISPLAY_ENABLED を False に設定してください。Claude Desktop のように画像表示機能を持つ MCP クライアントでは、IMAGE_DISPLAY_ENABLED を true に設定するとツールの出力を可視化できます。一般的に、リソースをサポートする MCP クライアント（こちらのリストを参照: https://modelcontextprotocol.io/clients）は画像表示をサポートします。

💡 プロンプトの例

🏗 アーキテクチャとフロー

┌────────────────────┐ 1. human prompt            ┌───────────────────┐
│ MCP-capable client │───────────────────────────▶│  VisionAgent MCP │
│  (Cursor, Claude)  │                            │   (this repo)     │
└────────────────────┘                            └─────────▲─────────┘
            ▲  6. rendered PNG / JSON                     │ 2. JSON tool call
            │                                             │
            │ 5. preview path / data         3. HTTPS     │
            │                                             ▼
       local disk  ◀──────────┐                Landing AI VisionAgent
                               └──────────────  Cloud APIs
                                           4. JSON / media blob

1. プロンプト → ツール呼び出し クライアントは自然言語のプロンプトを構造化された MCP 呼び出しに変換します。
2. 検証 サーバーは、ライブの OpenAPI 仕様から生成された Zod スキーマで引数を検証します。
3. 転送 認証済みの Axios リクエストが VisionAgent エンドポイントに到達します。
4. 応答 JSON と base64 メディア（ある場合）が返されます。
5. 可視化 有効になっている場合、マスク / ボックス / 深度マップがファイルにレンダリングされます。
6. チャットへの返却 MCP クライアントがデータとファイルパス（またはインラインプレビュー）を受け取ります。

🧑‍💻 開発者ガイド

コードを詳しく調べたり、新しいエンドポイントを追加したり、問題をトラブルシューティングしたりする方法は次のとおりです。

インストールとビルド

1. リポジトリをクローンします:

   git clone https://github.com/landing-ai/vision-agent-mcp.git
   

2. プロジェクトディレクトリに移動します:

   cd vision-agent-mcp
   

3. 依存関係をインストールします:

   npm install
   

4. プロジェクトをビルドします:

   npm run build
   

環境変数

• VISION_AGENT_API_KEY - VisionAgent 認証用の必須 API キー
• OUTPUT_DIRECTORY - 処理済み出力を保存するためのオプションのディレクトリ（相対パスと絶対パスをサポート）
• IMAGE_DISPLAY_ENABLED - 画像可視化機能を有効にするには "true" に設定します

クライアント設定

ビルド後、次の設定で MCP クライアントを構成します:

{
  "mcpServers": {
    "VisionAgent": {
      "command": "node",
      "args": [
        "/path/to/build/index.js"
      ],
      "env": {
        "VISION_AGENT_API_KEY": "<YOUR_API_KEY>",
        "OUTPUT_DIRECTORY": "../../output",
        "IMAGE_DISPLAY_ENABLED": "true"
      }
    }
  }
}

注意: /path/to/build/index.js をビルドした index.js ファイルへの実際のパスに置き換え、必要に応じて環境変数を設定してください。Cursor のように画像表示機能を持たない MCP クライアントでは、IMAGE_DISPLAY_ENABLED を False に設定してください。Claude Desktop のように画像表示機能を持つ MCP クライアントでは、IMAGE_DISPLAY_ENABLED を true に設定するとツールの出力を可視化できます。一般的に、リソースをサポートする MCP クライアント（こちらのリストを参照: https://modelcontextprotocol.io/clients）は画像表示をサポートします。

📑 スクリプトとコマンド

Pro Tip：src/ 配下のファイルを変更した場合や、VisionAgent の新しいエンドポイントを取り込みたい場合は、npm run build:all を実行して再コンパイルとツール定義の再生成を行ってください。

📂 プロジェクト構成

vision-agent-mcp/
├── .eslintrc.json              # ESLint config (optional)
├── .gitignore                  # Ignore node_modules, build/, .env, etc.
├── jest.config.js              # Placeholder for future unit tests
├── mcp-va.md                   # Draft docs (incomplete)
├── package.json                # npm metadata, scripts, dependencies
├── package-lock.json           # Lockfile
├── tsconfig.json               # TypeScript compiler config
├── .env                        # Your environment variables (not committed)
│
├── src/                        # TypeScript source code
│   ├── generateTools.ts        # Dev script: fetch OpenAPI → generate MCP tool definitions (Zod schemas)
│   ├── index.ts                # Entry point: load .env, start MCP server, handle signals
│   ├── toolDefinitionMap.ts    # Auto-generated MCP tool definitions (don’t edit by hand)
│   ├── toolUtils.ts            # Helpers to build MCP tool objects (metadata, descriptions)
│   ├── types.ts                # Core TS interfaces (MCP, environment config, etc.)
│   │
│   ├── server/                 # MCP server logic
│   │   ├── index.ts            # Create & start the MCP server (Server + Stdio transport)
│   │   ├── handlers.ts         # `handleListTools` & `handleCallTool` implementations
│   │   ├── visualization.ts    # Post-process & save image/video outputs (masks, boxes, depth maps)
│   │   └── config.ts           # Load & validate .env, export SERVER_CONFIG & EnvConfig
│   │
│   ├── utils/                  # Generic utilities
│   │   ├── file.ts             # File handling (base64 encode images/PDFs, read streams)
│   │   └── http.ts             # Axios wrappers & error formatting
│   │
│   └── validation/             # Zod schema generation & argument validation
│       └── schema.ts           # Convert JSON Schema → Zod, validate incoming tool args
│
├── build/                      # Compiled JavaScript (generated after `npm run build`)
│   ├── index.js
│   ├── generateTools.js
│   ├── toolDefinitionMap.js
│   └── …                       # Mirror of `src/` structure
│
├── output/                     # Runtime artifacts (bounding boxes, masks, depth maps, etc.)
│
└── assets/                     # Static assets (e.g., demo.gif)
    └── demo.gif

🔍 主要なコンポーネント

1. src/generateTools.ts

   • https://api.va.landing.ai/openapi.json（VisionAgent の公開 OpenAPI）を取得します。
   • ホワイトリストでエンドポイントをフィルタリングします（フィルタリングを無効にしてすべてを含めることもできます）。
   • JSON Schema → Zod スキーマに変換し、Map<string, McpToolDefinition> を持つ toolDefinitionMap.ts を書き出します。
   • 実行：npm run generate-tools。

2. src/toolDefinitionMap.ts

   • ツール名 → MCP 定義（name、description、inputSchema、endpoint、HTTP メソッド）のマップを含みます。
   • 自動生成されます—手動で編集しないでください。

3. src/server/handlers.ts

   • handleListTools を実装：[ { name, description, inputSchema } ] を返します。

   • handleCallTool を実装：

     • 受信した arguments を Zod で検証します。
     • ファイルベースの引数（例：imagePath、pdfPath）の場合、src/utils/file.ts を介して読み取りと base64 エンコードを行います。
     • Axios 用に multipart/form-data または JSON ペイロードを構築します。
     • VisionAgent エンドポイントを呼び出し、エラーを捕捉し、MCP 準拠の JSON レスポンスを返します。
     • IMAGE_DISPLAY_ENABLED=true の場合、src/server/visualization.ts を呼び出して PNG/JSON を保存します。

4. src/server/visualization.ts

   • マスクを後処理します（base64 → PNG）。
   • 必要に応じて元の画像にバウンディングボックスやセグメンテーションマスクをオーバーレイし、OUTPUT_DIRECTORY に保存します。
   • クライアントがレンダリングできるよう、MCP 結果にファイルパスを返します。

5. src/utils/file.ts

   • readFileAsBase64(path: string): Promise<string>：任意のバイナリ（画像、PDF、動画）を読み取り、base64 を返します。
   • loadFileStream(path: string)：大きなファイルのアップロード用に Node.js ストリームを返します。

6. src/utils/http.ts

   • ベース URL https://api.va.landing.ai で Axios を構成します。
   • Authorization: Bearer ${VISION_AGENT_API_KEY} ヘッダーを追加します。
   • VisionAgent エンドポイントへの呼び出しをラップし、4xx/5xx を処理し、エラーを MCP エラーオブジェクトに整形します。

7. src/validation/schema.ts

   • （OpenAPI からの）JSON Schema → Zod に変換するヘルパーを含みます。
   • generateTools.ts で使用される関数 buildZodSchema(jsonSchema: any): ZodObject を公開します。

8. src/index.ts

   • dotenv を読み込みます（.env を読み取ります）。

   • 必須の環境変数（VISION_AGENT_API_KEY）を検証します。

   • 生成された toolDefinitionMap をインポートします。

   • StdioServerTransport を使用して MCP Server（@modelcontextprotocol/sdk/server から）を作成します。

   • ListTools → handleListTools、CallTool → handleCallTool を接続します。

   • 起動情報をログ出力します：

     vision-tools-api MCP Server (v0.1.0) running on stdio, proxying to https://api.va.landing.ai
     

   • SIGINT/SIGTERM を監視し、正常にシャットダウンします。

🚧 エラーハンドリングとログ

• 検証エラー 無効または不足したパラメーターを送信した場合、サーバーは次を返します：

  {
    "id": 3,
    "error": {
      "code": -32602,
      "message": "Validation error: missing required parameter ‘imagePath’"
    }
  }
  

• ネットワークエラー Axios エラー（タイムアウト、5xx）は捕捉され、次のように返されます：

  {
    "id": 4,
    "error": {
      "code": -32000,
      "message": "VisionAgent API error: 502 Bad Gateway"
    }
  }
  

• 内部例外 ハンドラー内の未捕捉例外は次を生成します：

  {
    "id": 5,
    "error": {
      "code": -32603,
      "message": "Internal error: Unexpected token in JSON at position 345"
    }
  }
  

🛟 トラブルシューティング

npm run generate-tools
npm start

その他の問題については、MCP のドキュメントを参照してください: https://modelcontextprotocol.io/quickstart/user

また、特定のクライアントにはそれぞれの役立つドキュメントがあることに注意してください。たとえば、OpenAI Agents SDK を使用している場合は、こちらのドキュメントを参照してください: https://openai.github.io/openai-agents-python/mcp/

🤝 コントリビューション

PR を歓迎します！

1. Fork → git checkout -b feature/my-feature。
2. npm run typecheck（エラーなし）
3. 何を、なぜ 行ったのかを説明する PR を作成してください。

🔒 セキュリティとプライバシー

• MCP サーバーは ローカル で実行されるため、明示的に呼び出した Landing AI の API エンドポイント以外にファイルが転送されることはありません。
• 出力される画像/マスクは、あなたのマシン上にのみ OUTPUT_DIRECTORY に書き込まれます。
• このプロジェクトによってテレメトリは収集されません。

Made with ❤️ by the LandingAI Team.