@llmindset/hf-mcp 0.2.40 → 0.2.42

package/src/space/utils/parameter-formatter.ts

@@ -0,0 +1,200 @@
+import type { SchemaComplexityResult, ParameterInfo } from '../types.js';
+import { FILE_INPUT_HELP_MESSAGE } from '../types.js';
+
+/**
+ * Formats parameter schema for display to users
+ * Shows parameters in a clear, organized manner with:
+ * - Required parameters first
+ * - Alphabetical sorting within groups
+ * - Clear type information
+ * - Default values
+ * - Enum options
+ */
+export function formatParameters(schemaResult: SchemaComplexityResult, spaceName: string): string {
+	const { toolName, toolDescription, parameters } = schemaResult;
+
+	let output = `# Parameters for: ${toolName}\n\n`;
+
+	if (toolDescription) {
+		output += `**Description:** ${toolDescription}\n\n`;
+	}
+
+	// Sort parameters: required first, then alphabetical
+	const sortedParams = [...parameters].sort((a, b) => {
+		if (a.required !== b.required) {
+			return a.required ? -1 : 1;
+		}
+		return a.name.localeCompare(b.name);
+	});
+
+	output += `## Parameters:\n\n`;
+
+	for (const param of sortedParams) {
+		output += formatParameter(param);
+	}
+
+	// Add usage example
+	output += '\n## Usage Example:\n\n';
+	output += formatUsageExample(spaceName, parameters);
+
+	return output;
+}
+
+/**
+ * Formats a single parameter for display
+ */
+function formatParameter(param: ParameterInfo): string {
+	const badge = param.required ? '[REQUIRED]' : '[OPTIONAL]';
+	let output = `### ${param.name} ${badge}\n`;
+
+	// Type
+	output += `- **Type:** ${param.type}\n`;
+
+	// Description
+	if (param.description) {
+		output += `- **Description:** ${param.description}\n`;
+	}
+
+	// Default value
+	if (param.default !== undefined) {
+		const defaultStr = formatValue(param.default);
+		output += `- **Default:** ${defaultStr}\n`;
+	}
+
+	// Enum values
+	if (param.enum && param.enum.length > 0) {
+		const enumStr = param.enum.map((v) => formatValue(v)).join(', ');
+		output += `- **Allowed values:** ${enumStr}\n`;
+	}
+
+	// File input help
+	if (param.isFileData) {
+		output += `- **Note:** ${FILE_INPUT_HELP_MESSAGE}\n`;
+	}
+
+	output += '\n';
+	return output;
+}
+
+/**
+ * Formats a value for display
+ */
+function formatValue(value: unknown): string {
+	if (value === null) return 'null';
+	if (value === undefined) return 'undefined';
+	if (typeof value === 'string') return `"${value}"`;
+	if (typeof value === 'object') {
+		try {
+			return JSON.stringify(value);
+		} catch {
+			return '[object]';
+		}
+	}
+	if (typeof value === 'number' || typeof value === 'boolean') {
+		return String(value);
+	}
+	return JSON.stringify(value);
+}
+
+/**
+ * Formats a usage example
+ */
+function formatUsageExample(spaceName: string, parameters: ParameterInfo[]): string {
+	// Create example with required parameters and some optional ones
+	const exampleParams: Record<string, string> = {};
+
+	// Add required parameters
+	for (const param of parameters.filter((p) => p.required)) {
+		exampleParams[param.name] = getExampleValue(param);
+	}
+
+	// Add one or two optional parameters if they exist
+	const optionalParams = parameters.filter((p) => !p.required);
+	for (let i = 0; i < Math.min(2, optionalParams.length); i++) {
+		const param = optionalParams[i];
+		if (param) {
+			exampleParams[param.name] = getExampleValue(param);
+		}
+	}
+
+	const paramsJson = JSON.stringify(exampleParams, null, 2)
+		.split('\n')
+		.map((line) => `  ${line}`)
+		.join('\n')
+		.trim();
+
+	return `\`\`\`json
+{
+  "operation": "invoke",
+  "space_name": "${spaceName}",
+  "parameters": "${paramsJson.replace(/"/g, '\\"')}"
+}
+\`\`\``;
+}
+
+/**
+ * Gets an example value for a parameter
+ */
+function getExampleValue(param: ParameterInfo): string {
+	// Use default if available
+	if (param.default !== undefined) {
+		return formatValue(param.default);
+	}
+
+	// Use first enum value if available
+	if (param.enum && param.enum.length > 0) {
+		return formatValue(param.enum[0]);
+	}
+
+	// File data
+	if (param.isFileData) {
+		return '"https://example.com/file.jpg"';
+	}
+
+	// Generate example based on type
+	const baseType = param.type.split(' ')[0]?.split('<')[0];
+
+	switch (baseType) {
+		case 'string':
+			return '"example value"';
+		case 'number':
+		case 'integer':
+			return '42';
+		case 'boolean':
+			return 'true';
+		case 'array':
+			return '["item1", "item2"]';
+		case 'object':
+			return '{"key": "value"}';
+		default:
+			return '"value"';
+	}
+}
+
+/**
+ * Formats a complex schema error message
+ */
+export function formatComplexSchemaError(spaceName: string, reason: string): string {
+	return `Error: Schema too complex for space '${spaceName}'.
+
+${reason}
+
+Supported types: strings, numbers, booleans, arrays of primitives, enums, shallow objects, and file URLs.
+
+For this space, use the dedicated gr_* prefixed tools instead.`;
+}
+
+/**
+ * Formats validation errors
+ */
+export function formatValidationError(errors: string[], spaceName: string): string {
+	let output = `Error: Invalid parameters for space '${spaceName}'.\n\n`;
+
+	for (const error of errors) {
+		output += `- ${error}\n`;
+	}
+
+	output += `\nUse the view_parameters operation to see all required parameters and their types.`;
+
+	return output;
+}

