@llmindset/hf-mcp 0.2.53 → 0.2.54

package/dist/space/utils/gradio-schema.d.ts

@@ -0,0 +1,13 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+export type ParsedSchemaFormat = 'array' | 'object';
+export interface ParsedGradioSchema {
+    format: ParsedSchemaFormat;
+    tools: Array<{
+        name: string;
+        description?: string;
+        inputSchema: unknown;
+    }>;
+}
+export declare function parseGradioSchemaResponse(schemaResponse: unknown): ParsedGradioSchema;
+export declare function normalizeParsedTools(parsed: ParsedGradioSchema): Tool[];
+//# sourceMappingURL=gradio-schema.d.ts.map

package/dist/space/utils/gradio-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gradio-schema.d.ts","sourceRoot":"","sources":["../../../src/space/utils/gradio-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAE/D,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEpD,MAAM,WAAW,kBAAkB;IAClC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC3E;AAUD,wBAAgB,yBAAyB,CAAC,cAAc,EAAE,OAAO,GAAG,kBAAkB,CA2CrF;AAKD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,EAAE,CAQvE"}

package/dist/space/utils/gradio-schema.js

@@ -0,0 +1,44 @@
+export function parseGradioSchemaResponse(schemaResponse) {
+    if (Array.isArray(schemaResponse)) {
+        const tools = schemaResponse.filter((tool) => {
+            return (typeof tool === 'object' &&
+                tool !== null &&
+                'name' in tool &&
+                typeof tool.name === 'string' &&
+                'inputSchema' in tool);
+        });
+        if (tools.length === 0) {
+            throw new Error('Invalid schema: no tools found in array schema');
+        }
+        return {
+            format: 'array',
+            tools,
+        };
+    }
+    if (typeof schemaResponse === 'object' && schemaResponse !== null) {
+        const entries = Object.entries(schemaResponse);
+        const tools = entries.map(([name, toolSchema]) => ({
+            name,
+            description: typeof toolSchema.description === 'string' ? toolSchema.description : undefined,
+            inputSchema: toolSchema,
+        }));
+        if (tools.length === 0) {
+            throw new Error('Invalid schema: no tools found in object schema');
+        }
+        return {
+            format: 'object',
+            tools,
+        };
+    }
+    throw new Error('Invalid schema format: expected array or object');
+}
+export function normalizeParsedTools(parsed) {
+    return parsed.tools
+        .filter((t) => !t.name.toLowerCase().includes('<lambda'))
+        .map((parsedTool) => ({
+        name: parsedTool.name,
+        description: parsedTool.description || `${parsedTool.name} tool`,
+        inputSchema: parsedTool.inputSchema,
+    }));
+}
+//# sourceMappingURL=gradio-schema.js.map

