Asset Management MCP

Cloudinary资产管理MCP服务器

摘要

目录

• Cloudinary资产管理MCP服务器

- 安装 - 配置 - 认证 - 可用工具 - 定制工具 - 渐进式发现

• 发展

- 从源头构建 - 贡献

安装

Claude Desktop

使用预构建的作为桌面扩展安装MCP服务器 mcp-server.mcpb 文件：

只需拖放 mcp-server.mcpb 将文件安装到Claude Desktop上以安装扩展。

MCP捆绑包包括MCP服务器和所有必要的配置。安装后，服务器将无需额外设置即可使用。

\[！注意\] MCP捆绑包提供了一种简化的方式来打包和分发MCP服务器。更多了解 桌面扩展.

Cursor


或手动：

1. 打开光标设置
2. 选择工具和集成
3. 选择新MCP服务器
4. 如果配置文件为空，请将以下JSON粘贴到MCP服务器配置中：

{
  "command": "npx",
  "args": [
    "@cloudinary/asset-management-mcp",
    "start",
    "--api-key",
    "",
    "--api-secret",
    "",
    "--cloud-name",
    ""
  ]
}

Claude Code CLI

claude mcp add CloudinaryAssetMgmt -- npx -y @cloudinary/asset-management-mcp start --api-key  --api-secret  --cloud-name 

Gemini

gemini mcp add CloudinaryAssetMgmt -- npx -y @cloudinary/asset-management-mcp start --api-key  --api-secret  --cloud-name 

Windsurf

参见 官方Windsurf文档 获取最新信息

1. 打开风帆设置
2. 在左侧菜单中选择Cascade
3. 点击 Manage MCPs（要管理MCP，您应该使用Windsurf帐户登录）
4. 点击 View raw config 打开mcp配置文件。
5. 如果配置文件为空，请粘贴完整的json

{
  "command": "npx",
  "args": [
    "@cloudinary/asset-management-mcp",
    "start",
    "--api-key",
    "",
    "--api-secret",
    "",
    "--cloud-name",
    ""
  ]
}

VS Code


或手动：

参见 官方VS Code文档 获取最新信息

1. 打开 命令面板
2. 搜索并打开 MCP: Open User Configuration。这应该会打开mcp.json文件
3. 如果配置文件为空，请粘贴完整的json

{
  "command": "npx",
  "args": [
    "@cloudinary/asset-management-mcp",
    "start",
    "--api-key",
    "",
    "--api-secret",
    "",
    "--cloud-name",
    ""
  ]
}

Stdio installation via npm To start the MCP server, run:

npx @cloudinary/asset-management-mcp start --api-key  --api-secret  --cloud-name 

有关服务器参数的完整列表，请运行：

npx @cloudinary/asset-management-mcp --help

配置

环境变量

MCP服务器支持以下环境变量：

CLOUDINARY_URL格式

您可以使用单个 CLOUDINARY_URL 而不是单个变量：

CLOUDINARY_URL=cloudinary://API_KEY:API_SECRET@CLOUD_NAME

响应标头集合

您可以将服务器配置为包含Cloudinary API响应头（例如 x-request-id 以及工具输出中的速率限制信息。这对于调试和监控非常有用。

集 CLOUDINARY_COLLECT_HEADERS 控制收集哪些标头：

# Collect all response headers
CLOUDINARY_COLLECT_HEADERS=true

# Collect specific headers by exact name (comma-separated)
CLOUDINARY_COLLECT_HEADERS=x-request-id,x-featureratelimit-limit,x-featureratelimit-remaining

# Mix exact names, prefix matching, and regex matching
CLOUDINARY_COLLECT_HEADERS=x-request-id,prefix:x-featureratelimit-

标题匹配规格

逗号分隔列表中的每个条目都与响应标头名称相匹配：

您也可以通过以下方式进行设置 CLOUDINARY_URL 查询参数：

