🌀 Clarifai MCP Server (unofficial)

🌀 Clarifai MCP サーバー（非公式）

このハックデイプロジェクトは、Clarifai API へのブリッジとして機能する Model Context Protocol（MCP）サーバーを提供します。ユーザーのマシン上で（つまりローカルで）実行することを想定しています。MCP クライアント（IDE 拡張機能など）は、重いバイナリ結果で LLM のコンテキストを圧迫することなく、標準の MCP リクエストを使って、画像生成や推論などの Clarifai の機能を利用できます。

MCP サーバーを設定してシームレスに連携する

通常、サーバーは MCP クライアントのフレームワークによって自動的に起動されます（例：VS Code の設定経由）。設定では通常、ビルド済みバイナリのパスと、Clarifai PAT などの必要なコマンドライン引数を指定します。Go（バージョン 1.23 以降）が必要です。

cd ~
git clone [email protected]:tot-ra/clarifai-mcp-server-local.git
cd clarifai-mcp-server-local
go mod tidy

バイナリをビルドする： go build コマンドを使い、cmd/server ディレクトリ内のメインパッケージをビルドします。必要に応じて出力先と対象アーキテクチャを指定してください（macOS ARM の例）：

# For macOS ARM
make build

# For Linux AMD64
# GOOS=linux GOARCH=amd64 go build -o ./mcp_binary ./...

# For Windows AMD64
# GOOS=windows GOARCH=amd64 go build -o ./mcp_binary.exe ./...

これにより、プロジェクトのルートディレクトリに mcp_binary という名前の実行可能ファイル（Windows では mcp_binary.exe）が作成されます。

MCP 設定の記述例（cline_mcp_settings.json）。たとえば Cline では次のようになります。

{
  "mcpServers": {
    "clarifai": {
      "command": "~/clarifai-mcp-server-local/mcp_binary",
      "args": [
        "--pat", "YOUR_CLARIFAI_PAT",
        "--output-path", "~/Desktop/",
        "--default-user-id", "your_user_id",
        "--default-app-id", "your_app_id",
      ],
    }
  }
}

YOUR_CLARIFAI_PAT を Clarifai PAT トークンに置き換えてください。

テスト

いくつかのパッケージに単体テストが追加されています。すべてのテストを実行し、キャッシュを無効にして、詳細な出力（個々のテスト名とステータスを含む）を確認するには、次のコマンドを実行します。

cd clarifai-mcp-server-local
go test -v -count=1 ./...

機能

現在、サーバーは次の MCP 機能を公開しています。

ツール

• upload_file：ローカルファイルを入力として Clarifai にアップロードします。

  • 入力：filepath（必須、ローカルファイルへの絶対パス）、user_id、app_id（任意）。
  • 出力：アップロード成功時のテキスト確認メッセージと API レスポンスの詳細。

• generate_image：指定した、またはデフォルトの Clarifai テキスト画像生成モデルを使って、テキストプロンプトに基づく画像を生成します。

  • 入力：text_prompt（必須）、model_id、user_id、app_id（任意）。
  • 出力：Base64 エンコードされた画像データ（小さな画像の場合）、またはファイルパス（設定済みの --output-path に保存される大きな画像の場合）。

たとえば、ユーザーがプロンプトを入力すると、AI エージェントが自動的に画像生成を呼び出し、 結果をデスクトップに保存します。

Clarifaiで猫の画像を3枚生成してください。

• clarifai_image_by_path：指定した、またはデフォルトの Clarifai モデルを使って、ローカル画像ファイルに対して推論を実行します。
  • 入力：filepath（必須、ローカル画像へのパス）、model_id、user_id、app_id（任意）。
  • 出力：推論結果のテキストによる説明（検出された概念など）。

my_source_folder/images/内の画像をclarifaiで処理してください。

• clarifai_image_by_url：指定した、またはデフォルトの Clarifai モデルを使って、画像 URL に対して推論を実行します。

  • 入力：image_url（必須）、model_id、user_id、app_id（任意）。
  • 出力：推論結果のテキストによる説明（検出された概念など）。

• search_by_text：Clarifai の PostInputSearches を使って、テキストクエリに基づき入力を検索します。

  • 入力：query（必須、テキストクエリ文字列）、user_id、app_id、page、per_page（任意）。
  • 出力：検索結果（ヒット）を含む JSON 文字列。

