Metadata-Version: 2.4
Name: hf-trending-mcp
Version: 0.1.0
Summary: server that tracks trending models, datasets, and spaces on Hugging Face.
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp[cli]>=1.6.0
Dynamic: license-file

# HF Trending MCP Server

An MCP server that tracks trending models, datasets, and spaces on [Hugging Face](https://huggingface.co). 

It provides tools and prompts to fetch trending content, search for specific items, and analyze current trends, making it a valuable tool for developers, researchers, and AI enthusiasts.

![License](https://img.shields.io/badge/license-MIT-green.svg) 
![Python](https://img.shields.io/badge/python-3.10+-blue.svg) 
![Status](https://img.shields.io/badge/status-active-brightgreen.svg)


## Features

- **Trending Tools**: Retrieve the top trending models, datasets, and spaces with customizable limits.
- **Search Functionality**: Search trending items by query across models, datasets, or spaces.
- **Trend Analysis Prompt**: A built-in prompt to analyze and summarize current trends on Hugging Face.


## Installation

### Setup

1. **Clone the Repository**:
   ```bash
   git clone https://github.com/kukapay/hf-trending-mcp.git
   cd hf-trending-mcp
   ```

2. **Install Dependencies**:
   ```bash
   pip install mcp[cli] httpx
   ```

3. **Client Configuration**:
    ```
    "mcpServers": { 
      "hf-trending-mcp": { 
        "command": "python", 
        "args": [ "path/to/hf-trending-mcp/main.py" ]
      } 
    }
    ```

## Usage

Once the server is running or installed, you can interact with it using an MCP client (e.g., Claude Desktop). Below are some example prompts:

### Fetch Trending Content
**Input**: 
> "Show me the top 5 trending models on Hugging Face."

**Output**:
```
google/vit-base-patch16-224 (Downloads: 12345, Likes: 678)
Tags: vision, transformer

facebook/detr-resnet-50 (Downloads: 9876, Likes: 543)
Tags: object-detection, transformer
...
```

**Input**: 
> "What are the top 10 trending datasets right now?"

**Output**:
```
imdb (Downloads: 45678, Likes: 2345)
Tags: nlp, sentiment-analysis

squad (Downloads: 34567, Likes: 1987)
Tags: nlp, question-answering
...
```

**Input**: 
> "List the top 3 trending spaces."

**Output**:
```
gradio/image-classifier (Likes: 890, SDK: Gradio)
Tags: demo, vision

streamlit/text-generator (Likes: 765, SDK: Streamlit)
Tags: nlp, demo
...
```

### Search Trending Items

**Input**: 
> "Search for trending NLP models, limit to 5."

**Output**:
```
bert-base-uncased (Likes: 456)
Tags: nlp, transformer

distilbert-base-uncased (Likes: 321)
Tags: nlp, transformer
...
```

**Input**: 
> "Find trending datasets about computer vision."

**Output**:
  ```
  coco (Likes: 1234)
  Tags: computer-vision, object-detection

  imagenet-1k (Likes: 987)
  Tags: computer-vision, classification
  ...
  ```

### Analyze Trends

**Input**: 
> "Analyze the current trends on Hugging Face."
 
**Output**: 

A detailed response combining results from all trending tools, followed by an analysis (generated by the client’s AI):
```
Top Trending Models:
google/vit-base-patch16-224 (Downloads: 12345, Likes: 678)
Tags: vision, transformer
...

Top Trending Datasets:
imdb (Downloads: 45678, Likes: 2345)
Tags: nlp, sentiment-analysis
...

Top Trending Spaces:
gradio/image-classifier (Likes: 890, SDK: Gradio)
Tags: demo, vision
...

Summary: Vision models like ViT are trending, likely due to recent advancements in image processing. NLP datasets remain popular for text-based AI research, and Gradio spaces are gaining traction for interactive demos.
```


## API Details

### Tools
- **`get_trending_models(limit: int = 10)`**: Fetches trending models with downloads, likes, and tags.
- **`get_trending_datasets(limit: int = 10)`**: Fetches trending datasets with downloads, likes, and tags.
- **`get_trending_spaces(limit: int = 10)`**: Fetches trending spaces with likes, SDK info, and tags.
- **`search_trending(query: str, type: str = "models", limit: int = 10)`**: Searches trending items by query and type.

### Prompt
- **`analyze_trends()`**: Guides the analysis of trending items with a structured prompt.

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