CLOUDINARY_URL=cloudinary://API_KEY:API_SECRET@CLOUD_NAME?collect_headers=true

启用后，收集的标头将显示在 _headers 工具响应中的字段。如果未设置，则不会收集任何标头，响应也不会改变。

MCP应用程序

服务器可以公开交互式MCP UI 应用 （规格与 io.modelcontextprotocol/ui)主机可以与工具结果一起呈现，例如，列表结果的资产库、单个资产详细视图和上传UI。

应用程序是 选择加入.使用 --mcp-apps 标志（两者都有 start 和 serve)或 CLOUDINARY_MCP_APPS 环境变量来启用它们：

可用应用程序名称： asset-gallery, asset-details, asset-upload.

# Enable all apps via CLI flag (bare flag implies "all")
npx @cloudinary/asset-management-mcp start --mcp-apps

# Equivalent: explicit value
npx @cloudinary/asset-management-mcp start --mcp-apps all

# Enable just the gallery via env var
CLOUDINARY_MCP_APPS=asset-gallery npx @cloudinary/asset-management-mcp start

# Explicitly disable
npx @cloudinary/asset-management-mcp serve --mcp-apps none

优先级：CLI标志>环境变量>内置默认值。

认证

MCP服务器使用您的Cloudinary API密钥和机密进行身份验证：

{
  "env": {
    "CLOUDINARY_CLOUD_NAME": "demo",
    "CLOUDINARY_API_KEY": "123456789012345",
    "CLOUDINARY_API_SECRET": "abcdefghijklmnopqrstuvwxyz12"
  }
}

可用工具

MCP服务器将Cloudinary的资产管理API公开为工具。使用您的AI应用程序来发现和调用可用的工具，用于上传、管理、搜索和转换您的媒体资产。

用法示例

示例1：上传和转换图像

1. Upload a local image: "Upload file:///Users/me/photo.jpg to Cloudinary as 'hero-image'"
2. Transform it: "Transform asset 'hero-image' with transformations 'c_fill,w_800,h_600/e_sharpen'"
3. Get details: "Show me details for asset with ID [asset-id]"

示例2：搜索和组织资产

1. Search for images: "Find all images with tag 'product' uploaded in the last 7 days"
2. Create folder: "Create a new folder called 'summer-2024-products'"
3. List assets: "Show me all video assets in the 'marketing' folder"

示例3：生成存档

1. Get transformation docs: "Show me the Cloudinary transformation reference"
2. Apply transformations: "Transform 'banner' asset with 'c_scale,w_1200/f_auto,q_auto'"
3. Create archive: "Generate a ZIP archive of all images with tag 'export-ready'"

示例4：资产管理工作流

1. Upload multiple files: "Upload all images from folder /assets/new-products/"
2. Add tags: "Update asset [asset-id] and add tags 'featured,homepage'"
3. Get usage stats: "Show my Cloudinary account usage statistics"

定制工具

此MCP服务器包括两个强大的自定义工具：

get-tx-reference

检索完整的Cloudinary转换参考文档。

何时使用：

• 在创建或修改转换之前
• 当用户询问图像/视频效果、大小调整、裁剪、滤镜时

例子：

Use get-tx-reference to learn about available transformations

transform-asset

使用Cloudinary的显式API将转换应用于现有资产。

参数：

• publicId -资产的公共ID
• transformations -转换字符串（例如。， c_fill,w_300,h_200)
• resourceType -类型： image, video，或 raw （默认值： image)
• invalidate -CDN缓存无效（默认值： false)

例子：

Transform asset "sample" with transformations "c_fill,w_500,h_500/e_sepia"

渐进式发现

具有许多工具的MCP服务器可能会使LLM上下文窗口膨胀，导致令牌使用增加和工具混乱。动态模式通过只公开一小部分元工具来解决这个问题，这些元工具让代理根据需要逐步发现和调用工具。

要启用动态模式，请传递 --mode dynamic 启动服务器时标记：

