# Hugging Face MCP Server

MCP server for accessing the Hugging Face Inference API. Run 200,000+ machine learning models including LLMs, image generation, text classification, embeddings, and more.

## Features

- **Text Generation**: LLMs like Llama-3, Mistral, Gemma
- **Image Generation**: FLUX, Stable Diffusion XL, SD 2.1
- **Text Classification**: Sentiment analysis, topic classification
- **Token Classification**: Named entity recognition, POS tagging
- **Question Answering**: Extract answers from context
- **Summarization**: Condense long text
- **Translation**: 200+ language pairs
- **Image-to-Text**: Image captioning
- **Image Classification**: Classify images into categories
- **Object Detection**: Detect objects with bounding boxes
- **Text-to-Speech**: Convert text to audio
- **Speech Recognition**: Transcribe audio (Whisper)
- **Embeddings**: Get text/sentence embeddings
- **And more**: Fill-mask, sentence similarity

## Setup

### Prerequisites

- Hugging Face account
- API token (free or Pro)

### Environment Variables

- `HUGGINGFACE_API_TOKEN` (required): Your Hugging Face API token

**How to get an API token:**
1. Go to [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens)
2. Click "New token"
3. Give it a name and select permissions (read is sufficient for inference)
4. Copy the token (starts with `hf_`)
5. Store as `HUGGINGFACE_API_TOKEN`

## Available Tools

### Text Generation Tools

#### `text_generation`
Generate text using large language models.

**Parameters:**
- `prompt` (string, required): Input text prompt
- `model_id` (string, optional): Model ID (default: 'mistralai/Mistral-7B-Instruct-v0.3')
- `max_new_tokens` (int, optional): Maximum tokens to generate
- `temperature` (float, optional): Sampling temperature 0-2 (higher = more random)
- `top_p` (float, optional): Nucleus sampling 0-1
- `top_k` (int, optional): Top-k sampling
- `repetition_penalty` (float, optional): Penalty for repetition
- `return_full_text` (bool, optional): Return prompt + generation (default: False)

**Popular models:**
- `meta-llama/Llama-3.2-3B-Instruct` - Meta's Llama 3.2
- `mistralai/Mistral-7B-Instruct-v0.3` - Mistral 7B
- `google/gemma-2-2b-it` - Google Gemma 2
- `HuggingFaceH4/zephyr-7b-beta` - Zephyr 7B
- `tiiuae/falcon-7b-instruct` - Falcon 7B

**Example:**
```python
result = await text_generation(
    prompt="Write a Python function to calculate fibonacci numbers:",
    model_id="mistralai/Mistral-7B-Instruct-v0.3",
    max_new_tokens=200,
    temperature=0.7,
    top_p=0.9
)
```

### Classification Tools

#### `text_classification`
Classify text into categories (sentiment, topics, etc.).

**Parameters:**
- `text` (string, required): Text to classify
- `model_id` (string, optional): Model ID (default: 'distilbert-base-uncased-finetuned-sst-2-english')

**Popular models:**
- `distilbert-base-uncased-finetuned-sst-2-english` - Sentiment (positive/negative)
- `facebook/bart-large-mnli` - Zero-shot classification
- `cardiffnlp/twitter-roberta-base-sentiment-latest` - Twitter sentiment
- `finiteautomata/bertweet-base-sentiment-analysis` - Tweet sentiment

**Example:**
```python
result = await text_classification(
    text="I love this product! It exceeded my expectations.",
    model_id="distilbert-base-uncased-finetuned-sst-2-english"
)
# Returns: [{'label': 'POSITIVE', 'score': 0.9998}]
```

#### `token_classification`
Token-level classification for NER, POS tagging, etc.

**Parameters:**
- `text` (string, required): Input text
- `model_id` (string, optional): Model ID (default: 'dslim/bert-base-NER')

**Popular models:**
- `dslim/bert-base-NER` - Named Entity Recognition
- `Jean-Baptiste/roberta-large-ner-english` - Large NER model
- `dbmdz/bert-large-cased-finetuned-conll03-english` - CoNLL-2003 NER

**Example:**
```python
result = await token_classification(
    text="Apple Inc. is located in Cupertino, California.",
    model_id="dslim/bert-base-NER"
)
# Returns entities: ORG (Apple Inc.), LOC (Cupertino), LOC (California)
```

### Question Answering & Text Processing