package/dist/space/utils/gradio-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gradio-schema.js","sourceRoot":"","sources":["../../../src/space/utils/gradio-schema.ts"],"names":[],"mappings":"AAiBA,MAAM,UAAU,yBAAyB,CAAC,cAAuB;IAEhE,IAAI,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;QACnC,MAAM,KAAK,GAAI,cAAiC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAwE,EAAE;YACtI,OAAO,CACN,OAAO,IAAI,KAAK,QAAQ;gBACxB,IAAI,KAAK,IAAI;gBACb,MAAM,IAAI,IAAI;gBACd,OAAQ,IAA2B,CAAC,IAAI,KAAK,QAAQ;gBACrD,aAAa,IAAI,IAAI,CACrB,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACnE,CAAC;QAED,OAAO;YACN,MAAM,EAAE,OAAO;YACf,KAAK;SACL,CAAC;IACH,CAAC;IAGD,IAAI,OAAO,cAAc,KAAK,QAAQ,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;QACnE,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,cAAyC,CAAC,CAAC;QAC1E,MAAM,KAAK,GAAgC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC;YAC/E,IAAI;YACJ,WAAW,EAAE,OAAQ,UAAwC,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAE,UAAuC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS;YACzJ,WAAW,EAAE,UAAU;SACvB,CAAC,CAAC,CAAC;QAEJ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;QACpE,CAAC;QAED,OAAO;YACN,MAAM,EAAE,QAAQ;YAChB,KAAK;SACL,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;AACpE,CAAC;AAKD,MAAM,UAAU,oBAAoB,CAAC,MAA0B;IAC9D,OAAO,MAAM,CAAC,KAAK;SACjB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;SACxD,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QACrB,IAAI,EAAE,UAAU,CAAC,IAAI;QACrB,WAAW,EAAE,UAAU,CAAC,WAAW,IAAI,GAAG,UAAU,CAAC,IAAI,OAAO;QAChE,WAAW,EAAE,UAAU,CAAC,WAAkC;KAC1D,CAAC,CAAC,CAAC;AACN,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llmindset/hf-mcp",
-  "version": "0.2.53",
+  "version": "0.2.54",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -21,6 +21,8 @@ export * from './readme-utils.js';
 export * from './use-space.js';
 export * from './jobs/jobs-tool.js';
 export * from './space/dynamic-space-tool.js';
+export * from './space/utils/gradio-caller.js';
+export * from './space/utils/gradio-schema.js';
 
 // Export shared types
 export * from './types/tool-result.js';

package/src/space/commands/discover.ts

@@ -1,6 +1,6 @@
 import type { ToolResult } from '../../types/tool-result.js';
 import { escapeMarkdown } from '../../utilities.js';