• search_by_filepath：Clarifai の PostInputSearches を使って、ローカル画像ファイルとの類似性に基づき入力を検索します。

  • 入力：filepath（必須、ローカル画像ファイルへの絶対パス）、user_id、app_id、page、per_page（任意）。
  • 出力：検索結果（ヒット）を含む JSON 文字列。

• search_by_url：Clarifai の PostInputSearches を使って、画像 URL との類似性に基づき入力を検索します。

  • 入力：image_url（必須、画像の URL）、user_id、app_id、page、per_page（任意）。
  • 出力：検索結果（ヒット）を含む JSON 文字列。

### リソース（読み取り専用）

サーバーはさまざまな Clarifai エンティティを読み取り専用の MCP リソースとして公開しており、クライアントは標準の MCP メソッド（resources/list、resources/read）を使用してデータの一覧表示、検索、読み取りを行えます。エンティティの作成、更新、削除などの操作は、MCP ツールを使用して行います。

• リソース URI スキーム： リソースは一貫した URI 構造に従います： clarifai://{user_id}/{app_id}/{resource_type}[/{resource_id}][?query_params] モデルバージョンやデータセットバージョンなどのネストされたリソースは、次のような形式に従います： clarifai://{user_id}/{app_id}/models/{model_id}/versions[/{version_id}] clarifai://{user_id}/{app_id}/datasets/{dataset_id}/versions[/{version_id}] clarifai://{user_id}/{app_id}/inputs/{input_id}/annotations

• サポートされているリソーステンプレート（resources/templates/list）： サーバーは、利用可能なリソースを検出するためのテンプレートを提供します：

  • Inputs： 一覧表示、検索、取得
    • clarifai://{user_id}/{app_id}/inputs
    • clarifai://{user_id}/{app_id}/inputs?query={search_term}
    • clarifai://{user_id}/{app_id}/inputs/{input_id}
  • Annotations： 一覧表示、検索、取得、Input ごとの一覧表示
    • clarifai://{user_id}/{app_id}/annotations
    • clarifai://{user_id}/{app_id}/annotations?query={search_term}
    • clarifai://{user_id}/{app_id}/annotations/{annotation_id}
    • clarifai://{user_id}/{app_id}/inputs/{input_id}/annotations
  • Models： 一覧表示、検索、取得
    • clarifai://{user_id}/{app_id}/models
    • clarifai://{user_id}/{app_id}/models?query={search_term}
    • clarifai://{user_id}/{app_id}/models/{model_id}
  • Model Versions： 一覧表示、取得
    • clarifai://{user_id}/{app_id}/models/{model_id}/versions
    • clarifai://{user_id}/{app_id}/models/{model_id}/versions/{version_id}
  • Datasets： 一覧表示、取得
    • clarifai://{user_id}/{app_id}/datasets
    • clarifai://{user_id}/{app_id}/datasets/{dataset_id}
  • Dataset Versions： 一覧表示（特定のバージョンの読み取りはまだ実装されていません）
    • clarifai://{user_id}/{app_id}/datasets/{dataset_id}/versions

• 一覧表示（resources/list）：

  • テンプレート URI（例：clarifai://.../inputs）を使用して、その種類のリソースを一覧表示します。cursor パラメーター（ページ番号を表します）によるページネーションに対応しています。
  • 検索テンプレート URI（例：clarifai://.../inputs?query=cats）を使用して、リソースを検索します。
  • URI を指定せずに呼び出すと、--default-user-id と --default-app-id フラグで設定されたコンテキスト内の入力がデフォルトで一覧表示されます（設定されている場合）。

• 読み取り（resources/read）：

  • 特定のリソース URI（例：clarifai://.../models/{model_id}）を使用して、対応する Clarifai オブジェクト（Input、Model、Annotation など）の詳細全体を取得します。
  • 結果は、リソースコンテンツの text フィールドに JSON 文字列として返されます。

アーキテクチャの概要

サーバーは標準入力（stdin）で JSON-RPC 2.0 リクエストを待ち受け、標準出力（stdout）で応答を送信します。これにより、MCP クライアントフレームワークとシームレスに統合できます。

コンポーネント構成：

コードベースはいくつかの主要なパッケージで構成されています。

