⚖️ LegalYes Court Praxis🔎 Пошук практики📄 Документ як доказ⚖ Доказова модель📁 Типові кейси🔌 MCP

court-praxis MCP — інструкція для ШІ-споживача (2026-07-03, оновлено: auth + outcome-шар)

Самодостатній гайд: які дані може надати MCP-сервер court-praxis (LegalYes Court Praxis), як їх правильно запитувати і чому довіряти. Аудиторія — інший ШІ (Claude/GPT/ агент), який підключає цей сервер як інструмент.

Зміст

0. Що за система (один абзац)

Локальна RAG-система над усією базою ЄДРСР — 134 млн рішень судів України (104 млн із завантаженим повним текстом, 107 млн із розібраними метаданими). Весь масив працює на аналітику й відбір; у глибокий семантичний індекс відібрано 1,9 млн рішень (усі інстанції; глибоке покриття касації ВС 2024-2026), векторизованих (multilingual-e5-large, pgvector HNSW) + повнотекстовий індекс + cross-encoder реранкер.

⚠️ Формулювання «із 118 млн запланованих» прибрано свідомо: велика база не «запланована», а робоча — 1,9 млн це результат відбору, а не міра недоробки. Деталі шарів — SEARCH_LEVELS.md §0. Поверх корпусу — майнені шари: правові позиції ВС, темпоральний зв'язок «рішення ↔ редакція норми», доказові профілі документів (DEP/POF), типові кейси за статтями (склад, факти, дії сторін зі статистикою). Кожен факт даних має cause_num (номер справи) і doc_id → публічна перевірка: https://reyestr.court.gov.ua/Review/{doc_id}.

1. Підключення

"court-praxis": {
  "command": "C:\\Users\\Dmitriy\\source\\repos\\AiRagNerExpertDecisionsSystem\\.venv\\Scripts\\python.exe",
  "args": ["C:\\Users\\Dmitriy\\source\\repos\\AiRagNerExpertDecisionsSystem\\vs_core\\court_praxis_mcp.py"]
}

2. Інструменти та дані, які вони віддають

2.1 search_practice(query, top_k≤25, mode, instances?, justice_kinds?, positions_only?, date_from/to?)

Дані: топ-K рішень за фактурою запиту (природна мова укр.). Кожен результат: cause_num, doc_id, court, instance (касація/апеляція/перша), justice, judgment, date, has_position (є правова позиція), departs_from_practice, annotation (норми+резолютивна), snippet, reyestr_url. Коли: конкретна фактура — «аліменти у твердій сумі», «відшкодування шкоди ДТП». Режими: semantic (швидко) → hybrid → hybrid_rerank (найякісніше, повільніше).

2.2 cassation_doctrine(query, top_k≤15, justice_kinds?)

Дані: ЛИШЕ позиції касаційних судів ВС (КГС/КЦС/ККС/КАС/ВП) — пресет «касація + positions_only + rerank» (окремий частковий HNSW-індекс, швидко). Коли: «яка позиція ВС щодо X», доктринальні питання. Для перетину галузей передавай justice_kinds (напр. «зменшення неустойки» без фільтра тягне кримінальне «зменшення покарання»).

2.3 get_decision(doc_id)

Дані: ОДНЕ рішення повністю: метадані, тіло (обрізане API), застосовані норми, анотація, позиційні пасажі. Коли: треба процитувати/показати конкретне рішення після пошуку.

2.4 law_text(act, article, as_of?) — ТЕКСТ норми (як zakon.rada.gov.ua)

Дані: повний текст статті з локального темпорального шару законодавства: title, body (текст), effective_from/until, is_current, caveat, rada_url (лінк на zakon.rada.gov.ua за nreg). as_of=YYYY-MM-DD → редакція, чинна на дату (для старих справ). Повні тексти зараз: ЦК (1290 ст.), КК (442), КАС (391), КЗпП (253); для решти актів тексту може не бути — якщо body порожнє, чесно скажи це користувачу. Коли: «процитуй ст. 625 ЦК», «що каже норма», перед аналізом практики.

2.5 law_practice(act, article, top_k, mode, justice?)

