云化资产管理 MCP 服务器

内容提要

目录

• 云化资产管理 MCP 服务器
  • 安装
  • 配置
  • 认证
  • 可用工具
  • 自定义工具
  • 进步发现
• 发展
  • 来源建筑
  • 捐款

安装

MCP服务器需要Node.js 20.19.0或更晚.

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

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

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

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

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

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

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

配置

环境变量

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

克洛迪纳里-乌尔尔 格式

你可以用单曲 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.

Apps为 默认启用。使用 --mcp-apps 旗帜(可同时使用) start 财务报告和审定财务报表 serve)或为: CLOUDINARY_MCP_APPS 覆盖此行为的环境变量 :

可用的应用程序名称 : asset-gallery, (中文(简体) ), asset-details, (中文(简体) ), asset-upload。 。 。 .

# Disable all apps
npx @cloudinary/asset-management-mcp serve --mcp-apps none

# Enable only the gallery
npx @cloudinary/asset-management-mcp start --mcp-apps asset-gallery

# Disable via env var
CLOUDINARY_MCP_APPS=none npx @cloudinary/asset-management-mcp start

优先: 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

检索完整的"云变"参考文献.

何时使用 :

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

示例

Use get-tx-reference to learn about available transformations

transform-asset

使用 Cloudinary 的 API 来应用变换到现有的资产 .

参数:

• publicId - 该资产的公共身份
• 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服务器可以 bloat 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
    }
  }
}

发展

来源建筑

先决条件

• 节点.js v20 或以上
• npm, pnpm, bun, 或纱线

构建步骤

# 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/ (自动,自定义信头,响应信头,用户代理)
• 文件改进( 手动文件中的 README、 JSDoc)
• 错误报告和特性请求

生成的文件( 不编辑) :

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

当触摸生成的文件不可避免时, 更倾向于更新上游光谱或 Speakeeasy 配置 .speakeasy/ 所以改变能活下来.

我们期待着听到你的反馈。 随便你开个公关 或者用概念证明的问题 我们会尽力把它纳入未来的发行.

MCP 服务器创建于 说话方便