🌀

🌀 Clarifai MCP Server (unofficial)

Name: 🌀 Clarifai MCP Server (unofficial)
Author: tot-ra

本地服务

github.com/tot-raAI 与智能体276 周前更新

代码仓库

关于 🌀 Clarifai MCP Server (unofficial)

这是一款非官方的本地 MCP 服务，用于连接 MCP 客户端与 Clarifai API，提供图像生成、推理和可搜索的只读资源，并避免大量二进制结果占用大模型上下文。

主要功能

01根据文本提示词生成图像
02对本地图像或 URL 执行推理
03上传本地文件至 Clarifai
04按文本或图像搜索输入
05列出并读取 Clarifai 资源

适用场景

01根据 AI Agent 提示生成图像
02描述或分析本地图像
03按文本或图像相似度查找 Clarifai 输入

MCP 相关

通过 stdio 将 Clarifai 操作作为 MCP 工具和只读资源提供。客户端可生成图像、执行推理、搜索以及列出或读取 Clarifai 实体。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

暂未收录安装方式

我们还没有获取到这个服务的安装包或远程地址，请按项目 README 中的说明安装。

代码仓库

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

🌀 Clarifai MCP 服务（非官方）

这个黑客日项目提供了一个模型上下文协议（MCP）服务，作为通往 Clarifai API 的桥梁，旨在用户的机器上运行（即本地运行）。它允许 MCP 客户端（例如 IDE 扩展）通过标准 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 Agent 可以自动调用图像生成工具，并将结果放到桌面上

使用 Clarifai 生成 3 张猫咪图像

README 配图

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）：**服务提供用于发现可用资源的模板：
- **输入：**列出、搜索、获取
  - clarifai://{user_id}/{app_id}/inputs
  - clarifai://{user_id}/{app_id}/inputs?query={search_term}
  - clarifai://{user_id}/{app_id}/inputs/{input_id}
- **注释：**列出、搜索、获取、按输入列出
  - 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
- **模型：**列出、搜索、获取
  - clarifai://{user_id}/{app_id}/models
  - clarifai://{user_id}/{app_id}/models?query={search_term}
  - clarifai://{user_id}/{app_id}/models/{model_id}
- **模型版本：**列出、获取
  - clarifai://{user_id}/{app_id}/models/{model_id}/versions
  - clarifai://{user_id}/{app_id}/models/{model_id}/versions/{version_id}
- **数据集：**列出、获取
  - clarifai://{user_id}/{app_id}/datasets
  - clarifai://{user_id}/{app_id}/datasets/{dataset_id}
- **数据集版本：**列出（尚未实现读取特定版本）
  - 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 对象（输入、模型、注释等）的完整详情。
- 结果以 JSON 字符串的形式返回在资源内容的 text 字段中。

架构概览

服务通过标准输入（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：通过标准输入输出管理核心 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 命令行标志提供的个人访问令牌（PAT）。该令牌会包含在发往 Clarifai API 的 gRPC 请求元数据中。

支持 Markdown

登录后评论