mcp-hfspace MCP Server 🤗

[!TIP]

Hugging Face MCP hizmetlerine doğrudan https://hf.co/mcp adresinden erişebilir ve yapılandırabilirsıniz; buna Gradio spaces da dahildir.

Bu proje, resmi Hugging Face MCP Server ve Gradio MCP Endpoints tarafından yerine geçirilmiştir.

Alternatif olarak, hf-mcp-server'ı yerel olarak STDIO Server olarak çalıştırabilir veya SSE, Streaming HTTP ve Streaming HTTP JSON Mode için güçlü desteğe sahip olabilirsiniz. Bu ayrıca araçları ve endpoint'leri seçmek için yerel bir UI çalıştırır ve ToolListChangedNotifications desteğine de sahiptir.

hf.co/mcp

mcp-hfspace

Giriş yazısını burada okuyun llmindset.co.uk/resources/mcp-hfspace/

Minimal kurulum ile Hugging Face Spaces'a bağlanın - space'lerinizi ekleyin ve başlayın!

Varsayılan olarak, Claude Desktop'a Görüntü Oluşturma yetenekleri sağlayan black-forest-labs/FLUX.1-schnell'e bağlanır.

Gradio MCP Desteği

[!TIP] Gradio 5.28 artık SSE aracılığıyla entegre MCP Desteğine sahiptir: https://huggingface.co/blog/gradio-mcp. Hedef Space'inizin MCP Etkin olup olmadığını kontrol edin!

Kurulum

NPM paketi @llmindset/mcp-hfspace şeklindedir.

Platformunuz için NodeJS 'in son sürümünü yükleyin, ardından claude_desktop_config.json dosyanızın mcpServers bölümüne aşağıdakileri ekleyin:

    "mcp-hfspace": {
      "command": "npx",
      "args": [
        "-y",
        "@llmindset/mcp-hfspace"
      ]
    }

Claude Desktop 0.78 veya daha yüksek bir sürümü kullandığınızdan emin olun.

Bu size bir Görüntü Oluşturucu ile başlamanızı sağlayacaktır.

Temel kurulum

Argümanlarda HuggingFace space'lerinin bir listesini sağlayın. mcp-hfspace en uygun endpoint'i bulur ve kullanım için otomatik olarak yapılandırır. Örnek bir claude_desktop_config.json aşağıda verilmiştir.

Varsayılan olarak, dosya yükleme/indirme için mevcut çalışma dizini kullanılır. Windows'ta bu, \users\<username>\AppData\Roaming\Claude\<version.number\ konumunda bir okuma/yazma klasörüdür ve MacOS'ta salt okunur kök / olur.

Bunu geçersiz kılmak ve görüntülerin ve diğer dosya tabanlı içeriğin yüklenmesi ve indirilmesini işlemek için bir Çalışma Dizini ayarlamanız önerilir. --work-dir=/your_directory argümanını veya MCP_HF_WORK_DIR ortam değişkenini belirtin.

Modern bir görüntü oluşturucu, vision modeli ve metin okuma desteği ile çalışma dizini ayarlanmış bir yapılandırma örneği aşağıdadır:

    "mcp-hfspace": {
      "command": "npx",
      "args": [
        "-y",
        "@llmindset/mcp-hfspace",
        "--work-dir=/Users/evalstate/mcp-store",
        "shuttleai/shuttle-jaguar",
        "styletts2/styletts2",
        "Qwen/QVQ-72B-preview"
      ]
    }

Özel space'leri kullanmak için Hugging Face Token'ınızı --hf-token=hf_... argümanı veya HF_TOKEN ortam değişkeni ile sağlayın.

Gerekiyorsa farklı çalışma dizinleri ve tokenler kullanmak için birden fazla server örneğini çalıştırmak mümkündür.

Dosya İşleme ve Claude Desktop Modu

Varsayılan olarak, Server Claude Desktop Modu'nda çalışır. Bu modda, Görüntüler araç yanıtlarında döndürülür, diğer dosyalar ise çalışma klasörüne kaydedilir ve dosya yolu bir mesaj olarak döndürülür. Bu, genellikle Claude Desktop'ı client olarak kullanıyorsanız en iyi deneyimi sağlayacaktır.

URL'ler de giriş olarak sağlanabilir: içerik Space'e iletilir.