-import { VIEW_PARAMETERS } from '../dynamic-space-tool.js';
+import { VIEW_PARAMETERS } from '../types.js';
 
 /**
  * Prompt configuration for discover operation (from DYNAMIC_SPACE_DATA)

package/src/space/commands/invoke.ts

@@ -1,12 +1,11 @@
 import type { ToolResult } from '../../types/tool-result.js';
 import type { InvokeResult } from '../types.js';
 import type { Tool, ServerNotification, ServerRequest } from '@modelcontextprotocol/sdk/types.js';
-import type { RequestHandlerExtra, RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';
-import { CallToolResultSchema } from '@modelcontextprotocol/sdk/types.js';
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { SSEClientTransport, type SSEClientTransportOptions } from '@modelcontextprotocol/sdk/client/sse.js';
+import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
 import { analyzeSchemaComplexity, validateParameters, applyDefaults } from '../utils/schema-validator.js';
 import { formatComplexSchemaError, formatValidationError } from '../utils/parameter-formatter.js';
+import { callGradioToolWithHeaders } from '../utils/gradio-caller.js';
+import { parseGradioSchemaResponse, normalizeParsedTools } from '../utils/gradio-schema.js';
 
 /**
  * Invokes a Gradio space with provided parameters
@@ -88,44 +87,11 @@ export async function invokeSpace(
 		// Step 7: Apply default values for missing optional parameters
 		const finalParameters = applyDefaults(inputParameters, schemaResult);
 
-		// Step 8: Create SSE connection and invoke tool
-		const sseUrl = `https://${metadata.subdomain}.hf.space/gradio_api/mcp/sse`;
-		const client = await createLazyConnection(sseUrl, hfToken);
-
-		try {
-			// Check if the client is requesting progress notifications
-			const progressToken = extra?._meta?.progressToken;
-			const requestOptions: RequestOptions = {};
-
-			if (progressToken !== undefined && extra) {
-				// Set up progress relay from remote tool to our client
-				// eslint-disable-next-line @typescript-eslint/no-misused-promises
-				requestOptions.onprogress = async (progress) => {
-					// Relay the progress notification to our client
-					await extra.sendNotification({
-						method: 'notifications/progress',
-						params: {
-							progressToken,
-							progress: progress.progress,
-							total: progress.total,
-							message: progress.message,
-						},
-					});
-				};
-			}
-
-			const result = await client.request(
-				{
-					method: 'tools/call',
-					params: {
-						name: tool.name,
-						arguments: finalParameters,
-						_meta: progressToken !== undefined ? { progressToken } : undefined,
-					},
-				},
-				CallToolResultSchema,
-				requestOptions
-			);
+			// Step 8: Create SSE connection and invoke tool (shared helper)
+			const sseUrl = `https://${metadata.subdomain}.hf.space/gradio_api/mcp/sse`;
+			const { result } = await callGradioToolWithHeaders(sseUrl, tool.name, finalParameters, hfToken, extra, {
+				logProxiedReplica: true,
+			});
 
 			// Return raw MCP result with warnings if any
 			// This ensures the space tool behaves identically to proxied gr_* tools
@@ -136,10 +102,6 @@ export async function invokeSpace(
 				resultsShared: 1,
 				isError: result.isError,
 			};
-		} finally {
-			// Clean up connection
-			await client.close();
-		}
 	} catch (error) {
 		const errorMessage = error instanceof Error ? error.message : String(error);
 		return {
@@ -230,106 +192,10 @@ async function fetchGradioSchema(subdomain: string, isPrivate: boolean, hfToken?
 
 		const schemaResponse = (await response.json()) as unknown;
 
-		// Parse schema response (handle both array and object formats)
-		return parseSchemaResponse(schemaResponse);
-	} finally {
-		clearTimeout(timeoutId);
-	}
-}
-
-/**
- * Parses schema response and extracts tools
- */
-function parseSchemaResponse(schemaResponse: unknown): Tool[] {
-	const tools: Tool[] = [];
-
-	if (Array.isArray(schemaResponse)) {
-		// Array format: [{ name: "toolName", description: "...", inputSchema: {...} }, ...]
-		for (const item of schemaResponse) {
-			if (
-				typeof item === 'object' &&
-				item !== null &&
-				'name' in item &&
-				'inputSchema' in item
-			) {
-				const itemRecord = item as Record<string, unknown>;
-				if (typeof itemRecord.name === 'string') {
-					const tool = itemRecord as { name: string; description?: string; inputSchema: unknown };
-					tools.push({
-						name: tool.name,
-						description: tool.description || `${tool.name} tool`,
-						inputSchema: {
-							type: 'object',
-							...(tool.inputSchema as Record<string, unknown>),
-						},
-					});
-				}
-			}
-		}
-	} else if (typeof schemaResponse === 'object' && schemaResponse !== null) {
-		// Object format: { "toolName": { properties: {...}, required: [...] }, ... }
-		for (const [name, toolSchema] of Object.entries(schemaResponse)) {
-			if (typeof toolSchema === 'object' && toolSchema !== null) {
-				const schema = toolSchema as { description?: string };
-				tools.push({
-					name,
-					description: schema.description || `${name} tool`,
-					inputSchema: {
-						type: 'object',
-						...(toolSchema as Record<string, unknown>),
-					},
-				});
-			}
-		}
-	}
-
-	return tools.filter((tool) => !tool.name.toLowerCase().includes('<lambda'));
-}
-
-/**
- * Creates SSE connection to endpoint for tool execution
- */
-async function createLazyConnection(sseUrl: string, hfToken?: string): Promise<Client> {
-	// Create MCP client
-	const remoteClient = new Client(
-		{
-			name: 'hf-mcp-space-client',
-			version: '1.0.0',
-		},
-		{
-			capabilities: {},
+			// Parse schema response (handle both array and object formats)
+			const parsed = parseGradioSchemaResponse(schemaResponse);
+			return normalizeParsedTools(parsed);
+		} finally {
+			clearTimeout(timeoutId);
 		}
-	);
-
-	// Create SSE transport with HF token if available
-	const transportOptions: SSEClientTransportOptions = {};
-	if (hfToken) {
-		const headerName = 'X-HF-Authorization';
-		const customHeaders = {
-			[headerName]: `Bearer ${hfToken}`,
-		};
-
-		// Headers for POST requests
-		transportOptions.requestInit = {
-			headers: customHeaders,
-		};
-
-		// Headers for SSE connection
-		transportOptions.eventSourceInit = {
-			fetch: (url, init) => {
-				const headers = new Headers(init.headers);
-				Object.entries(customHeaders).forEach(([key, value]) => {
-					headers.set(key, value);
-				});
-				return fetch(url.toString(), { ...init, headers });
-			},
-		};
 	}
-
-	const transport = new SSEClientTransport(new URL(sseUrl), transportOptions);
-
-	// Connect the client to the transport
-	await remoteClient.connect(transport);
-
-	return remoteClient;
-}

