release: 7.2.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "7.1.1"
+  ".": "7.2.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 42
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/imagekit-inc%2Fimagekit-c7ad6f552b38f2145781847f8b390fa1ec43068d64e45a33012a97a9299edc10.yml
-openapi_spec_hash: 50f281e91210ad5018ac7e4eee216f56
-config_hash: 74a8263b80c732a2b016177e7d56bb9c
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/imagekit-inc%2Fimagekit-9d184cb502ab32a85db2889c796cdfebe812f2a55a604df79c85dd4b5e7e2add.yml
+openapi_spec_hash: a9aa620376fce66532c84f9364209b0b
+config_hash: eb4cf65a4c6b26a2901076eff5810d5d

CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 7.2.0 (2025-11-06)
+
+Full Changelog: [v7.1.1...v7.2.0](https://github.com/imagekit-developer/imagekit-nodejs/compare/v7.1.1...v7.2.0)
+
+### Features
+
+* **api:** add GetImageAttributesOptions and ResponsiveImageAttributes schemas; update resource references in main.yaml; remove dummy endpoint ([9ea439a](https://github.com/imagekit-developer/imagekit-nodejs/commit/9ea439a2d0a4c8300d14d4424dc72ab40a67c4d4))
+* **mcp:** enable optional code execution tool on http mcp servers ([cc68e38](https://github.com/imagekit-developer/imagekit-nodejs/commit/cc68e38fa61078db6a5c961e7ed75dad342dc7e8))
+
+
+### Bug Fixes
+
+* **mcpb:** pin @anthropic-ai/mcpb version ([d81e225](https://github.com/imagekit-developer/imagekit-nodejs/commit/d81e22560aab772ee9b241fb44a50561b8837034))
+
+
+### Chores
+
+* extract some types in mcp docs ([de606ba](https://github.com/imagekit-developer/imagekit-nodejs/commit/de606ba3b734389e1c52a9929dbf8487828822e0))
+* **internal:** codegen related update ([8c9026a](https://github.com/imagekit-developer/imagekit-nodejs/commit/8c9026ace5d217264e5753c01309a02a2c09095e))
+* **internal:** grammar fix (it's -> its) ([71e22a3](https://github.com/imagekit-developer/imagekit-nodejs/commit/71e22a30017324842fed5ab08ee1efbb1eecb6d2))
+* **internal:** use npm pack for build uploads ([bdfd369](https://github.com/imagekit-developer/imagekit-nodejs/commit/bdfd369118542dad02cf8a0fae8713d0d8bea4eb))
+* mcp code tool explicit error message when missing a run function ([6678ee1](https://github.com/imagekit-developer/imagekit-nodejs/commit/6678ee13cc1eee5ce1ac51b672144be77c38e9ea))
+* **mcp:** add friendlier MCP code tool errors on incorrect method invocations ([636829d](https://github.com/imagekit-developer/imagekit-nodejs/commit/636829d18a7dda730b65c0549298258afcea6341))
+* **mcp:** add line numbers to code tool errors ([25e4e59](https://github.com/imagekit-developer/imagekit-nodejs/commit/25e4e59f434c07c2d9afeef3f548dd99e250a7ab))
+* use structured error when code execution tool errors ([451f306](https://github.com/imagekit-developer/imagekit-nodejs/commit/451f306f6328e6c48374d0525dad9a0ddc6511d6))
+
+
+### Documentation
+
+* **mcp:** add a README button for one-click add to Cursor ([a7575d3](https://github.com/imagekit-developer/imagekit-nodejs/commit/a7575d308e3038715964f7416284bb012e27b240))
+* **mcp:** add a README link to add server to VS Code or Claude Code ([2a90d28](https://github.com/imagekit-developer/imagekit-nodejs/commit/2a90d2802e4814d97ec5bba77097eec2f0a5a718))
+
 ## 7.1.1 (2025-10-06)
 
 Full Changelog: [v7.1.0...v7.1.1](https://github.com/imagekit-developer/imagekit-nodejs/compare/v7.1.0...v7.1.1)

api.md

@@ -4,10 +4,12 @@ Types:
 
 - <code><a href="./src/resources/shared.ts">BaseOverlay</a></code>
 - <code><a href="./src/resources/shared.ts">Extensions</a></code>
+- <code><a href="./src/resources/shared.ts">GetImageAttributesOptions</a></code>
 - <code><a href="./src/resources/shared.ts">ImageOverlay</a></code>
 - <code><a href="./src/resources/shared.ts">Overlay</a></code>
 - <code><a href="./src/resources/shared.ts">OverlayPosition</a></code>
 - <code><a href="./src/resources/shared.ts">OverlayTiming</a></code>
+- <code><a href="./src/resources/shared.ts">ResponsiveImageAttributes</a></code>
 - <code><a href="./src/resources/shared.ts">SolidColorOverlay</a></code>
 - <code><a href="./src/resources/shared.ts">SolidColorOverlayTransformation</a></code>
 - <code><a href="./src/resources/shared.ts">SrcOptions</a></code>

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imagekit/nodejs",
-  "version": "7.1.1",
+  "version": "7.2.0",
   "description": "Offical NodeJS SDK for ImageKit.io integration",
   "author": "Image Kit <[email protected]>",
   "types": "dist/index.d.ts",

packages/mcp-server/README.md

@@ -36,12 +36,36 @@ For clients with a configuration JSON, it might look something like this:
 }
 ```
 
+### Cursor
+
+If you use Cursor, you can install the MCP server by using the button below. You will need to set your environment variables
+in Cursor's `mcp.json`, which can be found in Cursor Settings > Tools & MCP > New MCP Server.
+
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=@imagekit/api-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBpbWFnZWtpdC9hcGktbWNwIl0sImVudiI6eyJJTUFHRUtJVF9QUklWQVRFX0tFWSI6IlNldCB5b3VyIElNQUdFS0lUX1BSSVZBVEVfS0VZIGhlcmUuIiwiT1BUSU9OQUxfSU1BR0VLSVRfSUdOT1JFU19USElTIjoiU2V0IHlvdXIgT1BUSU9OQUxfSU1BR0VLSVRfSUdOT1JFU19USElTIGhlcmUuIiwiSU1BR0VLSVRfV0VCSE9PS19TRUNSRVQiOiJTZXQgeW91ciBJTUFHRUtJVF9XRUJIT09LX1NFQ1JFVCBoZXJlLiJ9fQ)
+
+### VS Code
+
+If you use MCP, you can install the MCP server by clicking the link below. You will need to set your environment variables
+in VS Code's `mcp.json`, which can be found via Command Palette > MCP: Open User Configuration.
+
+[Open VS Code](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22%40imagekit%2Fapi-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40imagekit%2Fapi-mcp%22%5D%2C%22env%22%3A%7B%22IMAGEKIT_PRIVATE_KEY%22%3A%22Set%20your%20IMAGEKIT_PRIVATE_KEY%20here.%22%2C%22OPTIONAL_IMAGEKIT_IGNORES_THIS%22%3A%22Set%20your%20OPTIONAL_IMAGEKIT_IGNORES_THIS%20here.%22%2C%22IMAGEKIT_WEBHOOK_SECRET%22%3A%22Set%20your%20IMAGEKIT_WEBHOOK_SECRET%20here.%22%7D%7D)
+
+### Claude Code
+
+If you use Claude Code, you can install the MCP server by running the command below in your terminal. You will need to set your
+environment variables in Claude Code's `.claude.json`, which can be found in your home directory.
+
+```
+claude mcp add --transport stdio imagekit_nodejs_api --env IMAGEKIT_PRIVATE_KEY="Your IMAGEKIT_PRIVATE_KEY here." OPTIONAL_IMAGEKIT_IGNORES_THIS="Your OPTIONAL_IMAGEKIT_IGNORES_THIS here." IMAGEKIT_WEBHOOK_SECRET="Your IMAGEKIT_WEBHOOK_SECRET here." -- npx -y @imagekit/api-mcp
+```
+
 ## Exposing endpoints to your MCP Client
 
-There are two ways to expose endpoints as tools in the MCP server:
+There are three ways to expose endpoints as tools in the MCP server:
 
 1. Exposing one tool per endpoint, and filtering as necessary
 2. Exposing a set of tools to dynamically discover and invoke endpoints from the API
+3. Exposing a docs search tool and a code execution tool, allowing the client to write code to be executed against the TypeScript client
 
 ### Filtering endpoints and tools
 
@@ -76,6 +100,18 @@ All of these command-line options can be repeated, combined together, and have c
 
 Use `--list` to see the list of available tools, or see below.
 
+### Code execution
+
+If you specify `--tools=code` to the MCP server, it will expose just two tools:
+
+- `search_docs` - Searches the API documentation and returns a list of markdown results
+- `execute` - Runs code against the TypeScript client
+
+This allows the LLM to implement more complex logic by chaining together many API calls without loading
+intermediary results into its context window.
+
+The code execution itself happens in a Deno sandbox that has network access only to the base URL for the API.
+
 ### Specifying the MCP Client
 
 Different clients have varying abilities to handle arbitrary tools and schemas.

packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imagekit/api-mcp",
-  "version": "7.1.1",
+  "version": "7.2.0",
   "description": "The official MCP Server for the Image Kit API",
   "author": "Image Kit <[email protected]>",
   "types": "dist/index.d.ts",
@@ -36,8 +36,10 @@
     "@valtown/deno-http-worker": "^0.0.21",
     "cors": "^2.8.5",
     "express": "^5.1.0",
+    "fuse.js": "^7.1.0",
     "jq-web": "https://github.com/stainless-api/jq-web/releases/download/v0.8.6/jq-web.tar.gz",
     "qs": "^6.14.0",
+    "typescript": "5.8.3",
     "yargs": "^17.7.2",
     "zod": "^3.25.20",
     "zod-to-json-schema": "^3.24.5",
@@ -47,7 +49,7 @@
     "mcp-server": "dist/index.js"
   },
   "devDependencies": {
-    "@anthropic-ai/mcpb": "^1.1.0",
+    "@anthropic-ai/mcpb": "1.1.0",
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.3",
     "@types/jest": "^29.4.0",
@@ -64,8 +66,7 @@
     "ts-morph": "^19.0.0",
     "ts-node": "^10.5.0",
     "tsc-multi": "https://github.com/stainless-api/tsc-multi/releases/download/v1.1.9/tsc-multi.tgz",
-    "tsconfig-paths": "^4.0.0",
-    "typescript": "5.8.3"
+    "tsconfig-paths": "^4.0.0"
   },
   "imports": {
     "@imagekit/api-mcp": ".",

packages/mcp-server/src/code-tool-worker.ts

@@ -1,11 +1,207 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import util from 'node:util';
+
+import Fuse from 'fuse.js';
+import ts from 'typescript';
+
 import { WorkerInput, WorkerSuccess, WorkerError } from './code-tool-types';
 import { ImageKit } from '@imagekit/nodejs';
 
+function getRunFunctionNode(
+  code: string,
+): ts.FunctionDeclaration | ts.FunctionExpression | ts.ArrowFunction | null {
+  const sourceFile = ts.createSourceFile('code.ts', code, ts.ScriptTarget.Latest, true);
+
+  for (const statement of sourceFile.statements) {
+    // Check for top-level function declarations
+    if (ts.isFunctionDeclaration(statement)) {
+      if (statement.name?.text === 'run') {
+        return statement;
+      }
+    }
+
+    // Check for variable declarations: const run = () => {} or const run = function() {}
+    if (ts.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        if (ts.isIdentifier(declaration.name) && declaration.name.text === 'run') {
+          // Check if it's initialized with a function
+          if (
+            declaration.initializer &&
+            (ts.isFunctionExpression(declaration.initializer) || ts.isArrowFunction(declaration.initializer))
+          ) {
+            return declaration.initializer;
+          }
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
+const fuse = new Fuse(
+  [
+    'client.customMetadataFields.create',
+    'client.customMetadataFields.delete',
+    'client.customMetadataFields.list',
+    'client.customMetadataFields.update',
+    'client.files.copy',
+    'client.files.delete',
+    'client.files.get',
+    'client.files.move',
+    'client.files.rename',
+    'client.files.update',
+    'client.files.upload',
+    'client.files.bulk.addTags',
+    'client.files.bulk.delete',
+    'client.files.bulk.removeAITags',
+    'client.files.bulk.removeTags',
+    'client.files.versions.delete',
+    'client.files.versions.get',
+    'client.files.versions.list',
+    'client.files.versions.restore',
+    'client.files.metadata.get',
+    'client.files.metadata.getFromURL',
+    'client.assets.list',
+    'client.cache.invalidation.create',
+    'client.cache.invalidation.get',
+    'client.folders.copy',
+    'client.folders.create',
+    'client.folders.delete',
+    'client.folders.move',
+    'client.folders.rename',
+    'client.folders.job.get',
+    'client.accounts.usage.get',
+    'client.accounts.origins.create',
+    'client.accounts.origins.delete',
+    'client.accounts.origins.get',
+    'client.accounts.origins.list',
+    'client.accounts.origins.update',
+    'client.accounts.urlEndpoints.create',
+    'client.accounts.urlEndpoints.delete',
+    'client.accounts.urlEndpoints.get',
+    'client.accounts.urlEndpoints.list',
+    'client.accounts.urlEndpoints.update',
+    'client.beta.v2.files.upload',
+    'client.webhooks.unsafeUnwrap',
+    'client.webhooks.unwrap',
+  ],
+  { threshold: 1, shouldSort: true },
+);
+
+function getMethodSuggestions(fullyQualifiedMethodName: string): string[] {
+  return fuse
+    .search(fullyQualifiedMethodName)
+    .map(({ item }) => item)
+    .slice(0, 5);
+}
+
+const proxyToObj = new WeakMap<any, any>();
+const objToProxy = new WeakMap<any, any>();
+
+type ClientProxyConfig = {
+  path: string[];
+  isBelievedBad?: boolean;
+};
+
+function makeSdkProxy<T extends object>(obj: T, { path, isBelievedBad = false }: ClientProxyConfig): T {
+  let proxy: T = objToProxy.get(obj);
+
+  if (!proxy) {
+    proxy = new Proxy(obj, {
+      get(target, prop, receiver) {
+        const propPath = [...path, String(prop)];
+        const value = Reflect.get(target, prop, receiver);
+
+        if (isBelievedBad || (!(prop in target) && value === undefined)) {
+          // If we're accessing a path that doesn't exist, it will probably eventually error.
+          // Let's proxy it and mark it bad so that we can control the error message.
+          // We proxy an empty class so that an invocation or construction attempt is possible.
+          return makeSdkProxy(class {}, { path: propPath, isBelievedBad: true });
+        }
+
+        if (value !== null && (typeof value === 'object' || typeof value === 'function')) {
+          return makeSdkProxy(value, { path: propPath, isBelievedBad });
+        }
+
+        return value;
+      },
+
+      apply(target, thisArg, args) {
+        if (isBelievedBad || typeof target !== 'function') {
+          const fullyQualifiedMethodName = path.join('.');
+          const suggestions = getMethodSuggestions(fullyQualifiedMethodName);
+          throw new Error(
+            `${fullyQualifiedMethodName} is not a function. Did you mean: ${suggestions.join(', ')}`,
+          );
+        }
+
+        return Reflect.apply(target, proxyToObj.get(thisArg) ?? thisArg, args);
+      },
+
+      construct(target, args, newTarget) {
+        if (isBelievedBad || typeof target !== 'function') {
+          const fullyQualifiedMethodName = path.join('.');
+          const suggestions = getMethodSuggestions(fullyQualifiedMethodName);
+          throw new Error(
+            `${fullyQualifiedMethodName} is not a constructor. Did you mean: ${suggestions.join(', ')}`,
+          );
+        }
+
+        return Reflect.construct(target, args, newTarget);
+      },
+    });
+
+    objToProxy.set(obj, proxy);
+    proxyToObj.set(proxy, obj);
+  }
+
+  return proxy;
+}
+
+function parseError(code: string, error: unknown): string | undefined {
+  if (!(error instanceof Error)) return;
+  const message = error.name ? `${error.name}: ${error.message}` : error.message;
+  try {
+    // Deno uses V8; the first "<anonymous>:LINE:COLUMN" is the top of stack.
+    const lineNumber = error.stack?.match(/<anonymous>:([0-9]+):[0-9]+/)?.[1];
+    // -1 for the zero-based indexing
+    const line =
+      lineNumber &&
+      code
+        .split('\n')
+        .at(parseInt(lineNumber, 10) - 1)
+        ?.trim();
+    return line ? `${message}\n  at line ${lineNumber}\n    ${line}` : message;
+  } catch {
+    return message;
+  }
+}
+
 const fetch = async (req: Request): Promise<Response> => {
   const { opts, code } = (await req.json()) as WorkerInput;
+  if (code == null) {
+    return Response.json(
+      {
+        message:
+          'The code param is missing. Provide one containing a top-level `run` function. Write code within this template:\n\n```\nasync function run(client) {\n  // Fill this out\n}\n```',
+      } satisfies WorkerError,
+      { status: 400, statusText: 'Code execution error' },
+    );
+  }
+
+  const runFunctionNode = getRunFunctionNode(code);
+  if (!runFunctionNode) {
+    return Response.json(
+      {
+        message:
+          'The code is missing a top-level `run` function. Write code within this template:\n\n```\nasync function run(client) {\n  // Fill this out\n}\n```',
+      } satisfies WorkerError,
+      { status: 400, statusText: 'Code execution error' },
+    );
+  }
+
   const client = new ImageKit({
     ...opts,
   });
@@ -22,21 +218,17 @@ const fetch = async (req: Request): Promise<Response> => {
   };
   try {
     let run_ = async (client: any) => {};
-    eval(`
-      ${code}
-      run_ = run;
-    `);
-    const result = await run_(client);
+    eval(`${code}\nrun_ = run;`);
+    const result = await run_(makeSdkProxy(client, { path: ['client'] }));
     return Response.json({
       result,
       logLines,
       errLines,
     } satisfies WorkerSuccess);
   } catch (e) {
-    const message = e instanceof Error ? e.message : undefined;
     return Response.json(
       {
-        message,
+        message: parseError(code, e),
       } satisfies WorkerError,
       { status: 400, statusText: 'Code execution error' },
     );