#### `question_answering`
Answer questions based on provided context.

**Parameters:**
- `question` (string, required): Question to answer
- `context` (string, required): Context containing the answer
- `model_id` (string, optional): Model ID (default: 'deepset/roberta-base-squad2')

**Popular models:**
- `deepset/roberta-base-squad2` - RoBERTa on SQuAD 2.0
- `distilbert-base-cased-distilled-squad` - DistilBERT on SQuAD

**Example:**
```python
result = await question_answering(
    question="Where is the Eiffel Tower located?",
    context="The Eiffel Tower is a landmark in Paris, France. It was built in 1889.",
    model_id="deepset/roberta-base-squad2"
)
# Returns: {'answer': 'Paris, France', 'score': 0.98, 'start': 35, 'end': 48}
```

#### `summarization`
Summarize long text into shorter version.

**Parameters:**
- `text` (string, required): Text to summarize
- `model_id` (string, optional): Model ID (default: 'facebook/bart-large-cnn')
- `max_length` (int, optional): Maximum summary length
- `min_length` (int, optional): Minimum summary length

**Popular models:**
- `facebook/bart-large-cnn` - BART CNN summarization
- `google/pegasus-xsum` - PEGASUS XSum
- `sshleifer/distilbart-cnn-12-6` - Distilled BART

**Example:**
```python
result = await summarization(
    text="Long article text here...",
    model_id="facebook/bart-large-cnn",
    max_length=130,
    min_length=30
)
```

#### `translation`
Translate text between languages.

**Parameters:**
- `text` (string, required): Text to translate
- `model_id` (string, required): Model ID for language pair

**Popular models:**
- `Helsinki-NLP/opus-mt-en-es` - English to Spanish
- `Helsinki-NLP/opus-mt-es-en` - Spanish to English
- `Helsinki-NLP/opus-mt-en-fr` - English to French
- `Helsinki-NLP/opus-mt-en-de` - English to German
- `facebook/mbart-large-50-many-to-many-mmt` - Multilingual (50 languages)

**Example:**
```python
result = await translation(
    text="Hello, how are you?",
    model_id="Helsinki-NLP/opus-mt-en-es"
)
# Returns: "Hola, ¿cómo estás?"
```

### Image Generation Tools

#### `text_to_image`
Generate images from text prompts.

**Parameters:**
- `prompt` (string, required): Text description of desired image
- `model_id` (string, optional): Model ID (default: 'black-forest-labs/FLUX.1-dev')
- `negative_prompt` (string, optional): What to avoid in image
- `num_inference_steps` (int, optional): Number of denoising steps
- `guidance_scale` (float, optional): How closely to follow prompt

**Popular models:**
- `black-forest-labs/FLUX.1-dev` - FLUX.1 (high quality)
- `stabilityai/stable-diffusion-xl-base-1.0` - SDXL
- `stabilityai/stable-diffusion-2-1` - SD 2.1
- `runwayml/stable-diffusion-v1-5` - SD 1.5

**Example:**
```python
result = await text_to_image(
    prompt="A serene mountain landscape at sunset, photorealistic, 8k",
    model_id="black-forest-labs/FLUX.1-dev",
    negative_prompt="blurry, low quality, distorted",
    guidance_scale=7.5
)
# Returns: {'image': 'base64_encoded_image', 'format': 'base64'}
```

### Computer Vision Tools

#### `image_to_text`
Generate text descriptions from images (captioning).

**Parameters:**
- `image_base64` (string, required): Base64 encoded image
- `model_id` (string, optional): Model ID (default: 'Salesforce/blip-image-captioning-large')

**Popular models:**
- `Salesforce/blip-image-captioning-large` - BLIP large
- `nlpconnect/vit-gpt2-image-captioning` - ViT-GPT2

**Example:**
```python
result = await image_to_text(
    image_base64="base64_encoded_image_data",
    model_id="Salesforce/blip-image-captioning-large"
)
# Returns: [{'generated_text': 'a dog playing in the park'}]
```

#### `image_classification`
Classify images into categories.

**Parameters:**
- `image_base64` (string, required): Base64 encoded image
- `model_id` (string, optional): Model ID (default: 'google/vit-base-patch16-224')

**Popular models:**
- `google/vit-base-patch16-224` - Vision Transformer
- `microsoft/resnet-50` - ResNet-50

