Structured Metadata MCP

云结构化元数据MCP服务器

摘要

目录

• 云结构化元数据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/structured-metadata-mcp",
    "start",
    "--api-key",
    "",
    "--api-secret",
    "",
    "--cloud-name",
    ""
  ]
}

Claude Code CLI

claude mcp add CloudinarySMD -- npx -y @cloudinary/structured-metadata-mcp start --api-key  --api-secret  --cloud-name 

Gemini

gemini mcp add CloudinarySMD -- npx -y @cloudinary/structured-metadata-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/structured-metadata-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/structured-metadata-mcp",
    "start",
    "--api-key",
    "",
    "--api-secret",
    "",
    "--cloud-name",
    ""
  ]
}

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

npx @cloudinary/structured-metadata-mcp start --api-key  --api-secret  --cloud-name 

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

npx @cloudinary/structured-metadata-mcp --help

配置

环境变量

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

CLOUDINARY_URL格式

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

CLOUDINARY_URL=cloudinary://API_KEY:API_SECRET@CLOUD_NAME

认证

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

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

可用工具

MCP服务器将Cloudinary的结构化元数据API作为工具公开。使用您的AI应用程序来发现和调用用于管理元数据字段和规则的可用工具。

用法示例

示例1：管理元数据字段

1. List fields: "Show me all metadata fields in my account"
2. Create field: "Create a metadata field named 'category' of type 'enum' with values 'product,service,other'"
3. Get field: "Get details for the metadata field 'category'"
4. Update field: "Update the 'category' field to add a new value 'subscription'"
5. Delete field: "Delete the metadata field 'old_field'"

示例2：管理字段数据源

1. Search datasource: "Search for values in the 'category' field datasource"
2. Update datasource: "Add a new value 'enterprise' to the 'category' field datasource"
3. Delete datasource entry: "Remove the value 'old_value' from the 'category' field"
4. Restore datasource: "Restore a deleted datasource entry for field 'category'"

示例3：管理元数据规则

1. List rules: "Show all metadata rules configured in my account"
2. Create rule: "Create a metadata rule to auto-tag assets in folder 'products' with category 'product'"
3. Update rule: "Update metadata rule [rule-id] to change the target folder"
4. Delete rule: "Delete metadata rule [rule-id]"

示例4：重新排序元数据字段

1. Reorder single field: "Move the 'priority' metadata field to position 2"
2. Reorder multiple fields: "Reorder metadata fields: set 'category' to position 1, 'priority' to position 2"

发展

从源头构建

先决条件

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

构建步骤

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

# Install dependencies
npm install

# Build the project
npm run build

# Run locally
npm start

项目结构

structured-metadata-mcp/
├── src/
│   ├── hooks/              # Custom authentication hooks
│   ├── mcp-server/         # MCP server implementation
│   │   ├── server.ts       # Main server (auto-generated)
│   │   └── tools/          # Generated tool wrappers
│   ├── funcs/              # API function implementations
│   └── models/             # Type definitions
├── .github/
│   └── workflows/          # CI/CD workflows
└── .speakeasy/             # Speakeasy configuration

贡献

虽然我们重视对此MCP服务器的贡献，但代码是以编程方式生成的。对生成文件的任何手动更改都将在下一代上被覆盖。

您可以贡献什么：

• ✅ 自定义挂钩 src/hooks/
• ✅ 文档改进
• ✅ 错误报告

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

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

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

______________________________________________________________________

MCP服务器由创建 地下酒吧

渐进式发现

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

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

{
  "mcpServers": {
    "CloudinarySMD": {
      "command": "npx",
      "args": ["@cloudinary/structured-metadata-mcp", "start", "--mode", "dynamic"],
      // ... other server arguments
    }
  }
}

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

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

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

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

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