Дані: практика застосування КОНКРЕТНОЇ статті акта. Акти: ЦК, ЦПК, КК, КПК, КАС, ГК, ГПК, КУпАП, СК, ПК, КЗпП, Конституція. Повертає: total (скільки рішень у корпусі злінковано з нормою), positions, departures, і рішення з темпоральною редакцією: applied_edition («ред. 2026-02-01…2026-07-30»), applied_is_current — тобто видно, чи рішення застосовувало ЧИННУ редакцію статті (унікальна фіча). Масштаб: ЦК ст.625 → 92 999 рішень; КК ст.125 → 4 374 (з них 3 591 кримінальні). justice — фільтр галузі: для «КК 125» без нього видача мішає цивільні позови про шкоду, що цитують КК — передавай justice="Кримінальне" для кримінальної практики.

2.6 typical_case(article?) — «Типові кейси»

Дані: структурований data-driven довідник за статтею (зараз ready: «ст. 125 КК»; каталог розширюється). Містить: - eof — склад правопорушення (обʼєкт/обʼєктивна сторона/субʼєкт/субʼєктивна сторона/кваліфікуючі); - pof_deep — факти складу зі статистикою з ~2076 рішень: скільки разів суд визнав установленим (proven/not_proven/n/rate), якими засобами (чим), приклади cause_num; - actions_mined — реальні дії/клопотання сторін (захист/обвинувачення/потерпілий/суд) з частотами n і номерами справ — намайнено з практики, не вигадано; - algorithms/defence_playbook — синтезовані покрокові алгоритми (позначені як орієнтовні); - practice — ключові рішення з holding; decisions_sample+decisions_total (повний перелік — на web /cases); - _deep_instances — розбивка проаналізованого по інстанціях; - outcome_stats (нове, тришарова модель) — результати справ: розподіл (засуджено/ виправдано/закрито_примирення/…), покарання (серед засуджених), процесуальна_смертність (% + причини з cause_num — червоні флаги: чекліст перевірок ДО подачі), засоби_за_результатом (ПАРНІ відсотки: % справ групи, де засіб використано — порівнюй засуджено vs виправдано, одне число без пари не значить нічого). Подавай ДЕСКРИПТИВНО («у N справах…»), НЕ як прогноз виграшу. Без article — повертає всі профілі (компактно).

2.7 case_catalog()

Дані: каталог типових кейсів: категорії (Кримінальні/Цивільні/Господарські) → статті → status: ready|planned. Викликати ПЕРЕД typical_case, щоб знати, що доступне.

2.8 article_practice(query, justice?, instance?, top_k)

Дані: практика за статтею по ВСІХ інстанціях (не лише ВС) з reyestr-лінками; instance фільтрується нативно під час retrieval («касація» поверне постанови ККС ВС навіть якщо топ видачі забитий вироками 1-ї інстанції).

2.9 list_evidence_profiles(published_only?) + evidence_pack(slug, side?)

Дані: доказові профілі ДОКУМЕНТІВ (18 типів: господарські — акт виконаних робіт, договір поставки, ТТН, ПДВ-накладна, рахунок-фактура, банківська виписка…; кримінальні — висновок СМЕ, медична документація, показання потерпілого/свідків/підозрюваного, протокол огляду, речові докази, відеозапис): що документ доводить, осі якості (підпис/реквізити/оригінал…) з вагами з практики ВС (p_acc/lift/decisiveness/БДС), дефекти-defeaters, типові заперечення, цитати позицій ВС з cause_num. side орієнтує пак під позивача/відповідача.

2.10 «Стіл заказів» — request_indexing(kind, target?, note?) + list_index_requests(status?)

Дані/дія: черга заявок на індексацію — ти можеш ПОПРОСИТИ систему додати/покращити/виправити дані, коли потрібного ще нема або воно неповне. - kind: index_article (нова стаття як типовий кейс, target="ст. 190 КК") · improve (покращити наявну — більше рішень, апеляція/касація, конкретна вісь POF) · correction (виправити помилку — note ОБОВʼЯЗКОВО з cause_num + що не так) · evidence_doc (додати доказовий профіль документа) · other. - Дедуп: однакові open-заявки за (kind,target) нарощують votes (пріоритет), а не дублюються. - list_index_requests — публічна дорожня карта; глянь ПЕРЕД новою заявкою, щоб проголосувати за наявну. Спершу переконайся, що даних справді нема (case_catalog/typical_case/ search_practice), щоб не замовляти вже наявне. Коли: користувач питає про статтю/документ, яких ще нема в каталозі → залиш index_article і скажи користувачу, що заявку прийнято (з id). - index_request_status(target?, request_id?) — перевірка ВИКОНАННЯ заявки: статус у черзі + чи вже проіндексовано (є в каталозі) + прогрес майнінгу (mined/total/active). Викликай, щоб дізнатись, чи виконано твій request_indexing, замість повторної заявки.