package/src/space/utils/result-formatter.ts

@@ -0,0 +1,226 @@
+import type { CallToolResultSchema } from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * Formats tool result for user-friendly display
+ * Handles different content types:
+ * - Text content (primary)
+ * - Image content (with descriptions)
+ * - Resource content (with URIs)
+ * - Error results
+ */
+export function formatToolResult(result: typeof CallToolResultSchema._type): string {
+	// Handle error results
+	if (result.isError) {
+		return formatErrorResult(result);
+	}
+
+	// Handle successful results with content
+	if (Array.isArray(result.content) && result.content.length > 0) {
+		return formatContentArray(result.content);
+	}
+
+	// Fallback for empty results
+	return 'Tool executed successfully (no content returned).';
+}
+
+/**
+ * Formats error results
+ */
+function formatErrorResult(result: typeof CallToolResultSchema._type): string {
+	if (!Array.isArray(result.content) || result.content.length === 0) {
+		return 'Error: Tool execution failed (no error details provided).';
+	}
+
+	const errorMessages: string[] = [];
+
+	for (const item of result.content) {
+		if (typeof item === 'string') {
+			errorMessages.push(item);
+		} else if (item && typeof item === 'object') {
+			const obj = item as Record<string, unknown>;
+			if (typeof obj.text === 'string') {
+				errorMessages.push(obj.text);
+			} else if (typeof obj.message === 'string') {
+				errorMessages.push(obj.message);
+			} else if (typeof obj.error === 'string') {
+				errorMessages.push(obj.error);
+			}
+		}
+	}
+
+	if (errorMessages.length > 0) {
+		return `Error: ${errorMessages.join('\n')}`;
+	}
+
+	return 'Error: Tool execution failed.';
+}
+
+/**
+ * Formats an array of content items
+ */
+function formatContentArray(content: unknown[]): string {
+	const formattedItems: string[] = [];
+
+	for (const item of content) {
+		const formatted = formatContentItem(item);
+		if (formatted) {
+			formattedItems.push(formatted);
+		}
+	}
+
+	if (formattedItems.length === 0) {
+		return 'Tool executed successfully (no displayable content).';
+	}
+
+	return formattedItems.join('\n\n');
+}
+
+/**
+ * Formats a single content item
+ */
+function formatContentItem(item: unknown): string | null {
+	if (!item) {
+		return null;
+	}
+
+	// Handle string content
+	if (typeof item === 'string') {
+		return item;
+	}
+
+	// Handle non-object content
+	if (typeof item !== 'object') {
+		if (typeof item === 'number' || typeof item === 'boolean') {
+			return String(item);
+		}
+		return JSON.stringify(item);
+	}
+
+	const obj = item as Record<string, unknown>;
+	const type = typeof obj.type === 'string' ? obj.type.toLowerCase() : undefined;
+
+	switch (type) {
+		case 'text':
+			return formatTextContent(obj);
+
+		case 'image':
+			return formatImageContent(obj);
+
+		case 'resource':
+			return formatResourceContent(obj);
+
+		case 'embedded_resource':
+			return formatEmbeddedResourceContent(obj);
+
+		default:
+			// Try to extract text from unknown types
+			if (typeof obj.text === 'string') {
+				return obj.text;
+			}
+			// Fallback to JSON representation
+			try {
+				return JSON.stringify(item, null, 2);
+			} catch {
+				return '[complex object]';
+			}
+	}
+}
+
+/**
+ * Formats text content
+ */
+function formatTextContent(obj: Record<string, unknown>): string | null {
+	if (typeof obj.text === 'string') {
+		return obj.text;
+	}
+	return null;
+}
+
+/**
+ * Formats image content
+ */
+function formatImageContent(obj: Record<string, unknown>): string {
+	const parts: string[] = ['[Image Content]'];
+
+	// Add MIME type if available
+	if (typeof obj.mimeType === 'string') {
+		parts.push(`Type: ${obj.mimeType}`);
+	}
+
+	// Add URL if available
+	if (typeof obj.url === 'string') {
+		parts.push(`URL: ${obj.url}`);
+	}
+
+	// Add data indicator if present
+	if (typeof obj.data === 'string') {
+		const dataLength = obj.data.length;
+		parts.push(`Data: ${dataLength} characters (base64)`);
+	}
+
+	return parts.join('\n');
+}
+
+/**
+ * Formats resource content
+ */
+function formatResourceContent(obj: Record<string, unknown>): string {
+	const parts: string[] = ['[Resource]'];
+
+	// Extract resource details
+	const resource = obj.resource as Record<string, unknown> | undefined;
+	if (resource) {
+		if (typeof resource.uri === 'string') {
+			parts.push(`URI: ${resource.uri}`);
+		}
+
+		if (typeof resource.name === 'string') {
+			parts.push(`Name: ${resource.name}`);
+		}
+
+		if (typeof resource.mimeType === 'string') {
+			parts.push(`Type: ${resource.mimeType}`);
+		}
+
+		if (typeof resource.description === 'string') {
+			parts.push(`Description: ${resource.description}`);
+		}
+	}
+
+	return parts.join('\n');
+}
+
+/**
+ * Formats embedded resource content
+ */
+function formatEmbeddedResourceContent(obj: Record<string, unknown>): string {
+	const parts: string[] = ['[Embedded Resource]'];
+
+	if (typeof obj.uri === 'string') {
+		parts.push(`URI: ${obj.uri}`);
+	}
+
+	if (typeof obj.mimeType === 'string') {
+		parts.push(`Type: ${obj.mimeType}`);
+	}
+
+	// Add blob indicator if present
+	if (typeof obj.blob === 'string') {
+		const blobLength = obj.blob.length;
+		parts.push(`Data: ${blobLength} characters`);
+	}
+
+	return parts.join('\n');
+}
+
+/**
+ * Formats a list of warnings
+ */
+export function formatWarnings(warnings: string[]): string {
+	if (warnings.length === 0) {
+		return '';
+	}
+
+	const header = warnings.length === 1 ? 'Warning:' : 'Warnings:';
+	return `${header}\n${warnings.map((w) => `- ${w}`).join('\n')}\n\n`;
+}

