Transcription Salad MCP
Serwer MCP do transcript-first transkrypcji plików audio, filmów z YouTube i publicznych adresów URL, z opcjonalną analizą klatek na żądanie.

Transcription Salad MCP to serwer, który łączy klientów AI z infrastrukturą transkrypcji Salad. Agent korzystający z Claude, Droida, Devin CLI albo Cursora może użyć tego samego interfejsu do transkrypcji lokalnego pliku, filmu z YouTube lub publicznego adresu URL.

📋 Metryki projektu

• Start: lipiec 2026
• Status: Produkcyjnie gotowa wersja v1
• Rola: System Architect / Full-Stack Developer
• Cel: Udostępnienie transkrypcji audio i wideo bezpośrednio w klientach AI obsługujących MCP
• Walidacja: Lokalny plik MP3 i 38-minutowy film z YouTube przetranskrybowane przez prawdziwego klienta MCP

🚀 Ewolucja produktu (Product Journey)

1. Architektura: Zaprojektowanie architektury ports and adapters z czystym functional core.
2. Fundament: Zbudowanie serwera MCP po stdio, routingu źródeł, walidacji konfiguracji i ujednoliconego modelu błędów.
3. Integracja z Salad: Dodanie asynchronicznych jobów transkrypcji, pollingu, watchdoga i pobierania SRT.
4. Pliki lokalne: Walidacja przez ffprobe, upload SCP, tymczasowy storage na VPS, weryfikacja HTTPS i automatyczne sprzątanie.
5. YouTube: Najpierw pobierane są dostępne napisy z YouTube. Dopiero gdy ich brakuje, skill korzysta z Salad, używając yt-dlp do pre-checku i ekstrakcji samego audio.
6. Walidacja: Testy jednostkowe, integracyjne i end-to-end z prawdziwym Salad API, VPS-em i yt-dlp.
7. Post-processing: Skrypt skill/watch/scripts/fix_srt_hallucinations.py usuwa powtórzenia i porządkuje transkrypcję SRT.

🎯 Problem biznesowy

Klienci AI potrafią pracować z transkrypcjami, ale samo uzyskanie dobrej transkrypcji z lokalnego nagrania albo filmu z YouTube często wymaga osobnego, ręcznego procesu.

Użytkownik musi pobrać materiał, znaleźć narzędzie do transkrypcji, przesłać plik, poczekać na wynik, oczyścić go i wkleić z powrotem do pierwotnej rozmowy.

W przypadku większych plików pojawia się dodatkowy problem: Salad potrzebuje publicznego adresu URL, a pliki lokalne nie są publicznie dostępne.

❌ „Bóle” i wyzwania operacyjne

• Ręczna praca: Pobieranie, upload i przenoszenie transkrypcji między narzędziami.
• Pliki lokalne: Klient MCP nie może bezpośrednio udostępnić lokalnego pliku chmurowemu API.
• Tymczasowy storage: Duże pliki muszą być publicznie dostępne, ale nie powinny pozostawać online bezterminowo.
• Długie zadania: Transkrypcja wymaga asynchronicznego pollingu zamiast blokowania klienta.
• Niedoskonały output: Whisper może powtarzać fragmenty podczas ciszy lub muzyki.
• Różne źródła: Pliki lokalne, adresy YouTube i bezpośrednie URL-e wymagają innych etapów przygotowania.

💡 Dlaczego to działa? (Podejście produktowe)

• Jeden interfejs MCP: Klient wywołuje transcribe i get_transcription, niezależnie od rodzaju źródła.
• Osobne adaptery: Ścieżki URL, pliku lokalnego i YouTube korzystają ze wspólnej integracji z Salad, ale zachowują własną walidację.
• Tymczasowy VPS: Pliki lokalne i audio wyekstrahowane z YouTube trafiają pod losowe nazwy UUID i są usuwane przez cron po dwóch godzinach.
• Transcript-first: Skill najpierw korzysta z natywnych napisów YouTube, a dopiero przy ich braku uruchamia transkrypcję przez Salad.
• Stateless polling: Serwer nie przechowuje lokalnej bazy jobów. Źródłem prawdy pozostaje Salad, a klient przechowuje job_id.
• Walidacja przed kolejnym krokiem: Długość, rozmiar, typ pliku, konfiguracja VPS, błędy subprocessów i odpowiedzi Salad są sprawdzane przed rozpoczęciem kolejnego etapu.
• Czyszczenie SRT: Poprawiony skrypt usuwa powtarzające się fragmenty i porządkuje wynik przed przekazaniem transkrypcji agentowi.
• Transcript-first: Domyślny przepływ skilla skupia się na timestampowanej transkrypcji i pomija klatki wideo. Po wyraźnej prośbie użytkownika skill może pobrać klatki przez ffmpeg i przekazać je agentowi do odczytu.

