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: MCP4Acumatica

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.

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

6. (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.