Çalışma dizininizden kullanılabilir dosyaları ve MIME türlerini Claude'a veren "Mevcut Kaynaklar" istemeti vardır. Bu şu anda dosyaları yönetmenin en iyi yoludur.

Örnek 1 - Görüntü Oluşturma (Görüntü İndir / Claude Vision)

shuttleai/shuttle-3.1-aesthetic ve FLUX.1-schnell tarafından oluşturulan görüntüleri karşılaştırmak için Claude'u kullanacağız. Görüntüler Çalışma Dizinine kaydedilir ve Claude'un bağlam penceresine dahil edilir - böylece Claude kendi vision yeteneklerini kullanabilir.

Örnek 2 - Vision Modeli (Görüntü Yükle)

merve/paligemma2-vqav2 space bağlantısı kullanarak bir görüntüyü sorgulamak için kullanacağız. Bu durumda, Çalışma Dizininde kullanılabilir olan dosya adını belirtiriz: Görüntüyü doğrudan Claude'un bağlam penceresine yüklememek istiyoruz. Bu nedenle Claude'u şu şekilde hızlandırabiliriz:

use paligemma to find out who is in "test_gemma.jpg" -> Text Output: david bowie

Bir şeyi Claude'un bağlamına yüklüyorsanız Ataş Düğmesini kullanın, aksi takdirde Server'ın doğrudan göndermesi için dosya adını belirtin.

Ayrıca bir URL sağlayabiliriz. Örneğin: use paligemma to detect humans in https://e3.365dm.com/24/12/1600x900/skynews-taylor-swift-eras-tour_6771083.jpg?20241209000914 -> One person is detected in the image - Taylor Swift on stage.

Örnek 3 - Metni Sese Dönüştürme (Ses İndir)

Claude Desktop Modu'nda, ses dosyası WORK_DIR'ye kaydedilir ve Claude'a bildirilir. Desktop modunda değilse, dosya base64 kodlanmış kaynak olarak Client'a döndürülür (gömülü Ses ekleri destekleyen client'lar için yararlı).

Örnek 4 - Sesi Metne Dönüştürme (Ses Yükle)

Burada, bazı sesleri transkripsiyonu yapmak ve Claude'a kullanılabilir hale getirmek için hf-audio/whisper-large-v3-turbo kullanıyoruz.

Örnek 5 - Görüntüden Görüntüye

Bu örnekte, microsoft/OmniParser'ın kullanması için dosya adını belirtiyoruz ve açıklamalı bir Görüntü ve 2 ayrı metin parçası döndürüyoruz: açıklamalar ve koordinatlar. Kullanılan istem use omniparser to analyse ./screenshot.png ve use the analysis to produce an artifact that reproduces that screen idi. DawnC/Pawmatch da bu konuda iyidir.

Örnek 6 - Sohbet

Bu örnekte Claude, Qwen için bir dizi akıl yürütme bulmacası belirler ve açıklamalar için takip soruları sorar.

API Endpoint'i Belirtme

Gerekirse, space adına bir API Endpoint ekleyerek belirtebilirsiniz. Bu nedenle Qwen/Qwen2.5-72B-Instruct yerine Qwen/Qwen2.5-72B-Instruct/model_chat kullanırsınız.

Claude Desktop Modu

Bu, --desktop-mode=false seçeneği veya CLAUDE_DESKTOP_MODE=false ortam değişkeni ile devre dışı bırakılabilir. Bu durumda içerik gömülü Base64 kodlanmış Kaynak olarak döndürülür.

Önerilen Spaces

Denemeye değer bazı önerilen spaces:

Görüntü Oluşturma

• shuttleai/shuttle-3.1-aesthetic
• black-forest-labs/FLUX.1-schnell
• yanze/PuLID-FLUX
• gokaygokay/Inspyrenet-Rembg (Arka Plan Kaldırma)
• diyism/Datou1111-shou_xin - Beautiful Pencil Drawings

Sohbet

• Qwen/Qwen2.5-72B-Instruct
• prithivMLmods/Mistral-7B-Instruct-v0.3

Metin Okuma / Ses Oluşturma

• fantaxy/Sound-AI-SFX
• parler-tts/parler_tts

Sesi Metne Dönüştürme

• hf-audio/whisper-large-v3-turbo
• (openai modelleri adlandırılmamış parametreleri kullandığından çalışmayacaktır)

Metni Müziğe Dönüştürme

• haoheliu/audioldm2-text2audio-text2music

Vision Görevleri

• microsoft/OmniParser
• merve/paligemma2-vqav2
• merve/paligemma-doc
• DawnC/PawMatchAI
• DawnC/PawMatchAI/on_find_match_click - etkileşimli köpek tavsiyeleri için

Diğer Özellikler

İstemler

Her Space için istemler oluşturulur ve giriş yapma fırsatı sunar. Space'lerin genellikle özellikle yararlı etiketlerle vb. yapılandırılmadığını unutmayın. Claude aslında bunu çözmede çok iyidir ve Tool açıklaması oldukça zengindir (ancak Claude Desktop'ta görünmez).