graph TD
    subgraph "clarifai-mcp-server-local"
        direction LR
        CmdServer["cmd/server (main)"] --> MCP["mcp (JSON-RPC/stdio)"]
        CmdServer --> Config["config (Flags)"]
        CmdServer --> Tools["tools (Handlers)"]
        CmdServer --> Resources["resources (Handlers)"]

        MCP --> Tools
        MCP --> Resources

        Tools --> ClarifaiClient["clarifai (gRPC Client)"]
        Tools --> Utils["utils (Filesystem)"]
        Tools --> Config

        Resources --> ClarifaiClient
        Resources --> Config

        ClarifaiClient --> Config
    end

    subgraph External
        MCPClient["MCP Client (e.g., IDE)"] -- stdio --> MCP
        ClarifaiClient -- gRPC --> ClarifaiAPI["Clarifai API"]
    end

    style MCPClient fill:#f9f,stroke:#333,stroke-width:2px
    style ClarifaiAPI fill:#ccf,stroke:#333,stroke-width:2px

• cmd/server：設定の初期化、MCP サーバーインスタンスのセットアップ、ハンドラーの登録を担当する、アプリケーションのメインエントリポイントです。
• config：コマンドラインフラグの解析を処理し、設定値（PAT、出力パスなど）を保持します。
• mcp：stdio を介した MCP 通信の中核となるループを管理し、受信した JSON-RPC リクエストを解析して、メソッド（tools/call、resources/list、resources/read など）に応じて適切なハンドラーに振り分けます。
• clarifai：Clarifai API と連携するための gRPC クライアントロジックを含みます。認証（リクエストへの PAT の追加）や API 呼び出しを行います。
• tools：公開する各 MCP ツール（generate_image、clarifai_image_by_path、clarifai_image_by_url）のロジックを実装します。これらのハンドラーは clarifai クライアントを使用して処理を実行します。
• resources：MCP リソースリクエスト（resources/list、resources/read）を処理するロジックを実装します。これらのハンドラーは clarifai クライアントを使用してデータを取得します。
• utils：生成した画像をローカルファイルシステムに保存するなどのユーティリティ関数を提供します。

リクエストの流れ：

次のシーケンス図は、ツールおよびリソースのリクエストを処理する際の一般的な流れを示しています。

sequenceDiagram
    participant Client as MCP Client (e.g., IDE)
    participant Server as clarifai-mcp-server (Go)
    participant Clarifai as Clarifai API (gRPC)
    participant Filesystem as Local Filesystem

    Client->>+Server: JSON-RPC Request (stdio)
    Server->>Server: Parse JSON-RPC Request (mcp)

    alt Tool Call (e.g., generate_image, clarifai_image_by_path, clarifai_image_by_url)
        Server->>Server: Route to Tool Handler (tools)
        Server->>Server: Extract tool parameters
        Server->>Server: Create gRPC Request (clarifai)
        Server->>Server: Add PAT to gRPC Context Metadata (clarifai)
        Server->>+Clarifai: Call Clarifai API (gRPC)
        Clarifai-->>-Server: gRPC Response (Data/Error)
        alt generate_image and image is large
            Server->>+Filesystem: Save image to disk (utils, config)
            Filesystem-->>-Server: File path
            Server->>Server: Format JSON-RPC Response (with file path) (mcp)
        else Tool Response (or small image)
            Server->>Server: Format JSON-RPC Response (with data/results) (mcp)
        end
    else Resource Call (e.g., resources/list, resources/read)
        Server->>Server: Route to Resource Handler (resources)
        Server->>Server: Parse URI and parameters
        alt resources/list or search
            Server->>+Clarifai: Call Clarifai List/Search API (gRPC) (clarifai)
            Clarifai-->>-Server: gRPC Response (List of items/Error)
            Server->>Server: Format JSON-RPC Response (List of Resources) (mcp)
        else resources/read
            Server->>+Clarifai: Call Clarifai Get API (gRPC) (clarifai)
            Clarifai-->>-Server: gRPC Response (Item details/Error)
            Server->>Server: Format JSON-RPC Response (Resource Content) (mcp)
        end
    else Other MCP Request (e.g., initialize, tools/list)
        Server->>Server: Handle request internally (mcp)
        Server->>Server: Format JSON-RPC Response (mcp)
    end
    Server-->>-Client: JSON-RPC Response (stdio)

認証には、--pat コマンドラインフラグで指定した Personal Access Token（PAT）を使用します。このトークンは、Clarifai API への送信 gRPC リクエストのメタデータに含まれます。