package/src/space/dynamic-space-tool.ts

@@ -10,6 +10,7 @@ import {
 	getOperationNames,
 	getSpaceArgsSchema,
 	VIEW_PARAMETERS,
+	FILE_HANDLING_TEXT,
 } from './types.js';
 import { findSpaces } from './commands/dynamic-find.js';
 import { discoverSpaces } from './commands/discover.js';
@@ -25,11 +26,6 @@ export * from './types.js';
 const USAGE_INSTRUCTIONS = `# Gradio Space Interaction
 
 Dynamically interact with any Gradio MCP Space. Find spaces, view space parameter schemas, and invoke spaces.
-
-## Supported Schema Types
-
-✅ **Simple types** (supported):
-- Strings, numbers, booleans
 - Enums (predefined value sets)
 - Arrays of primitives
 - Shallow objects (one level deep)
@@ -79,17 +75,9 @@ Execute a space's first tool with provided parameters.
 1. **Find Spaces** - Use \`find\` to find MCP-enabled spaces for your task
 2. **Inspect Parameters** - Use \`${VIEW_PARAMETERS}\` to see what a space accepts
 3. **Invoke the Space** - Use \`invoke\` with the required parameters
-
-## File Handling
-
 For parameters that accept files (FileData types):
 - Provide a publicly accessible URL (http:// or https://)
 - Example: \`{"image": "https://example.com/photo.jpg"}\`
-- Outputs from one tool may be used as inputs to another
-
-## Tips
-
-- Focus searches on specific tasks (e.g., "video generation", "object detection")
 - The tool automatically applies default values for optional parameters
 - Unknown parameters generate warnings but are still passed through (permissive inputs)
 - Enum parameters show all allowed values in ${VIEW_PARAMETERS} output
@@ -99,9 +87,17 @@ For parameters that accept files (FileData types):
 /**
  * Usage instructions for dynamic mode (when DYNAMIC_SPACE_DATA is set)
  */
-const DYNAMIC_USAGE_INSTRUCTIONS = `# Gradio Space Interaction
+const DYNAMIC_USAGE_INSTRUCTIONS = `# Hugging Face Space Dynamic Use
+
+Perform Tasks using Hugging Face Spaces. 
+
+## Workflow
+
+1. **Discover Taks and Spaces** - Use \`discover\` operation to see available spaces
+2. **View Parameters** - Use \`${VIEW_PARAMETERS}\` operation to inspect parameter schema
+3. **Invoke the Space** - Use \`invoke\` operation with the necessary parameters
 
-Use Hugging Face. Discover available spaces, view their parameter schemas, and invoke them. Use "discover" to find recommended spaces for tasks.
+${FILE_HANDLING_TEXT}
 
 ## Available Operations
 
@@ -116,7 +112,7 @@ List recommended spaces and their categories.
 \`\`\`
 
 ### ${VIEW_PARAMETERS}
-Display the parameter schema for a space's first tool.
+Display the parameter schema for the Space.
 
 **Example:**
 \`\`\`json
@@ -127,7 +123,7 @@ Display the parameter schema for a space's first tool.
 \`\`\`
 
 ### invoke
-Execute a space's first tool with provided parameters.
+Execute a Task on a Space.
 
 **Example:**
 \`\`\`json
@@ -138,18 +134,7 @@ Execute a space's first tool with provided parameters.
 }
 \`\`\`
 
-## Workflow
-
-1. **Discover Spaces** - Use \`discover\` to see available spaces
-2. **Inspect Parameters** - Use \`${VIEW_PARAMETERS}\` to see what a space accepts
-3. **Invoke the Space** - Use \`invoke\` with the required parameters
-
-## File Handling
 
-For parameters that accept files (FileData types):
-- Provide a publicly accessible URL (http:// or https://)
-- Example: \`{"image": "https://example.com/photo.jpg"}\`
-- Output url's from one tool may be used as inputs to another.
 `;
 
 /**
@@ -173,10 +158,10 @@ export function getDynamicSpaceToolConfig(): {
 	return {
 		name: 'dynamic_space',
 		description: dynamicMode
-			? 'Perform tasks with Hugging Face Spaces. Use "discover" to find available tasks for the User. Task types include Image Generation, Background Removal, Text to Speech, OCR and more ' +
-				'Call with no operation for full usage instructions.'
+			? 'Perform Tasks with Hugging Face Spaces. Use "discover" to view available Tasks. Examples are Image Generation/Editing, Background Removal, Text to Speech, OCR and many more. ' +
+				'Call with no arguments for full usage instructions.'
 			: 'Find (semantic/task search), inspect (view parameter schema) and dynamically invoke Hugging Face Spaces. ' +
-				'Call with no operation for full usage instructions.',
+				'Call with no arguments for full usage instructions.',
 		schema: getSpaceArgsSchema(),
 		annotations: {
 			title: 'Dynamically use Hugging Face Spaces',

package/src/space/types.ts

@@ -12,6 +12,21 @@ export const DYNAMIC_OPERATION_NAMES = ['discover', VIEW_PARAMETERS, 'invoke'] a
 export type OperationName = (typeof OPERATION_NAMES)[number];
 export type DynamicOperationName = (typeof DYNAMIC_OPERATION_NAMES)[number];
 
+/**
+ * File input help message constant
+ */
+export const FILE_INPUT_HELP_MESSAGE =
+	'Provide a publicly accessible URL (http:// or https://) for the file input. ' +
+	"Previously generated URL's are usable. ";
+
+/**
+ * File handling instructions for user-facing documentation
+ */
+export const FILE_HANDLING_TEXT = `For parameters that accept files (FileData, Images, file URL types):
+- Provide a publicly accessible URL (http:// or https://)
+- Example: \`{"image": "https://example.com/photo.jpg"}\`
+- URL's generated by one Space can be used as inputs to another Space.`;
+
 /**
  * Check if dynamic space mode is enabled
  */
