lk-tko-mcp

MCP-сервер (Model Context Protocol) на Python, который даёт Claude инструментальный доступ к системе ЛК (личный кабинет, проект lk-tko-v2).

Что это и зачем

MCP — открытый протокол, по которому внешний процесс отдаёт LLM набор «инструментов» (tools): обычных функций с типизированными аргументами. Подключив сервер к Claude Code, можно попросить Claude вызвать конкретную функцию («получить статус контрагента по ИНН», «посчитать пени по периоду для lkUser» и т.п.) вместо того, чтобы объяснять контекст текстом или лезть в БД/код вручную каждый раз.

Цель пет-проекта — получить переиспользуемый инструментальный слой над бизнес-логикой ЛК, которым можно пользоваться из любых будущих сессий Claude Code, а не только внутри основного репозитория.

Related MCP server: MCP4Acumatica

Стек

• Python 3.10+, менеджер зависимостей — uv

• SDK: mcp[cli] (v2, пакет mcp==2.1.0), класс mcp.server.MCPServer

• Транспорт: stdio (Claude Code запускает процесс и общается с ним по stdin/stdout)

Стек интеграции

Первый tool (get_contragent_status) ходит в CUBA REST API v2 lk-tko-v2 (OAuth2 password grant + generic entity search по rtneo$Contragent) — не напрямую в БД. Формат запросов подтверждён рабочими примерами из curls.txt репозитория lk-tko-v2.

Структура

lk-tko-mcp/
├── server.py       # MCPServer + @mcp.tool() функции — вся логика инструментов
├── lk_client.py     # REST-клиент к lk-tko-v2 (OAuth2 + entity search)
├── run.py          # точка входа, которую регистрирует Claude Code
├── .env.example    # шаблон переменных окружения для доступа к ЛК (реальный .env не коммитится)
├── pyproject.toml
└── uv.lock

Запуск и проверка локально

uv run mcp dev run.py   # открывает MCP Inspector в браузере — можно вручную вызывать tools

Подключение к Claude Code

claude mcp add lk-tko-mcp -- uv run run.py
claude mcp list          # проверить, что статус Connected

План разработки

1. Каркас — готово. Сервер с ping и get_contragent_status, запускается локально и через Inspector.

2. REST-клиент — готово. lk_client.py: OAuth2 password grant с кэшированием токена + search_entity() поверх CUBA REST v2.

3. Первая настоящая интеграция — готово и проверено вживую. get_contragent_status реально дёргает REST API lk-tko-v2 через lk_client.search_entity("rtneo$Contragent", ...), проверено через MCP Inspector с реальными данными тестового контура.

4. Подключение к Claude Code — готово. claude mcp add lk-tko-mcp -- uv run run.py, статус ✔ Connected. Гайд по разворачиванию для других разработчиков — см. ONBOARDING.md.

5. Долг/биллинг (Приоритет 1 из RESEARCH.md) — готово, 6 из 7 проверены. get_contragent_debt, get_debt_by_phone, get_debt_by_email, get_serviced_periods, get_calculation_amount_type, get_contract, get_fine_details — все реализованы через два новых REST-хелпера в lk_client.py (call_v3 для кастомных v3-контроллеров, call_service для декларативных v2-сервисов). get_contragent_bills реализован, но заблокирован багом на стороне lk-tko-v2 (см. примечание ниже). get_calculations_tabs, get_debt_breakdown_by_real_estate, find_contragents_with_debt_older_than — не реализованы, у них нет REST-обёртки в lk-tko-v2 вообще (подтверждено grep по всему репозиторию).

Известные проблемы

• get_contragent_bills падает с 500. Баг на стороне lk-tko-v2: BillRepository.getBillsByContragentAndPeriod (строка 71) ссылается на несуществующий алиас b.documentNumber вместо e.documentNumber — ломает JPQL-компиляцию при любом вызове /app/rest/v3/bill. Заведена отдельная задача на исправление в lk-tko-v2, наш код тут ни при чём.

5. Расширение набора инструментов — по одному инструменту на конкретный повторяющийся сценарий (например, период/пени для lkUser — см. память проекта project_lk_user_config), не абстрагировать заранее.

6. (Опционально) командный доступ — claude mcp add lk-tko-mcp --scope project -- uv run run.py создаст .mcp.json в репозитории, который можно закоммитить (без секретов).

Проверка (после заполнения .env)

# 1. Юнит-уровень, без Claude
uv run python -c "from lk_client import search_entity; print(search_entity('rtneo$Contragent', [{'property':'inn','operator':'=','value':'<реальный ИНН>'}]))"

# 2. Через MCP Inspector
uv run mcp dev run.py

# 3. End-to-end
claude mcp add lk-tko-mcp -- uv run run.py
claude mcp list

Примечания по безопасности

• .env не коммитится, реальные секреты (client_id/secret, логин/пароль) хранятся только локально.

• По умолчанию указывай локальный dev-инстанс lk-tko-v2 (http://localhost:8080), а не staging/прод — там может быть неанонимизированный ПДн.

• У сущности Contragent нет заранее подтверждённого поля "статус" — get_contragent_status возвращает найденную сущность целиком, поле для реального статуса нужно определить по факту ответа REST API.