Kaynaklar

WORK_DIR içindeki dosya listesi döndürülür ve kolaylık olması açısından "Dosyayı kullan..." metni olarak adı döndürür. Claude'un bağlamına bir şey eklemek istiyorsanız ataş düğmesini kullanın, aksi takdirde MCP Server'ı için dosya adını belirtin. Claude, Bağlam içinden kaynakları iletmeyi desteklemez.

Özel Spaces

Özel Spaces, HuggingFace token'ı ile desteklenir. Token, oluşturulan içeriği indirmek ve kaydetmek için kullanılır.

Claude Desktop'u Kullanma

Claude Desktop ile kullanmak için server config'i ekleyin:

MacOS'ta: ~/Library/Application Support/Claude/claude_desktop_config.json Windows'ta: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-hfspace": {
      "command": "npx"
      "args": [
        "-y",
        "@llmindset/mcp-hfspace",
        "--work-dir=~/mcp-files/ or x:/temp/mcp-files/",
        "--HF_TOKEN=HF_{optional token}"
        "Qwen/Qwen2-72B-Instruct",
        "black-forest-labs/FLUX.1-schnell",
        "space/example/specific-endpint"
        (... ve benzeri)
        ]
    }
  }
}

Bilinen Sorunlar ve Sınırlamalar

mcp-hfspace

• Adlandırılmamış parametrelere sahip Endpoint'ler şu an desteklenmiyor.
• Bazı karmaşık Python türlerinden uygun MCP formatlarına tam çeviri.

Claude Desktop

• Claude Desktop 0.75, MCP Server'dan hataları yanıtlamıyor gibi görünüyor, bunun yerine zaman aşımına uğruyor. Kalıcı sorunlar için, yanlış giden şeyi tanılamada daha iyi bir görünüm elde etmek için MCP Inspector'ı kullanın. Eğer bir şey aniden çalışmayı durdurursa, muhtemelen HuggingFace ZeroGPU kotasını tükettiniz demektir - kısa bir süre sonra tekrar deneyin veya barındırma için kendi Space'inizi kurun.
• Claude Desktop, 60 saniyelik bir hard zaman aşımı değeri kullanıyor gibi görünüyor ve Progress Notifications'ı UX'i yönetmek veya canlı tutmak için kullanmıyor gibi görünüyor. ZeroGPU spaces kullanıyorsanız, büyük/ağır işler zaman aşımına uğrayabilir. Sonuçlar için WORK_DIR'yi kontrol edin; MCP Server, üretilirse sonucu yakalayıp kaydedecektir.
• Claude Desktop'ın Server Durumu, günlükleme vb. raporlaması pek iyi değildir - sorunları tanılamaya yardımcı olmak için @modelcontextprotocol/inspector kullanın.

HuggingFace Spaces

• ZeroGPU kotaları veya kuyruklar çok uzunsa, space'i çoğaltmayı deneyin. İşiniz altmış saniyeden az sürerse, app.py dosyasındaki @spaces.GPU(duration=20) fonksiyon dekoratörünü iş çalışırken daha az kota talep etmek için değiştirebilirsiniz.
• HF_TOKEN'ı geçirmek ZeroGPU kotalarının (Pro) HF hesabınıza uygulanmasını sağlar
• Özel space'iniz varsa ve dedicated donanımınız varsa, HF_TOKEN size o alana doğrudan erişim verecektir - kota uygulanmaz. Herhangi bir Production görevi için bunu öneriyorum.

Üçüncü Taraf MCP Hizmetleri