lk-tko-mcp

基于 Python 的 MCP 服务器（Model Context Protocol），为 Claude 提供对 LK 系统（个人账户，项目 lk-tko-v2）的工具访问。

这是什么以及为什么

MCP 是一种开放协议，外部进程通过它向 LLM 提供一组「工具」（tools）：带有类型化参数的普通函数。将服务器连接到 Claude Code 后，可以让 Claude 调用特定函数（「按 ИНН 获取交易对手状态」、「按期间为 lkUser 计算滞纳金」等），而不是每次都用文本解释上下文，或手动去查数据库/代码。

这个业余项目的目标，是在 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）访问 CUBA REST API v2 lk-tko-v2（OAuth2 password grant + 按 rtneo$Contragent 的通用实体搜索），而不是直接访问数据库。请求格式已由 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 侧的 bug 阻塞（见下方备注）。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 侧的 bug：BillRepository.getBillsByContragentAndPeriod（第 71 行）引用了不存在的别名 b.documentNumber，而不是 e.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 的实际响应来确定。