📈 Wpływ na pracę (ROI)

„Zamiast budować osobny proces wokół każdego nagrania, można przekazać źródło bezpośrednio agentowi i odebrać gotowy SRT w tym samym kontekście.”

🔗 Integracja ze skillem watch

Do projektu dołączony jest osobny skill watch, dostosowany do współpracy z serwerem Transcription Salad MCP.

Skill watch jest adaptacją projektu bradautomates/claude-video na licencji MIT.

Skill działa w trybie transcript-first:

1. Najpierw próbuje pobrać istniejącą transkrypcję z YouTube.
2. Jeśli materiał nie ma dostępnych napisów, uruchamia transkrypcję przez Salad MCP.
3. Wynik SRT przechodzi przez poprawiony skrypt fix_srt_hallucinations.py, który usuwa typowe pętle powtórzeń i porządkuje numerację segmentów.

W tym przepływie priorytetem jest treść mówiona i timestampy. Analiza obrazu pozostaje opcjonalna: po wyraźnej prośbie użytkownika skill może pobrać klatki w trybie keyframe, scene-aware albo dla wskazanych timestampów, a następnie przekazać je agentowi do odczytu.

🛠️ Architektura i stack techniczny

• Język: Python 3.13
• Protokół: MCP po stdio
• Transkrypcja: Salad transcription-lite
• HTTP: httpx
• Media: yt-dlp, ffmpeg, ffprobe
• Transfer plików: OpenSSH, SCP
• Storage: nginx na VPS
• Testy: pytest, testy jednostkowe z mockami, testy integracyjne i realna walidacja E2E
• Architektura: Ports and adapters z functional core

Narzędzia serwera pozostają synchroniczne, a MCP SDK uruchamia je w osobnych worker threads. Długie operacje, takie jak SCP, yt-dlp i polling Salad, blokują tylko worker thread, a nie główny event loop serwera. Dzięki temu v1 zachowuje prostszą implementację bez migracji całego stosu na async I/O.

🔒 Bezpieczeństwo i decyzje operacyjne

• Klucze API są ładowane wyłącznie ze zmiennych środowiskowych.
• Sekrety, pełne ścieżki lokalne i adresy źródłowe nie są zwracane do LLM.
• Pliki lokalne są uploadowane pod losowymi nazwami UUID.
• Pliki tymczasowe są serwowane przez HTTPS.
• Pliki na VPS są automatycznie usuwane po dwóch godzinach.
• Subprocessy korzystają z list argumentów i nigdy z shell=True.
• Bezpośrednie URL-e nie wymagają konfiguracji VPS.
• Konfiguracja VPS jest walidowana tylko wtedy, gdy wybrane źródło rzeczywiście jej potrzebuje.

✅ Walidacja

Projekt zawiera:

• 460 testów jednostkowych
• 5 testów integracyjnych
• 5 testów end-to-end z prawdziwą infrastrukturą
• testy transportu MCP stdio
• testy odpowiedzi Salad API i mapowania błędów
• testy SCP, SSH, ffprobe i yt-dlp
• testy bezpieczeństwa dla path traversal, niepoprawnych danych wejściowych i wycieku sekretów

Pierwsza walidacja produkcyjna potwierdziła dwa kompletne przepływy przez prawdziwego klienta MCP:

1. Lokalny plik MP3 do SRT
2. Film z YouTube do SRT

🚀 Dalsze plany

• Dystrybucja skilla i prostszy onboarding użytkownika.
• Przegląd technicznego długu związanego z pierwszą wersją.
• Ewentualna migracja na pełny async I/O jako osobny etap v2.
• Dalsza automatyzacja konfiguracji i synchronizacji artefaktów projektu.

Artefakty

• Kod źródłowy: RafalWojciechRolsky/transcription-salad-mcp
• Serwer MCP: transcription-salad-mcp
• Powiązany skill: watch
• API transkrypcji: Salad