package/src/space/utils/schema-validator.ts

@@ -0,0 +1,232 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type {
+	JsonSchema,
+	JsonSchemaProperty,
+	SchemaComplexityResult,
+	ParameterInfo,
+} from '../types.js';
+import { isFileDataProperty } from '../types.js';
+
+/**
+ * Analyzes a tool schema to determine if it's simple enough for the dynamic space tool
+ *
+ * Supported types:
+ * - string, number, boolean
+ * - enum (with predefined values)
+ * - array of primitives
+ * - shallow objects (one level deep with primitive properties)
+ * - FileData (as string URLs)
+ *
+ * Rejected types:
+ * - Deeply nested objects (2+ levels)
+ * - Arrays of objects
+ * - Union types
+ * - Recursive schemas
+ */
+export function analyzeSchemaComplexity(tool: Tool): SchemaComplexityResult {
+	const result: SchemaComplexityResult = {
+		isSimple: true,
+		parameters: [],
+		toolName: tool.name,
+		toolDescription: tool.description,
+	};
+
+	const inputSchema = tool.inputSchema as JsonSchema;
+	if (!inputSchema || !inputSchema.properties) {
+		return result;
+	}
+
+	const properties = inputSchema.properties;
+	const required = inputSchema.required || [];
+
+	for (const [paramName, prop] of Object.entries(properties)) {
+		const paramInfo = analyzeProperty(paramName, prop, required.includes(paramName));
+
+		// Check if this parameter is too complex
+		if (paramInfo.complexType) {
+			result.isSimple = false;
+			result.reason = `Parameter "${paramName}" has complex type: ${paramInfo.complexType}`;
+			return result;
+		}
+
+		result.parameters.push(paramInfo);
+	}
+
+	return result;
+}
+
+/**
+ * Analyzes a single property to extract parameter information
+ */
+function analyzeProperty(name: string, prop: JsonSchemaProperty, isRequired: boolean): ParameterInfo {
+	const paramInfo: ParameterInfo = {
+		name,
+		type: prop.type || 'unknown',
+		description: prop.description,
+		required: isRequired,
+		default: prop.default,
+		enum: prop.enum,
+	};
+
+	// Check for FileData types - treat as string URLs
+	if (isFileDataProperty(prop)) {
+		paramInfo.type = 'string (file URL)';
+		paramInfo.isFileData = true;
+		return paramInfo;
+	}
+
+	// Check for enum types
+	if (prop.enum && Array.isArray(prop.enum) && prop.enum.length > 0) {
+		paramInfo.type = `enum (${prop.enum.length} values)`;
+		return paramInfo;
+	}
+
+	// Check for complex types
+	if (prop.type === 'object') {
+		// Check if it's a shallow object
+		if (prop.properties) {
+			const nestedProps = Object.values(prop.properties);
+			const hasComplexNested = nestedProps.some(
+				(nested) => nested.type === 'object' || nested.type === 'array'
+			);
+
+			if (hasComplexNested) {
+				paramInfo.complexType = 'deeply nested object (2+ levels)';
+			} else {
+				paramInfo.type = 'object (shallow)';
+			}
+		} else {
+			// Object without properties definition is too vague
+			paramInfo.complexType = 'object without defined properties';
+		}
+		return paramInfo;
+	}
+
+	// Check for array types
+	if (prop.type === 'array') {
+		if (prop.items) {
+			const itemType = prop.items.type;
+			if (itemType === 'object') {
+				paramInfo.complexType = 'array of objects';
+			} else if (itemType === 'array') {
+				paramInfo.complexType = 'nested arrays';
+			} else {
+				paramInfo.type = `array<${itemType || 'unknown'}>`;
+			}
+		} else {
+			paramInfo.type = 'array<any>';
+		}
+		return paramInfo;
+	}
+
+	// Simple types are fine
+	if (['string', 'number', 'integer', 'boolean'].includes(prop.type || '')) {
+		return paramInfo;
+	}
+
+	// Unknown or unsupported type
+	if (!prop.type) {
+		paramInfo.complexType = 'unknown type';
+	}
+
+	return paramInfo;
+}
+
+/**
+ * Validates parameter values against the schema
+ */
+export function validateParameters(
+	parameters: Record<string, unknown>,
+	schemaResult: SchemaComplexityResult
+): { valid: boolean; errors: string[] } {
+	const errors: string[] = [];
+
+	// Check for missing required parameters
+	const requiredParams = schemaResult.parameters.filter((p) => p.required);
+	for (const param of requiredParams) {
+		if (!(param.name in parameters) || parameters[param.name] === undefined) {
+			errors.push(`Missing required parameter: "${param.name}"`);
+		}
+	}
+
+	// Check types (basic validation)
+	for (const [key, value] of Object.entries(parameters)) {
+		const paramInfo = schemaResult.parameters.find((p) => p.name === key);
+
+		if (!paramInfo) {
+			// Unknown parameter - warning but not error (permissive inputs)
+			continue;
+		}
+
+		// Type checking
+		if (value !== null && value !== undefined) {
+			if (!validateType(value, paramInfo)) {
+				errors.push(
+					`Parameter "${key}" should be type ${paramInfo.type}, got ${typeof value}`
+				);
+			}
+		}
+	}
+
+	return {
+		valid: errors.length === 0,
+		errors,
+	};
+}
+
+/**
+ * Validates a value against a parameter type
+ */
+function validateType(value: unknown, paramInfo: ParameterInfo): boolean {
+	// FileData as string URL
+	if (paramInfo.isFileData) {
+		return typeof value === 'string';
+	}
+
+	// Enum validation
+	if (paramInfo.enum && Array.isArray(paramInfo.enum)) {
+		return paramInfo.enum.includes(value);
+	}
+
+	// Basic type validation
+	const baseType = paramInfo.type.split(' ')[0]?.split('<')[0]; // Extract base type
+
+	switch (baseType) {
+		case 'string':
+			return typeof value === 'string';
+		case 'number':
+		case 'integer':
+			return typeof value === 'number';
+		case 'boolean':
+			return typeof value === 'boolean';
+		case 'array':
+			return Array.isArray(value);
+		case 'object':
+			return typeof value === 'object' && value !== null && !Array.isArray(value);
+		case 'enum':
+			// Already checked above
+			return true;
+		default:
+			// Unknown type, allow it (permissive)
+			return true;
+	}
+}
+
+/**
+ * Applies default values to parameters
+ */
+export function applyDefaults(
+	parameters: Record<string, unknown>,
+	schemaResult: SchemaComplexityResult
+): Record<string, unknown> {
+	const result = { ...parameters };
+
+	for (const param of schemaResult.parameters) {
+		// Only apply defaults for optional parameters that are missing
+		if (!param.required && !(param.name in result) && param.default !== undefined) {
+			result[param.name] = param.default;
+		}
+	}
+
+	return result;
+}

