HuggingFace Spaces

Implements a Model Context Protocol server (src/index.ts) that translates incoming MCP protocol messages from Claude Desktop into Gradio API calls targeting Hugging Face Spaces, then marshals responses back into MCP format. Uses a request routing architecture that maps MCP tool invocations to specific Gradio endpoint schemas, handling protocol-level serialization/deserialization and maintaining bidirectional message flow through the MCP server lifecycle.

Implements a SemanticSearch component (src/semantic_search.ts) that queries the Hugging Face Hub API to discover Spaces matching user intents, then ranks results using semantic similarity scoring. The system converts Space metadata (name, description, tags) into embeddings and compares them against user queries to surface the most relevant Spaces for a given task, enabling Claude to automatically select appropriate models without manual URL specification.

Supports invoking multiple Spaces in sequence or parallel, aggregating results into a unified output. The system manages invocation order (sequential for dependent operations, parallel for independent ones), handles partial failures (continue with remaining Spaces if one fails), and combines results into a structured format. This enables multi-step workflows like 'generate image → analyze image → generate description'.

Maintains a taxonomy of Space capabilities (image generation, text-to-speech, vision analysis, chat, etc.) and allows filtering Spaces by capability tags. The system tags Spaces based on their function (inferred from name, description, or explicit configuration) and enables Claude to filter available Spaces by capability when selecting which Space to invoke. This supports use cases like 'find all image generation Spaces' or 'find the fastest text-to-speech Space'.

The EndpointWrapper component (src/endpoint_wrapper.ts) introspects Gradio endpoints to extract their input/output schemas, parameter types, and constraints. It makes introspection calls to the Gradio API (typically /config endpoint) to discover the structure of Space interfaces, then converts these schemas into MCP tool definitions with proper type annotations, default values, and validation rules. This enables dynamic tool generation without hardcoding Space-specific logic.

The ContentConverter component (src/content_converter.ts) handles bidirectional conversion between MCP message formats and Gradio API payloads across multiple data types (text, images, audio, video, structured data). It manages format detection, encoding/decoding (base64 for binary data), MIME type mapping, and handles edge cases like URL-based inputs vs. file uploads. The converter ensures that outputs from Gradio Spaces are normalized into formats Claude can consume (e.g., base64-encoded images, text transcriptions).

The ProgressNotifier component (src/progress_notifier.ts) manages status updates for long-running Gradio operations (e.g., image generation, model inference) by polling the Space's status endpoint and emitting progress notifications back to Claude. It tracks queue position, estimated time remaining, and intermediate results, allowing Claude to provide real-time feedback to users rather than blocking on completion. The system handles timeout management and graceful degradation if progress endpoints are unavailable.

The WorkingDirectory component (src/working_directory.ts) manages a local file system directory where Space outputs (generated images, audio files, transcriptions) are saved and organized. It handles file naming, deduplication, directory structure management, and provides file URLs that Claude can reference in subsequent operations. The system tracks file metadata (creation time, source Space, operation type) to enable file discovery and cleanup policies.

Implements a unified invocation pipeline that accepts multi-modal inputs (text, images, audio, URLs) and routes them to appropriate Gradio endpoints with type validation and format conversion. The system validates inputs against the Space's schema (parameter types, constraints, file size limits), converts inputs to the format expected by Gradio (file uploads, URLs, or raw data), and handles authentication if required. It supports both synchronous invocations (wait for completion) and asynchronous patterns (return job ID for polling).

Supports invocation of private or gated Hugging Face Spaces by managing authentication credentials (Hugging Face API tokens, user-specific tokens). The system stores credentials securely (environment variables or encrypted config) and injects them into Gradio API requests as required. It handles authentication failures gracefully and provides clear error messages when credentials are missing or invalid.

Implements MCP resource and prompt endpoints that expose Hugging Face Spaces and pre-configured prompts as first-class Claude resources. Resources provide metadata about available Spaces (name, description, capabilities, example inputs), while prompts expose pre-written instructions for common tasks (e.g., 'Generate a product image', 'Transcribe audio'). This enables Claude to discover and reference Spaces and prompts without requiring users to manually specify them.

Implements comprehensive error handling for Space invocation failures (network errors, Space downtime, quota limits, invalid inputs). The system catches Gradio API errors, translates them into user-friendly messages, and provides recovery suggestions (e.g., 'Try a different Space', 'Check your input format'). It implements retry logic with exponential backoff for transient failures and gracefully degrades functionality when Spaces are unavailable (e.g., falling back to alternative Spaces).