{
  "mcpServers": {
    "CloudinaryAssetMgmt": {
      "command": "npx",
      "args": ["@cloudinary/asset-management-mcp", "start", "--mode", "dynamic"],
      // ... other server arguments
    }
  }
}

在动态模式下，服务器只注册以下元工具，而不是每个单独的工具：

• list_tools：列出所有可用工具及其名称和描述。
• describe_tool_input：按名称返回一个或多个工具的输入架构。
• execute_tool：按名称及其参数执行工具。
• list_scopes：列出服务器上可用的作用域。

这种方法显著减少了每次请求时发送到LLM的令牌数量，这对于具有大量工具的服务器特别有用。

您可以将动态模式与范围和工具过滤器相结合：

{
  "mcpServers": {
    "CloudinaryAssetMgmt": {
      "command": "npx",
      "args": ["@cloudinary/asset-management-mcp", "start", "--mode", "dynamic", "--scope", "admin"],
      // ... other server arguments
    }
  }
}

发展

从源头构建

先决条件

• Node.js v20或更高版本
• npm、pnpm、包子或纱线

构建步骤

# Clone the repository
git clone https://github.com/cloudinary/asset-management-mcp.git
cd asset-management-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run locally
npm start

项目结构

asset-management-mcp/
├── src/
│   ├── hooks/              # SDK hooks (manual)
│   │   ├── cloudinaryAuthHook.ts   # Auth & file:// handling
│   │   ├── customHeadersHook.ts    # Inject custom request headers
│   │   ├── responseHeadersHook.ts  # Collect response headers
│   │   ├── userAgentHook.ts        # Build User-Agent string
│   │   └── registration.ts         # Hook registration
│   ├── mcp-server/         # MCP server implementation
│   │   ├── server.ts             # Main server (auto-generated)
│   │   ├── server.extensions.ts  # Custom tools & app wiring (manual)
│   │   ├── tools/                # Generated tool wrappers
│   │   └── apps/                 # MCP UI Apps (manual)
│   │       ├── config.ts             # App registry & --mcp-apps parsing
│   │       ├── cli-flag.ts           # stricli flag definition
│   │       ├── extensions.ts         # Resource-template registration
│   │       ├── uri.ts                # App URI helpers / tool-name injection
│   │       ├── tool-hooks.ts         # Per-tool app hooks
│   │       ├── app-shared.ts         # Shared app utilities
│   │       ├── asset-gallery-app.ts  # List results gallery UI
│   │       ├── asset-details-app.ts  # Single-asset detail UI
│   │       └── asset-upload-app.ts   # Upload UI
│   ├── funcs/              # API function implementations
│   └── models/             # Type definitions
├── .github/
│   └── workflows/          # CI/CD workflows
└── .speakeasy/             # Speakeasy configuration

贡献

虽然我们重视对该MCP服务器的贡献，但大多数代码都是通过Cloudinary API规范以编程方式生成的。对生成文件的任何手动更改都将在下一代中被覆盖-请将您的更改指向下面的手动扩展点。

您可以贡献什么：

• 自定义工具和服务器接线 src/mcp-server/server.extensions.ts
• MCP UI应用程序 src/mcp-server/apps/ （图库、详细信息、上传和新应用程序）
• SDK挂钩 src/hooks/ （身份验证、自定义标头、响应标头、用户代理）
• 文档改进（本自述文件、JSDoc手册文件）
• 错误报告

生成的文件（不可编辑）：

• src/mcp-server/server.ts
• src/mcp-server/tools/*.ts
• src/funcs/*.ts
• src/models/*.ts

当不可避免地要接触生成的文件时，最好在中更新上游规范或Speakeasy配置 .speakeasy/ 因此，这种变化在再生过程中得以幸存。

我们期待着您的反馈。请随时打开PR或问题，并提供概念证明，我们将尽最大努力将其纳入未来的版本中。

______________________________________________________________________

MCP服务器由创建 地下酒吧