# judikatura-mcp – MCP server pro soudní rozhodnutí ČR (rozhodnuti.justice.cz)

[![CI](https://github.com/marshall1727/judikatura-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/marshall1727/judikatura-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
![Python](https://img.shields.io/badge/python-3.10%2B-blue)

> **English summary.** A local [Model Context Protocol](https://modelcontextprotocol.io) server (stdio)
> for the Czech Ministry of Justice public database of **anonymised court decisions** of district, regional
> and high courts (rozhodnuti.justice.cz). Full-text search with filters (court, legal-institute keywords,
> statutory provision, judge, type, dates), lookup by case number or ECLI, browsing of the official
> open-data API by publication date, full decision text, DOCX/TXT export and a local SQLite/FTS5 cache.
> Czech documentation follows.

Lokální MCP server pro Claude Desktop, Claude Code a další MCP klienty. Umožňuje asistentovi
vyhledávat a číst **plné texty anonymizovaných rozhodnutí** okresních, krajských a vrchních soudů
zveřejňovaných Ministerstvem spravedlnosti.

## Nástroje

| Nástroj | Zdroj | Co dělá |
|---|---|---|
| `search_decisions` | vyhledávací API webu | fulltext (všechna slova / kterékoli / přesná fráze) + filtry: soud, klíčová slova, ustanovení předpisu (§ + číslo/rok), soudce, typ rozhodnutí, datum vydání / zveřejnění, vztah k napadenému rozhodnutí |
| `find_by_case_number` | vyhledávací API webu | hledání podle spisové značky `20 C 98/2026` (doporučeno zadat i soud) |
| `browse_published` | oficiální opendata API | procházení podle data zveřejnění: roky → měsíce → dny → seznam rozhodnutí (po 100) |
| `get_decision` | oficiální opendata API | plný text podle uuid nebo ECLI (záhlaví, výrok, odůvodnění, poučení, metadata); ukládá do cache |
| `export_decision` | – | uloží rozhodnutí jako `.docx` nebo `.txt` |
| `cache_fill`, `cache_fill_day` | obojí | hromadně stáhne plné texty podle filtru / za den do lokální SQLite cache |
| `cache_search` | lokální cache | fulltext FTS5 bez ohledu na diakritiku (`OR`, `"fráze"`, `prefix*`, `NOT`) nad staženými rozhodnutími |
| `cache_stats` | lokální cache | stav cache |
| `list_courts`, `list_keywords` | číselníky | 109 soudů (kód → název), 1 072 klíčových slov (právních institutů) |

Soudy i klíčová slova lze zadávat **česky** (`Krajský soud v Ostravě`, `bezdůvodné obohacení`) – server je
převede na kódy. Ustanovení se zadává jako `§ 2991 z. č. 89/2012 Sb.` nebo jen `89/2012`.

## Instalace

### A) Claude Desktop – jedním kliknutím (.mcpb)

1. Stáhněte `judikatura-mcp-X.Y.Z.mcpb` z [Releases](https://github.com/marshall1727/judikatura-mcp/releases).
2. Otevřete soubor dvojklikem (nebo Claude Desktop → Settings → Extensions → Advanced settings → Install Extension…).
3. V nastavení rozšíření volitelně zadejte umístění cache a složku pro export.

Balíček používá runtime **uv** – Claude Desktop si sám obstará Python i závislosti.

### B) Ručně (Claude Desktop, Claude Code, jiný klient)

```powershell
git clone https://github.com/marshall1727/judikatura-mcp.git
cd judikatura-mcp
.\install.ps1          # vytvoří .venv, nainstaluje, spustí testy a vypíše blok pro claude_desktop_config.json
```

nebo s `uv`:

```json
{
  "mcpServers": {
    "judikatura": {
      "command": "uv",
      "args": ["--directory", "C:\\cesta\\k\\judikatura-mcp", "run", "judikatura-mcp"]
    }
  }
}
```

### Proměnné prostředí

| Proměnná | Význam | Výchozí |
|---|---|---|
| `JUDIKATURA_MCP_DB` | soubor SQLite cache | `%LOCALAPPDATA%\judikatura-mcp\cache.sqlite` (Windows), `~/.local/share/judikatura-mcp/cache.sqlite` |
| `JUDIKATURA_MCP_EXPORT_DIR` | složka pro export DOCX/TXT | `~/Documents/judikatura-mcp` |

## Příklady dotazů

- „Najdi rozhodnutí Krajského soudu v Ostravě z roku 2026 k § 2991 OZ (bezdůvodné obohacení).“
- „Vyhledej rozsudky s klíčovými slovy *smluvní pokuta* a *ochrana spotřebitele* vydané po 01.01.2026.“
- „Najdi 8 Co 85/2026 u KSOS a ulož ho jako DOCX.“
- „Stáhni do cache rozhodnutí OSPH01 k § 2079 OZ z letošního roku a pak v nich najdi *odstoupení od smlouvy*.“
- „Co bylo zveřejněno 19.09.2026?“

## Zdroje dat a omezení

- **Oficiální opendata API** (https://rozhodnuti.justice.cz/opendata/) umožňuje jen procházení podle data
  zveřejnění a stažení detailu rozhodnutí. Používají ho `browse_published`, `get_decision`, `cache_fill_day`.
- **Vyhledávací endpoint** `/api/finaldoc?…` je interní API webové aplikace (stejné, které volá formulář
  na webu). Není dokumentované a může se změnit bez upozornění. Používají ho `search_decisions`,
  `find_by_case_number`, `cache_fill` a dohledání podle ECLI.
- Fulltext s velmi častými slovy („smlouva“, „žalobce“) trvá na straně serveru i desítky sekund a může
  skončit chybou – kombinujte s filtrem soudu, ustanovení nebo data.
- Texty jsou **anonymizované zdrojem**; jména, adresy, data a částky mohou být nahrazeny placeholdery,
  které server zobrazuje v hranatých závorkách (`[datum]`, `[Jméno žalobkyně]`). Při citaci používejte
  soud, spisovou značku, ECLI a datum vydání z metadat.
- Databáze obsahuje rozhodnutí nižších soudů zveřejňovaná **přibližně od roku 2021**; NS, NSS a ÚS jsou
  v číselníku, ale primárním zdrojem pro ně zůstávají jejich vlastní databáze.
- Server posílá nejvýše 4 souběžné požadavky; `cache_fill` má strop 500 rozhodnutí na volání.
- Číselníky soudů a klíčových slov odpovídají webové aplikaci verze 2.2.0 (říjen 2026).

## Vývoj

```powershell
pip install -e ".[dev]"
ruff check .
pytest                          # offline testy (fixture, mock HTTP)
python scripts\build_mcpb.py    # dist\judikatura-mcp-<verze>.mcpb (vyžaduje Node.js pro npx @anthropic-ai/mcpb)
```

Struktura:

```
judikatura_mcp/      server.py (nástroje), api.py (HTTP klient), format.py (text, číselníky),
                     cache.py (SQLite + FTS5), export.py (DOCX/TXT), courts.json, flags.json
mcpb/                manifest.json, icon.png, src/server.py – podklady balíčku pro Claude Desktop
scripts/build_mcpb.py
tests/               offline testy
.github/workflows/   CI (lint, testy, build) a Release (push tagu vX.Y.Z → .mcpb, wheel, sdist, zip)
```

## Licence

MIT. Data: Ministerstvo spravedlnosti ČR, otevřená data – https://rozhodnuti.justice.cz/opendata/