ufal-mcp 0.7.1

MCP server pro ÚFAL MFF UK NLP nástroje — production-grade anonymizace, multilingvální NER (33+ jazyků) + UDPipe (961 modelů, auto-detect 8 jazyků), Charles Translator (8 jazyků), PONK rich output (4 feature sety), Korektor, NameTag XML/vertical

ufal-mcp

MCP server obalující NLP nástroje ÚFAL MFF UK — multilingvální NER + morfologie (35 jazyků auto-detect), česká production-grade anonymizace, překlad CZ↔EN/UK/RU + EN↔FR/DE/PL/HI, čitelnost a korektura.

Co umí

Tool	Backend	K čemu
extract_entities	NameTag 3	NER pro CZ (bohatý CNEC 2.0 tagset) + 30+ dalších jazyků (UNER PER/ORG/LOC) s auto-detekcí
anonymize	MasKIT	Production-grade pseudonymizace (v0.6.0): regex pre-pass pro strukturovanou PII (telefon, IČO, č.j., e-mail, …) + stop-list filter (rollback MasKIT halucinací jako "stát"→"UniAgentury") + opt-in placeholder_mode (deterministic OSOBA1/MESTO1/ULICE1, dedup, reprodukovatelné)
analyze_morphology	UDPipe	Tokenizace, lemmatizace, POS tagging, závislostní parse — auto-detect CZ/SK
check_readability	PONK	Analýza čitelnosti právních textů (ARI, Verb Distance, Activity, Lexical diversity)
correct_text	Korektor	CZ spell checker + auto-doplnění/odstranění diakritiky (užitečné pro OCR výstupy, mobilní zprávy)
translate_text	Charles Translator	Překlad mezi 8 jazyky (CZ/EN/FR/DE/PL/RU/UK/HI), 17 párů incl. document mode pro CZ↔EN. Vlastní jména zachovává v originále.

Podporované jazyky NER (testováno na živém API 20.5.2026)

Plné pokrytí (33+ jazyků, ✓ = ověřeno):

• 🇨🇿 CZ (CNEC 2.0 nebo UNER) · 🇸🇰 SK · 🇬🇧 EN · 🇩🇪 DE · 🇫🇷 FR · 🇮🇹 IT · 🇪🇸 ES · 🇵🇹 PT · 🇳🇱 NL
• 🇵🇱 PL · 🇭🇺 HU · 🇷🇴 RO · 🇸🇮 SL · 🇧🇬 BG · 🇬🇷 EL · 🇭🇷 HR · 🇷🇸 SR · 🇺🇦 UK · 🇷🇺 RU
• 🇫🇮 FI · 🇱🇹 LT · 🇱🇻 LV · 🇪🇪 ET · 🇩🇰 DA · 🇸🇪 SV · 🇳🇴 NO (Bokmål + Nynorsk)
• 🇨🇳 ZH · 🇦🇪 AR · 🇹🇷 TR · 🇻🇳 VI · 🇮🇳 HI · 🌍 Maghrebi mix

Funguje cyrilice (UK, RU, BG, SR), latinka, čínské znaky, devanagari, hebrejské+arabské skripty. Drobné limity známé u JA/KO (particles), HE/TH (chudší coverage).

Instalace

Z PyPI (doporučeno):

pip install ufal-mcp

Nebo ze source:

git clone https://github.com/Buggy1111/ufal-mcp.git
cd ufal-mcp
pip install -e .

Registrace v MCP klientovi

ufal-mcp je standardní MCP server (stdio transport) — funguje s libovolným MCP klientem. Po registraci a restartu klienta máš k dispozici 6 nástrojů:

• mcp__ufal__extract_entities — multilingvální NER (33+ jazyků)
• mcp__ufal__anonymize — pseudonymizace CZ
• mcp__ufal__analyze_morphology — morfologie CZ/SK
• mcp__ufal__check_readability — čitelnost CZ
• mcp__ufal__correct_text — spell check + diakritika CZ
• mcp__ufal__translate_text — překlad mezi 8 jazyky (CZ↔EN/UK/RU + EN↔FR/DE/PL/HI)

Claude Code (terminál)

claude mcp add ufal -s user -- ufal-mcp

Claude Desktop

Starší Claude Desktop (Mac .app z anthropic.com, Windows .exe installer):

Edituj ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) nebo %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ufal": {
      "command": "ufal-mcp"
    }
  }
}

Nová Claude Desktop (Microsoft Store / appx package, "Cowork" UI): k 05/2026 podporuje pouze remote MCP servery přes HTTP URL (Settings → Connectors → Add custom connector). Lokální stdio MCP servery jako ufal-mcp zde přidat nelze. Workaround: použít Claude Code CLI nebo počkat, až Anthropic přidá stdio podporu i do nového UI.