@@ -34,10 +49,8 @@ export const spaceArgsSchema = z.object({
 	space_name: z
 		.string()
 		.optional()
-		.describe(
-			`The Hugging Face space ID (format: "username/space-name"). Required for ${VIEW_PARAMETERS} and invoke operations.`
-		),
-	parameters: z.string().optional().describe('For invoke operation: JSON object string of parameters'),
+		.describe(`Space ID (format: "username/space-name"). Required for operation = ${VIEW_PARAMETERS} or invoke.`),
+	parameters: z.string().optional().describe('Required for invoke operation: JSON object string of parameters'),
 	search_query: z
 		.string()
 		.optional()
@@ -56,7 +69,7 @@ export const dynamicSpaceArgsSchema = z.object({
 		.string()
 		.optional()
 		.describe(`Space ID (format: "username/space-name"). Required for "${VIEW_PARAMETERS}" and "invoke" operations.`),
-	parameters: z.string().optional().describe('JSON object string of parameters. Only required for "invoke" operation.'),
+	parameters: z.string().optional().describe('JSON object string of parameters. Only used for "invoke" operation.'),
 });
 
 /**
@@ -130,13 +143,6 @@ export interface JsonSchema {
 	[key: string]: unknown;
 }
 
-/**
- * File input help message constant
- */
-export const FILE_INPUT_HELP_MESSAGE =
-	'Provide a publicly accessible URL (http:// or https://) for the Gradio file input. ' +
-	"Content previously generated by 'invoke' is usable, as well as Hub Repository URLs. ";
-
 /**
  * Check if a property is a FileData type
  */

package/src/space/utils/gradio-caller.ts

@@ -0,0 +1,204 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { SSEClientTransport, type SSEClientTransportOptions } from '@modelcontextprotocol/sdk/client/sse.js';
+import { CallToolResultSchema, type ServerNotification, type ServerRequest } from '@modelcontextprotocol/sdk/types.js';
+import type { RequestHandlerExtra, RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';
+
+export interface GradioCallResult {
+	result: typeof CallToolResultSchema._type;
+	capturedHeaders: Record<string, string>;
+}
+
+export interface GradioCallOptions {
+	/** Called for every response to capture custom headers */
+	onHeaders?: (headers: Headers) => void;
+	/** Log the X-Proxied-Replica header to stderr once */
+	logProxiedReplica?: boolean;
+}
+
+/**
+ * Extract the replica ID from the X-Proxied-Replica header.
+ * Example: "oyerizs4-dspr4" => "dspr4"
+ */
+export function extractReplicaId(headerValue: string | undefined): string | null {
+	if (!headerValue) return null;
+	const parts = headerValue.split('-');
+	if (parts.length < 2) return null;
+	const replicaId = parts[parts.length - 1];
+	if (!replicaId || replicaId.trim() === '') return null;
+	return replicaId;
+}
+
+/**
+ * Rewrites any Gradio API URLs in text content to include the replica path segment.
+ * Example: https://mcp-tools-qwen-image-fast.hf.space/gradio_api =>
+ *          https://mcp-tools-qwen-image-fast.hf.space/--replicas/<replica_id>/gradio_api
+ */
+export function rewriteReplicaUrlsInResult(
+	result: typeof CallToolResultSchema._type,
+	proxiedReplicaHeader: string | undefined
+): typeof CallToolResultSchema._type {
+	if (process.env.NO_REPLICA_REWRITE) return result;
+	const replicaId = extractReplicaId(proxiedReplicaHeader);
+	if (!replicaId) return result;
+
+	const urlPattern = /https:\/\/([^\s"']+)\/gradio_api(\S*)?/g;
+
+	const rewriteText = (text: string): string =>
+		text.replace(urlPattern, (_match, host, rest = '') => {
+			return `https://${host}/--replicas/${replicaId}/gradio_api${rest}`;
+		});
+
+	let changed = false;
+	const newContent = result.content.map((item) => {
+		if (typeof item === 'string') {
+			const rewritten = rewriteText(item);
+			if (rewritten !== item) {
+				changed = true;
+				return { type: 'text', text: rewritten } as (typeof result.content)[number];
+			}
+			return { type: 'text', text: item } as (typeof result.content)[number];
+		}
+
+		if (item && typeof item === 'object' && 'text' in item && typeof item.text === 'string') {
+			const rewritten = rewriteText(item.text);
+			if (rewritten !== item.text) {
+				changed = true;
+				return { ...item, text: rewritten };
+			}
+		}
+
+		return item;
+	});
+
+	if (!changed) return result;
+	return {
+		...result,
+		content: newContent,
+	};
+}
+
+/**
+ * Shared helper to call a Gradio MCP tool over SSE, capturing response headers (including X-Proxied-Replica).
+ * This handles SSE setup, optional progress relay, and cleans up the client connection.
+ */
+export async function callGradioToolWithHeaders(
+	sseUrl: string,
+	toolName: string,
+	parameters: Record<string, unknown>,
+	hfToken: string | undefined,
+	extra: RequestHandlerExtra<ServerRequest, ServerNotification> | undefined,
+	options: GradioCallOptions = {}
+): Promise<GradioCallResult> {
+	const capturedHeaders: Record<string, string> = {};
+	let loggedHeader = false;
+
+	const handleHeaders = (headers: Headers): void => {
+		const proxiedReplica = headers.get('x-proxied-replica') ?? '';
+		if (proxiedReplica) {
+			capturedHeaders['x-proxied-replica'] = proxiedReplica;
+		}
+		if (options.logProxiedReplica && !loggedHeader) {
+			loggedHeader = true;
+		}
+		options.onHeaders?.(headers);
+	};
+
+	const captureHeadersFetch: SSEClientTransportOptions['fetch'] = async (url, init) => {
+		const response = await fetch(url, init);
+		handleHeaders(response.headers);
+		return response;
+	};
+
+	type EventSourceFetch = NonNullable<SSEClientTransportOptions['eventSourceInit']>['fetch'];
+	const buildEventSourceFetch =
+		(extraHeaders?: Record<string, string>): EventSourceFetch =>
+		(url, init) => {
+			const headers = new Headers(init?.headers);
+			if (extraHeaders) {
+				Object.entries(extraHeaders).forEach(([key, value]) => headers.set(key, value));
+			}
+			const requestInit: RequestInit = { ...(init as RequestInit), headers };
+			return captureHeadersFetch(url.toString(), requestInit);
+		};
+
+	// Create MCP client
+	const remoteClient = new Client(
+		{
+			name: 'hf-mcp-gradio-client',
+			version: '1.0.0',
+		},
+		{
+			capabilities: {},
+		}
+	);
+
+	// Create SSE transport with HF token if available
+	const transportOptions: SSEClientTransportOptions = {
+		fetch: captureHeadersFetch,
+	};
+	if (hfToken) {
+		const headerName = 'X-HF-Authorization';
+		const customHeaders = {
+			[headerName]: `Bearer ${hfToken}`,
+		};
+
+		// Headers for POST requests
+		transportOptions.requestInit = {
+			headers: customHeaders,
+		};
+
+		// Headers for SSE connection
+		transportOptions.eventSourceInit = {
+			fetch: buildEventSourceFetch(customHeaders),
+		};
+	} else {
+		transportOptions.eventSourceInit = {
+			fetch: buildEventSourceFetch(),
+		};
+	}
+
+	const transport = new SSEClientTransport(new URL(sseUrl), transportOptions);
+	await remoteClient.connect(transport);
+
+	try {
+		// Check if the client is requesting progress notifications
+		const progressToken = extra?._meta?.progressToken;
+		const requestOptions: RequestOptions = {};
+
+		if (progressToken !== undefined && extra) {
+			// Fire-and-forget; best-effort relay
+			requestOptions.onprogress = (progress) => {
+				void extra.sendNotification({
+					method: 'notifications/progress',
+					params: {
+						progressToken,
+						progress: progress.progress,
+						total: progress.total,
+						message: progress.message,
+					},
+				});
+			};
+			requestOptions.resetTimeoutOnProgress = true;
+		}
+
+		const result = await remoteClient.request(
+			{
+				method: 'tools/call',
+				params: {
+					name: toolName,
+					arguments: parameters,
+					_meta: progressToken !== undefined ? { progressToken } : undefined,
+				},
+			},
+			CallToolResultSchema,
+			requestOptions
+		);
+
+		const proxiedReplica = capturedHeaders['x-proxied-replica'];
+		const rewritten = rewriteReplicaUrlsInResult(result, proxiedReplica);
+
+		return { result: rewritten, capturedHeaders };
+	} finally {
+		await remoteClient.close();
+	}
+}