feat: enhance API response handling with custom path support and improved error messages

Author: yaonyan

README.md

@@ -54,25 +54,36 @@ extensions that provide fine-grained control over API interactions:
 - **`x-examples`**: Add request/response examples for better documentation
 - **`x-remap-path-to-header`**: Map path parameters to request headers
 - **`x-custom-base-url`**: Override base URL per operation
+- **`x-custom-path`**: Override operation path
 - **`x-sensitive-params`**: Mark sensitive data for automatic redaction
 - **`x-sensitive-response-fields`**: Mark response fields as sensitive
 
 #### Response Processing Extensions
 
 - **`x-response-config`**: Control response handling:
   - Maximum response length limits
-  - `includeResponseKeys`: Specify which keys to include in the response (all others will be excluded)
+  - `includeResponseKeys`: Specify which keys to include in the response (all
+    others will be excluded)
     - Supports dot notation for nested fields (e.g., `user.profile.email`)
-    - Supports wildcards: `*` for single level, `**` for all nested levels (e.g., `data.*.id`, `user.**`)
-    - Single words without dots will match all properties with that name at any level
+    - Supports wildcards: `*` for single level, `**` for all nested levels
+      (e.g., `data.*.id`, `user.**`)
+    - Single words without dots will match all properties with that name at any
+      level
   - `excludeResponseKeys`: Specify which keys to exclude from the response
     - Supports dot notation for nested fields (e.g., `user.profile.address`)
-    - Supports wildcards: `*` for single level, `**` for all nested levels (e.g., `data.*.secret`, `credentials.**`)
-    - Single words without dots will match all properties with that name at any level (e.g., `secret` will exclude all properties named "secret" at any depth)
-  - `sensitiveResponseFields`: Mark specific fields as sensitive (will be replaced with "\*SENSITIVE\*")
+    - Supports wildcards: `*` for single level, `**` for all nested levels
+      (e.g., `data.*.secret`, `credentials.**`)
+    - Single words without dots will match all properties with that name at any
+      level (e.g., `secret` will exclude all properties named "secret" at any
+      depth)
+  - `sensitiveResponseFields`: Mark specific fields as sensitive (will be
+    replaced with "\*SENSITIVE\*")
     - Supports dot notation for nested fields (e.g., `user.token`)
-    - Supports wildcards: `*` for single level, `**` for all nested levels (e.g., `*.password`, `**.secret`)
-    - Single words without dots will match all properties with that name at any level (e.g., `password` will mask all properties named "password" at any depth)
+    - Supports wildcards: `*` for single level, `**` for all nested levels
+      (e.g., `*.password`, `**.secret`)
+    - Single words without dots will match all properties with that name at any
+      level (e.g., `password` will mask all properties named "password" at any
+      depth)
 - **`x-tree-shaking-func`**: Custom response data filtering
 
 ### 📜 Script-Based Dynamic Values

deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcpc/oapi-invoker-mcp",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Invokes any OpenAPI through Model Context Protocol (MCP) server, supporting specification patches, custom authentication protocols, and data encryption/decryption",
   "license": "MIT",
   "repository": {

src/tool/invoker.ts

@@ -98,6 +98,7 @@ export async function invoke(
   const path = p(extendTool.path!)(processedPathParams);
   const _op = (extendTool._rawOperation || {}) as Record<string, unknown>;
   const specificUrl = _op["x-custom-base-url"] as string | undefined;
+  const customPathTemplate = _op["x-custom-path"] as string | undefined;
   const sensitiveParams =
     (_op["x-sensitive-params"] as Record<string, unknown>) ?? {};
 
@@ -137,7 +138,7 @@ export async function invoke(
   }
 
   if ((!specificUrl && !baseUrl) || !method || !path) {
-    throw new Error("Invalid tool configuration");
+    throw new Error("Invalid tool configuration, no URL/method/path");
   }
 
   let requestHeaders = { ...headers };
@@ -162,9 +163,23 @@ export async function invoke(
     }
   }
 
+  // Determine final path: use x-custom-path (processed) if provided, otherwise use operation path
+  const finalPath = customPathTemplate
+    ? p(customPathTemplate)(processedPathParams)
+    : path;
+
+  // Update debug info tool.path to reflect final path when debug is enabled
+  if (debugInfo) {
+    debugInfo.tool.path = finalPath;
+  }
+
+  if ((!specificUrl && !baseUrl) || !method || !finalPath) {
+    throw new Error("Invalid tool configuration");
+  }
+
   let url = new URL(specificUrl ?? baseUrl);
 
-  const pathItems = path.split("/").slice(1);
+  const pathItems = finalPath.split("/").slice(1);
   const pathRemaps = _op["x-remap-path-to-header"] as string[] | undefined;
   if (pathRemaps) {
     if (debugInfo) {
@@ -179,7 +194,7 @@ export async function invoke(
   } else {
     // Preserve base URL's path and append the tool path to support multi-level base URLs
     // Remove trailing slash from base path if present, then concatenate
-    url.pathname = url.pathname.replace(/\/$/, "") + path;
+    url.pathname = url.pathname.replace(/\/$/, "") + finalPath;
   }
 
   // Separate query parameters from body parameters for all requests
@@ -246,7 +261,7 @@ export async function invoke(
     // @ts-ignore: generateTencentCloudSignature function signature may not match perfectly with Type`Script`
     requestHeaders = generateTencentCloudSignature(
       method,
-      path,
+      finalPath,
       url.searchParams,
       requestHeaders,
       requestBody,
@@ -362,7 +377,7 @@ export async function invoke(
  * Supports:
  * - "*" wildcard for matching all properties at the current level
  * - "**" wildcard for matching all properties at all nested levels
- * 
+ *
  * @param item The object to process
  * @param keys Array of path strings that may contain wildcards
  * @returns Array of expanded path strings with wildcards resolved to actual paths
@@ -392,11 +407,11 @@ function expandWildcardPaths(item: any, keys: string[]): string[] {
  * Recursively expands a path with wildcards
  */
 function expandPathRecursive(
-  obj: any, 
-  segments: string[], 
-  index: number, 
-  currentPath: string, 
-  result: string[]
+  obj: any,
+  segments: string[],
+  index: number,
+  currentPath: string,
+  result: string[],
 ): void {
   if (index >= segments.length) {
     if (currentPath.length > 0) {
@@ -439,7 +454,13 @@ function expandPathRecursive(
       for (const key in obj) {
         const newPath = `${currentPath}.${key}`;
         // Use get to safely access properties
-        expandPathRecursive(get(obj, key), segments, index + 1, newPath, result);
+        expandPathRecursive(
+          get(obj, key),
+          segments,
+          index + 1,
+          newPath,
+          result,
+        );
       }
     }
     return;
@@ -448,7 +469,13 @@ function expandPathRecursive(
   // Regular property
   if (isObject(obj) && !isNull(obj) && has(obj, segment)) {
     const newPath = `${currentPath}.${segment}`;
-    expandPathRecursive(get(obj, segment), segments, index + 1, newPath, result);
+    expandPathRecursive(
+      get(obj, segment),
+      segments,
+      index + 1,
+      newPath,
+      result,
+    );
   }
 }
 
@@ -463,7 +490,7 @@ function findMatchingPropertyPaths(
   obj: any,
   key: string,
   currentPath: string = "",
-  result: string[] = []
+  result: string[] = [],
 ): string[] {
   if (!isObject(obj) || isNull(obj)) {
     return result;
@@ -504,23 +531,23 @@ function transformItem(
   }
 
   // Process keys that don't contain dots for recursive property name matching
-  const processedExcludeKeys = excludeKeys.flatMap(key => {
+  const processedExcludeKeys = excludeKeys.flatMap((key) => {
     // If key doesn't contain dots, find all paths with matching property name
-    if (!key.includes('.') && !key.includes('*')) {
+    if (!key.includes(".") && !key.includes("*")) {
       return findMatchingPropertyPaths(item, key);
     }
     return key;
   });
 
-  const processedIncludeKeys = includeKeys.flatMap(key => {
-    if (!key.includes('.') && !key.includes('*')) {
+  const processedIncludeKeys = includeKeys.flatMap((key) => {
+    if (!key.includes(".") && !key.includes("*")) {
       return findMatchingPropertyPaths(item, key);
     }
     return key;
   });
 
-  const processedSensitiveKeys = sensitiveKeys.flatMap(key => {
-    if (!key.includes('.') && !key.includes('*')) {
+  const processedSensitiveKeys = sensitiveKeys.flatMap((key) => {
+    if (!key.includes(".") && !key.includes("*")) {
       return findMatchingPropertyPaths(item, key);
     }
     return key;
@@ -529,7 +556,10 @@ function transformItem(
   // Expand wildcard paths in all key arrays
   const expandedIncludeKeys = expandWildcardPaths(item, processedIncludeKeys);
   const expandedExcludeKeys = expandWildcardPaths(item, processedExcludeKeys);
-  const expandedSensitiveKeys = expandWildcardPaths(item, processedSensitiveKeys);
+  const expandedSensitiveKeys = expandWildcardPaths(
+    item,
+    processedSensitiveKeys,
+  );
 
   /**
    * Step 1: Creates the initial processed item.
@@ -631,12 +661,10 @@ export function postProcess(
       return data;
     }
 
-    const includeResponseKeys: string[] = 
-      op["x-include-response-keys"] ||
+    const includeResponseKeys: string[] = op["x-include-response-keys"] ||
       responseConfigGlobal["includeResponseKeys"] ||
       [];
-    const excludeResponseKeys: string[] = 
-      op["x-exclude-response-keys"] ||
+    const excludeResponseKeys: string[] = op["x-exclude-response-keys"] ||
       responseConfigGlobal["excludeResponseKeys"] ||
       [];
     const sensitiveResponseFields: string[] =
@@ -684,7 +712,8 @@ function truncateData(data: unknown, maxLength?: number): unknown {
   }
 
   return {
-    message: `Response was truncated (length: ${stringified.length}, max: ${maxLength})`,
+    message:
+      `Response was truncated (length: ${stringified.length}, max: ${maxLength})`,
     truncatedData: stringified.slice(0, maxLength) + "...",
   };
 }

src/tool/parser.ts

@@ -153,6 +153,7 @@ const OperationExtensionSchema = z
     "x-remap-path-to-header": z
       .array(z.string().describe("Header key to remap to"))
       .optional(),
+    "x-custom-path": z.string().optional(),
     "x-custom-base-url": z.string().optional(),
     "x-sensitive-params": z
       .record(z.string(), z.string())