Na Windows může být ufal-mcp.exe mimo PATH (typicky C:\Python\Python3xx\Scripts\ufal-mcp.exe nebo %APPDATA%\Python\Python3xx\Scripts\ufal-mcp.exe). V configu pak místo "command": "ufal-mcp" použij plnou cestu.

OpenAI Codex CLI (struktura dle Codex docs, autorem netestováno)

Edituj ~/.codex/config.toml:

[mcp_servers.ufal]
command = "ufal-mcp"

Cursor (autorem netestováno)

Edituj .cursor/mcp.json v projektu (nebo globálně ~/.cursor/mcp.json):

{
  "mcpServers": {
    "ufal": {
      "command": "ufal-mcp"
    }
  }
}

Windsurf, Cline, Zed, VS Code Copilot Agent (autorem netestováno)

Stejný mcpServers JSON formát — viz dokumentace daného klienta. command: "ufal-mcp" (případně absolutní cesta ~/path/to/.venv/bin/ufal-mcp pokud nemáš ufal-mcp v PATH).

Otestováno autorem: Claude Code (Linux/WSL2), Claude Desktop MS Store na Windows (neuspěšně — viz výše). Ostatní klienti používají standardní MCP stdio + JSON config, takže by teoreticky měli fungovat, ale nedostalo se to k otestování. Pull request s potvrzením vítaný.

Použití

V Claude Code stačí napsat například:

Anonymizuj text z PRICHOZI_POSTA/2026-03-02_odpoved_na_stiznost.md a vrať mi čistou verzi pro veřejný demo.

Vytáhni z dokumentu všechny osoby, soudy a č.j. — chystám matter intake pro /litigation-legal:matter-intake.

Zlemmatizuj tenhle text a vyhoď mi všechny tvary slova "soud" — potřebuju fulltextové vyhledávání.

Projeď moje podání přes PONK — kolik vět má příliš dlouhých?

Licence

Tento wrapper ufal-mcp má MIT licenci (viz LICENSE).

Pod ním jsou ale čtyři samostatné ÚFAL nástroje, každý s vlastní licencí. Pro úplný obrázek:

Komponenta	Autoři	Licence software	Licence modelů
NameTag 3	Jana Straková, Milan Straka	MPL 2.0 (commercial OK)	CC BY-NC-SA (NON-commercial)
UDPipe	Milan Straka, Jana Straková	MPL 2.0 (commercial OK)	CC BY-NC-SA (NON-commercial)
MasKIT	Jiří Mírovský, Barbora Hladká	MPL 2.0 (commercial OK)	(rule-based, není separátní model)
PONK	Jiří Mírovský, Silvie Cinková, Barbora Hladká + autoři podaplikací: Ivan Kraus, Arnold Stanovský, Jan Černý, Ivana Kvapilíková, Tomáš Polák, Silvie Cinková	MPL 2.0 (commercial OK)	(rule-based + UDPipe pro tokenizaci → viz CC BY-NC-SA výše)

Důležité: tento wrapper nevolá lokální instalaci ÚFAL nástrojů, ale jejich veřejné API služby (lindat.mff.cuni.cz, quest.ms.mff.cuni.cz). Na použití API se vztahují podmínky LINDAT/CLARIAH-CZ a ÚFAL — krátce: bezplatné pro akademické a osobní použití, hromadný / placený / produkční traffic vyžaduje explicitní souhlas autorů a provozovatele API.

Pro placené (komerční) nasazení nebo vyšší zátěž doporučuji:

1. Kontaktovat příslušné autory (viz tabulka výše) a [e-mail]
2. Zvážit lokální self-host (NameTag i UDPipe mají modely ke stažení) — pak se na tebe licence modelů (CC BY-NC-SA) vztahují přímo a víš přesně, co ti loguje co.

Bezpečnost

• Vše posíláš na externí server ÚFAL (quest.ms.mff.cuni.cz, lindat.mff.cuni.cz). Tento wrapper to nijak nešifruje ani neanonymizuje před odesláním — kromě toho, co dělá anonymize tool, pokud ho voláš.
• Provoz typického HTTPS access logu na ÚFAL straně standardně eviduje minimálně čas, IP, velikost požadavku a konfigurační parametry. K explicitnímu vyjádření ÚFAL ohledně loggingu obsahu POST body autor zatím nedohledal písemný zdroj — chovej se proto, jako že obsah teoreticky logovat může, a před odesláním citlivých dat nejdřív projeď text přes anonymize.
• Pro plně privátní zpracování doporučuji lokální self-host: NameTag i UDPipe mají modely ke stažení (CC BY-NC-SA → osobní/akademické použití OK), MasKIT a PONK mají MPL 2.0 source. Tento wrapper se zatím připojuje jen k veřejnému ÚFAL API; lokální backend není podporovaný (může přibýt v budoucnu).