package/src/space-search.ts

@@ -34,7 +34,8 @@ const RESULTS_TO_RETURN = 10;
 export const SEMANTIC_SEARCH_TOOL_CONFIG = {
 	name: 'space_search',
 	description:
-		'Find Hugging Face Spaces using semantic search. ' + 'Include links to the Space when presenting the results.',
+		'Find Hugging Face Spaces using semantic search. IMPORTANT Only MCP Servers can be used with the dynamic_space tool' +
+		'Include links to the Space when presenting the results.',
 	schema: z.object({
 		query: z.string().min(1, 'Query is required').max(100, 'Query too long').describe('Semantic Search Query'),
 		limit: z.number().optional().default(RESULTS_TO_RETURN).describe('Number of results to return'),
@@ -115,7 +116,7 @@ export class SpaceSearchTool extends HfApiCall<SpaceSearchParams, SpaceSearchRes
 				return {
 					formatted: `No matching Hugging Face Spaces found referencing ${filter}.`,
 					totalResults: 0,
-					resultsShared: 0
+					resultsShared: 0,
 				};
 			}
 
@@ -150,7 +151,7 @@ export const formatSearchResults = (
 		return {
 			formatted: `No matching Hugging Face Spaces found for the query '${query}'. Try a different query.`,
 			totalResults: 0,
-			resultsShared: 0
+			resultsShared: 0,
 		};
 	}
 
@@ -185,6 +186,6 @@ export const formatSearchResults = (
 	return {
 		formatted: markdown,
 		totalResults: totalCount,
-		resultsShared: results.length
+		resultsShared: results.length,
 	};
 };