2.10b report_feedback(title, details, kind) — канал «АГЕНТ → РОЗРОБНИК» (v1.7) ⭐

Якщо ти аудитуєш цей сервіс і бачиш дефект чи слабке місце — скажи розробнику. Твій звіт потрапляє у стіл замовлень, і мейнтейнер (ШІ-розробник) фіксить код / покращує / доробляє. - kind='bug' — щось НЕ ПРАЦЮЄ / некоректні дані / хибна цитата / зламана фіча; - kind='improve' — що можна ПОКРАЩИТИ (якість відповіді, релевантність, покриття, UX); - kind='todo' — чого БРАКУЄ / що доробити (нема категорії, фічі, даних).

Як писати: конкретний actionable title + details (де саме, що очікував, приклад/cause_num, який інструмент). Дедуп за title (однакові → votes = пріоритет). Повертає id заявки. report_bug(title, details) — короткий alias для kind='bug'.

Приклад: report_feedback("cassation_doctrine повертає рішення без правової позиції", "запит «позовна давність», у 3/10 результатів немає holding; варто фільтрувати positions_only", kind="bug")

2.11 fulltext_search(query, top_k≤25, category_code?) — ES-повнотекст (v1.6)

Що: лексичний повнотекстовий пошук по рішеннях через Elasticsearch з українською морфологією — словоформи матчаться (стягнув↔стягнення, крадіжки↔крадіжка). Коли: точний термін/фраза, коли семантика search_practice заширока; або точний збіг слова. category_code (опц.) звужує до піддерева категорії ЄДРСР. Формат відповіді — як search_practice. vs search_practice: там — семантика/гібрид; тут — точні слова з лематизацією.

2.12 fact_categories() + category_facts(category_code) — довідник фактів (v1.6)

Майнінг «від категорії ЄДРСР → до атому»: канонічні факти, намайнені з реальних рішень категорії. - fact_categories() — які категорії мають намайнений довідник: category_code, name, justice_kind, n_facts, n_decisions_mined. Discovery ПЕРЕД category_facts. - category_facts(code) — доказовий профіль категорії: канонічні факти за kind (element_of_claim/defense/procedural/qualifying), для кожного — established (proven/partial/not_proven) і топ засобів доказування; плюс top_means по категорії. Коли: «які факти доводяться у справах категорії X і чим», «що треба довести у спорі про Y». Довіра: факти канонізовані (дедуп), щоб однаково інтерпретувати; статистика дескриптивна.

2.13 server_info() — версія, changelog, виявлення оновлень

Дані: version, changelog[], список інструментів, A2A-ендпоінти, update_hint. Коли: ПЕРШИМ викликом сесії (дізнатись актуальні можливості) або коли інструмент повівся несподівано. Якщо version виросла проти твоєї попередньої — зʼявились нові інструменти. Оновитись: stdio → git pull+reconnect; hosted HTTP → централізовано (сам). Ресурс-аналог: court-praxis://changelog.

2.12 Ресурс court-praxis://stats

Живі показники корпусу (кількість рішень, черга векторизації).

3. Семантика й довіра до даних

4. Патерни використання (рецепти)

Питання користувача Виклик
«Позиція ВС щодо …» cassation_doctrine(query, justice_kinds=[галузь])
«Практика по ст. 625 ЦК» law_practice("ЦК","625") → для доктрини далі cassation_doctrine
«Процитуй текст ст. 125 КК» law_text("КК","125") (as_of для старої редакції)
«Мене звинувачують за ст.125 КК, що робити» typical_case("ст. 125 КК") → algorithms+pof+actions
«Чим довести факт поставки» list_evidence_profiles() → evidence_pack(slug, side)
«Знайди справи схожі на мою фактуру» search_practice(опис фактури, mode=hybrid_rerank)
«Покажи повний текст рішення» get_decision(doc_id) або reyestr-лінк
«Скільки рішень по X у якій інстанції» article_practice(..., instance=…) + typical_case._deep_instances

5. Обмеження/етикет

6. A2A (Agent2Agent) — делегувати таск нашому агенту (DEMO)

Крім MCP (ми = інструменти для ТВОГО агента), сервіс експонує себе як автономний агент за протоколом A2A — інший агент делегує йому цілий таск і забирає результат async.