Dokumentace

Rozhraní nástrojů pro agenta

Agent může překládat přes BetterTranslator pomocí protokolu Model Context Protocol. Je to týž překlad, jaký dělá okno aplikace, přes tutéž továrnu a tytéž pojistky, a výsledky přistávají ve stejné historii chatu.

Co to je

Implementací je balíček pro C# ModelContextProtocol 2.1.0. Server se představuje jako bettertranslator

a nese pokyny, které si agent přečte při připojení. Překlad od agenta se směruje podle obsahu, nejprve JSON, pak Markdown, pak prostý text, a posílá se po jednotkách, ne jako jedno generování všechno nebo nic. Uložená teplota a trvalá instrukce z Pokročilého panelu putují s ním, poté běží tatáž kontrola a zjištění ze skládání dorazí jako poznámka.

Dva přenosy

Oba registrují totožných deset nástrojů touž cestou v kódu.

Roura, kterou spustí agent, přes bt mcp
Koncový bod HTTP hostovaný uvnitř aplikace, namapovaný na /mcp

Jeden rozdíl v chování tu je. Samostatně spuštěný server na rouře nemá okno, se kterým by mluvil, takže nástroj, který záznam zobrazí v rozhraní, hlásí, že žádné okno není: show_in_gui

Deset nástrojů

Test ověřuje, že nabízené rozhraní tvoří přesně těchto deset nástrojů a nic jiného.

Nástroj	Co dělá
translate_text	Synchronní. Bere text a zdrojový a cílový jazyk a odpovídá výsledkem, modelem, počtem tokenů, dobou trvání, případnou poznámkou a identifikátorem uloženého záznamu.
translate_file	Asynchronní. Odpovídá identifikátorem úlohy a stavem ve frontě, a chybu vrátí ještě před zařazením do fronty, když soubor neexistuje nebo když pro daný formát není čtečka.
translate_batch	Asynchronní. Odpovídá identifikátorem úlohy, složkou a počtem souborů. Berou se jen soubory přímo ve složce.
job_status	Dotazovací nástroj pro obě asynchronní úlohy. Odpovídá stavem, průběhem a jedním řádkem výsledku na soubor. Idempotentní.
job_cancel	Soubory, které už jsou zapsané, zapsané zůstanou, a zbytek se nepřeloží. Volání na dokončené úloze nic nezmění.
list_languages	Bez parametrů. Odpovídá modelem a jedním řádkem na jazyk s kódem, názvem, endonymem, písmem, směrem, dostupností a důvodem.
list_models	Bez parametrů. Odpovídá názvem, souborem, cestou, velikostí a příznaky nainstalováno a vybráno u každého modelu.
select_model	Hledá podle názvu, názvu souboru nebo úplné cesty. Volba se uloží a přežije server; běžící okno si ji převezme okamžitě.
show_in_gui	Jediný nástroj, který potřebuje okno. Bez něj vrátí chybu nástroje, která to říká.
get_entry	Přečte jeden uložený překlad podle identifikátoru. Neexistuje nástroj, který by záznamy vypisoval. Zdroj i výsledek se ořezávají a ořez uvádí, kolik znaků jich bylo celkem.

Paměť je volbou pouze u textového nástroje a je vypnutá, dokud si ji nevyžádáte. U nástrojů pro soubor ani pro složku neexistuje: use_memory

Každý nástroj nese popis, vstupní schéma s popisem u každé vlastnosti, výstupní schéma a anotace, takže agentovi stačí výpis nástrojů, který nabízí sám protokol, a žádnou další dokumentaci nepotřebuje.

Identifikátory úloh a dotazování

Identifikátory se počítají nahoru od job_0001

Najednou běží jedna úloha, takže úloha ve frontě čeká na tu běžící. Úloha končí jako neúspěšná, když nevytvořila žádné výsledky nebo když každý výsledek selhal, jinak končí jako hotová. Stavy jsou: queued running done failed cancelled

Čím každý nástroj odpovídá

Každá odpověď nese strojově čitelnou strukturu ve stylu snake case a vedle ní blok v Markdownu pro člověka. Chyba nastaví příznak chyby s prostou větou a bez struktury. Tabulky jsou skutečné tabulky Markdownu a každá buňka se ořezává, aby jedna dlouhá hodnota nezaplavila přepis.

Jak to zapnout

Koncový bod je ve výchozím stavu vypnutý. Po zapnutí naslouchá na loopbacku: 127.0.0.1:8765

Nastavení má oddíl Agent, ve kterém je přepínač, stavový řádek, adresa, token a dva registrační příkazy ke zkopírování. Naslouchání se zastaví a znovu rozběhne bez restartu aplikace.

Jak to zaregistrovat

Přes HTTP, se spuštěnou aplikací:

claude mcp add --transport http bettertranslator http://127.0.0.1:8765/mcp

Je-li nastaven token, připojte hlavičku authorization: --header "Authorization: Bearer <token>"

Přes rouru, bez spuštěné aplikace:

claude mcp add -s user bettertranslator -- "<path to>\cli\bt.exe" mcp

Vyžaduje se úplná cesta, protože holý název se rozřeší jen tam, kde soubor leží na vyhledávací cestě spustitelných souborů, a agent, který jej nenajde, hlásí uzavřené spojení místo chybějícího souboru. Sestavení umístí kopii vedle spustitelného souboru aplikace. U klienta nastaveného souborem JSON je záznamem server se standardním vstupem a výstupem, jehož příkazem je tato úplná cesta s jediným argumentem.

Odmítnutí a síť

Start odmítne port mimo platný rozsah i prázdného hostitele. Odmítne také jakoukoli vazbu mimo loopback bez tokenu, a to z toho důvodu, že navázání veřejné adresy otevírá počítač do sítě. Název localhost se počítá jako loopback.

Je-li nastaven token, hlavička authorization se porovnává přesně a cokoli jiného se odmítne.

Dvě omezení patří k těmto odmítnutím jedním dechem. Když je vazba mimo loopback záměrně nastavena, provoz jde prostým HTTP, protože hostitel nemá vůbec žádnou šifrovanou větev. A souborová úloha od agenta není omezena na žádnou konkrétní složku.

Diagnostika mrtvého spojení

První řádek na standardním chybovém výstupu je hlavička:

bettertranslator mcp <version>, built <yyyy-MM-dd HH:mm>, from <path>

Čas sestavení starší než vaše poslední změna znamená, že agent běží na zastaralé kopii, která příkaz mcp nemá. Sestavte znovu a poté se připojte.

Kam jdou výsledky

Sezení agenta dostane vlastní chat, pojmenovaný podle první věci v něm a poté přejmenovaný modelem, který právě přeložil, se záznamem na každý překlad. Otevřené okno řádek převezme bez restartu.

Identifikátor záznamu vrací jen textový nástroj a právě ten spotřebovává čtečka záznamů a nástroj pro zobrazení: entry_id

Zpět nahoru