ufal-mcp 0.3.2

MCP server pro ÚFAL MFF UK NLP nástroje (NameTag, MasKIT, UDPipe, PONK) — česká právní AI

ufal-mcp

MCP server obalující NLP nástroje ÚFAL MFF UK pro zpracování českých právních textů.

Co umí

Tool	Backend	K čemu
anonymize	MasKIT	Pseudonymizace osobních údajů (jména, IČO, telefony, adresy, č.j., rodná čísla, data narození…)
extract_entities	NameTag 3	Named Entity Recognition — osoby, instituce, firmy, geo, data
analyze_morphology	UDPipe	Tokenizace, lemmatizace, POS tagging, závislostní parse
check_readability	PONK	Analýza čitelnosti právních textů (ARI, Verb Distance, Activity, Lexical diversity)

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 4 nástroje:

• mcp__ufal__anonymize
• mcp__ufal__extract_entities
• mcp__ufal__analyze_morphology
• mcp__ufal__check_readability

Claude Code (terminál)

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

Claude Desktop (Mac/Windows)

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

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

OpenAI Codex CLI

Edituj ~/.codex/config.toml:

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

Cursor

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

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

Windsurf, Cline, Zed, VS Code Copilot Agent

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).

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

• Kód: MIT
• Modely (přes API): CC BY-NC-SA — NEKOMERČNÍ použití. Pro placené nasazení potřebuješ explicitní písemné svolení autorů (Jana Straková, Milan Straka).

Bezpečnost

• Vše posíláš na externí server ÚFAL (quest.ms.mff.cuni.cz, lindat.mff.cuni.cz)
• ÚFAL loguje: čas, velikost dat, konfigurace serveru, IP. Obsah neloguje (přes POST).
• Pro plně privátní variantu lze rozšířit o lokální self-host (UDPipe + NameTag mají modely ke stažení).

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") — nižší přesnost než čeština	NameTag i UDPipe trénované primárně na CZ	Funguje, ale očekávej občasné chyby morfologie a NER
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	NameTag nemá SK model, UDPipe ano	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 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.