**Example:**
```python
result = await image_classification(
    image_base64="base64_encoded_image_data",
    model_id="google/vit-base-patch16-224"
)
# Returns: [{'label': 'golden retriever', 'score': 0.95}, ...]
```

#### `object_detection`
Detect objects in images with bounding boxes.

**Parameters:**
- `image_base64` (string, required): Base64 encoded image
- `model_id` (string, optional): Model ID (default: 'facebook/detr-resnet-50')

**Popular models:**
- `facebook/detr-resnet-50` - DETR with ResNet-50
- `hustvl/yolos-tiny` - YOLOS tiny

**Example:**
```python
result = await object_detection(
    image_base64="base64_encoded_image_data",
    model_id="facebook/detr-resnet-50"
)
# Returns: [{'label': 'dog', 'score': 0.98, 'box': {...}}, ...]
```

### Audio Tools

#### `text_to_speech`
Convert text to speech audio.

**Parameters:**
- `text` (string, required): Text to synthesize
- `model_id` (string, optional): Model ID (default: 'facebook/mms-tts-eng')

**Popular models:**
- `facebook/mms-tts-eng` - MMS TTS English
- `espnet/kan-bayashi_ljspeech_vits` - VITS LJSpeech

**Example:**
```python
result = await text_to_speech(
    text="Hello, this is a test of text to speech.",
    model_id="facebook/mms-tts-eng"
)
# Returns: {'audio': 'base64_encoded_audio', 'format': 'base64'}
```

#### `automatic_speech_recognition`
Transcribe audio to text (speech recognition).

**Parameters:**
- `audio_base64` (string, required): Base64 encoded audio
- `model_id` (string, optional): Model ID (default: 'openai/whisper-large-v3')

**Popular models:**
- `openai/whisper-large-v3` - Whisper large v3 (best quality)
- `openai/whisper-medium` - Whisper medium (faster)
- `facebook/wav2vec2-base-960h` - Wav2Vec 2.0

**Example:**
```python
result = await automatic_speech_recognition(
    audio_base64="base64_encoded_audio_data",
    model_id="openai/whisper-large-v3"
)
# Returns: {'text': 'transcribed audio text here'}
```

### Embedding & Similarity Tools

#### `sentence_similarity`
Compute similarity between sentences.

**Parameters:**
- `source_sentence` (string, required): Reference sentence
- `sentences` (list, required): List of sentences to compare
- `model_id` (string, optional): Model ID (default: 'sentence-transformers/all-MiniLM-L6-v2')

**Popular models:**
- `sentence-transformers/all-MiniLM-L6-v2` - Fast, good quality
- `sentence-transformers/all-mpnet-base-v2` - Best quality
- `BAAI/bge-small-en-v1.5` - BGE small

**Example:**
```python
result = await sentence_similarity(
    source_sentence="The cat sits on the mat",
    sentences=[
        "A cat is sitting on a mat",
        "The dog runs in the park",
        "Cats are great pets"
    ],
    model_id="sentence-transformers/all-MiniLM-L6-v2"
)
# Returns: [0.95, 0.23, 0.65]
```

#### `feature_extraction`
Get embeddings (feature vectors) for text.

**Parameters:**
- `text` (string, required): Input text
- `model_id` (string, optional): Model ID (default: 'sentence-transformers/all-MiniLM-L6-v2')

**Popular models:**
- `sentence-transformers/all-MiniLM-L6-v2` - 384 dimensions
- `sentence-transformers/all-mpnet-base-v2` - 768 dimensions
- `BAAI/bge-small-en-v1.5` - 384 dimensions

**Example:**
```python
result = await feature_extraction(
    text="This is a sample sentence.",
    model_id="sentence-transformers/all-MiniLM-L6-v2"
)
# Returns: [[0.012, -0.034, 0.056, ...]] (384-dimensional vector)
```

#### `fill_mask`
Fill in masked words in text.

**Parameters:**
- `text` (string, required): Text with [MASK] token
- `model_id` (string, optional): Model ID (default: 'bert-base-uncased')

**Popular models:**
- `bert-base-uncased` - BERT base
- `roberta-base` - RoBERTa base
- `distilbert-base-uncased` - DistilBERT

**Example:**
```python
result = await fill_mask(
    text="Paris is the [MASK] of France.",
    model_id="bert-base-uncased"
)
# Returns: [{'token_str': 'capital', 'score': 0.95}, ...]
```

