@cloudinary/asset-management-mcp 0.9.0-rc.0 → 0.9.1

package/README.md

@@ -17,10 +17,10 @@
   * [Authentication](#authentication)
   * [Available Tools](#available-tools)
   * [Custom Tools](#custom-tools)
+  * [Progressive Discovery](#progressive-discovery)
 * [Development](#development)
   * [Building from Source](#building-from-source)
   * [Contributions](#contributions)
-  * [Progressive Discovery](#progressive-discovery)
 
 <!-- End Table of Contents [toc] -->
 
@@ -30,9 +30,9 @@
 <details>
 <summary>Claude Desktop</summary>
 
-Install the MCP server as a Desktop Extension using the pre-built [`mcp-server.mcpb`](https://github.com/cloudinary/asset-management-mcp/releases/download/v0.9.0-rc.0/mcp-server.mcpb) file:
+Install the MCP server as a Desktop Extension using the pre-built [`mcp-server.mcpb`](https://github.com/cloudinary/asset-management-mcp/releases/download/v0.9.1/mcp-server.mcpb) file:
 
-Simply drag and drop the [`mcp-server.mcpb`](https://github.com/cloudinary/asset-management-mcp/releases/download/v0.9.0-rc.0/mcp-server.mcpb) file onto Claude Desktop to install the extension.
+Simply drag and drop the [`mcp-server.mcpb`](https://github.com/cloudinary/asset-management-mcp/releases/download/v0.9.1/mcp-server.mcpb) file onto Claude Desktop to install the extension.
 
 The MCP bundle package includes the MCP server and all necessary configuration. Once installed, the server will be available without additional setup.
 
@@ -174,6 +174,7 @@ The MCP server supports the following environment variables:
 | `CLOUDINARY_API_SECRET` | Your Cloudinary API secret | Yes |
 | `CLOUDINARY_URL` | Complete Cloudinary URL (alternative to individual vars) | No |
 | `CLOUDINARY_COLLECT_HEADERS` | Collect API response headers (see below) | No |
+| `CLOUDINARY_MCP_APPS` | Enable MCP Apps (see [MCP Apps](#mcp-apps)) | No |
 
 ### CLOUDINARY_URL Format
 
@@ -218,6 +219,37 @@ CLOUDINARY_URL=cloudinary://API_KEY:API_SECRET@CLOUD_NAME?collect_headers=true
 
 When enabled, collected headers appear in an `_headers` field in the tool response. When not set, no headers are collected and responses are unchanged.
 
+### MCP Apps
+
+The server can expose interactive MCP UI **Apps** (spec-aligned with `io.modelcontextprotocol/ui`) that hosts can render alongside tool results — for example, an asset gallery for list results, a single-asset detail view, and an upload UI.
+
+Apps are **opt-in**. Use the `--mcp-apps` flag (available on both `start` and `serve`) or the `CLOUDINARY_MCP_APPS` environment variable to enable them:
+
+| Value | Effect |
+|-------|--------|
+| bare `--mcp-apps` (no value), `all`, or `true` | Enable every app |
+| `none` or `false` | Disable every app (kill-switch) |
+| comma-separated subset, e.g. `asset-gallery,asset-details` | Enable only the listed apps |
+| unset | Default (currently **off**; may flip on in a future release) |
+
+Available app names: `asset-gallery`, `asset-details`, `asset-upload`.
+
+```bash
+# 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
+```
+
+Precedence: CLI flag > environment variable > built-in default.
+
 <!-- Start Authentication [security] -->
 
 ## Authentication
@@ -310,6 +342,49 @@ Applies transformations to existing assets using Cloudinary's explicit API.
 Transform asset "sample" with transformations "c_fill,w_500,h_500/e_sepia"
 ```
 
+<!-- Start Progressive Discovery [dynamic-mode] -->
+## Progressive Discovery
+
+MCP servers with many tools can bloat LLM context windows, leading to increased token usage and tool confusion. Dynamic mode solves this by exposing only a small set of meta-tools that let agents progressively discover and invoke tools on demand.
+
+To enable dynamic mode, pass the `--mode dynamic` flag when starting your server:
+
+```jsonc
+{
+  "mcpServers": {
+    "CloudinaryAssetMgmt": {
+      "command": "npx",
+      "args": ["@cloudinary/asset-management-mcp", "start", "--mode", "dynamic"],
+      // ... other server arguments
+    }
+  }
+}
+```
+
+In dynamic mode, the server registers only the following meta-tools instead of every individual tool:
+
+- **`list_tools`**: Lists all available tools with their names and descriptions.
+- **`describe_tool_input`**: Returns the input schema for one or more tools by name.
+- **`execute_tool`**: Executes a tool by name with its arguments.
+- **`list_scopes`**: Lists the scopes available on the server.
+
+This approach significantly reduces the number of tokens sent to the LLM on each request, which is especially useful for servers with a large number of tools.
+
+You can combine dynamic mode with scope and tool filters:
+
+```jsonc
+{
+  "mcpServers": {
+    "CloudinaryAssetMgmt": {
+      "command": "npx",
+      "args": ["@cloudinary/asset-management-mcp", "start", "--mode", "dynamic", "--scope", "admin"],
+      // ... other server arguments
+    }
+  }
+}
+```
+<!-- End Progressive Discovery [dynamic-mode] -->
+
 # Development
 
 ## Building from Source
@@ -348,9 +423,19 @@ asset-management-mcp/
 │   │   ├── 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 (manual)
-│   │   └── tools/          # Generated tool wrappers
+│   │   ├── 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/
@@ -360,21 +445,24 @@ asset-management-mcp/
 
 ## Contributions
 
-While we value contributions to this MCP Server, the code is generated programmatically. Any manual changes to generated files will be overwritten on the next generation.
+While we value contributions to this MCP Server, most of the code is generated programmatically from the Cloudinary API spec. Any manual changes to generated files will be overwritten on the next generation — please direct your changes to the manual extension points below.
 
 **What you can contribute:**
 
-- ✅ Custom tools in `server.extensions.ts`
-- ✅ Custom hooks in `src/hooks/`
-- ✅ Documentation improvements
-- ✅ Bug reports and feature requests
+- Custom tools and server wiring in `src/mcp-server/server.extensions.ts`
+- MCP UI Apps in `src/mcp-server/apps/` (gallery, details, upload, and new apps)
+- SDK hooks in `src/hooks/` (auth, custom headers, response headers, user agent)
+- Documentation improvements (this README, JSDoc on manual files)
+- Bug reports and feature requests
 
 **Generated files (do not edit):**
 
-- ❌ `src/mcp-server/server.ts`
-- ❌ `src/mcp-server/tools/*.ts`
-- ❌ `src/funcs/*.ts`
-- ❌ `src/models/*.ts`
+- `src/mcp-server/server.ts`
+- `src/mcp-server/tools/*.ts`
+- `src/funcs/*.ts`
+- `src/models/*.ts`
+
+When touching generated files is unavoidable, prefer updating the upstream spec or Speakeasy configuration in `.speakeasy/` so the change survives regeneration.
 
 We look forward to hearing your feedback. Feel free to open a PR or issue with a proof of concept and we'll do our best to include it in a future release.
 
@@ -382,47 +470,4 @@ We look forward to hearing your feedback. Feel free to open a PR or issue with a
 
 ### MCP Server Created by [Speakeasy](https://www.speakeasy.com/?utm_source=asset-management-mcp&utm_campaign=mcp-typescript)
 
-<!-- Start Progressive Discovery [dynamic-mode] -->
-## Progressive Discovery
-
-MCP servers with many tools can bloat LLM context windows, leading to increased token usage and tool confusion. Dynamic mode solves this by exposing only a small set of meta-tools that let agents progressively discover and invoke tools on demand.
-
-To enable dynamic mode, pass the `--mode dynamic` flag when starting your server:
-
-```jsonc
-{
-  "mcpServers": {
-    "CloudinaryAssetMgmt": {
-      "command": "npx",
-      "args": ["@cloudinary/asset-management-mcp", "start", "--mode", "dynamic"],
-      // ... other server arguments
-    }
-  }
-}
-```
-
-In dynamic mode, the server registers only the following meta-tools instead of every individual tool:
-
-- **`list_tools`**: Lists all available tools with their names and descriptions.
-- **`describe_tool`**: Returns the input schema for one or more tools by name.
-- **`execute_tool`**: Executes a tool by name with the provided input parameters.
-- **`list_scopes`**: Lists the scopes available on the server.
-
-This approach significantly reduces the number of tokens sent to the LLM on each request, which is especially useful for servers with a large number of tools.
-
-You can combine dynamic mode with scope and tool filters:
-
-```jsonc
-{
-  "mcpServers": {
-    "CloudinaryAssetMgmt": {
-      "command": "npx",
-      "args": ["@cloudinary/asset-management-mcp", "start", "--mode", "dynamic", "--scope", "admin"],
-      // ... other server arguments
-    }
-  }
-}
-```
-<!-- End Progressive Discovery [dynamic-mode] -->
-
 <!-- Placeholder for Future Speakeasy SDK Sections -->