lk-tko-mcp

Python 기반 MCP 서버(Model Context Protocol)로, Claude에게 LK 시스템(개인 계정, lk-tko-v2 프로젝트)에 대한 도구 액세스를 제공합니다.

이게 무엇이고 왜 필요한가

MCP는 외부 프로세스가 LLM에 일련의 도구(tools), 즉 타입이 지정된 인자를 가진 일반 함수를 제공하는 개방형 프로토콜입니다. 서버를 Claude Code에 연결하면 Claude에게 특정 함수를 호출하도록 요청할 수 있습니다(예: "ИНН으로 거래처 상태 가져오기", "lkUser의 기간별 연체료 계산하기" 등). 매번 컨텍스트를 글로 설명하거나 수동으로 DB/코드를 뒤질 필요가 없습니다.

이 펫 프로젝트의 목표는 LK 비즈니스 로직 위에 재사용 가능한 도구 계층을 확보하는 것입니다. 기본 리포지토리 안에서만이 아니라 향후 모든 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으로 통신)

통합 스택

첫 번째 도구(get_contragent_status)는 lk-tko-v2의 CUBA REST API v2(OAuth2 password grant + rtneo$Contragent에 대한 generic entity search)를 호출하며, DB에 직접 접근하지 않습니다. 요청 형식은 lk-tko-v2 리포지토리의 curls.txt에 있는 실제 동작 예제로 확인되었습니다.

구조

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 + CUBA REST v2 기반 search_entity().

3. 첫 실제 통합 — 완료, 실제 환경에서 검증됨. get_contragent_status는 lk_client.search_entity("rtneo$Contragent", ...)를 통해 실제로 lk-tko-v2 REST API를 호출하며, 테스트 환경의 실제 데이터로 MCP Inspector를 통해 검증했습니다.

4. Claude Code 연결 — 완료. claude mcp add lk-tko-mcp -- uv run run.py, 상태 ✔ Connected. 다른 개발자를 위한 배포 가이드는 ONBOARDING.md를 참조하세요.

5. 부채/빌링(RESEARCH.md의 우선순위 1) — 완료, 7개 중 6개 검증됨. get_contragent_debt, get_debt_by_phone, get_debt_by_email, get_serviced_periods, get_calculation_amount_type, get_contract, get_fine_details — 모두 lk_client.py의 두 가지 새 REST 헬퍼(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은 구현되지 않았습니다. lk-tko-v2에 REST 래퍼가 아예 없습니다(리포지토리 전체 grep으로 확인됨).

알려진 문제

• get_contragent_bills가 500 오류로 실패합니다. lk-tko-v2 측 버그: BillRepository.getBillsByContragentAndPeriod(71번째 줄)가 e.documentNumber 대신 존재하지 않는 별칭 b.documentNumber를 참조하여 /app/rest/v3/bill을 호출할 때마다 JPQL 컴파일이 깨집니다. 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, 로그인/비밀번호)은 로컬에만 저장됩니다.

• 기본적으로 lk-tko-v2의 로컬 dev 인스턴스(http://localhost:8080)를 지정하고 staging/프로덕션은 사용하지 마세요. 거기에는 비식별화되지 않은 개인정보가 있을 수 있습니다.

• Contragent 엔티티에는 사전에 확인된 "상태" 필드가 없습니다. get_contragent_status는 찾은 엔티티 전체를 반환하므로, 실제 상태 필드는 REST API 응답을 보고 결정해야 합니다.