lk-tko-mcp

Servidor MCP (Model Context Protocol) en Python que da a Claude acceso a las herramientas del sistema ЛК (cuenta personal, proyecto lk-tko-v2).

Qué es y para qué

MCP es un protocolo abierto por el que un proceso externo entrega a la LLM un conjunto de «herramientas» (tools): funciones ordinarias con argumentos tipados. Al conectar el servidor a Claude Code, se puede pedir a Claude que invoque una función concreta («obtener el estado del contraparte por INN», «calcular los intereses de demora por período para lkUser», etc.) en lugar de explicar el contexto con texto o tener que entrar en la BD/el código manualmente cada vez.

El objetivo de este pet project es disponer de una capa de herramientas reutilizable sobre la lógica de negocio de ЛК, que se pueda usar desde cualquier futura sesión de Claude Code, y no solo dentro del repositorio principal.

Related MCP server: MCP4Acumatica

Stack

• Python 3.10+, gestor de dependencias — uv

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

• Transporte: stdio (Claude Code lanza el proceso y se comunica con él a través de stdin/stdout)

Stack de integración

La primera tool (get_contragent_status) accede a la CUBA REST API v2 de lk-tko-v2 (OAuth2 password grant + generic entity search por rtneo$Contragent), no directamente a la BD. El formato de las peticiones está confirmado por ejemplos funcionales del curls.txt del repositorio lk-tko-v2.

Estructura

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

Ejecución y verificación local

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

Conexión con Claude Code

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

Plan de desarrollo

1. Esqueleto — listo. Servidor con ping y get_contragent_status; se ejecuta localmente y mediante Inspector.

2. Cliente REST — listo. lk_client.py: OAuth2 password grant con caché de token + search_entity() sobre CUBA REST v2.

3. Primera integración real — lista y probada en vivo. get_contragent_status invoca realmente la REST API de lk-tko-v2 mediante lk_client.search_entity("rtneo$Contragent", ...), probado con MCP Inspector con datos reales del entorno de pruebas.

4. Conexión con Claude Code — lista. claude mcp add lk-tko-mcp -- uv run run.py, estado ✔ Connected. Guía de despliegue para otros desarrolladores — ver ONBOARDING.md.

5. Deuda/facturación (Prioridad 1 de RESEARCH.md) — listo, 6 de 7 verificados. get_contragent_debt, get_debt_by_phone, get_debt_by_email, get_serviced_periods, get_calculation_amount_type, get_contract, get_fine_details — todos implementados mediante dos nuevos helpers REST en lk_client.py (call_v3 para controladores v3 personalizados, call_service para servicios v2 declarativos). get_contragent_bills está implementado, pero bloqueado por un bug en lk-tko-v2 (ver nota más abajo). get_calculations_tabs, get_debt_breakdown_by_real_estate, find_contragents_with_debt_older_than — no implementados; no tienen ningún wrapper REST en lk-tko-v2 (confirmado con grep en todo el repositorio).

Problemas conocidos

• get_contragent_bills falla con 500. Bug en lk-tko-v2: BillRepository.getBillsByContragentAndPeriod (línea 71) hace referencia a un alias inexistente b.documentNumber en lugar de e.documentNumber — rompe la compilación JPQL en cualquier llamada a /app/rest/v3/bill. Se ha registrado una tarea aparte para su corrección en lk-tko-v2; nuestro código no tiene nada que ver.

5. Ampliación del conjunto de herramientas — una herramienta por cada escenario concreto y recurrente (por ejemplo, período/intereses de demora para lkUser — ver la memoria del proyecto project_lk_user_config), sin abstraer de antemano.

6. (Opcional) acceso del equipo — claude mcp add lk-tko-mcp --scope project -- uv run run.py creará un .mcp.json en el repositorio, que se puede incluir en un commit (sin secretos).

Verificación (después de rellenar .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

Notas de seguridad

• .env no se hace commit; los secretos reales (client_id/secret, login/contraseña) se guardan solo localmente.

• Por defecto, apunta a una instancia local de desarrollo de lk-tko-v2 (http://localhost:8080), no a staging/prod — allí puede haber datos personales no anonimizados.

• La entidad Contragent no tiene un campo «estado» confirmado de antemano — get_contragent_status devuelve la entidad encontrada completa; el campo para el estado real debe determinarse según la respuesta de la REST API.