lk-tko-mcp

Python ベースの MCP サーバー（Model Context Protocol）で、Claude に ЛК システム（個人キャビネット、プロジェクト lk-tko-v2）へのツールアクセスを提供します。

これは何か、なぜ作るのか

MCP は、外部プロセスが LLM に「ツール」（型付き引数を持つ通常の関数）のセットを提供するオープンプロトコルです。 サーバーを Claude Code に接続すれば、毎回テキストでコンテキストを説明したり、手動で DB やコードを調べたりする代わりに、Claude に特定の関数（「ИНН で取引先のステータスを取得」「lkUser の期間ごとの延滞金を計算」など）を呼び出してもらうことができます。

このペットプロジェクトの目的は、ЛК のビジネスロジックの上に再利用可能なツール層を用意し、メインリポジトリの中だけでなく、将来のあらゆる 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 に対する汎用エンティティ検索）を経由します。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 を参照。

既知の問題

• get_contragent_bills が 500 エラーになる。 lk-tko-v2 側のバグ: BillRepository.getBillsByContragentAndPeriod（71 行目）が e.documentNumber ではなく存在しないエイリアス b.documentNumber を参照しており、/app/rest/v3/bill を呼び出すたびに JPQL コンパイルが失敗します。修正タスクは lk-tko-v2 側に別途登録済みで、私たちのコードは無関係です。

5. ツールセットの拡張 — 反復的な具体的シナリオごとに 1 ツールずつ追加する（例: 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、ログイン/パスワード）はローカルのみに保存されます。

• デフォルトでは、staging/本番ではなく、lk-tko-v2 のローカル dev インスタンス（http://localhost:8080）を指定してください。そこには匿名化されていない個人データ（ПДн）が含まれる可能性があります。

• Contragent エンティティには、事前に確認された「ステータス」フィールドはありません。get_contragent_status は見つかったエンティティ全体を返すため、実際のステータスに使うフィールドは REST API の応答を確認して決める必要があります。