Skip to main content
Glama

lk-tko-mcp

An MCP server (Model Context Protocol) in Python that gives Claude tool access to the LK system (personal account, project lk-tko-v2).

What it is and why

MCP is an open protocol through which an external process gives the LLM a set of “tools”: ordinary functions with typed arguments. By connecting the server to Claude Code, you can ask Claude to call a specific function (“get counterparty status by INN”, “calculate penalties for a period for lkUser”, etc.) instead of explaining the context in text or manually digging into the DB/code every time.

The goal of this pet project is to build a reusable tool layer over the LK business logic that you can use from any future Claude Code session, not just inside the main repository.

Related MCP server: MikroCLAW

Stack

  • Python 3.10+, dependency manager — uv

  • SDK: mcp[cli] (v2, package mcp==2.1.0), class mcp.server.MCPServer

  • Transport: stdio (Claude Code launches the process and communicates with it over stdin/stdout)

Integration stack

The first tool (get_contragent_status) talks to the CUBA REST API v2 of lk-tko-v2 (OAuth2 password grant + generic entity search on rtneo$Contragent) — not directly to the DB. The request format is confirmed by working examples from curls.txt in the lk-tko-v2 repository.

Structure

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

Running and verifying locally

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

Connecting to Claude Code

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

Development plan

  1. Scaffold — done. A server with ping and get_contragent_status; runs locally and via Inspector.

  2. REST client — done. lk_client.py: OAuth2 password grant with token caching + search_entity() on top of CUBA REST v2.

  3. First real integration — done and verified live. get_contragent_status actually calls the lk-tko-v2 REST API via lk_client.search_entity("rtneo$Contragent", ...); verified via MCP Inspector with real data from the test environment.

  4. Connecting to Claude Code — done. claude mcp add lk-tko-mcp -- uv run run.py, status ✔ Connected. A guide for onboarding other developers — see ONBOARDING.md.

  5. Debt/billing (Priority 1 from RESEARCH.md) — done, 6 of 7 verified. get_contragent_debt, get_debt_by_phone, get_debt_by_email, get_serviced_periods, get_calculation_amount_type, get_contract, get_fine_details — all implemented via two new REST helpers in lk_client.py (call_v3 for custom v3 controllers, call_service for declarative v2 services). get_contragent_bills is implemented but blocked by a bug on the lk-tko-v2 side (see note below). get_calculations_tabs, get_debt_breakdown_by_real_estate, find_contragents_with_debt_older_than — not implemented, they have no REST wrapper in lk-tko-v2 at all (confirmed by grep across the entire repository).

Known issues

  • get_contragent_bills fails with 500. A bug on the lk-tko-v2 side: BillRepository.getBillsByContragentAndPeriod (line 71) references a nonexistent alias b.documentNumber instead of e.documentNumber — this breaks JPQL compilation on any call to /app/rest/v3/bill. A separate task has been filed to fix it in lk-tko-v2; our code is not at fault here.

  1. Expanding the toolset — one tool per specific recurring scenario (e.g., period/penalties for lkUser — see project memory project_lk_user_config), don't abstract in advance.

  2. (Optional) team access — claude mcp add lk-tko-mcp --scope project -- uv run run.py will create .mcp.json in the repository, which can be committed (without secrets).

Verification (after filling in .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

Security notes

  • .env is not committed; real secrets (client_id/secret, login/password) are stored only locally.

  • By default, point to the local dev instance of lk-tko-v2 (http://localhost:8080) rather than staging/prod — there may be non-anonymized personal data there.

  • The Contragent entity has no pre-confirmed "status" field — get_contragent_status returns the found entity in full; the field for the real status needs to be determined based on the actual REST API response.

Available Tools

10 tools
get_calculation_amount_typeC

Тип расчёта начислений и текущий долг по лицевому счёту/ИНН.

Inputs: pa_or_inn (required).

get_contractB

Список договоров контрагента с суммами начислений/платежей/пеней/долга.

contragent_id — UUID контрагента (см. поле "id" в get_contragent_status).

Inputs: contragent_id (required).

get_contragent_billsB

Счета контрагента за период.

contragent_id — UUID контрагента (см. поле "id" в get_contragent_status). date_from/date_to — даты в формате dd.MM.yyyy.

Inputs: contragent_id (required), date_to, is_paid, date_from.

get_contragent_debtA

Долг контрагента (основной долг, пени, госпошлина) по лицевому счёту или ИНН.

Inputs: pa_or_inn (required).

get_contragent_statusB

Найти контрагента ЛК по ИНН и вернуть его данные.

Возвращает найденную сущность Contragent целиком через REST API lk-tko-v2 — отдельного поля "статус" может не быть, это нужно смотреть по реальным данным, которые вернёт CUBA REST.

Inputs: inn (required).

get_debt_by_emailB

Долг по всем лицевым счетам, привязанным к email.

Inputs: email (required).

get_debt_by_phoneB

Долг по всем лицевым счетам, привязанным к телефону.

Inputs: phone (required).

get_fine_detailsA

Детализация пеней по лицевому счёту за период, по договорам и месяцам.

date_from/date_to — даты в формате dd.MM.yyyy.

Inputs: date_to (required), date_from (required), personal_account (required).

get_serviced_periodsB

Периоды обслуживания (даты начала/окончания) лицевого счёта или ИНН.

Inputs: pa_or_inn (required).

pingA

Проверка того, что сервер жив и подключён.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 10 tools

    Disambiguation3/5

    There are several debt-related tools (get_contragent_debt, get_debt_by_phone, get_debt_by_email, get_calculation_amount_type, get_contract) whose outputs overlap in debt/penalty figures; descriptions clarify different lookup keys or levels, but an agent could still struggle to choose among them. ping and the document/period tools are clearly distinct.

    Naming Consistency4/5

    All tools follow a get_ prefix and snake_case, and most use a readable get_<resource>_<detail> or get_<detail>_by_<identifier> pattern. The deviations are minor: ping has no get_, and names like get_calculation_amount_type are less intuitive than the rest.

    Tool Count5/5

    Ten tools is a reasonable size for a debt/contract lookup server. Each tool covers a distinct query need without excessive redundancy or an overwhelming surface.

    Completeness4/5

    The set provides solid read-only coverage: contragent lookup, debt by multiple identifiers, bills, contracts, service periods, and fine details. A minor gap is the lack of a direct debt lookup by contragent UUID, which would require using an INN from get_contragent_status as a workaround.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables Claude to interact with Acumatica ERP through a remote MCP server with per-user OAuth, role-based access, and 44 tools for querying and managing ERP data.
      21
      Apache 2.0
    • F
      license
      Not graded
      quality
      D
      maintenance
      Connects Claude to the Qoyod accounting system via its REST API, enabling natural language management of customers, invoices, vendors, journal entries, and other accounting resources through MCP tools.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables Claude Code to access amoCRM data such as pipelines, deals, contacts, and users via the MCP protocol.
      ISC