## Model Loading & Cold Starts

**Important**: Models may take 20-60 seconds to load on first request (cold start). Subsequent requests are faster.

**Tips:**
- Use popular models for faster loading
- Implement retry logic for timeouts
- Consider caching model responses
- Use smaller models for faster inference

## Rate Limits

### Free Tier
- Rate limited to prevent abuse
- Suitable for testing and small projects
- May experience queuing during high load

### Pro Subscription ($9/month)
- No rate limits
- Priority access to models
- Faster inference
- No queuing

Visit [huggingface.co/pricing](https://huggingface.co/pricing) for details.

## Base64 Encoding

For images and audio, you need to provide base64 encoded data:

**Python example:**
```python
import base64

# Encode image
with open("image.jpg", "rb") as f:
    image_base64 = base64.b64encode(f.read()).decode('utf-8')

# Encode audio
with open("audio.wav", "rb") as f:
    audio_base64 = base64.b64encode(f.read()).decode('utf-8')

# Decode image response
image_bytes = base64.b64decode(response['image'])
with open("generated.jpg", "wb") as f:
    f.write(image_bytes)
```

## Parameter Tuning

### Text Generation
- **temperature** (0-2): Higher = more creative/random, Lower = more focused/deterministic
- **top_p** (0-1): Nucleus sampling, typically 0.9-0.95
- **top_k**: Number of highest probability tokens to keep
- **repetition_penalty**: Penalize repeated tokens (>1.0 reduces repetition)

### Image Generation
- **guidance_scale** (1-20): Higher = follows prompt more strictly (typical: 7-7.5)
- **num_inference_steps**: More steps = higher quality but slower (typical: 20-50)
- **negative_prompt**: Describe what you don't want in the image

## Error Handling

Common errors:

- **503 Service Unavailable**: Model is loading (cold start), retry after 20-60 seconds
- **401 Unauthorized**: Invalid or missing API token
- **429 Too Many Requests**: Rate limit exceeded (upgrade to Pro)
- **400 Bad Request**: Invalid parameters or model ID
- **504 Gateway Timeout**: Model took too long to respond

**Retry logic example:**
```python
import time

max_retries = 3
for attempt in range(max_retries):
    try:
        result = await text_generation(prompt="Hello")
        break
    except httpx.HTTPStatusError as e:
        if e.response.status_code == 503 and attempt < max_retries - 1:
            time.sleep(20)  # Wait for model to load
            continue
        raise
```

## Finding Models

**Browse models:**
- Visit [huggingface.co/models](https://huggingface.co/models)
- Filter by task (Text Generation, Image Generation, etc.)
- Sort by downloads, likes, or trending
- Check model card for usage examples

**Popular categories:**
- Text Generation: 50,000+ models
- Text Classification: 30,000+ models
- Image Generation: 10,000+ models
- Translation: 5,000+ models
- Embeddings: 3,000+ models

## Best Practices

1. **Use popular models**: Faster loading and better maintained
2. **Implement timeouts**: Set appropriate timeouts (60-120 seconds)
3. **Cache responses**: Store results to reduce API calls
4. **Handle cold starts**: Implement retry logic for 503 errors
5. **Monitor usage**: Track API calls and costs
6. **Test locally**: Use Hugging Face Transformers library for testing
7. **Read model cards**: Understand model capabilities and limitations
8. **Optimize parameters**: Tune settings for your use case

## Use Cases

- **Chatbots**: LLM-powered conversational AI
- **Content Generation**: Blog posts, articles, creative writing
- **Image Creation**: Art, illustrations, product images
- **Sentiment Analysis**: Customer feedback analysis
- **Translation**: Multi-language support
- **Transcription**: Meeting notes, podcast transcripts
- **Semantic Search**: Embedding-based search
- **Data Extraction**: NER for document processing
- **Content Moderation**: Text and image classification

## API Documentation

- [Hugging Face Inference API](https://huggingface.co/docs/api-inference/index)
- [Supported Tasks](https://huggingface.co/docs/api-inference/supported-tasks)
- [Model Hub](https://huggingface.co/models)
- [Pricing](https://huggingface.co/pricing)

## Support

- [Hugging Face Forums](https://discuss.huggingface.co/)
- [Discord Community](https://huggingface.co/join/discord)
- [Documentation](https://huggingface.co/docs)
- [Status Page](https://status.huggingface.co/)