Známé limitace

Wrapper sám funguje deterministicky, ale upstream API mají několik dokumentovaných nedostatků. Pro každý je v této verzi přidaná detekce / warning:

Limitace	Příčina	Co s tím
Fragmentace názvů firem ("ZR Trade s.r.o." → MasKIT zachytí jen "ZR" a "s.r.o.", slovo "Trade" zůstane neanonymizované)	MasKIT tokenizace	anonymize vrací warnings — NameTag cross-check najde celou entitu a upozorní, že MasKIT nepokryl celý název
Římské číslice v názvech soudů ("MS Bratislava II" → "II" není anonymizováno)	MasKIT regex pattern	Detekováno warningem (viz výše)
Soudci se neanonymizují	MasKIT záměrný whitelist	By-design — pokud potřebuješ anonymizovat soudce, použij extract_entities + manuální post-processing
Slovenské tvary ("Tóthovej", "súd", "sa") v CZ-only modelech	Default NameTag (nametag3-czech-cnec2.0-240830) a CZ UDPipe model jsou trénované jen na češtině	Pro NameTag použij multilingvální nametag3-multilingual-uner-250203 — pokrývá CZ + SK + 11 dalších jazyků (UNER + cross-lingual transfer); pro UDPipe analyze_morphology(model="auto") přepne na SK model
Generické placeholdery v MasKIT ("FABBR1", "IABBR1") bez typu entity	MasKIT API	Tool anonymize má classify_types=True (default) — 100 % náhrad klasifikováno čtyřvrstvým fallbackem (placeholder pattern → pre-context → NameTag → fallback dle obsahu)
MasKIT systematicky neanonymizuje názvy státních institucí (Nejvyšší soud, Ústavní soud, ministerstva, soudy obecně)	MasKIT design	anonymize má strict=True (default) — pre-pass přes NameTag najde firmy/úřady/instituce v originálu a sám je nahradí placeholdery FIRMA1, INSTITUCE1, … ještě před voláním MasKIT
Slovenský text v UDPipe morfologii	Default UDPipe model je CZ; SK model existuje samostatně	analyze_morphology má model="auto" (default) — auto-detect SK podle markerů (som, vďaka, súd, ktorá, vo…) a přepne na slovenský UDPipe model
NER mimo češtinu (slovenština, angličtina, němčina, polština, ukrajinština…)	Default model nametag3-czech-cnec2.0-240830 je CZ-only	Volej extract_entities(model="nametag3-multilingual-uner-250203") — NameTag 3 multilingvální UNER pokrývá 13+ jazyků (CZ, SK, EN, DE, ZH, HR, DA, NO, PT, SR, SV, UK + cross-lingual transfer). Roadmap: auto-detect non-CZ i v extract_entities
NER nepokrývá: ID karty, řidičáky, pasy, čísla účtů, datovky, spisové značky	MasKIT roadmap (future updates)	Tyto údaje dohledat ručně před odesláním do veřejného sdílení

Pro citlivá data: vždy zkontroluj warnings v odpovědi anonymize a anonymizovaný výstup ručně před zveřejněním. Wrapper je nástroj na první průchod, ne náhrada za lidskou kontrolu.

Použité API

• POST https://lindat.mff.cuni.cz/services/nametag/api/recognize
• POST https://lindat.mff.cuni.cz/services/udpipe/api/process
• POST https://quest.ms.mff.cuni.cz/maskit/api/process
• POST https://quest.ms.mff.cuni.cz/ponk/api/process

Vývoj

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Smoke test (volá živé ÚFAL API)
python test_live.py

Release proces

PyPI publish je automatický přes Trusted Publisher (OIDC).

Jednorázové nastavení (PyPI strana):

1. Vytvořit balíček na https://pypi.org (nebo nechat workflow, ať ho vytvoří první run)
2. PyPI → Account settings → Publishing → Add pending publisher:
   • PyPI Project Name: ufal-mcp
   • Owner: Buggy1111
   • Repository: ufal-mcp
   • Workflow: release.yml
   • Environment: pypi

Release nového releasu:

# Bump version v pyproject.toml a src/ufal_mcp/__init__.py
git commit -am "release: v0.X.0"
git tag v0.X.0
git push origin main --tags

GHA workflow release.yml automaticky postaví distribution, publishne na PyPI a vytvoří GitHub Release s artefakty.