lk-tko-mcp

MCP-Server (Model Context Protocol) auf Python, der Claude Werkzeugzugriff auf das System LK (persönliches Konto, Projekt lk-tko-v2) verschafft.

Was das ist und warum

MCP — ein offenes Protokoll, über das ein externer Prozess einem LLM einen Satz von „Werkzeugen“ (Tools) bereitstellt: normale Funktionen mit typisierten Argumenten. Wenn der Server an Claude Code angeschlossen ist, kann man Claude bitten, eine bestimmte Funktion aufzurufen („Kontrahentenstatus anhand der INN abrufen“, „Verzugszinsen für einen Zeitraum für lkUser berechnen“ usw.), anstatt den Kontext jedes Mal als Text zu erklären oder manuell in Datenbank/Code nachzusehen.

Ziel des Pet-Projekts ist es, eine wiederverwendbare Werkzeugschicht über der Geschäftslogik von LK zu erhalten, die aus allen zukünftigen Claude-Code-Sitzungen genutzt werden kann, nicht nur innerhalb des Hauptrepositorys.

Related MCP server: MCP4Acumatica

Stack

• Python 3.10+, Abhängigkeitsverwaltung — uv

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

• Transport: stdio (Claude Code startet den Prozess und kommuniziert über stdin/stdout mit ihm)

Integrations-Stack

Das erste Tool (get_contragent_status) greift auf die CUBA REST API v2 von lk-tko-v2 zu (OAuth2-Password-Grant + generische Entitätssuche über rtneo$Contragent) — nicht direkt auf die Datenbank. Das Format der Anfragen ist durch funktionierende Beispiele aus curls.txt des Repositories lk-tko-v2 bestätigt.

Struktur

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

Start und lokale Überprüfung

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

Anbindung an Claude Code

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

Entwicklungsplan

1. Grundgerüst — fertig. Der Server mit ping und get_contragent_status lässt sich lokal und über den Inspector starten.

2. REST-Client — fertig. lk_client.py: OAuth2-Password-Grant mit Token-Caching + search_entity() auf Grundlage von CUBA REST v2.

3. Erste echte Integration — fertig und live geprüft. get_contragent_status ruft tatsächlich die REST API von lk-tko-v2 über lk_client.search_entity("rtneo$Contragent", ...) auf; geprüft über den MCP Inspector mit realen Daten der Testumgebung.

4. Anbindung an Claude Code — fertig. claude mcp add lk-tko-mcp -- uv run run.py, Status ✔ Connected. Einrichtungsanleitung für andere Entwickler — siehe ONBOARDING.md.

5. Schulden/Billing (Priorität 1 aus RESEARCH.md) — fertig, 6 von 7 geprüft. get_contragent_debt, get_debt_by_phone, get_debt_by_email, get_serviced_periods, get_calculation_amount_type, get_contract, get_fine_details — alle über zwei neue REST-Helfer in lk_client.py implementiert (call_v3 für benutzerdefinierte v3-Controller, call_service für deklarative v2-Services). get_contragent_bills ist implementiert, wird aber durch einen Bug auf Seiten von lk-tko-v2 blockiert (siehe Hinweis unten). get_calculations_tabs, get_debt_breakdown_by_real_estate, find_contragents_with_debt_older_than — nicht implementiert, für sie gibt es in lk-tko-v2 überhaupt keinen REST-Wrapper (per grep über das gesamte Repository bestätigt).

Bekannte Probleme

• get_contragent_bills schlägt mit 500 fehl. Bug auf Seiten von lk-tko-v2: BillRepository.getBillsByContragentAndPeriod (Zeile 71) verweist auf den nicht existierenden Alias b.documentNumber statt e.documentNumber — das führt bei jedem Aufruf von /app/rest/v3/bill zu einem JPQL-Kompilierungsfehler. Es wurde ein separates Ticket zur Korrektur in lk-tko-v2 angelegt; unser Code hat damit nichts zu tun.

5. Erweiterung des Tool-Satzes — jeweils ein Tool pro konkretem, wiederkehrendem Szenario (z. B. Zeitraum/Verzugszinsen für lkUser — siehe Projektgedächtnis project_lk_user_config), nicht im Voraus abstrahieren.

6. (Optional) Team-Zugriff — claude mcp add lk-tko-mcp --scope project -- uv run run.py erstellt eine .mcp.json im Repository, die committet werden kann (ohne Geheimnisse).

Überprüfung (nach dem Ausfüllen der .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

Sicherheitshinweise

• .env wird nicht committet, echte Geheimnisse (client_id/secret, Login/Passwort) werden nur lokal gespeichert.

• Gib standardmäßig die lokale Dev-Instanz von lk-tko-v2 an (http://localhost:8080), nicht Staging/Prod — dort können nicht anonymisierte personenbezogene Daten vorhanden sein.

• Die Entität Contragent hat kein vorab bestätigtes Feld „Status“ — get_contragent_status gibt die gefundene Entität vollständig zurück; das Feld für den tatsächlichen Status muss anhand der tatsächlichen Antwort der REST API bestimmt werden.